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

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