lwres_getaddrinfo.html revision 2eeb74d1cf5355dd98f6d507a10086e16bb08c4b
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<!--
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - Copyright (C) 2004, 2005, 2007, 2014 Internet Systems Consortium, Inc. ("ISC")
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync -
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - Permission to use, copy, modify, and/or distribute this software for any
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - purpose with or without fee is hereby granted, provided that the above
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - copyright notice and this permission notice appear in all copies.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync -
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync - PERFORMANCE OF THIS SOFTWARE.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync-->
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<html>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<head>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<title>lwres_getaddrinfo</title>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync</head>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" title="lwres_getaddrinfo">
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<a name="idp60785488"></a><div class="titlepage"></div>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <div class="refnamediv">
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<h2>Name</h2>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync lwres_getaddrinfo,
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync lwres_freeaddrinfo
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync &#8212; socket address structure to host and service name
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync </p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync</div>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <div class="refsynopsisdiv" title="Synopsis">
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<h2>Synopsis</h2>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <div class="funcsynopsis">
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<pre class="funcsynopsisinfo">#include &lt;lwres/netdb.h&gt;</pre>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table">
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<tr>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<td><code class="funcdef">
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsyncint
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<b class="fsfunc">lwres_getaddrinfo</b>(</code></td>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<td>const char *<var class="pdparam">hostname</var>, </td>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync</tr>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<tr>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<td>�</td>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<td>const char *<var class="pdparam">servname</var>, </td>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync</tr>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<tr>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<td>�</td>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<td>const struct addrinfo *<var class="pdparam">hints</var>, </td>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync</tr>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<tr>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<td>�</td>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<td>struct addrinfo **<var class="pdparam">res</var><code>)</code>;</td>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync</tr>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync</table>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<div class="funcprototype-spacer">�</div>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<td><code class="funcdef">
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsyncvoid
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<b class="fsfunc">lwres_freeaddrinfo</b>(</code></td>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<td>struct addrinfo *<var class="pdparam">ai</var><code>)</code>;</td>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync</tr></table>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<div class="funcprototype-spacer">�</div>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync</div>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync If the operating system does not provide a
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <span class="type">struct addrinfo</span>,
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync the following structure is used:
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync </p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <pre class="programlisting">
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsyncstruct addrinfo {
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync int ai_flags; /* AI_PASSIVE, AI_CANONNAME */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync int ai_family; /* PF_xxx */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync int ai_socktype; /* SOCK_xxx */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync size_t ai_addrlen; /* length of ai_addr */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync char *ai_canonname; /* canonical name for hostname */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync struct sockaddr *ai_addr; /* binary address */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync struct addrinfo *ai_next; /* next structure in linked list */
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync};
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync</pre>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync </p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync </div>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <div class="refsection" title="DESCRIPTION">
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<a name="idp60848592"></a><h2>DESCRIPTION</h2>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <p><code class="function">lwres_getaddrinfo()</code>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync is used to get a list of IP addresses and port numbers for host
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <em class="parameter"><code>hostname</code></em> and service
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <em class="parameter"><code>servname</code></em>.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync The function is the lightweight resolver's implementation of
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <code class="function">getaddrinfo()</code> as defined in RFC2133.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <em class="parameter"><code>hostname</code></em> and
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <em class="parameter"><code>servname</code></em> are pointers to null-terminated
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync strings or <span class="type">NULL</span>.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <em class="parameter"><code>hostname</code></em> is either a host name or a
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync numeric host address string: a dotted decimal IPv4 address or an
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync IPv6 address. <em class="parameter"><code>servname</code></em> is either a
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync decimal port number or a service name as listed in
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <code class="filename">/etc/services</code>.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync </p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <p><em class="parameter"><code>hints</code></em>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync is an optional pointer to a
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <span class="type">struct addrinfo</span>.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync This structure can be used to provide hints concerning the type of
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync socket
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync that the caller supports or wishes to use.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync The caller can supply the following structure elements in
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <em class="parameter"><code>*hints</code></em>:
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync </p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<div class="variablelist"><dl>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<dt><span class="term"><code class="constant">ai_family</code></span></dt>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<dd>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync The protocol family that should be used.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync When
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <code class="constant">ai_family</code>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync is set to
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <span class="type">PF_UNSPEC</span>,
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync it means the caller will accept any protocol family supported by
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync the
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync operating system.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync </p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync </dd>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<dt><span class="term"><code class="constant">ai_socktype</code></span></dt>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<dd>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync denotes the type of socket &#8212;
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <span class="type">SOCK_STREAM</span>,
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <span class="type">SOCK_DGRAM</span>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync or
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <span class="type">SOCK_RAW</span>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync &#8212; that is wanted.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync When
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <code class="constant">ai_socktype</code>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync is zero the caller will accept any socket type.
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync </p>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync </dd>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<dt><span class="term"><code class="constant">ai_protocol</code></span></dt>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync<dd>
040abec2534dadc53ebc8fa378ef03f4feecb7dbvboxsync <p>
indicates which transport protocol is wanted: IPPROTO_UDP or
IPPROTO_TCP.
If
<code class="constant">ai_protocol</code>
is zero the caller will accept any protocol.
</p>
</dd>
<dt><span class="term"><code class="constant">ai_flags</code></span></dt>
<dd>
<p>
Flag bits.
If the
<span class="type">AI_CANONNAME</span>
bit is set, a successful call to
<code class="function">lwres_getaddrinfo()</code>
will return a null-terminated string containing the canonical
name
of the specified hostname in
<code class="constant">ai_canonname</code>
of the first
<span class="type">addrinfo</span>
structure returned.
Setting the
<span class="type">AI_PASSIVE</span>
bit indicates that the returned socket address structure is
intended
for used in a call to
<span class="citerefentry">
<span class="refentrytitle">bind</span>(2)
</span>.
In this case, if the hostname argument is a
<span class="type">NULL</span>
pointer, then the IP address portion of the socket
address structure will be set to
<span class="type">INADDR_ANY</span>
for an IPv4 address or
<span class="type">IN6ADDR_ANY_INIT</span>
for an IPv6 address.
</p>
<p>
When
<code class="constant">ai_flags</code>
does not set the
<span class="type">AI_PASSIVE</span>
bit, the returned socket address structure will be ready
for use in a call to
<span class="citerefentry">
<span class="refentrytitle">connect</span>(2)
</span>
for a connection-oriented protocol or
<span class="citerefentry">
<span class="refentrytitle">connect</span>(2)
</span>,
<span class="citerefentry">
<span class="refentrytitle">sendto</span>(2)
</span>,
or
<span class="citerefentry">
<span class="refentrytitle">sendmsg</span>(2)
</span>
if a connectionless protocol was chosen.
The IP address portion of the socket address structure will be
set to the loopback address if
<em class="parameter"><code>hostname</code></em>
is a
<span class="type">NULL</span>
pointer and
<span class="type">AI_PASSIVE</span>
is not set in
<code class="constant">ai_flags</code>.
</p>
<p>
If
<code class="constant">ai_flags</code>
is set to
<span class="type">AI_NUMERICHOST</span>
it indicates that
<em class="parameter"><code>hostname</code></em>
should be treated as a numeric string defining an IPv4 or IPv6
address
and no name resolution should be attempted.
</p>
</dd>
</dl></div>
<p>
</p>
<p>
All other elements of the <span class="type">struct addrinfo</span> passed
via <em class="parameter"><code>hints</code></em> must be zero.
</p>
<p>
A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is
treated as if
the caller provided a <span class="type">struct addrinfo</span> initialized to zero
with <code class="constant">ai_family</code>set to
<code class="constant">PF_UNSPEC</code>.
</p>
<p>
After a successful call to
<code class="function">lwres_getaddrinfo()</code>,
<em class="parameter"><code>*res</code></em>
is a pointer to a linked list of one or more
<span class="type">addrinfo</span>
structures.
Each
<span class="type">struct addrinfo</span>
in this list cn be processed by following
the
<code class="constant">ai_next</code>
pointer, until a
<span class="type">NULL</span>
pointer is encountered.
The three members
<code class="constant">ai_family</code>,
<code class="constant">ai_socktype</code>,
and
<code class="constant">ai_protocol</code>
in each
returned
<span class="type">addrinfo</span>
structure contain the corresponding arguments for a call to
<span class="citerefentry">
<span class="refentrytitle">socket</span>(2)
</span>.
For each
<span class="type">addrinfo</span>
structure in the list, the
<code class="constant">ai_addr</code>
member points to a filled-in socket address structure of length
<code class="constant">ai_addrlen</code>.
</p>
<p>
All of the information returned by
<code class="function">lwres_getaddrinfo()</code>
is dynamically allocated: the addrinfo structures, and the socket
address structures and canonical host name strings pointed to by the
<code class="constant">addrinfo</code>structures.
Memory allocated for the dynamically allocated structures created by
a successful call to
<code class="function">lwres_getaddrinfo()</code>
is released by
<code class="function">lwres_freeaddrinfo()</code>.
<em class="parameter"><code>ai</code></em>
is a pointer to a
<span class="type">struct addrinfo</span>
created by a call to
<code class="function">lwres_getaddrinfo()</code>.
</p>
</div>
<div class="refsection" title="RETURN VALUES">
<a name="idp60895440"></a><h2>RETURN VALUES</h2>
<p><code class="function">lwres_getaddrinfo()</code>
returns zero on success or one of the error codes listed in
<span class="citerefentry">
<span class="refentrytitle">gai_strerror</span>(3)
</span>
if an error occurs. If both <em class="parameter"><code>hostname</code></em> and
<em class="parameter"><code>servname</code></em> are <span class="type">NULL</span>
<code class="function">lwres_getaddrinfo()</code> returns
<span class="errorcode">EAI_NONAME</span>.
</p>
</div>
<div class="refsection" title="SEE ALSO">
<a name="idp60904272"></a><h2>SEE ALSO</h2>
<p><span class="citerefentry">
<span class="refentrytitle">lwres</span>(3)
</span>,
<span class="citerefentry">
<span class="refentrytitle">lwres_getaddrinfo</span>(3)
</span>,
<span class="citerefentry">
<span class="refentrytitle">lwres_freeaddrinfo</span>(3)
</span>,
<span class="citerefentry">
<span class="refentrytitle">lwres_gai_strerror</span>(3)
</span>,
<span class="citerefentry">
<span class="refentrytitle">RFC2133</span>
</span>,
<span class="citerefentry">
<span class="refentrytitle">getservbyname</span>(3)
</span>,
<span class="citerefentry">
<span class="refentrytitle">bind</span>(2)
</span>,
<span class="citerefentry">
<span class="refentrytitle">connect</span>(2)
</span>,
<span class="citerefentry">
<span class="refentrytitle">sendto</span>(2)
</span>,
<span class="citerefentry">
<span class="refentrytitle">sendmsg</span>(2)
</span>,
<span class="citerefentry">
<span class="refentrytitle">socket</span>(2)
</span>.
</p>
</div>
</div></body>
</html>