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

   1 <!--
   2  - Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
   3  - Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
   4  -
   5  - Permission to use, copy, modify, and 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.8.2.1.4.10 2005/10/13 02:33:56 marka 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.69.1">
  23 </head>
  24 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
  25 <a name="id2463721"></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> </td>
  40 <td>, </td>
  41 </tr>
  42 <tr>
  43 <td> </td>
  44 <td> </td>
  45 <td>, </td>
  46 </tr>
  47 <tr>
  48 <td> </td>
  49 <td> </td>
  50 <td>, </td>
  51 </tr>
  52 <tr>
  53 <td> </td>
  54 <td> </td>
  55 <td>
  56 <code>)</code>;</td>
  57 </tr>
  58 </table>
  59 <table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr>
  60 <td><code class="funcdef">
  61 void
  62 <b class="fsfunc">lwres_freeaddrinfo</b>(</code></td>
  63 <td> </td>
  64 <td>
  65 <code>)</code>;</td>
  66 </tr></table>
  67 </div>
  68 <p>
  69 If the operating system does not provide a
  70 <span class="type">struct addrinfo</span>,
  71 the following structure is used:
  72
  73 </p>
  74 <pre class="programlisting">
  75 struct  addrinfo {
  76         int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
  77         int             ai_family;      /* PF_xxx */
  78         int             ai_socktype;    /* SOCK_xxx */
  79         int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
  80         size_t          ai_addrlen;     /* length of ai_addr */
  81         char            *ai_canonname;  /* canonical name for hostname */
  82         struct sockaddr *ai_addr;       /* binary address */
  83         struct addrinfo *ai_next;       /* next structure in linked list */
  84 };
  85 </pre>
  86 <p>
  87 </p>
  88 </div>
  89 <div class="refsect1" lang="en">
  90 <a name="id2525883"></a><h2>DESCRIPTION</h2>
  91 <p>
  92 <code class="function">lwres_getaddrinfo()</code>
  93 is used to get a list of IP addresses and port numbers for host
  94 <em class="parameter"><code>hostname</code></em>
  95 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>
 100 as defined in RFC2133.
 101 <em class="parameter"><code>hostname</code></em>
 102 and
 103 <em class="parameter"><code>servname</code></em>
 104 are pointers to null-terminated
 105 strings or
 106 <span class="type">NULL</span>.
 107
 108 <em class="parameter"><code>hostname</code></em>
 109 is either a host name or a numeric host address string: a dotted decimal
 110 IPv4 address or an IPv6 address.
 111 <em class="parameter"><code>servname</code></em>
 112 is either a decimal port number or a service name as listed in
 113 <code class="filename">/etc/services</code>.
 114 </p>
 115 <p>
 116 <em class="parameter"><code>hints</code></em>
 117 is an optional pointer to a
 118 <span class="type">struct addrinfo</span>.
 119 This structure can be used to provide hints concerning the type of socket
 120 that the caller supports or wishes to use.
 121 The caller can supply the following structure elements in
 122 <em class="parameter"><code>*hints</code></em>:
 123
 124 </p>
 125 <div class="variablelist"><dl>
 126 <dt><span class="term"><code class="constant">ai_family</code></span></dt>
 127 <dd><p>The protocol family that should be used.
 128 When
 129 <code class="constant">ai_family</code>
 130 is set to
 131 <span class="type">PF_UNSPEC</span>,
 132 it means the caller will accept any protocol family supported by the
 133 operating system.
 134 </p></dd>
 135 <dt><span class="term"><code class="constant">ai_socktype</code></span></dt>
 136 <dd><p>
 137 denotes the type of socket &#8212;
 138 <span class="type">SOCK_STREAM</span>,
 139 <span class="type">SOCK_DGRAM</span>
 140 or
 141 <span class="type">SOCK_RAW</span>
 142 &#8212; that is wanted.
 143 When
 144 <code class="constant">ai_socktype</code>
 145 is zero the caller will accept any socket type.
 146 </p></dd>
 147 <dt><span class="term"><code class="constant">ai_protocol</code></span></dt>
 148 <dd><p>
 149 indicates which transport protocol is wanted: IPPROTO_UDP or
 150 IPPROTO_TCP.
 151 If
 152 <code class="constant">ai_protocol</code>
 153 is zero the caller will accept any protocol.
 154 </p></dd>
 155 <dt><span class="term"><code class="constant">ai_flags</code></span></dt>
 156 <dd>
 157 <p>
 158 Flag bits.
 159 If the
 160 <span class="type">AI_CANONNAME</span>
 161 bit is set, a successful call to
 162 <code class="function">lwres_getaddrinfo()</code>
 163 will return a null-terminated string containing the canonical name
 164 of the specified hostname in
 165 <code class="constant">ai_canonname</code>
 166 of the first
 167 <span class="type">addrinfo</span>
 168 structure returned.
 169 Setting the
 170 <span class="type">AI_PASSIVE</span>
 171 bit indicates that the returned socket address structure is intended
 172 for used in a call to
 173 <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>.
 174
 175 In this case, if the hostname argument is a
 176 <span class="type">NULL</span>
 177 pointer, then the IP address portion of the socket
 178 address structure will be set to
 179 <span class="type">INADDR_ANY</span>
 180 for an IPv4 address or
 181 <span class="type">IN6ADDR_ANY_INIT</span>
 182 for an IPv6 address.
 183 </p>
 184 <p>
 185 When
 186 <code class="constant">ai_flags</code>
 187 does not set the
 188 <span class="type">AI_PASSIVE</span>
 189 bit, the returned socket address structure will be ready
 190 for use in a call to
 191 <span class="citerefentry"><span class="refentrytitle">connect</span>(2
 192 )</span>
 193 for a connection-oriented protocol or
 194 <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>,
 195
 196 <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>,
 197
 198 or
 199 <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2
 200 )</span>
 201 if a connectionless protocol was chosen.
 202 The IP address portion of the socket address structure will be
 203 set to the loopback address if
 204 <em class="parameter"><code>hostname</code></em>
 205 is a
 206 <span class="type">NULL</span>
 207 pointer and
 208 <span class="type">AI_PASSIVE</span>
 209 is not set in
 210 <code class="constant">ai_flags</code>.
 211 </p>
 212 <p>
 213 If
 214 <code class="constant">ai_flags</code>
 215 is set to
 216 <span class="type">AI_NUMERICHOST</span>
 217 it indicates that
 218 <em class="parameter"><code>hostname</code></em>
 219 should be treated as a numeric string defining an IPv4 or IPv6 address
 220 and no name resolution should be attempted.
 221 </p>
 222 </dd>
 223 </dl></div>
 224 <p>
 225 </p>
 226 <p>
 227 All other elements of the <span class="type">struct addrinfo</span> passed
 228 via <em class="parameter"><code>hints</code></em> must be zero.
 229 </p>
 230 <p>
 231 A <em class="parameter"><code>hints</code></em> of <span class="type">NULL</span> is treated as if
 232 the caller provided a <span class="type">struct addrinfo</span> initialized to zero
 233 with <code class="constant">ai_family</code>set to
 234 <code class="constant">PF_UNSPEC</code>.
 235 </p>
 236 <p>
 237 After a successful call to
 238 <code class="function">lwres_getaddrinfo()</code>,
 239 <em class="parameter"><code>*res</code></em>
 240 is a pointer to a linked list of one or more
 241 <span class="type">addrinfo</span>
 242 structures.
 243 Each
 244 <span class="type">struct addrinfo</span>
 245 in this list cn be processed by following
 246 the
 247 <code class="constant">ai_next</code>
 248 pointer, until a
 249 <span class="type">NULL</span>
 250 pointer is encountered.
 251 The three members
 252 <code class="constant">ai_family</code>,
 253 <code class="constant">ai_socktype</code>,
 254 and
 255 <code class="constant">ai_protocol</code>
 256 in each
 257 returned
 258 <span class="type">addrinfo</span>
 259 structure contain the corresponding arguments for a call to
 260 <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>.
 261 For each
 262 <span class="type">addrinfo</span>
 263 structure in the list, the
 264 <code class="constant">ai_addr</code>
 265 member points to a filled-in socket address structure of length
 266 <code class="constant">ai_addrlen</code>.
 267 </p>
 268 <p>
 269 All of the information returned by
 270 <code class="function">lwres_getaddrinfo()</code>
 271 is dynamically allocated: the addrinfo structures, and the socket
 272 address structures and canonical host name strings pointed to by the
 273 <code class="constant">addrinfo</code>structures.
 274 Memory allocated for the dynamically allocated structures created by
 275 a successful call to
 276 <code class="function">lwres_getaddrinfo()</code>
 277 is released by
 278 <code class="function">lwres_freeaddrinfo()</code>.
 279 <em class="parameter"><code>ai</code></em>
 280 is a pointer to a
 281 <span class="type">struct addrinfo</span>
 282 created by a call to
 283 <code class="function">lwres_getaddrinfo()</code>.
 284 </p>
 285 </div>
 286 <div class="refsect1" lang="en">
 287 <a name="id2526309"></a><h2>RETURN VALUES</h2>
 288 <p>
 289 <code class="function">lwres_getaddrinfo()</code>
 290 returns zero on success or one of the error codes listed in
 291 <span class="citerefentry"><span class="refentrytitle">gai_strerror</span>(3
 292 )</span>
 293 if an error occurs.
 294 If both
 295 <em class="parameter"><code>hostname</code></em>
 296 and
 297 <em class="parameter"><code>servname</code></em>
 298 are
 299 <span class="type">NULL</span>
 300 <code class="function">lwres_getaddrinfo()</code>
 301 returns
 302 <span class="errorcode">EAI_NONAME</span>.
 303
 304 </p>
 305 </div>
 306 <div class="refsect1" lang="en">
 307 <a name="id2526347"></a><h2>SEE ALSO</h2>
 308 <p>
 309 <span class="citerefentry"><span class="refentrytitle">lwres</span>(3)</span>,
 310
 311 <span class="citerefentry"><span class="refentrytitle">lwres_getaddrinfo</span>(3)</span>,
 312
 313 <span class="citerefentry"><span class="refentrytitle">lwres_freeaddrinfo</span>(3)</span>,
 314
 315 <span class="citerefentry"><span class="refentrytitle">lwres_gai_strerror</span>(3)</span>,
 316
 317 <span class="citerefentry"><span class="refentrytitle">RFC2133</span></span>,
 318
 319 <span class="citerefentry"><span class="refentrytitle">getservbyname</span>(3)</span>,
 320
 321 <span class="citerefentry"><span class="refentrytitle">bind</span>(2)</span>,
 322
 323 <span class="citerefentry"><span class="refentrytitle">connect</span>(2)</span>,
 324
 325 <span class="citerefentry"><span class="refentrytitle">sendto</span>(2)</span>,
 326
 327 <span class="citerefentry"><span class="refentrytitle">sendmsg</span>(2)</span>,
 328
 329 <span class="citerefentry"><span class="refentrytitle">socket</span>(2)</span>.
 330 </p>
 331 </div>
 332 </div></body>
 333 </html>