lib/libc/net/getaddrinfo.3

   1 .\"     $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $
   2 .\"     $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $
   3 .\"     $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.29 2005/01/23 16:02:48 gnn Exp $
   4 .\"     $DragonFly: src/lib/libc/net/getaddrinfo.3,v 1.4 2006/05/26 19:39:37 swildner Exp $
   5 .\"
   6 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   7 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
   8 .\"
   9 .\" Permission to use, copy, modify, and distribute this software for any
  10 .\" purpose with or without fee is hereby granted, provided that the above
  11 .\" copyright notice and this permission notice appear in all copies.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  14 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  15 .\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  16 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  17 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  18 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  19 .\" PERFORMANCE OF THIS SOFTWARE.
  20 .\"
  21 .Dd December 20, 2004
  22 .Dt GETADDRINFO 3
  23 .Os
  24 .Sh NAME
  25 .Nm getaddrinfo ,
  26 .Nm freeaddrinfo
  27 .Nd socket address structure to host and service name
  28 .Sh SYNOPSIS
  29 .In sys/types.h
  30 .In sys/socket.h
  31 .In netdb.h
  32 .Ft int
  33 .Fn getaddrinfo "const char *hostname" "const char *servname" \
  34     "const struct addrinfo *hints" "struct addrinfo **res"
  35 .Ft void
  36 .Fn freeaddrinfo "struct addrinfo *ai"
  37 .Sh DESCRIPTION
  38 The
  39 .Fn getaddrinfo
  40 function is used to get a list of
  41 .Tn IP
  42 addresses and port numbers for host
  43 .Fa hostname
  44 and service
  45 .Fa servname .
  46 It is a replacement for and provides more flexibility than the
  47 .Xr gethostbyname 3
  48 and
  49 .Xr getservbyname 3
  50 functions.
  51 .Pp
  52 The
  53 .Fa hostname
  54 and
  55 .Fa servname
  56 arguments are either pointers to NUL-terminated strings or the null pointer.
  57 An acceptable value for
  58 .Fa hostname
  59 is either a valid host name or a numeric host address string consisting
  60 of a dotted decimal IPv4 address or an IPv6 address.
  61 The
  62 .Fa servname
  63 is either a decimal port number or a service name listed in
  64 .Xr services 5 .
  65 At least one of
  66 .Fa hostname
  67 and
  68 .Fa servname
  69 must be non-null.
  70 .Pp
  71 .Fa hints
  72 is an optional pointer to a
  73 .Li struct addrinfo ,
  74 as defined by
  75 .In netdb.h :
  76 .Bd -literal
  77 struct addrinfo {
  78         int ai_flags;           /* input flags */
  79         int ai_family;          /* protocol family for socket */
  80         int ai_socktype;        /* socket type */
  81         int ai_protocol;        /* protocol for socket */
  82         socklen_t ai_addrlen;   /* length of socket-address */
  83         struct sockaddr *ai_addr; /* socket-address for socket */
  84         char *ai_canonname;     /* canonical name for service location */
  85         struct addrinfo *ai_next; /* pointer to next in list */
  86 };
  87 .Ed
  88 .Pp
  89 This structure can be used to provide hints concerning the type of socket
  90 that the caller supports or wishes to use.
  91 The caller can supply the following structure elements in
  92 .Fa hints :
  93 .Bl -tag -width "ai_socktypeXX"
  94 .It Fa ai_family
  95 The protocol family that should be used.
  96 When
  97 .Fa ai_family
  98 is set to
  99 .Dv PF_UNSPEC ,
 100 it means the caller will accept any protocol family supported by the
 101 operating system.
 102 .It Fa ai_socktype
 103 Denotes the type of socket that is wanted:
 104 .Dv SOCK_STREAM ,
 105 .Dv SOCK_DGRAM ,
 106 or
 107 .Dv SOCK_RAW .
 108 When
 109 .Fa ai_socktype
 110 is zero the caller will accept any socket type.
 111 .It Fa ai_protocol
 112 Indicates which transport protocol is desired,
 113 .Dv IPPROTO_UDP
 114 or
 115 .Dv IPPROTO_TCP .
 116 If
 117 .Fa ai_protocol
 118 is zero the caller will accept any protocol.
 119 .It Fa ai_flags
 120 .Fa ai_flags
 121 is formed by
 122 .Tn OR Ns 'ing
 123 the following values:
 124 .Bl -tag -width "AI_CANONNAMEXX"
 125 .It Dv AI_CANONNAME
 126 If the
 127 .Dv AI_CANONNAME
 128 bit is set, a successful call to
 129 .Fn getaddrinfo
 130 will return a NUL-terminated string containing the canonical name
 131 of the specified hostname in the
 132 .Fa ai_canonname
 133 element of the first
 134 .Li addrinfo
 135 structure returned.
 136 .It Dv AI_NUMERICHOST
 137 If the
 138 .Dv AI_NUMERICHOST
 139 bit is set, it indicates that
 140 .Fa hostname
 141 should be treated as a numeric string defining an IPv4 or IPv6 address
 142 and no name resolution should be attempted.
 143 .It Dv AI_PASSIVE
 144 If the
 145 .Dv AI_PASSIVE
 146 bit is set it indicates that the returned socket address structure
 147 is intended for use in a call to
 148 .Xr bind 2 .
 149 In this case, if the
 150 .Fa hostname
 151 argument is the null pointer, then the IP address portion of the
 152 socket address structure will be set to
 153 .Dv INADDR_ANY
 154 for an IPv4 address or
 155 .Dv IN6ADDR_ANY_INIT
 156 for an IPv6 address.
 157 .Pp
 158 If the
 159 .Dv AI_PASSIVE
 160 bit is not set, the returned socket address structure will be ready
 161 for use in a call to
 162 .Xr connect 2
 163 for a connection-oriented protocol or
 164 .Xr connect 2 ,
 165 .Xr sendto 2 ,
 166 or
 167 .Xr sendmsg 2
 168 if a connectionless protocol was chosen.
 169 The
 170 .Tn IP
 171 address portion of the socket address structure will be set to the
 172 loopback address if
 173 .Fa hostname
 174 is the null pointer and
 175 .Dv AI_PASSIVE
 176 is not set.
 177 .El
 178 .El
 179 .Pp
 180 All other elements of the
 181 .Li addrinfo
 182 structure passed via
 183 .Fa hints
 184 must be zero or the null pointer.
 185 .Pp
 186 If
 187 .Fa hints
 188 is the null pointer,
 189 .Fn getaddrinfo
 190 behaves as if the caller provided a
 191 .Li struct addrinfo
 192 with
 193 .Fa ai_family
 194 set to
 195 .Dv PF_UNSPEC
 196 and all other elements set to zero or
 197 .Dv NULL .
 198 .Pp
 199 After a successful call to
 200 .Fn getaddrinfo ,
 201 .Fa *res
 202 is a pointer to a linked list of one or more
 203 .Li addrinfo
 204 structures.
 205 The list can be traversed by following the
 206 .Fa ai_next
 207 pointer in each
 208 .Li addrinfo
 209 structure until a null pointer is encountered.
 210 The three members
 211 .Fa ai_family,
 212 .Fa ai_socktype,
 213 and
 214 .Fa ai_protocol
 215 in each returned
 216 .Li addrinfo
 217 structure are suitable for a call to
 218 .Xr socket 2 .
 219 For each
 220 .Li addrinfo
 221 structure in the list, the
 222 .Fa ai_addr
 223 member points to a filled-in socket address structure of length
 224 .Fa ai_addrlen .
 225 .Pp
 226 This implementation of
 227 .Fn getaddrinfo
 228 allows numeric IPv6 address notation with scope identifier,
 229 as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
 230 By appending the percent character and scope identifier to addresses,
 231 one can fill the
 232 .Li sin6_scope_id
 233 field for addresses.
 234 This would make management of scoped addresses easier
 235 and allows cut-and-paste input of scoped addresses.
 236 .Pp
 237 At this moment the code supports only link-local addresses with the format.
 238 The scope identifier is hardcoded to the name of the hardware interface
 239 associated
 240 with the link
 241 .Po
 242 such as
 243 .Li ne0
 244 .Pc .
 245 An example is
 246 .Dq Li fe80::1%ne0 ,
 247 which means
 248 .Do
 249 .Li fe80::1
 250 on the link associated with the
 251 .Li ne0
 252 interface
 253 .Dc .
 254 .Pp
 255 The current implementation assumes a one-to-one relationship between
 256 the interface and link, which is not necessarily true from the specification.
 257 .Pp
 258 All of the information returned by
 259 .Fn getaddrinfo
 260 is dynamically allocated: the
 261 .Li addrinfo
 262 structures themselves as well as the socket address structures and
 263 the canonical host name strings included in the
 264 .Li addrinfo
 265 structures.
 266 .Pp
 267 Memory allocated for the dynamically allocated structures created by
 268 a successful call to
 269 .Fn getaddrinfo
 270 is released by the
 271 .Fn freeaddrinfo
 272 function.
 273 The
 274 .Fa ai
 275 pointer should be a
 276 .Li addrinfo
 277 structure created by a call to
 278 .Fn getaddrinfo .
 279 .Sh RETURN VALUES
 280 .Fn getaddrinfo
 281 returns zero on success or one of the error codes listed in
 282 .Xr gai_strerror 3
 283 if an error occurs.
 284 .Sh EXAMPLES
 285 The following code tries to connect to
 286 .Dq Li www.kame.net
 287 service
 288 .Dq Li http
 289 via a stream socket.
 290 It loops through all the addresses available, regardless of address family.
 291 If the destination resolves to an IPv4 address, it will use an
 292 .Dv AF_INET
 293 socket.
 294 Similarly, if it resolves to IPv6, an
 295 .Dv AF_INET6
 296 socket is used.
 297 Observe that there is no hardcoded reference to a particular address family.
 298 The code works even if
 299 .Fn getaddrinfo
 300 returns addresses that are not IPv4/v6.
 301 .Bd -literal -offset indent
 302 struct addrinfo hints, *res, *res0;
 303 int error;
 304 int s;
 305 const char *cause = NULL;
 306
 307 memset(&hints, 0, sizeof(hints));
 308 hints.ai_family = PF_UNSPEC;
 309 hints.ai_socktype = SOCK_STREAM;
 310 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
 311 if (error) {
 312         errx(1, "%s", gai_strerror(error));
 313         /*NOTREACHED*/
 314 }
 315 s = -1;
 316 for (res = res0; res; res = res->ai_next) {
 317         s = socket(res->ai_family, res->ai_socktype,
 318             res->ai_protocol);
 319         if (s < 0) {
 320                 cause = "socket";
 321                 continue;
 322         }
 323
 324         if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
 325                 cause = "connect";
 326                 close(s);
 327                 s = -1;
 328                 continue;
 329         }
 330
 331         break;  /* okay we got one */
 332 }
 333 if (s < 0) {
 334         err(1, "%s", cause);
 335         /*NOTREACHED*/
 336 }
 337 freeaddrinfo(res0);
 338 .Ed
 339 .Pp
 340 The following example tries to open a wildcard listening socket onto service
 341 .Dq Li http ,
 342 for all the address families available.
 343 .Bd -literal -offset indent
 344 struct addrinfo hints, *res, *res0;
 345 int error;
 346 int s[MAXSOCK];
 347 int nsock;
 348 const char *cause = NULL;
 349
 350 memset(&hints, 0, sizeof(hints));
 351 hints.ai_family = PF_UNSPEC;
 352 hints.ai_socktype = SOCK_STREAM;
 353 hints.ai_flags = AI_PASSIVE;
 354 error = getaddrinfo(NULL, "http", &hints, &res0);
 355 if (error) {
 356         errx(1, "%s", gai_strerror(error));
 357         /*NOTREACHED*/
 358 }
 359 nsock = 0;
 360 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
 361         s[nsock] = socket(res->ai_family, res->ai_socktype,
 362             res->ai_protocol);
 363         if (s[nsock] < 0) {
 364                 cause = "socket";
 365                 continue;
 366         }
 367
 368         if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
 369                 cause = "bind";
 370                 close(s[nsock]);
 371                 continue;
 372         }
 373         (void) listen(s[nsock], 5);
 374
 375         nsock++;
 376 }
 377 if (nsock == 0) {
 378         err(1, "%s", cause);
 379         /*NOTREACHED*/
 380 }
 381 freeaddrinfo(res0);
 382 .Ed
 383 .Sh SEE ALSO
 384 .Xr bind 2 ,
 385 .Xr connect 2 ,
 386 .Xr send 2 ,
 387 .Xr socket 2 ,
 388 .Xr gai_strerror 3 ,
 389 .Xr gethostbyname 3 ,
 390 .Xr getnameinfo 3 ,
 391 .Xr getservbyname 3 ,
 392 .Xr resolver 3 ,
 393 .Xr hosts 5 ,
 394 .Xr resolv.conf 5 ,
 395 .Xr services 5 ,
 396 .Xr hostname 7 ,
 397 .Xr named 8
 398 .Rs
 399 .%A R. Gilligan
 400 .%A S. Thomson
 401 .%A J. Bound
 402 .%A J. McCann
 403 .%A W. Stevens
 404 .%T Basic Socket Interface Extensions for IPv6
 405 .%R RFC 3493
 406 .%D February 2003
 407 .Re
 408 .Rs
 409 .%A S. Deering
 410 .%A B. Haberman
 411 .%A T. Jinmei
 412 .%A E. Nordmark
 413 .%A B. Zill
 414 .%T "IPv6 Scoped Address Architecture"
 415 .%R internet draft
 416 .%N draft-ietf-ipv6-scoping-arch-02.txt
 417 .%O work in progress material
 418 .Re
 419 .Rs
 420 .%A Craig Metz
 421 .%T Protocol Independence Using the Sockets API
 422 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 423 .%D June 2000
 424 .Re
 425 .Sh STANDARDS
 426 The
 427 .Fn getaddrinfo
 428 function is defined by the
 429 .St -p1003.1g-2000
 430 draft specification and documented in
 431 .Dv "RFC 3493" ,
 432 .Dq Basic Socket Interface Extensions for IPv6 .
 433 .Sh BUGS
 434 The implementation of
 435 .Fn getaddrinfo
 436 is not thread-safe.