contrib/bind9/lib/lwres/man/lwres_getaddrinfo.3

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