lib/libc/net/getaddrinfo.3

   1 .\"     $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.2.2.10 2002/04/28 05:40:24 suz Exp $
   2 .\"     $KAME: getaddrinfo.3,v 1.31 2001/08/05 18:19:38 itojun Exp $
   3 .\"
   4 .\" Copyright (c) 1983, 1987, 1991, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
  36 .\"
  37 .Dd May 25, 1995
  38 .Dt GETADDRINFO 3
  39 .Os
  40 .\"
  41 .Sh NAME
  42 .Nm getaddrinfo ,
  43 .Nm freeaddrinfo ,
  44 .Nm gai_strerror
  45 .Nd nodename-to-address translation in protocol-independent manner
  46 .\"
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In sys/types.h
  51 .In sys/socket.h
  52 .In netdb.h
  53 .Ft int
  54 .Fn getaddrinfo "const char *nodename" "const char *servname" \
  55 "const struct addrinfo *hints" "struct addrinfo **res"
  56 .Ft void
  57 .Fn freeaddrinfo "struct addrinfo *ai"
  58 .Ft "char *"
  59 .Fn gai_strerror "int ecode"
  60 .\"
  61 .Sh DESCRIPTION
  62 The
  63 .Fn getaddrinfo
  64 function is defined for protocol-independent nodename-to-address translation.
  65 It performs the functionality of
  66 .Xr gethostbyname 3
  67 and
  68 .Xr getservbyname 3 ,
  69 but in a more sophisticated manner.
  70 .Pp
  71 The
  72 .Li addrinfo
  73 structure is defined as a result of including the
  74 .Aq Pa netdb.h
  75 header:
  76 .Bd -literal -offset
  77 struct addrinfo {
  78      int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
  79      int     ai_family;    /* PF_xxx */
  80      int     ai_socktype;  /* SOCK_xxx */
  81      int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
  82      size_t  ai_addrlen;   /* length of ai_addr */
  83      char   *ai_canonname; /* canonical name for nodename */
  84      struct sockaddr  *ai_addr; /* binary address */
  85      struct addrinfo  *ai_next; /* next structure in linked list */
  86 };
  87 .Ed
  88 .Pp
  89 The
  90 .Fa nodename
  91 and
  92 .Fa servname
  93 arguments are pointers to null-terminated strings or
  94 .Dv NULL .
  95 One or both of these two arguments must be a
  96 .Pf non Dv -NULL
  97 pointer.
  98 In the normal client scenario, both the
  99 .Fa nodename
 100 and
 101 .Fa servname
 102 are specified.
 103 In the normal server scenario, only the
 104 .Fa servname
 105 is specified.
 106 A
 107 .Pf non Dv -NULL
 108 .Fa nodename
 109 string can be either a node name or a numeric host address string
 110 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
 111 A
 112 .Pf non Dv -NULL
 113 .Fa servname
 114 string can be either a service name or a decimal port number.
 115 .Pp
 116 The caller can optionally pass an
 117 .Li addrinfo
 118 structure, pointed to by the third argument,
 119 to provide hints concerning the type of socket that the caller supports.
 120 In this
 121 .Fa hints
 122 structure all members other than
 123 .Fa ai_flags ,
 124 .Fa ai_family ,
 125 .Fa ai_socktype ,
 126 and
 127 .Fa ai_protocol
 128 must be zero or a
 129 .Dv NULL
 130 pointer.
 131 A value of
 132 .Dv PF_UNSPEC
 133 for
 134 .Fa ai_family
 135 means the caller will accept any protocol family.
 136 A value of 0 for
 137 .Fa ai_socktype
 138 means the caller will accept any socket type.
 139 A value of 0 for
 140 .Fa ai_protocol
 141 means the caller will accept any protocol.
 142 For example, if the caller handles only TCP and not UDP, then the
 143 .Fa ai_socktype
 144 member of the hints structure should be set to
 145 .Dv SOCK_STREAM
 146 when
 147 .Fn getaddrinfo
 148 is called.
 149 If the caller handles only IPv4 and not IPv6, then the
 150 .Fa ai_family
 151 member of the
 152 .Fa hints
 153 structure should be set to
 154 .Dv PF_INET
 155 when
 156 .Fn getaddrinfo
 157 is called.
 158 If the third argument to
 159 .Fn getaddrinfo
 160 is a
 161 .Dv NULL
 162 pointer, this is the same as if the caller had filled in an
 163 .Li addrinfo
 164 structure initialized to zero with
 165 .Fa ai_family
 166 set to
 167 .Dv PF_UNSPEC .
 168 .Pp
 169 Upon successful return a pointer to a linked list of one or more
 170 .Li addrinfo
 171 structures is returned through the final argument.
 172 The caller can process each
 173 .Li addrinfo
 174 structure in this list by following the
 175 .Fa ai_next
 176 pointer, until a
 177 .Dv NULL
 178 pointer is encountered.
 179 In each returned
 180 .Li addrinfo
 181 structure the three members
 182 .Fa ai_family ,
 183 .Fa ai_socktype ,
 184 and
 185 .Fa ai_protocol
 186 are the corresponding arguments for a call to the
 187 .Fn socket
 188 function.
 189 In each
 190 .Li addrinfo
 191 structure the
 192 .Fa ai_addr
 193 member points to a filled-in socket address structure whose length is
 194 specified by the
 195 .Fa ai_addrlen
 196 member.
 197 .Pp
 198 If the
 199 .Dv AI_PASSIVE
 200 bit is set in the
 201 .Fa ai_flags
 202 member of the
 203 .Fa hints
 204 structure, then the caller plans to use the returned socket address
 205 structure in a call to
 206 .Fn bind .
 207 In this case, if the
 208 .Fa nodename
 209 argument is a
 210 .Dv NULL
 211 pointer, then the IP address portion of the socket
 212 address structure will be set to
 213 .Dv INADDR_ANY
 214 for an IPv4 address or
 215 .Dv IN6ADDR_ANY_INIT
 216 for an IPv6 address.
 217 .Pp
 218 If the
 219 .Dv AI_PASSIVE
 220 bit is not set in the
 221 .Fa ai_flags
 222 member of the
 223 .Fa hints
 224 structure, then the returned socket address structure will be ready for a
 225 call to
 226 .Fn connect
 227 (for a connection-oriented protocol)
 228 or either
 229 .Fn connect ,
 230 .Fn sendto ,
 231 or
 232 .Fn sendmsg
 233 (for a connectionless protocol).
 234 In this case, if the
 235 .Fa nodename
 236 argument is a
 237 .Dv NULL
 238 pointer, then the IP address portion of the
 239 socket address structure will be set to the loopback address.
 240 .Pp
 241 If the
 242 .Dv AI_CANONNAME
 243 bit is set in the
 244 .Fa ai_flags
 245 member of the
 246 .Fa hints
 247 structure, then upon successful return the
 248 .Fa ai_canonname
 249 member of the first
 250 .Li addrinfo
 251 structure in the linked list will point to a null-terminated string
 252 containing the canonical name of the specified
 253 .Fa nodename .
 254 .Pp
 255 If the
 256 .Dv AI_NUMERICHOST
 257 bit is set in the
 258 .Fa ai_flags
 259 member of the
 260 .Fa hints
 261 structure, then a
 262 .Pf non Dv -NULL
 263 .Fa nodename
 264 string must be a numeric host address string.
 265 Otherwise an error of
 266 .Dv EAI_NONAME
 267 is returned.
 268 This flag prevents any type of name resolution service (e.g., the DNS)
 269 from being called.
 270 .Pp
 271 The arguments to
 272 .Fn getaddrinfo
 273 must be sufficiently consistent and unambiguous.
 274 Here are some problem cases you may encounter:
 275 .Bl -bullet
 276 .It
 277 .Fn getaddrinfo
 278 will fail if the members in the
 279 .Fa hints
 280 structure are not consistent.
 281 For example, for internet address families,
 282 .Fn getaddrinfo
 283 will fail if you specify
 284 .Dv SOCK_STREAM
 285 to
 286 .Fa ai_socktype
 287 while you specify
 288 .Dv IPPROTO_UDP
 289 to
 290 .Fa ai_protocol .
 291 .It
 292 If you specify a
 293 .Fa servname
 294 which is defined only for certain
 295 .Fa ai_socktype ,
 296 .Fn getaddrinfo
 297 will fail because the arguments are not consistent.
 298 For example,
 299 .Fn getaddrinfo
 300 will return an error if you ask for
 301 .Dq Li tftp
 302 service on
 303 .Dv SOCK_STREAM .
 304 .It
 305 For internet address families, if you specify
 306 .Fa servname
 307 while you set
 308 .Fa ai_socktype
 309 to
 310 .Dv SOCK_RAW ,
 311 .Fn getaddrinfo
 312 will fail, because service names are not defined for the internet
 313 .Dv SOCK_RAW
 314 space.
 315 .It
 316 If you specify numeric
 317 .Fa servname ,
 318 while leaving
 319 .Fa ai_socktype
 320 and
 321 .Fa ai_protocol
 322 unspecified,
 323 .Fn getaddrinfo
 324 will fail.
 325 This is because the numeric
 326 .Fa servname
 327 does not identify any socket type, and
 328 .Fn getaddrinfo
 329 is not allowed to glob the argument in such case.
 330 .El
 331 .Pp
 332 All of the information returned by
 333 .Fn getaddrinfo
 334 is dynamically allocated:
 335 the
 336 .Li addrinfo
 337 structures, the socket address structures, and canonical node name
 338 strings pointed to by the addrinfo structures.
 339 To return this information to the system the function
 340 .Fn freeaddrinfo
 341 is called.
 342 The
 343 .Fa addrinfo
 344 structure pointed to by the
 345 .Fa ai argument
 346 is freed, along with any dynamic storage pointed to by the structure.
 347 This operation is repeated until a
 348 .Dv NULL
 349 .Fa ai_next
 350 pointer is encountered.
 351 .Pp
 352 To aid applications in printing error messages based on the
 353 .Dv EAI_xxx
 354 codes returned by
 355 .Fn getaddrinfo ,
 356 .Fn gai_strerror
 357 is defined.
 358 The argument is one of the
 359 .Dv EAI_xxx
 360 values defined earlier and the return value points to a string describing
 361 the error.
 362 If the argument is not one of the
 363 .Dv EAI_xxx
 364 values, the function still returns a pointer to a string whose contents
 365 indicate an unknown error.
 366 .\"
 367 .Sh EXTENSIONS
 368 This implementation supports numeric IPv6 address notation with the
 369 experimental scope identifier.
 370 By appending a percent sign and scope identifier to the address, you
 371 can specify the value of the
 372 .Li sin6_scope_id
 373 field of the socket address.
 374 This makes management of scoped address easier,
 375 and allows cut-and-paste input of scoped addresses.
 376 .Pp
 377 At the moment the code supports only link-local addresses in this format.
 378 The scope identifier is hardcoded to name of hardware interface associated
 379 with the link,
 380 (such as
 381 .Li ne0 ) .
 382 For example,
 383 .Dq Li fe80::1%ne0 ,
 384 which means
 385 .Do
 386 .Li fe80::1
 387 on the link associated with the
 388 .Li ne0
 389 interface
 390 .Dc .
 391 .Pp
 392 This implementation is still very experimental and non-standard.
 393 The current implementation assumes a one-to-one relationship between
 394 interfaces and links, which is not necessarily true according to the
 395 specification.
 396 .\"
 397 .Sh EXAMPLES
 398 The following code tries to connect to
 399 .Dq Li www.kame.net
 400 service
 401 .Dq Li http .
 402 via stream socket.
 403 It loops through all the addresses available, regardless of the address family.
 404 If the destination resolves to an IPv4 address, it will use an
 405 .Dv AF_INET
 406 socket.
 407 Similarly, if it resolves to IPv6, an
 408 .Dv AF_INET6
 409 socket is used.
 410 Observe that there is no hardcoded reference to particular address family.
 411 The code works even if
 412 .Fn getaddrinfo
 413 returns addresses that are not IPv4/v6.
 414 .Bd -literal -offset indent
 415 struct addrinfo hints, *res, *res0;
 416 int error;
 417 int s;
 418 const char *cause = NULL;
 419
 420 memset(&hints, 0, sizeof(hints));
 421 hints.ai_family = PF_UNSPEC;
 422 hints.ai_socktype = SOCK_STREAM;
 423 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
 424 if (error) {
 425         errx(1, "%s", gai_strerror(error));
 426         /*NOTREACHED*/
 427 }
 428 s = -1;
 429 cause = "no addresses";
 430 errno = EADDRNOTAVAIL;
 431 for (res = res0; res; res = res->ai_next) {
 432         s = socket(res->ai_family, res->ai_socktype,
 433             res->ai_protocol);
 434         if (s < 0) {
 435                 cause = "socket";
 436                 continue;
 437         }
 438
 439         if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
 440                 cause = "connect";
 441                 close(s);
 442                 s = -1;
 443                 continue;
 444         }
 445
 446         break;  /* okay we got one */
 447 }
 448 if (s < 0) {
 449         err(1, cause);
 450         /*NOTREACHED*/
 451 }
 452 freeaddrinfo(res0);
 453 .Ed
 454 .Pp
 455 The following example tries to open a wildcard listening socket onto service
 456 .Dq Li http ,
 457 for all the address families available.
 458 .Bd -literal -offset indent
 459 struct addrinfo hints, *res, *res0;
 460 int error;
 461 int s[MAXSOCK];
 462 int nsock;
 463 const char *cause = NULL;
 464
 465 memset(&hints, 0, sizeof(hints));
 466 hints.ai_family = PF_UNSPEC;
 467 hints.ai_socktype = SOCK_STREAM;
 468 hints.ai_flags = AI_PASSIVE;
 469 error = getaddrinfo(NULL, "http", &hints, &res0);
 470 if (error) {
 471         errx(1, "%s", gai_strerror(error));
 472         /*NOTREACHED*/
 473 }
 474 nsock = 0;
 475 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
 476         s[nsock] = socket(res->ai_family, res->ai_socktype,
 477             res->ai_protocol);
 478         if (s[nsock] < 0) {
 479                 cause = "socket";
 480                 continue;
 481         }
 482
 483         if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
 484                 cause = "bind";
 485                 close(s[nsock]);
 486                 continue;
 487         }
 488
 489         if (listen(s[nsock], SOMAXCONN) < 0) {
 490                 cause = "listen";
 491                 close(s[nsock]);
 492                 continue;
 493         }
 494
 495         nsock++;
 496 }
 497 if (nsock == 0) {
 498         err(1, cause);
 499         /*NOTREACHED*/
 500 }
 501 freeaddrinfo(res0);
 502 .Ed
 503 .\"
 504 .Sh FILES
 505 .Bl -tag -width /etc/resolv.conf -compact
 506 .It Pa /etc/hosts
 507 .It Pa /etc/host.conf
 508 .It Pa /etc/resolv.conf
 509 .El
 510 .\"
 511 .Sh DIAGNOSTICS
 512 Error return status from
 513 .Fn getaddrinfo
 514 is zero on success and non-zero on errors.
 515 Non-zero error codes are defined in
 516 .Aq Pa netdb.h ,
 517 and as follows:
 518 .Pp
 519 .Bl -tag -width EAI_ADDRFAMILY -compact
 520 .It Dv EAI_ADDRFAMILY
 521 Address family for
 522 .Fa nodename
 523 not supported.
 524 .It Dv EAI_AGAIN
 525 Temporary failure in name resolution.
 526 .It Dv EAI_BADFLAGS
 527 Invalid value for
 528 .Fa ai_flags .
 529 .It Dv EAI_FAIL
 530 Non-recoverable failure in name resolution.
 531 .It Dv EAI_FAMILY
 532 .Fa ai_family
 533 not supported.
 534 .It Dv EAI_MEMORY
 535 Memory allocation failure.
 536 .It Dv EAI_NODATA
 537 No address associated with
 538 .Fa nodename .
 539 .It Dv EAI_NONAME
 540 .Fa nodename
 541 nor
 542 .Fa servname
 543 provided, or not known.
 544 .It Dv EAI_SERVICE
 545 .Fa servname
 546 not supported for
 547 .Fa ai_socktype .
 548 .It Dv EAI_SOCKTYPE
 549 .Fa ai_socktype
 550 not supported.
 551 .It Dv EAI_SYSTEM
 552 System error returned in
 553 .Va errno .
 554 .El
 555 .Pp
 556 If called with an appropriate argument,
 557 .Fn gai_strerror
 558 returns a pointer to a string describing the given error code.
 559 If the argument is not one of the
 560 .Dv EAI_xxx
 561 values, the function still returns a pointer to a string whose contents
 562 indicate an unknown error.
 563 .\"
 564 .Sh SEE ALSO
 565 .Xr gethostbyname 3 ,
 566 .Xr getnameinfo 3 ,
 567 .Xr getservbyname 3 ,
 568 .Xr hosts 5 ,
 569 .Xr resolv.conf 5 ,
 570 .Xr services 5 ,
 571 .Xr hostname 7 ,
 572 .Xr named 8
 573 .Pp
 574 .Rs
 575 .%A R. Gilligan
 576 .%A S. Thomson
 577 .%A J. Bound
 578 .%A W. Stevens
 579 .%T Basic Socket Interface Extensions for IPv6
 580 .%R RFC2553
 581 .%D March 1999
 582 .Re
 583 .Rs
 584 .%A Tatsuya Jinmei
 585 .%A Atsushi Onoe
 586 .%T "An Extension of Format for IPv6 Scoped Addresses"
 587 .%R internet draft
 588 .%N draft-ietf-ipngwg-scopedaddr-format-02.txt
 589 .%O work in progress material
 590 .Re
 591 .Rs
 592 .%A Craig Metz
 593 .%T Protocol Independence Using the Sockets API
 594 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 595 .%D June 2000
 596 .Re
 597 .\"
 598 .Sh HISTORY
 599 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 600 .\"
 601 .Sh STANDARDS
 602 The
 603 .Fn getaddrinfo
 604 function is defined in
 605 .St -p1003.1g-2000 ,
 606 and documented in
 607 .Dq Basic Socket Interface Extensions for IPv6
 608 (RFC2553).
 609 .\"
 610 .Sh BUGS
 611 The current implementation is not thread-safe.
 612 .Pp
 613 The text was shamelessly copied from RFC2553.