lookup.subproj/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 .\"
   4 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   5 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
   6 .\"
   7 .\" Permission to use, copy, modify, and distribute this software for any
   8 .\" purpose with or without fee is hereby granted, provided that the above
   9 .\" copyright notice and this permission notice appear in all copies.
  10 .\"
  11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  12 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  13 .\" AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  14 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  15 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  16 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17 .\" PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .\" $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.34 2008/07/01 22:59:20 danger Exp $
  20 .\"
  21 .Dd July 1, 2008
  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 .Fd #include <sys/types.h>
  30 .Fd #include <sys/socket.h>
  31 .Fd #include <netdb.h>
  32 .Ft int
  33 .Fo getaddrinfo
  34 .Fa "const char *hostname" "const char *servname"
  35 .Fa "const struct addrinfo *hints" "struct addrinfo **res"
  36 .Fc
  37 .Ft void
  38 .Fn freeaddrinfo "struct addrinfo *ai"
  39 .Sh DESCRIPTION
  40 The
  41 .Fn getaddrinfo
  42 function is used to get a list of
  43 .Tn IP
  44 addresses and port numbers for host
  45 .Fa hostname
  46 and service
  47 .Fa servname .
  48 It is a replacement for and provides more flexibility than the
  49 .Xr gethostbyname 3
  50 and
  51 .Xr getservbyname 3
  52 functions.
  53 .Pp
  54 The
  55 .Fa hostname
  56 and
  57 .Fa servname
  58 arguments are either pointers to NUL-terminated strings or the null pointer.
  59 An acceptable value for
  60 .Fa hostname
  61 is either a valid host name or a numeric host address string consisting
  62 of a dotted decimal IPv4 address or an IPv6 address.
  63 The
  64 .Fa servname
  65 is either a decimal port number or a service name listed in
  66 .Xr services 5 .
  67 At least one of
  68 .Fa hostname
  69 and
  70 .Fa servname
  71 must be non-null.
  72 .Pp
  73 .Fa hints
  74 is an optional pointer to a
  75 .Li struct addrinfo ,
  76 as defined by
  77 .Aq Pa netdb.h :
  78 .Bd -literal
  79 struct addrinfo {
  80         int ai_flags;           /* input flags */
  81         int ai_family;          /* protocol family for socket */
  82         int ai_socktype;        /* socket type */
  83         int ai_protocol;        /* protocol for socket */
  84         socklen_t ai_addrlen;   /* length of socket-address */
  85         struct sockaddr *ai_addr; /* socket-address for socket */
  86         char *ai_canonname;     /* canonical name for service location */
  87         struct addrinfo *ai_next; /* pointer to next in list */
  88 };
  89 .Ed
  90 .Pp
  91 This structure can be used to provide hints concerning the type of socket
  92 that the caller supports or wishes to use.
  93 The caller can supply the following structure elements in
  94 .Fa hints :
  95 .Bl -tag -width "ai_socktypeXX"
  96 .It Fa ai_family
  97 The protocol family that should be used.
  98 When
  99 .Fa ai_family
 100 is set to
 101 .Dv PF_UNSPEC ,
 102 it means the caller will accept any protocol family supported by the
 103 operating system.
 104 .It Fa ai_socktype
 105 Denotes the type of socket that is wanted:
 106 .Dv SOCK_STREAM ,
 107 .Dv SOCK_DGRAM ,
 108 or
 109 .Dv SOCK_RAW .
 110 When
 111 .Fa ai_socktype
 112 is zero the caller will accept any socket type.
 113 .It Fa ai_protocol
 114 Indicates which transport protocol is desired,
 115 .Dv IPPROTO_UDP
 116 or
 117 .Dv IPPROTO_TCP .
 118 If
 119 .Fa ai_protocol
 120 is zero the caller will accept any protocol.
 121 .It Fa ai_flags
 122 The
 123 .Fa ai_flags
 124 field to which the
 125 .Fa hints
 126 parameter points shall be set to zero
 127 or be the bitwise-inclusive OR of one or more of the values
 128 .Dv AI_ADDRCONFIG ,
 129 .Dv AI_ALL ,
 130 .Dv AI_CANONNAME ,
 131 .Dv AI_NUMERICHOST ,
 132 .Dv AI_NUMERICSERV ,
 133 .Dv AI_PASSIVE ,
 134 .Dv AI_V4MAPPED ,
 135 .Dv AI_V4MAPPED_CFG ,
 136 and
 137 .Dv AI_DEFAULT .
 138 .Bl -tag -width "AI_CANONNAMEXX"
 139 .It Dv AI_ADDRCONFIG
 140 If the
 141 .Dv AI_ADDRCONFIG
 142 bit is set, IPv4 addresses shall be returned only if
 143 an IPv4 address is configured on the local system,
 144 and IPv6 addresses shall be returned only if
 145 an IPv6 address is configured on the local system.
 146 .It Dv AI_ALL
 147 If the
 148 .Dv AI_ALL
 149 bit is set with the
 150 .Dv AI_V4MAPPED
 151 bit, then
 152 .Fn getaddrinfo
 153 shall return all matching IPv6 and IPv4 addresses.
 154 The
 155 .Dv AI_ALL
 156 bit without the
 157 .Dv AI_V4MAPPED
 158 bit is ignored.
 159 .It Dv AI_CANONNAME
 160 If the
 161 .Dv AI_CANONNAME
 162 bit is set, a successful call to
 163 .Fn getaddrinfo
 164 will return a NUL-terminated string containing the canonical name
 165 of the specified hostname in the
 166 .Fa ai_canonname
 167 element of the first
 168 .Li addrinfo
 169 structure returned.
 170 .It Dv AI_NUMERICHOST
 171 If the
 172 .Dv AI_NUMERICHOST
 173 bit is set, it indicates that
 174 .Fa hostname
 175 should be treated as a numeric string defining an IPv4 or IPv6 address
 176 and no name resolution should be attempted.
 177 .It Dv AI_NUMERICSERV
 178 If the
 179 .Dv AI_NUMERICSERV
 180 bit is set,
 181 then a non-null
 182 .Fa servname
 183 string supplied shall be a numeric port string.
 184 Otherwise, an
 185 .Dv EAI_NONAME
 186 error shall be returned.
 187 This bit shall prevent any type of name resolution service
 188 (for example, NIS+) from being invoked.
 189 .It Dv AI_PASSIVE
 190 If the
 191 .Dv AI_PASSIVE
 192 bit is set it indicates that the returned socket address structure
 193 is intended for use in a call to
 194 .Xr bind 2 .
 195 In this case, if the
 196 .Fa hostname
 197 argument is the null pointer, then the IP address portion of the
 198 socket address structure will be set to
 199 .Dv INADDR_ANY
 200 for an IPv4 address or
 201 .Dv IN6ADDR_ANY_INIT
 202 for an IPv6 address.
 203 .Pp
 204 If the
 205 .Dv AI_PASSIVE
 206 bit is not set, the returned socket address structure will be ready
 207 for use in a call to
 208 .Xr connect 2
 209 for a connection-oriented protocol or
 210 .Xr connect 2 ,
 211 .Xr sendto 2 ,
 212 or
 213 .Xr sendmsg 2
 214 if a connectionless protocol was chosen.
 215 The
 216 .Tn IP
 217 address portion of the socket address structure will be set to the
 218 loopback address if
 219 .Fa hostname
 220 is the null pointer and
 221 .Dv AI_PASSIVE
 222 is not set.
 223 .It Dv AI_V4MAPPED
 224 If the
 225 .Dv AI_V4MAPPED
 226 flag is specified along with an
 227 .Fa ai_family
 228 of
 229 .Dv PF_INET6 ,
 230 then
 231 .Fn getaddrinfo
 232 shall return IPv4-mapped IPv6 addresses
 233 on finding no matching IPv6 addresses (
 234 .Fa ai_addrlen
 235 shall be 16).
 236 The
 237 .Dv AI_V4MAPPED
 238 flag shall be ignored unless
 239 .Fa ai_family
 240 equals
 241 .Dv PF_INET6 .
 242 .It Dv AI_V4MAPPED_CFG
 243 The
 244 .Dv AI_V4MAPPED_CFG
 245 flag behaves exactly like the
 246 .Dv AI_V4MAPPED
 247 flag if the kernel supports IPv4-mapped IPv6 addresses. Otherwise it is ignored.
 248 .It Dv AI_DEFAULT
 249 .Dv AI_DEFAULT
 250 is defined as (
 251 .Dv AI_V4MAPPED_CFG
 252 |
 253 .Dv AI_ADDRCONFIG
 254 ).
 255 .It Dv AI_UNUSABLE
 256 To override the automatic
 257 .Dv AI_DEFAULT
 258 behavior that occurs when
 259 .Fa ai_flags
 260 is zero pass
 261 .Dv AI_UNUSABLE
 262 instead of zero.
 263 This suppresses the implicit setting of
 264 .Dv AI_V4MAPPED_CFG
 265 and
 266 .Dv AI_ADDRCONFIG ,
 267 thereby causing unusable addresses to be included in the results.
 268 .El
 269 .El
 270 .Pp
 271 If
 272 .Fa ai_flags
 273 is zero,
 274 .Fn getaddrinfo
 275 gives the
 276 .Dv AI_DEFAULT
 277 behavior (
 278 .Dv AI_V4MAPPED_CFG
 279 |
 280 .Dv AI_ADDRCONFIG
 281 ). To override this default behavior, pass any nonzero value for
 282 .Fa ai_flags ,
 283 by setting any desired flag values, or setting
 284 .Dv AI_UNUSABLE
 285 if no other flags are desired.
 286 .Pp
 287 All other elements of the
 288 .Li addrinfo
 289 structure passed via
 290 .Fa hints
 291 must be zero or the null pointer.
 292 .Pp
 293 If
 294 .Fa hints
 295 is the null pointer,
 296 .Fn getaddrinfo
 297 behaves as if the caller provided a
 298 .Li struct addrinfo
 299 with
 300 .Fa ai_family
 301 set to
 302 .Dv PF_UNSPEC
 303 and all other elements set to zero or
 304 .Dv NULL
 305 (which includes treating the
 306 .Fa ai_flags
 307 field as effectively zero, giving the automatic default
 308 .Dv AI_DEFAULT
 309 behavior).
 310 .Pp
 311 After a successful call to
 312 .Fn getaddrinfo ,
 313 .Fa *res
 314 is a pointer to a linked list of one or more
 315 .Li addrinfo
 316 structures.
 317 The list can be traversed by following the
 318 .Fa ai_next
 319 pointer in each
 320 .Li addrinfo
 321 structure until a null pointer is encountered.
 322 The three members
 323 .Fa ai_family,
 324 .Fa ai_socktype,
 325 and
 326 .Fa ai_protocol
 327 in each returned
 328 .Li addrinfo
 329 structure are suitable for a call to
 330 .Xr socket 2 .
 331 For each
 332 .Li addrinfo
 333 structure in the list, the
 334 .Fa ai_addr
 335 member points to a filled-in socket address structure of length
 336 .Fa ai_addrlen .
 337 .Pp
 338 This implementation of
 339 .Fn getaddrinfo
 340 allows numeric IPv6 address notation with scope identifier,
 341 as documented in section 11 of RFC 4007.
 342 By appending the percent character and scope identifier to addresses,
 343 one can fill the
 344 .Li sin6_scope_id
 345 field for addresses.
 346 This would make management of scoped addresses easier
 347 and allows cut-and-paste input of scoped addresses.
 348 .Pp
 349 At this moment the code supports only link-local addresses with the format.
 350 The scope identifier is hardcoded to the name of the hardware interface
 351 associated
 352 with the link
 353 .Po
 354 such as
 355 .Li ne0
 356 .Pc .
 357 An example is
 358 .Dq Li fe80::1%ne0 ,
 359 which means
 360 .Do
 361 .Li fe80::1
 362 on the link associated with the
 363 .Li ne0
 364 interface
 365 .Dc .
 366 .Pp
 367 The current implementation assumes a one-to-one relationship between
 368 the interface and link, which is not necessarily true from the specification.
 369 .Pp
 370 All of the information returned by
 371 .Fn getaddrinfo
 372 is dynamically allocated: the
 373 .Li addrinfo
 374 structures themselves as well as the socket address structures and
 375 the canonical host name strings included in the
 376 .Li addrinfo
 377 structures.
 378 .Pp
 379 Memory allocated for the dynamically allocated structures created by
 380 a successful call to
 381 .Fn getaddrinfo
 382 is released by the
 383 .Fn freeaddrinfo
 384 function.
 385 The
 386 .Fa ai
 387 pointer should be an
 388 .Li addrinfo
 389 structure created by a call to
 390 .Fn getaddrinfo .
 391 .Pp
 392 The current implementation supports synthesis of NAT64 mapped IPv6 addresses.
 393 If
 394 .Fa hostname
 395 is a numeric string defining an IPv4 address (for example,
 396 .Dq Li 192.0.2.1
 397 ) and
 398 .Fa ai_family
 399 is set to
 400 .Dv PF_UNSPEC
 401 or
 402 .Dv PF_INET6,
 403 .Fn getaddrinfo
 404 will synthesize the appropriate IPv6 address(es) (for example,
 405 .Dq Li 64:ff9b::192.0.2.1
 406 ) if the current interface supports IPv6, NAT64 and DNS64
 407 and does not support IPv4. If the
 408 .Dv AI_ADDRCONFIG
 409 flag is set, the IPv4 address will be suppressed on those interfaces.
 410 On non-qualifying interfaces,
 411 .Fn getaddrinfo
 412 is guaranteed to return immediately without attempting any resolution, and will
 413 return the IPv4 address if
 414 .Fa ai_family
 415 is
 416 .Dv PF_UNSPEC
 417 or
 418 .Dv PF_INET.
 419 NAT64 address synthesis can be disabled by setting the
 420 .Dv AI_NUMERICHOST
 421 flag. To best support NAT64 networks, it is recommended to resolve all
 422 IP address literals with
 423 .Fa ai_family
 424 set to
 425 .Dv PF_UNSPEC
 426 and
 427 .Fa ai_flags
 428 set to
 429 .Dv AI_DEFAULT.
 430 .Pp
 431 Note that NAT64 address synthesis is always disabled for IPv4 addresses
 432 in the following ranges:
 433 0.0.0.0/8,
 434 127.0.0.0/8,
 435 169.254.0.0/16,
 436 192.0.0.0/29,
 437 192.88.99.0/24,
 438 224.0.0.0/4, and
 439 255.255.255.255/32.
 440 Additionally, NAT64 address synthesis is disabled when the network uses
 441 the well-known prefix (64:ff9b::/96)
 442 for IPv4 addresses in the following ranges:
 443 10.0.0.0/8,
 444 100.64.0.0/10,
 445 172.16.0.0/12, and
 446 192.168.0.0/16.
 447 .Pp
 448 Historically, passing a host's own hostname to
 449 .Fn getaddrinfo
 450 has been a popular
 451 technique for determining that host's IP address(es), but this is fragile,
 452 and doesn't work reliably in all cases. The appropriate way for software to
 453 discover the IP address(es) of the host it is running on is to use
 454 .Xr getifaddrs 3 .
 455 .Pp
 456 The
 457 .Fn getaddrinfo
 458 implementations on all versions of OS X and iOS are now, and always have been,
 459 thread-safe. Previous versions of this man page incorrectly reported that
 460 .Fn getaddrinfo
 461 was not thread-safe.
 462 .Sh RETURN VALUES
 463 .Fn getaddrinfo
 464 returns zero on success or one of the error codes listed in
 465 .Xr gai_strerror 3
 466 if an error occurs.
 467 .Sh EXAMPLES
 468 The following code tries to connect to
 469 .Dq Li www.kame.net
 470 service
 471 .Dq Li http
 472 via a stream socket.
 473 It loops through all the addresses available, regardless of address family.
 474 If the destination resolves to an IPv4 address, it will use an
 475 .Dv PF_INET
 476 socket.
 477 Similarly, if it resolves to IPv6, an
 478 .Dv PF_INET6
 479 socket is used.
 480 Observe that there is no hardcoded reference to a particular address family.
 481 The code works even if
 482 .Fn getaddrinfo
 483 returns addresses that are not IPv4/v6.
 484 .Bd -literal -offset indent
 485 struct addrinfo hints, *res, *res0;
 486 int error;
 487 int s;
 488 const char *cause = NULL;
 489
 490 memset(&hints, 0, sizeof(hints));
 491 hints.ai_family = PF_UNSPEC;
 492 hints.ai_socktype = SOCK_STREAM;
 493 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
 494 if (error) {
 495         errx(1, "%s", gai_strerror(error));
 496         /*NOTREACHED*/
 497 }
 498 s = -1;
 499 for (res = res0; res; res = res->ai_next) {
 500         s = socket(res->ai_family, res->ai_socktype,
 501             res->ai_protocol);
 502         if (s < 0) {
 503                 cause = "socket";
 504                 continue;
 505         }
 506
 507         if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
 508                 cause = "connect";
 509                 close(s);
 510                 s = -1;
 511                 continue;
 512         }
 513
 514         break;  /* okay we got one */
 515 }
 516 if (s < 0) {
 517         err(1, "%s", cause);
 518         /*NOTREACHED*/
 519 }
 520 freeaddrinfo(res0);
 521 .Ed
 522 .Pp
 523 The following example tries to open a wildcard listening socket onto service
 524 .Dq Li http ,
 525 for all the address families available.
 526 .Bd -literal -offset indent
 527 struct addrinfo hints, *res, *res0;
 528 int error;
 529 int s[MAXSOCK];
 530 int nsock;
 531 const char *cause = NULL;
 532
 533 memset(&hints, 0, sizeof(hints));
 534 hints.ai_family = PF_UNSPEC;
 535 hints.ai_socktype = SOCK_STREAM;
 536 hints.ai_flags = AI_PASSIVE;
 537 error = getaddrinfo(NULL, "http", &hints, &res0);
 538 if (error) {
 539         errx(1, "%s", gai_strerror(error));
 540         /*NOTREACHED*/
 541 }
 542 nsock = 0;
 543 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
 544         s[nsock] = socket(res->ai_family, res->ai_socktype,
 545             res->ai_protocol);
 546         if (s[nsock] < 0) {
 547                 cause = "socket";
 548                 continue;
 549         }
 550
 551         if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
 552                 cause = "bind";
 553                 close(s[nsock]);
 554                 continue;
 555         }
 556         (void) listen(s[nsock], 5);
 557
 558         nsock++;
 559 }
 560 if (nsock == 0) {
 561         err(1, "%s", cause);
 562         /*NOTREACHED*/
 563 }
 564 freeaddrinfo(res0);
 565 .Ed
 566 .Sh SEE ALSO
 567 .Xr bind 2 ,
 568 .Xr connect 2 ,
 569 .Xr send 2 ,
 570 .Xr socket 2 ,
 571 .Xr gai_strerror 3 ,
 572 .Xr gethostbyname 3 ,
 573 .Xr getnameinfo 3 ,
 574 .Xr getservbyname 3 ,
 575 .Xr resolver 3 ,
 576 .Xr hosts 5 ,
 577 .Xr resolv.conf 5 ,
 578 .Xr services 5 ,
 579 .Xr hostname 7 ,
 580 .Xr named 8
 581 .Rs
 582 .%A R. Gilligan
 583 .%A S. Thomson
 584 .%A J. Bound
 585 .%A J. McCann
 586 .%A W. Stevens
 587 .%T Basic Socket Interface Extensions for IPv6
 588 .%R RFC 3493
 589 .%D February 2003
 590 .Re
 591 .Rs
 592 .%A S. Deering
 593 .%A B. Haberman
 594 .%A T. Jinmei
 595 .%A E. Nordmark
 596 .%A B. Zill
 597 .%T "IPv6 Scoped Address Architecture"
 598 .%R RFC 4007
 599 .%D March 2005
 600 .Re
 601 .Rs
 602 .%A Craig Metz
 603 .%T Protocol Independence Using the Sockets API
 604 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 605 .%D June 2000
 606 .Re
 607 .\".Sh BUGS
 608 .\"The
 609 .\".Nm
 610 .\"function as implemented in
 611 .\".Fx
 612 .\"currently does not support
 613 .\".Dv AI_ALL
 614 .\"and
 615 .\".Dv AI_V4MAPPED
 616 .\"flags and returns
 617 .\".Dv EAI_BADFLAGS
 618 .\"if one of them is specified.
 619 .Sh STANDARDS
 620 The
 621 .Fn getaddrinfo
 622 function is defined by the
 623 .St -p1003.1-2004
 624 specification and documented in
 625 .Dv "RFC 3493" ,
 626 .Dq Basic Socket Interface Extensions for IPv6 .