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