contrib/bind-9.2.4rc7/lib/lwres/man/lwres_getaddrinfo.3

   1 .\" Copyright (C) 2004  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.3 2004/03/15 04:45:02 marka Exp $
  17 .\"
  18 .TH "LWRES_GETADDRINFO" "3" "Jun 30, 2000" "BIND9" ""
  19 .SH NAME
  20 lwres_getaddrinfo, lwres_freeaddrinfo \- socket address structure to host and service name
  21 .SH SYNOPSIS
  22 \fB#include <lwres/netdb.h>
  23 .sp
  24 .na
  25 int
  26 lwres_getaddrinfo(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res);
  27 .ad
  28 .sp
  29 .na
  30 void
  31 lwres_freeaddrinfo(struct addrinfo *ai);
  32 .ad
  33 \fR
  34 .PP
  35 If the operating system does not provide a
  36 \fBstruct addrinfo\fR,
  37 the following structure is used:
  38 .sp
  39 .nf
  40 struct  addrinfo {
  41         int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
  42         int             ai_family;      /* PF_xxx */
  43         int             ai_socktype;    /* SOCK_xxx */
  44         int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
  45         size_t          ai_addrlen;     /* length of ai_addr */
  46         char            *ai_canonname;  /* canonical name for hostname */
  47         struct sockaddr *ai_addr;       /* binary address */
  48         struct addrinfo *ai_next;       /* next structure in linked list */
  49 };
  50 .sp
  51 .fi
  52 .SH "DESCRIPTION"
  53 .PP
  54 \fBlwres_getaddrinfo()\fR
  55 is used to get a list of IP addresses and port numbers for host
  56 \fIhostname\fR
  57 and service
  58 \fIservname\fR.
  59 The function is the lightweight resolver's implementation of
  60 \fBgetaddrinfo()\fR
  61 as defined in RFC2133.
  62 \fIhostname\fR
  63 and
  64 \fIservname\fR
  65 are pointers to null-terminated
  66 strings or
  67 \fBNULL\fR.
  68 \fIhostname\fR
  69 is either a host name or a numeric host address string: a dotted decimal
  70 IPv4 address or an IPv6 address.
  71 \fIservname\fR
  72 is either a decimal port number or a service name as listed in
  73 \fI/etc/services\fR.
  74 .PP
  75 \fIhints\fR
  76 is an optional pointer to a
  77 \fBstruct addrinfo\fR.
  78 This structure can be used to provide hints concerning the type of socket
  79 that the caller supports or wishes to use.
  80 The caller can supply the following structure elements in
  81 \fI*hints\fR:
  82 .TP
  83 \fBai_family\fR
  84 The protocol family that should be used.
  85 When
  86 ai_family
  87 is set to
  88 \fBPF_UNSPEC\fR,
  89 it means the caller will accept any protocol family supported by the
  90 operating system.
  91 .TP
  92 \fBai_socktype\fR
  93 denotes the type of socket \(em
  94 \fBSOCK_STREAM\fR,
  95 \fBSOCK_DGRAM\fR
  96 or
  97 \fBSOCK_RAW\fR
  98 \(em that is wanted.
  99 When
 100 ai_socktype
 101 is zero the caller will accept any socket type.
 102 .TP
 103 \fBai_protocol\fR
 104 indicates which transport protocol is wanted: IPPROTO_UDP or
 105 IPPROTO_TCP.
 106 If
 107 ai_protocol
 108 is zero the caller will accept any protocol.
 109 .TP
 110 \fBai_flags\fR
 111 Flag bits.
 112 If the
 113 \fBAI_CANONNAME\fR
 114 bit is set, a successful call to
 115 \fBlwres_getaddrinfo()\fR
 116 will return a null-terminated string containing the canonical name
 117 of the specified hostname in
 118 ai_canonname
 119 of the first
 120 \fBaddrinfo\fR
 121 structure returned.
 122 Setting the
 123 \fBAI_PASSIVE\fR
 124 bit indicates that the returned socket address structure is intended
 125 for used in a call to
 126 \fBbind\fR(2).
 127 In this case, if the hostname argument is a
 128 \fBNULL\fR
 129 pointer, then the IP address portion of the socket
 130 address structure will be set to
 131 \fBINADDR_ANY\fR
 132 for an IPv4 address or
 133 \fBIN6ADDR_ANY_INIT\fR
 134 for an IPv6 address.
 135
 136 When
 137 ai_flags
 138 does not set the
 139 \fBAI_PASSIVE\fR
 140 bit, the returned socket address structure will be ready
 141 for use in a call to
 142 \fBconnect\fR(2)
 143 for a connection-oriented protocol or
 144 \fBconnect\fR(2),
 145 \fBsendto\fR(2),
 146 or
 147 \fBsendmsg\fR(2)
 148 if a connectionless protocol was chosen.
 149 The IP address portion of the socket address structure will be
 150 set to the loopback address if
 151 \fIhostname\fR
 152 is a
 153 \fBNULL\fR
 154 pointer and
 155 \fBAI_PASSIVE\fR
 156 is not set in
 157 ai_flags.
 158
 159 If
 160 ai_flags
 161 is set to
 162 \fBAI_NUMERICHOST\fR
 163 it indicates that
 164 \fIhostname\fR
 165 should be treated as a numeric string defining an IPv4 or IPv6 address
 166 and no name resolution should be attempted.
 167 .PP
 168 All other elements of the \fBstruct addrinfo\fR passed
 169 via \fIhints\fR must be zero.
 170 .PP
 171 A \fIhints\fR of \fBNULL\fR is treated as if
 172 the caller provided a \fBstruct addrinfo\fR initialized to zero
 173 with ai_familyset to
 174 PF_UNSPEC.
 175 .PP
 176 After a successful call to
 177 \fBlwres_getaddrinfo()\fR,
 178 \fI*res\fR
 179 is a pointer to a linked list of one or more
 180 \fBaddrinfo\fR
 181 structures.
 182 Each
 183 \fBstruct addrinfo\fR
 184 in this list cn be processed by following
 185 the
 186 ai_next
 187 pointer, until a
 188 \fBNULL\fR
 189 pointer is encountered.
 190 The three members
 191 ai_family,
 192 ai_socktype,
 193 and
 194 ai_protocol
 195 in each
 196 returned
 197 \fBaddrinfo\fR
 198 structure contain the corresponding arguments for a call to
 199 \fBsocket\fR(2).
 200 For each
 201 \fBaddrinfo\fR
 202 structure in the list, the
 203 ai_addr
 204 member points to a filled-in socket address structure of length
 205 ai_addrlen.
 206 .PP
 207 All of the information returned by
 208 \fBlwres_getaddrinfo()\fR
 209 is dynamically allocated: the addrinfo structures, and the socket
 210 address structures and canonical host name strings pointed to by the
 211 addrinfostructures.
 212 Memory allocated for the dynamically allocated structures created by
 213 a successful call to
 214 \fBlwres_getaddrinfo()\fR
 215 is released by
 216 \fBlwres_freeaddrinfo()\fR.
 217 \fIai\fR
 218 is a pointer to a
 219 \fBstruct addrinfo\fR
 220 created by a call to
 221 \fBlwres_getaddrinfo()\fR.
 222 .SH "RETURN VALUES"
 223 .PP
 224 \fBlwres_getaddrinfo()\fR
 225 returns zero on success or one of the error codes listed in
 226 \fBgai_strerror\fR(3)
 227 if an error occurs.
 228 If both
 229 \fIhostname\fR
 230 and
 231 \fIservname\fR
 232 are
 233 \fBNULL\fR
 234 \fBlwres_getaddrinfo()\fR
 235 returns
 236 EAI_NONAME.
 237 .SH "SEE ALSO"
 238 .PP
 239 \fBlwres\fR(3),
 240 \fBlwres_getaddrinfo\fR(3),
 241 \fBlwres_freeaddrinfo\fR(3),
 242 \fBlwres_gai_strerror\fR(3),
 243 \fBRFC2133\fR,
 244 \fBgetservbyname\fR(3),
 245 \fBbind\fR(2),
 246 \fBconnect\fR(2),
 247 \fBsendto\fR(2),
 248 \fBsendmsg\fR(2),
 249 \fBsocket\fR(2).