contrib/bind-9.5.2/lib/lwres/man/lwres_getaddrinfo.html

   1 <!--
   2  - Copyright (C) 2004, 2005, 2007 Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and/or distribute this software for any
   6  - purpose with or without fee is hereby granted, provided that the above
   7  - copyright notice and this permission notice appear in all copies.
   8  -
   9  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  - AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  - PERFORMANCE OF THIS SOFTWARE.
  16 -->
  17 <!-- $Id: lwres_getaddrinfo.html,v 1.27.214.1 2009/07/11 01:43:31 tbox Exp $ -->
  18 <html>
  19 <head>
  20 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  21 <title>lwres_getaddrinfo</title>
  22 <meta name="generator" content="DocBook XSL Stylesheets V1.71.1">
  23 </head>
  24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
  25 <a name="id2476275"></a><div class="titlepage"></div>
  26 <div class="refnamediv">
  27 <h2>Name</h2>
  28 <p>lwres_getaddrinfo, lwres_freeaddrinfo &#8212; socket address structure to host and service name</p>
  29 </div>
  30 <div class="refsynopsisdiv">
  31 <h2>Synopsis</h2>
  32 <div class="funcsynopsis">
  33 <pre class="funcsynopsisinfo">#include &lt;lwres/netdb.h&gt;</pre>
  34 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" style="padding-bottom: 1em">
  35 <tr>
  36 <td><code class="funcdef">
  37 int
  38 <b class="fsfunc">lwres_getaddrinfo</b>(</code></td>
  39 <td>const char * </td>
  40 <td>
  41 <var class="pdparam">hostname</var>, </td>
  42 </tr>
  43 <tr>
  44 <td> </td>
  45 <td>const char * </td>
  46 <td>
  47 <var class="pdparam">servname</var>, </td>
  48 </tr>
  49 <tr>
  50 <td> </td>
  51 <td>const struct addrinfo * </td>
  52 <td>
  53 <var class="pdparam">hints</var>, </td>
  54 </tr>
  55 <tr>
  56 <td> </td>
  57 <td>struct addrinfo ** </td>
  58 <td>
  59 <var class="pdparam">res</var><code>)</code>;</td>
  60 </tr>
  61 </table>
  62 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr>
  63 <td><code class="funcdef">
  64 void
  65 <b class="fsfunc">lwres_freeaddrinfo</b>(</code></td>
  66 <td>struct addrinfo * </td>
  67 <td>
  68 <var class="pdparam">ai</var><code>)</code>;</td>
  69 </tr></table>
  70 </div>
  71 <p>
  72       If the operating system does not provide a
  73       <span class="type">struct addrinfo</span>,
  74       the following structure is used:
  75     </p>
  76 <pre class="programlisting">
  77 struct  addrinfo {
  78         int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
  79         int             ai_family;      /* PF_xxx */
  80         int             ai_socktype;    /* SOCK_xxx */
  81         int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
  82         size_t          ai_addrlen;     /* length of ai_addr */
  83         char            *ai_canonname;  /* canonical name for hostname */
  84         struct sockaddr *ai_addr;       /* binary address */
  85         struct addrinfo *ai_next;       /* next structure in linked list */
  86 };
  87 </pre>
  88 <p>
  89     </p>
  90 </div>
  91 <div class="refsect1" lang="en">
  92 <a name="id2543412"></a><h2>DESCRIPTION</h2>
  93 <p><code class="function">lwres_getaddrinfo()</code>
  94       is used to get a list of IP addresses and port numbers for host
  95       <em class="parameter"><code>hostname</code></em> and service
  96       <em class="parameter"><code>servname</code></em>.
  97
  98       The function is the lightweight resolver's implementation of
  99       <code class="function">getaddrinfo()</code> as defined in RFC2133.
 100       <em class="parameter"><code>hostname</code></em> and
 101       <em class="parameter"><code>servname</code></em> are pointers to null-terminated
 102       strings or <span class="type">NULL</span>.
 103
 104       <em class="parameter"><code>hostname</code></em> is either a host name or a
 105       numeric host address string: a dotted decimal IPv4 address or an
 106       IPv6 address.  <em class="parameter"><code>servname</code></em> is either a
 107       decimal port number or a service name as listed in
 108       <code class="filename">/etc/services</code>.
 109     </p>
 110 <p><em class="parameter"><code>hints</code></em>
 111       is an optional pointer to a
 112       <span class="type">struct addrinfo</span>.
 113       This structure can be used to provide hints concerning the type of
 114       socket
 115       that the caller supports or wishes to use.
 116       The caller can supply the following structure elements in
 117       <em class="parameter"><code>*hints</code></em>:
 118
 119       </p>
 120 <div class="variablelist"><dl>
 121 <dt><span class="term"><code class="constant">ai_family</code></span></dt>
 122 <dd><p>
 123               The protocol family that should be used.
 124               When
 125               <code class="constant">ai_family</code>
 126               is set to
 127               <span class="type">PF_UNSPEC</span>,
 128               it means the caller will accept any protocol family supported by
 129               the
 130               operating system.
 131             </p></dd>
 132 <dt><span class="term"><code class="constant">ai_socktype</code></span></dt>
 133 <dd><p>
 134               denotes the type of socket &#8212;
 135               <span class="type">SOCK_STREAM</span>,
 136               <span class="type">SOCK_DGRAM</span>
 137               or
 138               <span class="type">SOCK_RAW</span>
 139               &#8212; that is wanted.
 140               When
 141               <code class="constant">ai_socktype</code>
 142               is zero the caller will accept any socket type.
 143             </p></dd>
 144 <dt><span class="term"><code class="constant">ai_protocol</code></span></dt>
 145 <dd><p>
 146               indicates which transport protocol is wanted: IPPROTO_UDP or
 147               IPPROTO_TCP.
 148               If
 149               <code class="constant">ai_protocol</code>
 150               is zero the caller will accept any protocol.
 151             </p></dd>
 152 <dt><span class="term"><code class="constant">ai_flags</code></span></dt>
 153 <dd>
 154 <p>
 155               Flag bits.
 156               If the
 157               <span class="type">AI_CANONNAME</span>
 158               bit is set, a successful call to
 159               <code class="function">lwres_getaddrinfo()</code>
 160               will return a null-terminated string containing the canonical
 161               name
 162               of the specified hostname in
 163               <code class="constant">ai_canonname</code>
 164               of the first
 165               <span class="type">addrinfo</span>
 166               structure returned.
 167               Setting the
 168               <span class="type">AI_PASSIVE</span>
 169               bit indicates that the returned socket address structure is
 170               intended
 171               for used in a call to
 172               <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>.
 173
 174               In this case, if the hostname argument is a
 175               <span class="type">NULL</span>
 176               pointer, then the IP address portion of the socket
 177               address structure will be set to
 178               <span class="type">INADDR_ANY</span>
 179               for an IPv4 address or
 180               <span class="type">IN6ADDR_ANY_INIT</span>
 181               for an IPv6 address.
 182             </p>
 183 <p>
 184               When
 185               <code class="constant">ai_flags</code>
 186               does not set the
 187               <span class="type">AI_PASSIVE</span>
 188               bit, the returned socket address structure will be ready
 189               for use in a call to
 190               <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>
 191               for a connection-oriented protocol or
 192               <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>,
 193
 194               <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>,
 195
 196               or
 197               <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>
 198               if a connectionless protocol was chosen.
 199               The IP address portion of the socket address structure will be
 200               set to the loopback address if
 201               <em class="parameter"><code>hostname</code></em>
 202               is a
 203               <span class="type">NULL</span>
 204               pointer and
 205               <span class="type">AI_PASSIVE</span>
 206               is not set in
 207               <code class="constant">ai_flags</code>.
 208             </p>
 209 <p>
 210               If
 211               <code class="constant">ai_flags</code>
 212               is set to
 213               <span class="type">AI_NUMERICHOST</span>
 214               it indicates that
 215               <em class="parameter"><code>hostname</code></em>
 216               should be treated as a numeric string defining an IPv4 or IPv6
 217               address
 218               and no name resolution should be attempted.
 219             </p>
 220 </dd>
 221 </dl></div>
 222 <p>
 223     </p>
 224 <p>
 225       All other elements of the <span class="type">struct addrinfo</span> passed
 226       via <em class="parameter"><code>hints</code></em> must be zero.
 227     </p>
 228 <p>
 229       A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is
 230       treated as if
 231       the caller provided a <span class="type">struct addrinfo</span> initialized to zero
 232       with <code class="constant">ai_family</code>set to
 233       <code class="constant">PF_UNSPEC</code>.
 234     </p>
 235 <p>
 236       After a successful call to
 237       <code class="function">lwres_getaddrinfo()</code>,
 238       <em class="parameter"><code>*res</code></em>
 239       is a pointer to a linked list of one or more
 240       <span class="type">addrinfo</span>
 241       structures.
 242       Each
 243       <span class="type">struct addrinfo</span>
 244       in this list cn be processed by following
 245       the
 246       <code class="constant">ai_next</code>
 247       pointer, until a
 248       <span class="type">NULL</span>
 249       pointer is encountered.
 250       The three members
 251       <code class="constant">ai_family</code>,
 252       <code class="constant">ai_socktype</code>,
 253       and
 254       <code class="constant">ai_protocol</code>
 255       in each
 256       returned
 257       <span class="type">addrinfo</span>
 258       structure contain the corresponding arguments for a call to
 259       <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>.
 260       For each
 261       <span class="type">addrinfo</span>
 262       structure in the list, the
 263       <code class="constant">ai_addr</code>
 264       member points to a filled-in socket address structure of length
 265       <code class="constant">ai_addrlen</code>.
 266     </p>
 267 <p>
 268       All of the information returned by
 269       <code class="function">lwres_getaddrinfo()</code>
 270       is dynamically allocated: the addrinfo structures, and the socket
 271       address structures and canonical host name strings pointed to by the
 272       <code class="constant">addrinfo</code>structures.
 273       Memory allocated for the dynamically allocated structures created by
 274       a successful call to
 275       <code class="function">lwres_getaddrinfo()</code>
 276       is released by
 277       <code class="function">lwres_freeaddrinfo()</code>.
 278       <em class="parameter"><code>ai</code></em>
 279       is a pointer to a
 280       <span class="type">struct addrinfo</span>
 281       created by a call to
 282       <code class="function">lwres_getaddrinfo()</code>.
 283     </p>
 284 </div>
 285 <div class="refsect1" lang="en">
 286 <a name="id2543789"></a><h2>RETURN VALUES</h2>
 287 <p><code class="function">lwres_getaddrinfo()</code>
 288       returns zero on success or one of the error codes listed in
 289       <span class="citerefentry"><span class="refentrytitle">gai_strerror</span>(3)</span>
 290       if an error occurs.  If both <em class="parameter"><code>hostname</code></em> and
 291       <em class="parameter"><code>servname</code></em> are <span class="type">NULL</span>
 292       <code class="function">lwres_getaddrinfo()</code> returns
 293       <span class="errorcode">EAI_NONAME</span>.
 294     </p>
 295 </div>
 296 <div class="refsect1" lang="en">
 297 <a name="id2543827"></a><h2>SEE ALSO</h2>
 298 <p><span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>,
 299
 300       <span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>,
 301
 302       <span class="citerefentry"><span class="refentrytitle">lwres_freeaddrinfo</span>(3)</span>,
 303
 304       <span class="citerefentry"><span class="refentrytitle">lwres_gai_strerror</span>(3)</span>,
 305
 306       <span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>,
 307
 308       <span class="citerefentry"><span class="refentrytitle">getservbyname</span>(3)</span>,
 309
 310       <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>,
 311
 312       <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>,
 313
 314       <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>,
 315
 316       <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>,
 317
 318       <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>.
 319     </p>
 320 </div>
 321 </div></body>
 322 </html>