doc/html/ref/net-common-tcpip-manpages-getaddrinfo.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >getaddrinfo</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="TCP/IP Library Reference"
  23 HREF="tcpip-library-reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="ethers"
  26 HREF="net-common-tcpip-manpages-ethers.html"><LINK
  27 REL="NEXT"
  28 TITLE="gethostbyname"
  29 HREF="net-common-tcpip-manpages-gethostbyname.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="net-common-tcpip-manpages-ethers.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 38. TCP/IP Library Reference</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="net-common-tcpip-manpages-gethostbyname.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="NET-COMMON-TCPIP-MANPAGES-GETADDRINFO">getaddrinfo</H1
  86 ><TABLE
  87 BORDER="5"
  88 BGCOLOR="#E0E0F0"
  89 WIDTH="70%"
  90 ><TR
  91 ><TD
  92 ><PRE
  93 CLASS="SCREEN"
  94 >GETADDRINFO(3)          System Library Functions Manual         GETADDRINFO(3)
  95
  96 NAME
  97      getaddrinfo, freeaddrinfo, gai_strerror - nodename-to-address translation
  98      in protocol-independent manner
  99
 100 SYNOPSIS
 101      #include &lt;sys/types.h&#62;
 102      #include &lt;sys/socket.h&#62;
 103      #include &lt;netdb.h&#62;
 104
 105      int
 106      getaddrinfo(const char *nodename, const char *servname,
 107              const struct addrinfo *hints, struct addrinfo **res);
 108
 109      void
 110      freeaddrinfo(struct addrinfo *ai);
 111
 112      char *
 113      gai_strerror(int ecode);
 114
 115 DESCRIPTION
 116      The getaddrinfo() function is defined for protocol-independent nodename-
 117      to-address translation.  It performs the functionality of
 118      gethostbyname(3) and getservbyname(3), but in a more sophisticated man-
 119      ner.
 120
 121      The addrinfo structure is defined as a result of including the &lt;netdb.h&#62;
 122      header:
 123
 124      struct addrinfo {                                                  *
 125           int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
 126           int     ai_family;    /* PF_xxx */
 127           int     ai_socktype;  /* SOCK_xxx */
 128           int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
 129           size_t  ai_addrlen;   /* length of ai_addr */
 130           char   *ai_canonname; /* canonical name for nodename */
 131           struct sockaddr  *ai_addr; /* binary address */
 132           struct addrinfo  *ai_next; /* next structure in linked list */
 133      };
 134
 135      The nodename and servname arguments are pointers to NUL-terminated
 136      strings or NULL.  One or both of these two arguments must be a non-null
 137      pointer.  In the normal client scenario, both the nodename and servname
 138      are specified.  In the normal server scenario, only the servname is spec-
 139      ified.  A non-null nodename string can be either a node name or a numeric
 140      host address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex
 141      address).  A non-null servname string can be either a service name or a
 142      decimal port number.
 143
 144      The caller can optionally pass an addrinfo structure, pointed to by the
 145      third argument, to provide hints concerning the type of socket that the
 146      caller supports.  In this hints structure all members other than
 147      ai_flags, ai_family, ai_socktype, and ai_protocol must be zero or a null
 148      pointer.  A value of PF_UNSPEC for ai_family means the caller will accept
 149      any protocol family.  A value of 0 for ai_socktype means the caller will
 150      accept any socket type.  A value of 0 for ai_protocol means the caller
 151      will accept any protocol.  For example, if the caller handles only TCP
 152      and not UDP, then the ai_socktype member of the hints structure should be
 153      set to SOCK_STREAM when getaddrinfo() is called.  If the caller handles
 154      only IPv4 and not IPv6, then the ai_family member of the hints structure
 155      should be set to PF_INET when getaddrinfo() is called.  If the third
 156      argument to getaddrinfo() is a null pointer, this is the same as if the
 157      caller had filled in an addrinfo structure initialized to zero with
 158      ai_family set to PF_UNSPEC.
 159
 160      Upon successful return a pointer to a linked list of one or more addrinfo
 161      structures is returned through the final argument.  The caller can pro-
 162      cess each addrinfo structure in this list by following the ai_next
 163      pointer, until a null pointer is encountered.  In each returned addrinfo
 164      structure the three members ai_family, ai_socktype, and ai_protocol are
 165      the corresponding arguments for a call to the socket() function.  In each
 166      addrinfo structure the ai_addr member points to a filled-in socket
 167      address structure whose length is specified by the ai_addrlen member.
 168
 169      If the AI_PASSIVE bit is set in the ai_flags member of the hints struc-
 170      ture, then the caller plans to use the returned socket address structure
 171      in a call to bind().  In this case, if the nodename argument is a null
 172      pointer, then the IP address portion of the socket address structure will
 173      be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
 174      address.
 175
 176      If the AI_PASSIVE bit is not set in the ai_flags member of the hints
 177      structure, then the returned socket address structure will be ready for a
 178      call to connect() (for a connection-oriented protocol) or either
 179      connect(), sendto(), or sendmsg() (for a connectionless protocol).  In
 180      this case, if the nodename argument is a null pointer, then the IP
 181      address portion of the socket address structure will be set to the loop-
 182      back address.
 183
 184      If the AI_CANONNAME bit is set in the ai_flags member of the hints struc-
 185      ture, then upon successful return the ai_canonname member of the first
 186      addrinfo structure in the linked list will point to a NUL-terminated
 187      string containing the canonical name of the specified nodename.
 188
 189      If the AI_NUMERICHOST bit is set in the ai_flags member of the hints
 190      structure, then a non-null nodename string must be a numeric host address
 191      string.  Otherwise an error of EAI_NONAME is returned.  This flag pre-
 192      vents any type of name resolution service (e.g., the DNS) from being
 193      called.
 194
 195      The arguments to getaddrinfo() must sufficiently be consistent and unam-
 196      biguous.  Here are pitfall cases you may encounter:
 197
 198      o   getaddrinfo() will raise an error if members of the hints structure
 199          are not consistent.  For example, for internet address families,
 200          getaddrinfo() will raise an error if you specify SOCK_STREAM to
 201          ai_socktype while you specify IPPROTO_UDP to ai_protocol.
 202
 203      o   If you specify a servname which is defined only for certain
 204          ai_socktype, getaddrinfo() will raise an error because the arguments
 205          are not consistent.  For example, getaddrinfo() will raise an error
 206          if you ask for ``tftp'' service on SOCK_STREAM.
 207
 208      o   For internet address families, if you specify servname while you set
 209          ai_socktype to SOCK_RAW, getaddrinfo() will raise an error, because
 210          service names are not defined for the internet SOCK_RAW space.
 211
 212      o   If you specify a numeric servname, while leaving ai_socktype and
 213          ai_protocol unspecified, getaddrinfo() will raise an error.  This is
 214          because the numeric servname does not identify any socket type, and
 215          getaddrinfo() is not allowed to glob the argument in such case.
 216
 217      All of the information returned by getaddrinfo() is dynamically allo-
 218      cated: the addrinfo structures, the socket address structures, and canon-
 219      ical node name strings pointed to by the addrinfo structures.  To return
 220      this information to the system the function freeaddrinfo() is called.
 221      The addrinfo structure pointed to by the ai argument is freed, along with
 222      any dynamic storage pointed to by the structure.  This operation is
 223      repeated until a NULL ai_next pointer is encountered.
 224
 225      To aid applications in printing error messages based on the EAI_xxx codes
 226      returned by getaddrinfo(), gai_strerror() is defined.  The argument is
 227      one of the EAI_xxx values defined earlier and the return value points to
 228      a string describing the error.  If the argument is not one of the EAI_xxx
 229      values, the function still returns a pointer to a string whose contents
 230      indicate an unknown error.
 231
 232    Extension for scoped IPv6 address
 233      The implementation allows experimental numeric IPv6 address notation with
 234      scope identifier.  By appending the percent character and scope identi-
 235      fier to addresses, you can fill sin6_scope_id field for addresses.  This
 236      would make management of scoped address easier, and allows cut-and-paste
 237      input of scoped address.
 238
 239      At this moment the code supports only link-local addresses with the for-
 240      mat.  Scope identifier is hardcoded to name of hardware interface associ-
 241      ated with the link.  (such as ne0).  Example would be like
 242      ``fe80::1%ne0'', which means ``fe80::1 on the link associated with ne0
 243      interface''.
 244
 245      The implementation is still very experimental and non-standard.  The cur-
 246      rent implementation assumes one-by-one relationship between interface and
 247      link, which is not necessarily true from the specification.
 248
 249 EXAMPLES
 250      The following code tries to connect to ``www.kame.net'' service ``http''.
 251      via stream socket.  It loops through all the addresses available, regard-
 252      less from address family.  If the destination resolves to IPv4 address,
 253      it will use AF_INET socket.  Similarly, if it resolves to IPv6, AF_INET6
 254      socket is used.  Observe that there is no hardcoded reference to particu-
 255      lar address family.  The code works even if getaddrinfo returns addresses
 256      that are not IPv4/v6.
 257
 258            struct addrinfo hints, *res, *res0;
 259            int error;
 260            int s;
 261            const char *cause = NULL;
 262
 263            memset(&amp;hints, 0, sizeof(hints));
 264            hints.ai_family = PF_UNSPEC;
 265            hints.ai_socktype = SOCK_STREAM;
 266            error = getaddrinfo("www.kame.net", "http", &amp;hints, &amp;res0);
 267            if (error) {
 268                    errx(1, "%s", gai_strerror(error));
 269                    /*NOTREACHED*/
 270            }
 271            s = -1;
 272            for (res = res0; res; res = res-&#62;ai_next) {
 273                    s = socket(res-&#62;ai_family, res-&#62;ai_socktype,
 274                        res-&#62;ai_protocol);
 275                    if (s &lt; 0) {
 276                            cause = "socket";
 277                            continue;
 278                    }
 279
 280                    if (connect(s, res-&#62;ai_addr, res-&#62;ai_addrlen) &lt; 0) {
 281                            cause = "connect";
 282                            close(s);
 283                            s = -1;
 284                            continue;
 285                    }
 286
 287                    break;  /* okay we got one */
 288            }
 289            if (s &lt; 0) {
 290                    err(1, cause);
 291                    /*NOTREACHED*/
 292            }
 293            freeaddrinfo(res0);
 294
 295      The following example tries to open a wildcard listening socket onto ser-
 296      vice ``http'', for all the address families available.
 297
 298            struct addrinfo hints, *res, *res0;
 299            int error;
 300            int s[MAXSOCK];
 301            int nsock;
 302            const char *cause = NULL;
 303
 304            memset(&amp;hints, 0, sizeof(hints));
 305            hints.ai_family = PF_UNSPEC;
 306            hints.ai_socktype = SOCK_STREAM;
 307            hints.ai_flags = AI_PASSIVE;
 308            error = getaddrinfo(NULL, "http", &amp;hints, &amp;res0);
 309            if (error) {
 310                    errx(1, "%s", gai_strerror(error));
 311                    /*NOTREACHED*/
 312            }
 313            nsock = 0;
 314            for (res = res0; res &amp;&amp; nsock &lt; MAXSOCK; res = res-&#62;ai_next) {
 315                    s[nsock] = socket(res-&#62;ai_family, res-&#62;ai_socktype,
 316                        res-&#62;ai_protocol);
 317                    if (s[nsock] &lt; 0) {
 318                            cause = "socket";
 319                            continue;
 320                    }
 321
 322                    if (bind(s[nsock], res-&#62;ai_addr, res-&#62;ai_addrlen) &lt; 0) {
 323                            cause = "bind";
 324                            close(s[nsock]);
 325                            continue;
 326                    }
 327                    (void) listen(s[nsock], 5);
 328
 329                    nsock++;
 330            }
 331            if (nsock == 0) {
 332                    err(1, cause);
 333                    /*NOTREACHED*/
 334            }
 335            freeaddrinfo(res0);
 336
 337 DIAGNOSTICS
 338      Error return status from getaddrinfo() is zero on success and non-zero on
 339      errors.  Non-zero error codes are defined in &lt;netdb.h&#62;, and as follows:
 340
 341      EAI_ADDRFAMILY  Address family for nodename not supported.
 342      EAI_AGAIN       Temporary failure in name resolution.
 343      EAI_BADFLAGS    Invalid value for ai_flags.
 344      EAI_FAIL        Non-recoverable failure in name resolution.
 345      EAI_FAMILY      ai_family not supported.
 346      EAI_MEMORY      Memory allocation failure.
 347      EAI_NODATA      No address associated with nodename.
 348      EAI_NONAME      nodename nor servname provided, or not known.
 349      EAI_SERVICE     servname not supported for ai_socktype.
 350      EAI_SOCKTYPE    ai_socktype not supported.
 351      EAI_SYSTEM      System error returned in errno.
 352
 353      If called with proper argument, gai_strerror() returns a pointer to a
 354      string describing the given error code.  If the argument is not one of
 355      the EAI_xxx values, the function still returns a pointer to a string
 356      whose contents indicate an unknown error.
 357
 358 SEE ALSO
 359      getnameinfo(3), gethostbyname(3), getservbyname(3), hosts(5),
 360      resolv.conf(5), services(5), hostname(7), named(8)
 361
 362      R. Gilligan, S. Thomson, J. Bound, and W. Stevens, Basic Socket Interface
 363      Extensions for IPv6, RFC2553, March 1999.
 364
 365      Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
 366      Addresses, internet draft, draft-ietf-ipngwg-scopedaddr-format-02.txt,
 367      work in progress material.
 368
 369      Craig Metz, "Protocol Independence Using the Sockets API", Proceedings of
 370      the freenix track: 2000 USENIX annual technical conference, June 2000.
 371
 372 HISTORY
 373      The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
 374      kit.
 375
 376 STANDARDS
 377      The getaddrinfo() function is defined in IEEE POSIX 1003.1g draft speci-
 378      fication, and documented in ``Basic Socket Interface Extensions for
 379      IPv6'' (RFC2553).
 380
 381 BUGS
 382      The current implementation is not thread-safe.
 383
 384      The text was shamelessly copied from RFC2553.
 385
 386 BSD                              May 25, 1995                              BSD
 387     </PRE
 388 ></TD
 389 ></TR
 390 ></TABLE
 391 ></DIV
 392 ><DIV
 393 CLASS="NAVFOOTER"
 394 ><HR
 395 ALIGN="LEFT"
 396 WIDTH="100%"><TABLE
 397 SUMMARY="Footer navigation table"
 398 WIDTH="100%"
 399 BORDER="0"
 400 CELLPADDING="0"
 401 CELLSPACING="0"
 402 ><TR
 403 ><TD
 404 WIDTH="33%"
 405 ALIGN="left"
 406 VALIGN="top"
 407 ><A
 408 HREF="net-common-tcpip-manpages-ethers.html"
 409 ACCESSKEY="P"
 410 >Prev</A
 411 ></TD
 412 ><TD
 413 WIDTH="34%"
 414 ALIGN="center"
 415 VALIGN="top"
 416 ><A
 417 HREF="ecos-ref.html"
 418 ACCESSKEY="H"
 419 >Home</A
 420 ></TD
 421 ><TD
 422 WIDTH="33%"
 423 ALIGN="right"
 424 VALIGN="top"
 425 ><A
 426 HREF="net-common-tcpip-manpages-gethostbyname.html"
 427 ACCESSKEY="N"
 428 >Next</A
 429 ></TD
 430 ></TR
 431 ><TR
 432 ><TD
 433 WIDTH="33%"
 434 ALIGN="left"
 435 VALIGN="top"
 436 >ethers</TD
 437 ><TD
 438 WIDTH="34%"
 439 ALIGN="center"
 440 VALIGN="top"
 441 ><A
 442 HREF="tcpip-library-reference.html"
 443 ACCESSKEY="U"
 444 >Up</A
 445 ></TD
 446 ><TD
 447 WIDTH="33%"
 448 ALIGN="right"
 449 VALIGN="top"
 450 >gethostbyname</TD
 451 ></TR
 452 ></TABLE
 453 ></DIV
 454 ></BODY
 455 ></HTML
 456 >