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