contrib/bind-9.3/lib/lwres/man/lwres_getaddrinfo.3

   1 .\" Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
   2 .\" Copyright (C) 2000, 2001, 2003 Internet Software Consortium.
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
   9 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  10 .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  11 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  12 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  13 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  14 .\" PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .\" $Id: lwres_getaddrinfo.3,v 1.16.2.1.8.6 2005/10/13 02:33:53 marka Exp $
  17 .\"
  18 .hy 0
  19 .ad l
  20 .\" ** You probably do not want to edit this file directly **
  21 .\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
  22 .\" Instead of manually editing it, you probably should edit the DocBook XML
  23 .\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
  24 .TH "LWRES_GETADDRINFO" "3" "Jun 30, 2000" "BIND9" "BIND9"
  25 .\" disable hyphenation
  26 .nh
  27 .\" disable justification (adjust text to left margin only)
  28 .ad l
  29 .SH "NAME"
  30 lwres_getaddrinfo, lwres_freeaddrinfo \- socket address structure to host and service name
  31 .SH "SYNOPSIS"
  32 .nf
  33 #include <lwres/netdb.h>
  34 .fi
  35 .HP 22
  36 \fBint\ \fBlwres_getaddrinfo\fR\fR\fB(\fR\fBconst\ char\ *hostname\fR\fB, \fR\fBconst\ char\ *servname\fR\fB, \fR\fBconst\ struct\ addrinfo\ *hints\fR\fB, \fR\fBstruct\ addrinfo\ **res\fR\fB);\fR
  37 .HP 24
  38 \fBvoid\ \fBlwres_freeaddrinfo\fR\fR\fB(\fR\fBstruct\ addrinfo\ *ai\fR\fB);\fR
  39 .PP
  40 If the operating system does not provide a
  41 \fBstruct addrinfo\fR, the following structure is used:
  42 .sp
  43 .nf
  44 struct  addrinfo {
  45         int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
  46         int             ai_family;      /* PF_xxx */
  47         int             ai_socktype;    /* SOCK_xxx */
  48         int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
  49         size_t          ai_addrlen;     /* length of ai_addr */
  50         char            *ai_canonname;  /* canonical name for hostname */
  51         struct sockaddr *ai_addr;       /* binary address */
  52         struct addrinfo *ai_next;       /* next structure in linked list */
  53 };
  54 .fi
  55 .sp
  56 .SH "DESCRIPTION"
  57 .PP
  58 \fBlwres_getaddrinfo()\fR
  59 is used to get a list of IP addresses and port numbers for host
  60 \fIhostname\fR
  61 and service
  62 \fIservname\fR. The function is the lightweight resolver's implementation of
  63 \fBgetaddrinfo()\fR
  64 as defined in RFC2133.
  65 \fIhostname\fR
  66 and
  67 \fIservname\fR
  68 are pointers to null\-terminated strings or
  69 \fBNULL\fR.
  70 \fIhostname\fR
  71 is either a host name or a numeric host address string: a dotted decimal IPv4 address or an IPv6 address.
  72 \fIservname\fR
  73 is either a decimal port number or a service name as listed in
  74 \fI/etc/services\fR.
  75 .PP
  76 \fIhints\fR
  77 is an optional pointer to a
  78 \fBstruct addrinfo\fR. This structure can be used to provide hints concerning the type of socket that the caller supports or wishes to use. The caller can supply the following structure elements in
  79 \fI*hints\fR:
  80 .TP
  81 \fBai_family\fR
  82 The protocol family that should be used. When
  83 \fBai_family\fR
  84 is set to
  85 \fBPF_UNSPEC\fR, it means the caller will accept any protocol family supported by the operating system.
  86 .TP
  87 \fBai_socktype\fR
  88 denotes the type of socket \(em
  89 \fBSOCK_STREAM\fR,
  90 \fBSOCK_DGRAM\fR
  91 or
  92 \fBSOCK_RAW\fR
  93 \(em that is wanted. When
  94 \fBai_socktype\fR
  95 is zero the caller will accept any socket type.
  96 .TP
  97 \fBai_protocol\fR
  98 indicates which transport protocol is wanted: IPPROTO_UDP or IPPROTO_TCP. If
  99 \fBai_protocol\fR
 100 is zero the caller will accept any protocol.
 101 .TP
 102 \fBai_flags\fR
 103 Flag bits. If the
 104 \fBAI_CANONNAME\fR
 105 bit is set, a successful call to
 106 \fBlwres_getaddrinfo()\fR
 107 will return a null\-terminated string containing the canonical name of the specified hostname in
 108 \fBai_canonname\fR
 109 of the first
 110 \fBaddrinfo\fR
 111 structure returned. Setting the
 112 \fBAI_PASSIVE\fR
 113 bit indicates that the returned socket address structure is intended for used in a call to
 114 \fBbind\fR(2). In this case, if the hostname argument is a
 115 \fBNULL\fR
 116 pointer, then the IP address portion of the socket address structure will be set to
 117 \fBINADDR_ANY\fR
 118 for an IPv4 address or
 119 \fBIN6ADDR_ANY_INIT\fR
 120 for an IPv6 address.
 121 .sp
 122 When
 123 \fBai_flags\fR
 124 does not set the
 125 \fBAI_PASSIVE\fR
 126 bit, the returned socket address structure will be ready for use in a call to
 127 \fBconnect\fR(2 )
 128 for a connection\-oriented protocol or
 129 \fBconnect\fR(2),
 130 \fBsendto\fR(2), or
 131 \fBsendmsg\fR(2 )
 132 if a connectionless protocol was chosen. The IP address portion of the socket address structure will be set to the loopback address if
 133 \fIhostname\fR
 134 is a
 135 \fBNULL\fR
 136 pointer and
 137 \fBAI_PASSIVE\fR
 138 is not set in
 139 \fBai_flags\fR.
 140 .sp
 141 If
 142 \fBai_flags\fR
 143 is set to
 144 \fBAI_NUMERICHOST\fR
 145 it indicates that
 146 \fIhostname\fR
 147 should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted.
 148 .PP
 149 All other elements of the
 150 \fBstruct addrinfo\fR
 151 passed via
 152 \fIhints\fR
 153 must be zero.
 154 .PP
 155 A
 156 \fIhints\fR
 157 of
 158 \fBNULL\fR
 159 is treated as if the caller provided a
 160 \fBstruct addrinfo\fR
 161 initialized to zero with
 162 \fBai_family\fRset to
 163 \fBPF_UNSPEC\fR.
 164 .PP
 165 After a successful call to
 166 \fBlwres_getaddrinfo()\fR,
 167 \fI*res\fR
 168 is a pointer to a linked list of one or more
 169 \fBaddrinfo\fR
 170 structures. Each
 171 \fBstruct addrinfo\fR
 172 in this list cn be processed by following the
 173 \fBai_next\fR
 174 pointer, until a
 175 \fBNULL\fR
 176 pointer is encountered. The three members
 177 \fBai_family\fR,
 178 \fBai_socktype\fR, and
 179 \fBai_protocol\fR
 180 in each returned
 181 \fBaddrinfo\fR
 182 structure contain the corresponding arguments for a call to
 183 \fBsocket\fR(2). For each
 184 \fBaddrinfo\fR
 185 structure in the list, the
 186 \fBai_addr\fR
 187 member points to a filled\-in socket address structure of length
 188 \fBai_addrlen\fR.
 189 .PP
 190 All of the information returned by
 191 \fBlwres_getaddrinfo()\fR
 192 is dynamically allocated: the addrinfo structures, and the socket address structures and canonical host name strings pointed to by the
 193 \fBaddrinfo\fRstructures. Memory allocated for the dynamically allocated structures created by a successful call to
 194 \fBlwres_getaddrinfo()\fR
 195 is released by
 196 \fBlwres_freeaddrinfo()\fR.
 197 \fIai\fR
 198 is a pointer to a
 199 \fBstruct addrinfo\fR
 200 created by a call to
 201 \fBlwres_getaddrinfo()\fR.
 202 .SH "RETURN VALUES"
 203 .PP
 204 \fBlwres_getaddrinfo()\fR
 205 returns zero on success or one of the error codes listed in
 206 \fBgai_strerror\fR(3 )
 207 if an error occurs. If both
 208 \fIhostname\fR
 209 and
 210 \fIservname\fR
 211 are
 212 \fBNULL\fR\fBlwres_getaddrinfo()\fR
 213 returns
 214 \fBEAI_NONAME\fR.
 215 .SH "SEE ALSO"
 216 .PP
 217 \fBlwres\fR(3),
 218 \fBlwres_getaddrinfo\fR(3),
 219 \fBlwres_freeaddrinfo\fR(3),
 220 \fBlwres_gai_strerror\fR(3),
 221 \fBRFC2133\fR(),
 222 \fBgetservbyname\fR(3),
 223 \fBbind\fR(2),
 224 \fBconnect\fR(2),
 225 \fBsendto\fR(2),
 226 \fBsendmsg\fR(2),
 227 \fBsocket\fR(2).