external/bsd/bind/dist/lib/lwres/man/lwres_getaddrinfo.docbook

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2004, 2005, 2007  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000, 2001, 2003  Internet Software Consortium.
   7  -
   8  - Permission to use, copy, modify, and/or distribute this software for any
   9  - purpose with or without fee is hereby granted, provided that the above
  10  - copyright notice and this permission notice appear in all copies.
  11  -
  12  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  13  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  14  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  15  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  16  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  17  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  18  - PERFORMANCE OF THIS SOFTWARE.
  19 -->
  20
  21 <!-- Id: lwres_getaddrinfo.docbook,v 1.13 2007/06/18 23:47:51 tbox Exp -->
  22 <refentry>
  23
  24   <refentryinfo>
  25     <date>Jun 30, 2000</date>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle>lwres_getaddrinfo</refentrytitle>
  30     <manvolnum>3</manvolnum>
  31     <refmiscinfo>BIND9</refmiscinfo>
  32   </refmeta>
  33
  34   <docinfo>
  35     <copyright>
  36       <year>2004</year>
  37       <year>2005</year>
  38       <year>2007</year>
  39       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  40     </copyright>
  41     <copyright>
  42       <year>2000</year>
  43       <year>2001</year>
  44       <year>2003</year>
  45       <holder>Internet Software Consortium.</holder>
  46     </copyright>
  47   </docinfo>
  48
  49   <refnamediv>
  50     <refname>lwres_getaddrinfo</refname>
  51     <refname>lwres_freeaddrinfo</refname>
  52     <refpurpose>socket address structure to host and service name</refpurpose>
  53   </refnamediv>
  54   <refsynopsisdiv>
  55     <funcsynopsis>
  56 <funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
  57 <funcprototype>
  58         <funcdef>
  59 int
  60 <function>lwres_getaddrinfo</function></funcdef>
  61         <paramdef>const char *<parameter>hostname</parameter></paramdef>
  62         <paramdef>const char *<parameter>servname</parameter></paramdef>
  63         <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>
  64         <paramdef>struct addrinfo **<parameter>res</parameter></paramdef>
  65         </funcprototype>
  66 <funcprototype>
  67         <funcdef>
  68 void
  69 <function>lwres_freeaddrinfo</function></funcdef>
  70         <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>
  71       </funcprototype>
  72 </funcsynopsis>
  73
  74     <para>
  75       If the operating system does not provide a
  76       <type>struct addrinfo</type>,
  77       the following structure is used:
  78     </para>
  79     <para><programlisting>
  80 struct  addrinfo {
  81         int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
  82         int             ai_family;      /* PF_xxx */
  83         int             ai_socktype;    /* SOCK_xxx */
  84         int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
  85         size_t          ai_addrlen;     /* length of ai_addr */
  86         char            *ai_canonname;  /* canonical name for hostname */
  87         struct sockaddr *ai_addr;       /* binary address */
  88         struct addrinfo *ai_next;       /* next structure in linked list */
  89 };
  90 </programlisting>
  91     </para>
  92
  93   </refsynopsisdiv>
  94
  95   <refsect1>
  96     <title>DESCRIPTION</title>
  97
  98     <para><function>lwres_getaddrinfo()</function>
  99       is used to get a list of IP addresses and port numbers for host
 100       <parameter>hostname</parameter> and service
 101       <parameter>servname</parameter>.
 102
 103       The function is the lightweight resolver's implementation of
 104       <function>getaddrinfo()</function> as defined in RFC2133.
 105       <parameter>hostname</parameter> and
 106       <parameter>servname</parameter> are pointers to null-terminated
 107       strings or <type>NULL</type>.
 108
 109       <parameter>hostname</parameter> is either a host name or a
 110       numeric host address string: a dotted decimal IPv4 address or an
 111       IPv6 address.  <parameter>servname</parameter> is either a
 112       decimal port number or a service name as listed in
 113       <filename>/etc/services</filename>.
 114     </para>
 115
 116     <para><parameter>hints</parameter>
 117       is an optional pointer to a
 118       <type>struct addrinfo</type>.
 119       This structure can be used to provide hints concerning the type of
 120       socket
 121       that the caller supports or wishes to use.
 122       The caller can supply the following structure elements in
 123       <parameter>*hints</parameter>:
 124
 125       <variablelist>
 126         <varlistentry>
 127           <term><constant>ai_family</constant></term>
 128           <listitem>
 129             <para>
 130               The protocol family that should be used.
 131               When
 132               <constant>ai_family</constant>
 133               is set to
 134               <type>PF_UNSPEC</type>,
 135               it means the caller will accept any protocol family supported by
 136               the
 137               operating system.
 138             </para>
 139           </listitem>
 140         </varlistentry>
 141         <varlistentry>
 142           <term><constant>ai_socktype</constant></term>
 143           <listitem>
 144             <para>
 145               denotes the type of socket &mdash;
 146               <type>SOCK_STREAM</type>,
 147               <type>SOCK_DGRAM</type>
 148               or
 149               <type>SOCK_RAW</type>
 150               &mdash; that is wanted.
 151               When
 152               <constant>ai_socktype</constant>
 153               is zero the caller will accept any socket type.
 154             </para>
 155           </listitem>
 156         </varlistentry>
 157         <varlistentry>
 158           <term><constant>ai_protocol</constant></term>
 159           <listitem>
 160             <para>
 161               indicates which transport protocol is wanted: IPPROTO_UDP or
 162               IPPROTO_TCP.
 163               If
 164               <constant>ai_protocol</constant>
 165               is zero the caller will accept any protocol.
 166             </para>
 167           </listitem>
 168         </varlistentry>
 169         <varlistentry>
 170           <term><constant>ai_flags</constant></term>
 171           <listitem>
 172             <para>
 173               Flag bits.
 174               If the
 175               <type>AI_CANONNAME</type>
 176               bit is set, a successful call to
 177               <function>lwres_getaddrinfo()</function>
 178               will return a null-terminated string containing the canonical
 179               name
 180               of the specified hostname in
 181               <constant>ai_canonname</constant>
 182               of the first
 183               <type>addrinfo</type>
 184               structure returned.
 185               Setting the
 186               <type>AI_PASSIVE</type>
 187               bit indicates that the returned socket address structure is
 188               intended
 189               for used in a call to
 190               <citerefentry>
 191                 <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
 192               </citerefentry>.
 193
 194               In this case, if the hostname argument is a
 195               <type>NULL</type>
 196               pointer, then the IP address portion of the socket
 197               address structure will be set to
 198               <type>INADDR_ANY</type>
 199               for an IPv4 address or
 200               <type>IN6ADDR_ANY_INIT</type>
 201               for an IPv6 address.
 202             </para>
 203             <para>
 204               When
 205               <constant>ai_flags</constant>
 206               does not set the
 207               <type>AI_PASSIVE</type>
 208               bit, the returned socket address structure will be ready
 209               for use in a call to
 210               <citerefentry>
 211                 <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
 212               </citerefentry>
 213               for a connection-oriented protocol or
 214               <citerefentry>
 215                 <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
 216               </citerefentry>,
 217
 218               <citerefentry>
 219                 <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
 220               </citerefentry>,
 221
 222               or
 223               <citerefentry>
 224                 <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
 225               </citerefentry>
 226               if a connectionless protocol was chosen.
 227               The IP address portion of the socket address structure will be
 228               set to the loopback address if
 229               <parameter>hostname</parameter>
 230               is a
 231               <type>NULL</type>
 232               pointer and
 233               <type>AI_PASSIVE</type>
 234               is not set in
 235               <constant>ai_flags</constant>.
 236             </para>
 237             <para>
 238               If
 239               <constant>ai_flags</constant>
 240               is set to
 241               <type>AI_NUMERICHOST</type>
 242               it indicates that
 243               <parameter>hostname</parameter>
 244               should be treated as a numeric string defining an IPv4 or IPv6
 245               address
 246               and no name resolution should be attempted.
 247             </para>
 248           </listitem>
 249         </varlistentry>
 250       </variablelist>
 251     </para>
 252
 253     <para>
 254       All other elements of the <type>struct addrinfo</type> passed
 255       via <parameter>hints</parameter> must be zero.
 256     </para>
 257
 258     <para>
 259       A <parameter>hints</parameter> of <type>NULL</type> is
 260       treated as if
 261       the caller provided a <type>struct addrinfo</type> initialized to zero
 262       with <constant>ai_family</constant>set to
 263       <constant>PF_UNSPEC</constant>.
 264     </para>
 265
 266     <para>
 267       After a successful call to
 268       <function>lwres_getaddrinfo()</function>,
 269       <parameter>*res</parameter>
 270       is a pointer to a linked list of one or more
 271       <type>addrinfo</type>
 272       structures.
 273       Each
 274       <type>struct addrinfo</type>
 275       in this list cn be processed by following
 276       the
 277       <constant>ai_next</constant>
 278       pointer, until a
 279       <type>NULL</type>
 280       pointer is encountered.
 281       The three members
 282       <constant>ai_family</constant>,
 283       <constant>ai_socktype</constant>,
 284       and
 285       <constant>ai_protocol</constant>
 286       in each
 287       returned
 288       <type>addrinfo</type>
 289       structure contain the corresponding arguments for a call to
 290       <citerefentry>
 291         <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
 292       </citerefentry>.
 293       For each
 294       <type>addrinfo</type>
 295       structure in the list, the
 296       <constant>ai_addr</constant>
 297       member points to a filled-in socket address structure of length
 298       <constant>ai_addrlen</constant>.
 299     </para>
 300
 301     <para>
 302       All of the information returned by
 303       <function>lwres_getaddrinfo()</function>
 304       is dynamically allocated: the addrinfo structures, and the socket
 305       address structures and canonical host name strings pointed to by the
 306       <constant>addrinfo</constant>structures.
 307       Memory allocated for the dynamically allocated structures created by
 308       a successful call to
 309       <function>lwres_getaddrinfo()</function>
 310       is released by
 311       <function>lwres_freeaddrinfo()</function>.
 312       <parameter>ai</parameter>
 313       is a pointer to a
 314       <type>struct addrinfo</type>
 315       created by a call to
 316       <function>lwres_getaddrinfo()</function>.
 317     </para>
 318
 319   </refsect1>
 320
 321   <refsect1>
 322     <title>RETURN VALUES</title>
 323
 324     <para><function>lwres_getaddrinfo()</function>
 325       returns zero on success or one of the error codes listed in
 326       <citerefentry>
 327         <refentrytitle>gai_strerror</refentrytitle><manvolnum>3</manvolnum>
 328       </citerefentry>
 329       if an error occurs.  If both <parameter>hostname</parameter> and
 330       <parameter>servname</parameter> are <type>NULL</type>
 331       <function>lwres_getaddrinfo()</function> returns
 332       <errorcode>EAI_NONAME</errorcode>.
 333     </para>
 334   </refsect1>
 335   <refsect1>
 336     <title>SEE ALSO</title>
 337     <para><citerefentry>
 338         <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
 339       </citerefentry>,
 340
 341       <citerefentry>
 342         <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
 343       </citerefentry>,
 344
 345       <citerefentry>
 346         <refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
 347       </citerefentry>,
 348
 349       <citerefentry>
 350         <refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
 351       </citerefentry>,
 352
 353       <citerefentry>
 354         <refentrytitle>RFC2133</refentrytitle>
 355       </citerefentry>,
 356
 357       <citerefentry>
 358         <refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
 359       </citerefentry>,
 360
 361       <citerefentry>
 362         <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
 363       </citerefentry>,
 364
 365       <citerefentry>
 366         <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
 367       </citerefentry>,
 368
 369       <citerefentry>
 370         <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
 371       </citerefentry>,
 372
 373       <citerefentry>
 374         <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
 375       </citerefentry>,
 376
 377       <citerefentry>
 378         <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
 379       </citerefentry>.
 380     </para>
 381
 382   </refsect1>
 383 </refentry><!--
 384  - Local variables:
 385  - mode: sgml
 386  - End:
 387 -->