contrib/bind9/lib/lwres/man/lwres_getaddrinfo.docbook

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000, 2001, 2003  Internet Software Consortium.
   7  -
   8  - Permission to use, copy, modify, and 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.5.206.4 2005/05/12 21:36:14 sra Exp $ -->
  22
  23 <refentry>
  24
  25 <refentryinfo>
  26 <date>Jun 30, 2000</date>
  27 </refentryinfo>
  28
  29 <refmeta>
  30 <refentrytitle>lwres_getaddrinfo</refentrytitle>
  31 <manvolnum>3</manvolnum>
  32 <refmiscinfo>BIND9</refmiscinfo>
  33 </refmeta>
  34
  35   <docinfo>
  36     <copyright>
  37       <year>2004</year>
  38       <year>2005</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 *hostname</paramdef>
  62 <paramdef>const char *servname</paramdef>
  63 <paramdef>const struct addrinfo *hints</paramdef>
  64 <paramdef>struct addrinfo **res</paramdef>
  65 </funcprototype>
  66 <funcprototype>
  67 <funcdef>
  68 void
  69 <function>lwres_freeaddrinfo</function></funcdef>
  70 <paramdef>struct addrinfo *ai</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
  79 <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 <para>
  98 <function>lwres_getaddrinfo()</function>
  99 is used to get a list of IP addresses and port numbers for host
 100 <parameter>hostname</parameter>
 101 and service
 102 <parameter>servname</parameter>.
 103
 104 The function is the lightweight resolver's implementation of
 105 <function>getaddrinfo()</function>
 106 as defined in RFC2133.
 107 <parameter>hostname</parameter>
 108 and
 109 <parameter>servname</parameter>
 110 are pointers to null-terminated
 111 strings or
 112 <type>NULL</type>.
 113
 114 <parameter>hostname</parameter>
 115 is either a host name or a numeric host address string: a dotted decimal
 116 IPv4 address or an IPv6 address.
 117 <parameter>servname</parameter>
 118 is either a decimal port number or a service name as listed in
 119 <filename>/etc/services</filename>.
 120 </para>
 121
 122 <para>
 123 <parameter>hints</parameter>
 124 is an optional pointer to a
 125 <type>struct addrinfo</type>.
 126 This structure can be used to provide hints concerning the type of socket
 127 that the caller supports or wishes to use.
 128 The caller can supply the following structure elements in
 129 <parameter>*hints</parameter>:
 130
 131 <variablelist>
 132 <varlistentry><term><constant>ai_family</constant></term>
 133 <listitem>
 134 <para>The protocol family that should be used.
 135 When
 136 <constant>ai_family</constant>
 137 is set to
 138 <type>PF_UNSPEC</type>,
 139 it means the caller will accept any protocol family supported by the
 140 operating system.
 141 </para></listitem></varlistentry>
 142 <varlistentry><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><term><constant>ai_protocol</constant></term>
 158 <listitem>
 159 <para>
 160 indicates which transport protocol is wanted: IPPROTO_UDP or
 161 IPPROTO_TCP.
 162 If
 163 <constant>ai_protocol</constant>
 164 is zero the caller will accept any protocol.
 165 </para>
 166 </listitem>
 167 </varlistentry>
 168 <varlistentry><term><constant>ai_flags</constant></term>
 169 <listitem>
 170 <para>
 171 Flag bits.
 172 If the
 173 <type>AI_CANONNAME</type>
 174 bit is set, a successful call to
 175 <function>lwres_getaddrinfo()</function>
 176 will return a null-terminated string containing the canonical name
 177 of the specified hostname in
 178 <constant>ai_canonname</constant>
 179 of the first
 180 <type>addrinfo</type>
 181 structure returned.
 182 Setting the
 183 <type>AI_PASSIVE</type>
 184 bit indicates that the returned socket address structure is intended
 185 for used in a call to
 186 <citerefentry>
 187 <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
 188 </citerefentry>.
 189
 190 In this case, if the hostname argument is a
 191 <type>NULL</type>
 192 pointer, then the IP address portion of the socket
 193 address structure will be set to
 194 <type>INADDR_ANY</type>
 195 for an IPv4 address or
 196 <type>IN6ADDR_ANY_INIT</type>
 197 for an IPv6 address.
 198 </para>
 199 <para>
 200 When
 201 <constant>ai_flags</constant>
 202 does not set the
 203 <type>AI_PASSIVE</type>
 204 bit, the returned socket address structure will be ready
 205 for use in a call to
 206 <citerefentry>
 207 <refentrytitle>connect</refentrytitle><manvolnum>2
 208 </manvolnum>
 209 </citerefentry>
 210 for a connection-oriented protocol or
 211 <citerefentry>
 212 <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
 213 </citerefentry>,
 214
 215 <citerefentry>
 216 <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
 217 </citerefentry>,
 218
 219 or
 220 <citerefentry>
 221 <refentrytitle>sendmsg</refentrytitle><manvolnum>2
 222 </manvolnum>
 223 </citerefentry>
 224 if a connectionless protocol was chosen.
 225 The IP address portion of the socket address structure will be
 226 set to the loopback address if
 227 <parameter>hostname</parameter>
 228 is a
 229 <type>NULL</type>
 230 pointer and
 231 <type>AI_PASSIVE</type>
 232 is not set in
 233 <constant>ai_flags</constant>.
 234 </para>
 235 <para>
 236 If
 237 <constant>ai_flags</constant>
 238 is set to
 239 <type>AI_NUMERICHOST</type>
 240 it indicates that
 241 <parameter>hostname</parameter>
 242 should be treated as a numeric string defining an IPv4 or IPv6 address
 243 and no name resolution should be attempted.
 244 </para>
 245 </listitem>
 246 </varlistentry>
 247 </variablelist>
 248 </para>
 249
 250 <para>
 251 All other elements of the <type>struct addrinfo</type> passed
 252 via <parameter>hints</parameter> must be zero.
 253 </para>
 254
 255 <para>
 256 A <parameter>hints</parameter> of <type>NULL</type> is treated as if
 257 the caller provided a <type>struct addrinfo</type> initialized to zero
 258 with <constant>ai_family</constant>set to
 259 <constant>PF_UNSPEC</constant>.
 260 </para>
 261
 262 <para>
 263 After a successful call to
 264 <function>lwres_getaddrinfo()</function>,
 265 <parameter>*res</parameter>
 266 is a pointer to a linked list of one or more
 267 <type>addrinfo</type>
 268 structures.
 269 Each
 270 <type>struct addrinfo</type>
 271 in this list cn be processed by following
 272 the
 273 <constant>ai_next</constant>
 274 pointer, until a
 275 <type>NULL</type>
 276 pointer is encountered.
 277 The three members
 278 <constant>ai_family</constant>,
 279 <constant>ai_socktype</constant>,
 280 and
 281 <constant>ai_protocol</constant>
 282 in each
 283 returned
 284 <type>addrinfo</type>
 285 structure contain the corresponding arguments for a call to
 286 <citerefentry>
 287 <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
 288 </citerefentry>.
 289 For each
 290 <type>addrinfo</type>
 291 structure in the list, the
 292 <constant>ai_addr</constant>
 293 member points to a filled-in socket address structure of length
 294 <constant>ai_addrlen</constant>.
 295 </para>
 296
 297 <para>
 298 All of the information returned by
 299 <function>lwres_getaddrinfo()</function>
 300 is dynamically allocated: the addrinfo structures, and the socket
 301 address structures and canonical host name strings pointed to by the
 302 <constant>addrinfo</constant>structures.
 303 Memory allocated for the dynamically allocated structures created by
 304 a successful call to
 305 <function>lwres_getaddrinfo()</function>
 306 is released by
 307 <function>lwres_freeaddrinfo()</function>.
 308 <parameter>ai</parameter>
 309 is a pointer to a
 310 <type>struct addrinfo</type>
 311 created by a call to
 312 <function>lwres_getaddrinfo()</function>.
 313 </para>
 314
 315 </refsect1>
 316
 317 <refsect1>
 318 <title>RETURN VALUES</title>
 319 <para>
 320 <function>lwres_getaddrinfo()</function>
 321 returns zero on success or one of the error codes listed in
 322 <citerefentry>
 323 <refentrytitle>gai_strerror</refentrytitle><manvolnum>3
 324 </manvolnum>
 325 </citerefentry>
 326 if an error occurs.
 327 If both
 328 <parameter>hostname</parameter>
 329 and
 330 <parameter>servname</parameter>
 331 are
 332 <type>NULL</type>
 333 <function>lwres_getaddrinfo()</function>
 334 returns
 335 <errorcode>EAI_NONAME</errorcode>.
 336
 337 </para>
 338 </refsect1>
 339 <refsect1>
 340 <title>SEE ALSO</title>
 341 <para>
 342 <citerefentry>
 343 <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
 344 </citerefentry>,
 345
 346 <citerefentry>
 347 <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
 348 </citerefentry>,
 349
 350 <citerefentry>
 351 <refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
 352 </citerefentry>,
 353
 354 <citerefentry>
 355 <refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
 356 </citerefentry>,
 357
 358 <citerefentry>
 359 <refentrytitle>RFC2133</refentrytitle>
 360 </citerefentry>,
 361
 362 <citerefentry>
 363 <refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
 364 </citerefentry>,
 365
 366 <citerefentry>
 367 <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
 368 </citerefentry>,
 369
 370 <citerefentry>
 371 <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
 372 </citerefentry>,
 373
 374 <citerefentry>
 375 <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
 376 </citerefentry>,
 377
 378 <citerefentry>
 379 <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
 380 </citerefentry>,
 381
 382 <citerefentry>
 383 <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
 384 </citerefentry>.
 385 </para>
 386
 387 </refsect1>
 388 </refentry>