external/bsd/libbind/dist/doc/getaddrinfo.cat3

   1 GETADDRINFO(3)           BSD Library Functions Manual           GETADDRINFO(3)
   2
   3 N\bNA\bAM\bME\bE
   4      g\bge\bet\bta\bad\bdd\bdr\bri\bin\bnf\bfo\bo f\bfr\bre\bee\bea\bad\bdd\bdr\bri\bin\bnf\bfo\bo, g\bga\bai\bi_\b_s\bst\btr\bre\ber\brr\bro\bor\br - nodename-to-address translation
   5      in protocol-independent manner
   6
   7 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
   8      #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<s\bsy\bys\bs/\b/s\bso\boc\bck\bke\bet\bt.\b.h\bh>\b>
   9      #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<n\bne\bet\btd\bdb\bb.\b.h\bh>\b>
  10
  11      _\bi_\bn_\bt
  12      g\bge\bet\bta\bad\bdd\bdr\bri\bin\bnf\bfo\bo(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\bo_\bd_\be_\bn_\ba_\bm_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bs_\be_\br_\bv_\bn_\ba_\bm_\be,
  13              _\bc_\bo_\bn_\bs_\bt _\bs_\bt_\br_\bu_\bc_\bt _\ba_\bd_\bd_\br_\bi_\bn_\bf_\bo _\b*_\bh_\bi_\bn_\bt_\bs, _\bs_\bt_\br_\bu_\bc_\bt _\ba_\bd_\bd_\br_\bi_\bn_\bf_\bo _\b*_\b*_\br_\be_\bs);
  14
  15      _\bv_\bo_\bi_\bd
  16      f\bfr\bre\bee\bea\bad\bdd\bdr\bri\bin\bnf\bfo\bo(_\bs_\bt_\br_\bu_\bc_\bt _\ba_\bd_\bd_\br_\bi_\bn_\bf_\bo _\b*_\ba_\bi);
  17
  18      _\bc_\bh_\ba_\br _\b*
  19      g\bga\bai\bi_\b_s\bst\btr\bre\ber\brr\bro\bor\br(_\bi_\bn_\bt _\be_\bc_\bo_\bd_\be);
  20
  21 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  22      The g\bge\bet\bta\bad\bdd\bdr\bri\bin\bnf\bfo\bo() function is defined for protocol-independent nodename-
  23      to-address translation.  It performs functionality of gethostbyname(3)
  24      and getservbyname(3), in more sophisticated manner.
  25
  26      The addrinfo structure is defined as a result of including the <netdb.h>
  27      header:
  28
  29      struct addrinfo {                                                  *
  30           int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
  31           int     ai_family;    /* PF_xxx */
  32           int     ai_socktype;  /* SOCK_xxx */
  33           int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
  34           size_t  ai_addrlen;   /* length of ai_addr */
  35           char   *ai_canonname; /* canonical name for nodename */
  36           struct sockaddr  *ai_addr; /* binary address */
  37           struct addrinfo  *ai_next; /* next structure in linked list */
  38      };
  39
  40      The _\bn_\bo_\bd_\be_\bn_\ba_\bm_\be and _\bs_\be_\br_\bv_\bn_\ba_\bm_\be arguments are pointers to null-terminated
  41      strings or NULL.  One or both of these two arguments must be a non-NULL
  42      pointer.  In the normal client scenario, both the _\bn_\bo_\bd_\be_\bn_\ba_\bm_\be and _\bs_\be_\br_\bv_\bn_\ba_\bm_\be
  43      are specified.  In the normal server scenario, only the _\bs_\be_\br_\bv_\bn_\ba_\bm_\be is spec‐
  44      ified.  A non-NULL _\bn_\bo_\bd_\be_\bn_\ba_\bm_\be string can be either a node name or a numeric
  45      host address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex
  46      address).  A non-NULL _\bs_\be_\br_\bv_\bn_\ba_\bm_\be string can be either a service name or a
  47      decimal port number.
  48
  49      The caller can optionally pass an addrinfo structure, pointed to by the
  50      third argument, to provide hints concerning the type of socket that the
  51      caller supports.  In this _\bh_\bi_\bn_\bt_\bs structure all members other than
  52      _\ba_\bi_\b__\bf_\bl_\ba_\bg_\bs, _\ba_\bi_\b__\bf_\ba_\bm_\bi_\bl_\by, _\ba_\bi_\b__\bs_\bo_\bc_\bk_\bt_\by_\bp_\be, and _\ba_\bi_\b__\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl must be zero or a NULL
  53      pointer.  A value of PF_UNSPEC for _\ba_\bi_\b__\bf_\ba_\bm_\bi_\bl_\by means the caller will accept
  54      any protocol family.  A value of 0 for _\ba_\bi_\b__\bs_\bo_\bc_\bk_\bt_\by_\bp_\be means the caller will
  55      accept any socket type.  A value of 0 for _\ba_\bi_\b__\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl means the caller
  56      will accept any protocol.  For example, if the caller handles only TCP
  57      and not UDP, then the _\ba_\bi_\b__\bs_\bo_\bc_\bk_\bt_\by_\bp_\be member of the hints structure should be
  58      set to SOCK_STREAM when g\bge\bet\bta\bad\bdd\bdr\bri\bin\bnf\bfo\bo() is called.  If the caller handles
  59      only IPv4 and not IPv6, then the _\ba_\bi_\b__\bf_\ba_\bm_\bi_\bl_\by member of the _\bh_\bi_\bn_\bt_\bs structure
  60      should be set to PF_INET when g\bge\bet\bta\bad\bdd\bdr\bri\bin\bnf\bfo\bo() is called.  If the third
  61      argument to g\bge\bet\bta\bad\bdd\bdr\bri\bin\bnf\bfo\bo() is a NULL pointer, this is the same as if the
  62      caller had filled in an addrinfo structure initialized to zero with
  63      _\ba_\bi_\b__\bf_\ba_\bm_\bi_\bl_\by set to PF_UNSPEC.
  64
  65      Upon successful return a pointer to a linked list of one or more addrinfo
  66      structures is returned through the final argument.  The caller can pro‐
  67      cess each addrinfo structure in this list by following the _\ba_\bi_\b__\bn_\be_\bx_\bt
  68      pointer, until a NULL pointer is encountered.  In each returned addrinfo
  69      structure the three members _\ba_\bi_\b__\bf_\ba_\bm_\bi_\bl_\by, _\ba_\bi_\b__\bs_\bo_\bc_\bk_\bt_\by_\bp_\be, and _\ba_\bi_\b__\bp_\br_\bo_\bt_\bo_\bc_\bo_\bl are
  70      the corresponding arguments for a call to the s\bso\boc\bck\bke\bet\bt() function.  In each
  71      addrinfo structure the _\ba_\bi_\b__\ba_\bd_\bd_\br member points to a filled-in socket
  72      address structure whose length is specified by the _\ba_\bi_\b__\ba_\bd_\bd_\br_\bl_\be_\bn member.
  73
  74      If the AI_PASSIVE bit is set in the _\ba_\bi_\b__\bf_\bl_\ba_\bg_\bs member of the _\bh_\bi_\bn_\bt_\bs struc‐
  75      ture, then the caller plans to use the returned socket address structure
  76      in a call to b\bbi\bin\bnd\bd().  In this case, if the _\bn_\bo_\bd_\be_\bn_\ba_\bm_\be argument is a NULL
  77      pointer, then the IP address portion of the socket address structure will
  78      be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6
  79      address.
  80
  81      If the AI_PASSIVE bit is not set in the _\ba_\bi_\b__\bf_\bl_\ba_\bg_\bs member of the _\bh_\bi_\bn_\bt_\bs
  82      structure, then the returned socket address structure will be ready for a
  83      call to c\bco\bon\bnn\bne\bec\bct\bt() (for a connection-oriented protocol) or either
  84      c\bco\bon\bnn\bne\bec\bct\bt(), s\bse\ben\bnd\bdt\bto\bo(), or s\bse\ben\bnd\bdm\bms\bsg\bg() (for a connectionless protocol).  In
  85      this case, if the _\bn_\bo_\bd_\be_\bn_\ba_\bm_\be argument is a NULL pointer, then the IP
  86      address portion of the socket address structure will be set to the loop‐
  87      back address.
  88
  89      If the AI_CANONNAME bit is set in the _\ba_\bi_\b__\bf_\bl_\ba_\bg_\bs member of the _\bh_\bi_\bn_\bt_\bs struc‐
  90      ture, then upon successful return the _\ba_\bi_\b__\bc_\ba_\bn_\bo_\bn_\bn_\ba_\bm_\be member of the first
  91      addrinfo structure in the linked list will point to a null-terminated
  92      string containing the canonical name of the specified _\bn_\bo_\bd_\be_\bn_\ba_\bm_\be.
  93
  94      If the AI_NUMERICHOST bit is set in the _\ba_\bi_\b__\bf_\bl_\ba_\bg_\bs member of the _\bh_\bi_\bn_\bt_\bs
  95      structure, then a non-NULL _\bn_\bo_\bd_\be_\bn_\ba_\bm_\be string must be a numeric host address
  96      string.  Otherwise an error of EAI_NONAME is returned.  This flag pre‐
  97      vents any type of name resolution service (e.g., the DNS) from being
  98      called.
  99
 100      All of the information returned by g\bge\bet\bta\bad\bdd\bdr\bri\bin\bnf\bfo\bo() is dynamically allo‐
 101      cated: the addrinfo structures, and the socket address structures and
 102      canonical node name strings pointed to by the addrinfo structures.  To
 103      return this information to the system the function Fn freeaddrinfo is
 104      called.  The _\ba_\bd_\bd_\br_\bi_\bn_\bf_\bo structure pointed to by the _\ba_\bi _\ba_\br_\bg_\bu_\bm_\be_\bn_\bt is freed,
 105      along with any dynamic storage pointed to by the structure.  This opera‐
 106      tion is repeated until a NULL _\ba_\bi_\b__\bn_\be_\bx_\bt pointer is encountered.
 107
 108      To aid applications in printing error messages based on the EAI_xxx codes
 109      returned by g\bge\bet\bta\bad\bdd\bdr\bri\bin\bnf\bfo\bo(), g\bga\bai\bi_\b_s\bst\btr\bre\ber\brr\bro\bor\br() is defined.  The argument is
 110      one of the EAI_xxx values defined earlier and the return value points to
 111      a string describing the error.  If the argument is not one of the EAI_xxx
 112      values, the function still returns a pointer to a string whose contents
 113      indicate an unknown error.
 114
 115 F\bFI\bIL\bLE\bES\bS
 116      /etc/hosts
 117      /etc/host.conf
 118      /etc/resolv.conf
 119
 120 D\bDI\bIA\bAG\bGN\bNO\bOS\bST\bTI\bIC\bCS\bS
 121      Error return status from g\bge\bet\bta\bad\bdd\bdr\bri\bin\bnf\bfo\bo() is zero on success and non-zero on
 122      errors.  Non-zero error codes are defined in <netdb.h>, and as follows:
 123
 124      EAI_ADDRFAMILY  address family for nodename not supported
 125      EAI_AGAIN       temporary failure in name resolution
 126      EAI_BADFLAGS    invalid value for ai_flags
 127      EAI_FAIL        non-recoverable failure in name resolution
 128      EAI_FAMILY      ai_family not supported
 129      EAI_MEMORY      memory allocation failure
 130      EAI_NODATA      no address associated with nodename
 131      EAI_NONAME      nodename nor servname provided, or not known
 132      EAI_SERVICE     servname not supported for ai_socktype
 133      EAI_SOCKTYPE    ai_socktype not supported
 134      EAI_SYSTEM      system error returned in errno
 135
 136      If called with proper argument, g\bga\bai\bi_\b_s\bst\btr\bre\ber\brr\bro\bor\br() returns a pointer to a
 137      string describing the given error code.  If the argument is not one of
 138      the EAI_xxx values, the function still returns a pointer to a string
 139      whose contents indicate an unknown error.
 140
 141 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
 142      getnameinfo(3), gethostbyname(3), getservbyname(3), hosts(5),
 143      services(5), hostname(7)
 144
 145      R. Gilligan, S.  Thomson, J. Bound, and W. Stevens, ‘‘Basic Socket Inter‐
 146      face Extensions for IPv6,’’ RFC2133, April 1997.
 147
 148 H\bHI\bIS\bST\bTO\bOR\bRY\bY
 149      The implementation first appeared in WIDE Hydrangea IPv6 protocol stack
 150      kit.
 151
 152 S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS
 153      The g\bge\bet\bta\bad\bdd\bdr\bri\bin\bnf\bfo\bo() function is defined IEEE POSIX 1003.1g draft specifica‐
 154      tion, and documented in ‘‘Basic Socket Interface Extensions for IPv6’’
 155      (RFC2133).
 156
 157 B\bBU\bUG\bGS\bS
 158      The text was shamelessly copied from RFC2133.
 159
 160 KAME                             May 25, 1995                             KAME