diff options
Diffstat (limited to 'usr.sbin/bind/lib/lwres/man/lwres_getaddrinfo.html')
| -rw-r--r-- | usr.sbin/bind/lib/lwres/man/lwres_getaddrinfo.html | 452 |
1 files changed, 214 insertions, 238 deletions
diff --git a/usr.sbin/bind/lib/lwres/man/lwres_getaddrinfo.html b/usr.sbin/bind/lib/lwres/man/lwres_getaddrinfo.html index e9d2f0c5c7a..054dbfca014 100644 --- a/usr.sbin/bind/lib/lwres/man/lwres_getaddrinfo.html +++ b/usr.sbin/bind/lib/lwres/man/lwres_getaddrinfo.html @@ -1,5 +1,5 @@ <!-- - - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC") + - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC") - Copyright (C) 2000, 2001, 2003 Internet Software Consortium. - - Permission to use, copy, modify, and distribute this software for any @@ -14,15 +14,15 @@ - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR - PERFORMANCE OF THIS SOFTWARE. --> -<!-- $ISC: lwres_getaddrinfo.html,v 1.8.2.1.4.12 2006/06/29 13:02:31 marka Exp $ --> +<!-- $ISC: lwres_getaddrinfo.html,v 1.10.18.17 2007/01/30 00:23:45 marka Exp $ --> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <title>lwres_getaddrinfo</title> -<meta name="generator" content="DocBook XSL Stylesheets V1.70.1"> +<meta name="generator" content="DocBook XSL Stylesheets V1.71.1"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en"> -<a name="id2482688"></a><div class="titlepage"></div> +<a name="id2476275"></a><div class="titlepage"></div> <div class="refnamediv"> <h2>Name</h2> <p>lwres_getaddrinfo, lwres_freeaddrinfo — socket address structure to host and service name</p> @@ -36,54 +36,43 @@ <td><code class="funcdef"> int <b class="fsfunc">lwres_getaddrinfo</b>(</code></td> -<td> </td> -<td>, </td> -</tr> -<tr> -<td> </td> -<td> </td> -<td>, </td> +<td>const char * </td> +<td> +<var class="pdparam">hostname</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>const char * </td> +<td> +<var class="pdparam">servname</var>, </td> </tr> <tr> <td> </td> -<td> </td> -<td>, </td> +<td>const struct addrinfo * </td> +<td> +<var class="pdparam">hints</var>, </td> </tr> <tr> <td> </td> -<td> </td> +<td>struct addrinfo ** </td> <td> -<code>)</code>;</td> +<var class="pdparam">res</var><code>)</code>;</td> </tr> </table> -<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> -<tr> +<table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr> <td><code class="funcdef"> void <b class="fsfunc">lwres_freeaddrinfo</b>(</code></td> -<td> </td> +<td>struct addrinfo * </td> <td> -<code>)</code>;</td> -</tr> -<tr> -<td> </td> -<td> </td> -<td> -<code>)</code>;</td> -</tr> -</table> +<var class="pdparam">ai</var><code>)</code>;</td> +</tr></table> </div> <p> -If the operating system does not provide a -<span class="type">struct addrinfo</span>, -the following structure is used: - -</p> + If the operating system does not provide a + <span class="type">struct addrinfo</span>, + the following structure is used: + </p> <pre class="programlisting"> struct addrinfo { int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ @@ -97,250 +86,237 @@ struct addrinfo { }; </pre> <p> -</p> + </p> </div> <div class="refsect1" lang="en"> -<a name="id2549448"></a><h2>DESCRIPTION</h2> -<p> -<code class="function">lwres_getaddrinfo()</code> -is used to get a list of IP addresses and port numbers for host -<em class="parameter"><code>hostname</code></em> -and service -<em class="parameter"><code>servname</code></em>. +<a name="id2543412"></a><h2>DESCRIPTION</h2> +<p><code class="function">lwres_getaddrinfo()</code> + is used to get a list of IP addresses and port numbers for host + <em class="parameter"><code>hostname</code></em> and service + <em class="parameter"><code>servname</code></em>. -The function is the lightweight resolver's implementation of -<code class="function">getaddrinfo()</code> -as defined in RFC2133. -<em class="parameter"><code>hostname</code></em> -and -<em class="parameter"><code>servname</code></em> -are pointers to null-terminated -strings or -<span class="type">NULL</span>. + The function is the lightweight resolver's implementation of + <code class="function">getaddrinfo()</code> as defined in RFC2133. + <em class="parameter"><code>hostname</code></em> and + <em class="parameter"><code>servname</code></em> are pointers to null-terminated + strings or <span class="type">NULL</span>. -<em class="parameter"><code>hostname</code></em> -is either a host name or a numeric host address string: a dotted decimal -IPv4 address or an IPv6 address. -<em class="parameter"><code>servname</code></em> -is either a decimal port number or a service name as listed in -<code class="filename">/etc/services</code>. -</p> -<p> -<em class="parameter"><code>hints</code></em> -is an optional pointer to a -<span class="type">struct addrinfo</span>. -This structure can be used to provide hints concerning the type of socket -that the caller supports or wishes to use. -The caller can supply the following structure elements in -<em class="parameter"><code>*hints</code></em>: + <em class="parameter"><code>hostname</code></em> is either a host name or a + numeric host address string: a dotted decimal IPv4 address or an + IPv6 address. <em class="parameter"><code>servname</code></em> is either a + decimal port number or a service name as listed in + <code class="filename">/etc/services</code>. + </p> +<p><em class="parameter"><code>hints</code></em> + is an optional pointer to a + <span class="type">struct addrinfo</span>. + This structure can be used to provide hints concerning the type of + socket + that the caller supports or wishes to use. + The caller can supply the following structure elements in + <em class="parameter"><code>*hints</code></em>: -</p> + </p> <div class="variablelist"><dl> <dt><span class="term"><code class="constant">ai_family</code></span></dt> -<dd><p>The protocol family that should be used. -When -<code class="constant">ai_family</code> -is set to -<span class="type">PF_UNSPEC</span>, -it means the caller will accept any protocol family supported by the -operating system. -</p></dd> +<dd><p> + The protocol family that should be used. + When + <code class="constant">ai_family</code> + is set to + <span class="type">PF_UNSPEC</span>, + it means the caller will accept any protocol family supported by + the + operating system. + </p></dd> <dt><span class="term"><code class="constant">ai_socktype</code></span></dt> <dd><p> -denotes the type of socket — -<span class="type">SOCK_STREAM</span>, -<span class="type">SOCK_DGRAM</span> -or -<span class="type">SOCK_RAW</span> -— that is wanted. -When -<code class="constant">ai_socktype</code> -is zero the caller will accept any socket type. -</p></dd> + denotes the type of socket — + <span class="type">SOCK_STREAM</span>, + <span class="type">SOCK_DGRAM</span> + or + <span class="type">SOCK_RAW</span> + — that is wanted. + When + <code class="constant">ai_socktype</code> + is zero the caller will accept any socket type. + </p></dd> <dt><span class="term"><code class="constant">ai_protocol</code></span></dt> <dd><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> + 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>. + 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> + 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>, + 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>, + <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> + 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> + 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> <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> + 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> + 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> + 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> + 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="refsect1" lang="en"> -<a name="id2549874"></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> +<a name="id2543789"></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="refsect1" lang="en"> -<a name="id2549912"></a><h2>SEE ALSO</h2> -<p> -<span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>, +<a name="id2543827"></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_getaddrinfo</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">lwres_freeaddrinfo</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">lwres_gai_strerror</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">RFC2133</span></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">getservbyname</span>(3)</span>, -<span class="citerefentry"><span class="refentrytitle">bind</span>(2)</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">connect</span>(2)</span>, -<span class="citerefentry"><span class="refentrytitle">sendto</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">sendmsg</span>(2)</span>, -<span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>. -</p> + <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>. + </p> </div> </div></body> </html> |