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

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