packages/net/common/v2_0/doc/manpages/net/getaddrinfo.3

   1 .\"     $OpenBSD: getaddrinfo.3,v 1.19 2001/08/06 10:42:26 mpech Exp $
   2 .\"     $KAME: getaddrinfo.3,v 1.29 2001/02/12 09:24:45 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 SYNOPSIS
  48 .Fd #include <sys/types.h>
  49 .Fd #include <sys/socket.h>
  50 .Fd #include <netdb.h>
  51 .Ft int
  52 .Fn getaddrinfo "const char *nodename" "const char *servname" \
  53 "const struct addrinfo *hints" "struct addrinfo **res"
  54 .Ft void
  55 .Fn freeaddrinfo "struct addrinfo *ai"
  56 .Ft "char *"
  57 .Fn gai_strerror "int ecode"
  58 .\"
  59 .Sh DESCRIPTION
  60 The
  61 .Fn getaddrinfo
  62 function is defined for protocol-independent nodename-to-address translation.
  63 It performs the functionality of
  64 .Xr gethostbyname 3
  65 and
  66 .Xr getservbyname 3 ,
  67 but in a more sophisticated manner.
  68 .Pp
  69 The
  70 .Li addrinfo
  71 structure is defined as a result of including the
  72 .Aq Pa netdb.h
  73 header:
  74 .Bd -literal -offset
  75 struct addrinfo {                                                  *
  76      int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
  77      int     ai_family;    /* PF_xxx */
  78      int     ai_socktype;  /* SOCK_xxx */
  79      int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
  80      size_t  ai_addrlen;   /* length of ai_addr */
  81      char   *ai_canonname; /* canonical name for nodename */
  82      struct sockaddr  *ai_addr; /* binary address */
  83      struct addrinfo  *ai_next; /* next structure in linked list */
  84 };
  85 .Ed
  86 .Pp
  87 The
  88 .Fa nodename
  89 and
  90 .Fa servname
  91 arguments are pointers to NUL-terminated strings or
  92 .Dv NULL .
  93 One or both of these two arguments must be a non-null pointer.
  94 In the normal client scenario, both the
  95 .Fa nodename
  96 and
  97 .Fa servname
  98 are specified.
  99 In the normal server scenario, only the
 100 .Fa servname
 101 is specified.
 102 A non-null
 103 .Fa nodename
 104 string can be either a node name or a numeric host address string
 105 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
 106 A non-null
 107 .Fa servname
 108 string can be either a service name or a decimal port number.
 109 .Pp
 110 The caller can optionally pass an
 111 .Li addrinfo
 112 structure, pointed to by the third argument,
 113 to provide hints concerning the type of socket that the caller supports.
 114 In this
 115 .Fa hints
 116 structure all members other than
 117 .Fa ai_flags ,
 118 .Fa ai_family ,
 119 .Fa ai_socktype ,
 120 and
 121 .Fa ai_protocol
 122 must be zero or a null pointer.
 123 A value of
 124 .Dv PF_UNSPEC
 125 for
 126 .Fa ai_family
 127 means the caller will accept any protocol family.
 128 A value of 0 for
 129 .Fa ai_socktype
 130 means the caller will accept any socket type.
 131 A value of 0 for
 132 .Fa ai_protocol
 133 means the caller will accept any protocol.
 134 For example, if the caller handles only TCP and not UDP, then the
 135 .Fa ai_socktype
 136 member of the hints structure should be set to
 137 .Dv SOCK_STREAM
 138 when
 139 .Fn getaddrinfo
 140 is called.
 141 If the caller handles only IPv4 and not IPv6, then the
 142 .Fa ai_family
 143 member of the
 144 .Fa hints
 145 structure should be set to
 146 .Dv PF_INET
 147 when
 148 .Fn getaddrinfo
 149 is called.
 150 If the third argument to
 151 .Fn getaddrinfo
 152 is a null pointer, this is the same as if the caller had filled in an
 153 .Li addrinfo
 154 structure initialized to zero with
 155 .Fa ai_family
 156 set to
 157 .Dv PF_UNSPEC .
 158 .Pp
 159 Upon successful return a pointer to a linked list of one or more
 160 .Li addrinfo
 161 structures is returned through the final argument.
 162 The caller can process each
 163 .Li addrinfo
 164 structure in this list by following the
 165 .Fa ai_next
 166 pointer, until a null pointer is encountered.
 167 In each returned
 168 .Li addrinfo
 169 structure the three members
 170 .Fa ai_family ,
 171 .Fa ai_socktype ,
 172 and
 173 .Fa ai_protocol
 174 are the corresponding arguments for a call to the
 175 .Fn socket
 176 function.
 177 In each
 178 .Li addrinfo
 179 structure the
 180 .Fa ai_addr
 181 member points to a filled-in socket address structure whose length is
 182 specified by the
 183 .Fa ai_addrlen
 184 member.
 185 .Pp
 186 If the
 187 .Dv AI_PASSIVE
 188 bit is set in the
 189 .Fa ai_flags
 190 member of the
 191 .Fa hints
 192 structure, then the caller plans to use the returned socket address
 193 structure in a call to
 194 .Fn bind .
 195 In this case, if the
 196 .Fa nodename
 197 argument is a null pointer, then the IP address portion of the socket
 198 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 in the
 207 .Fa ai_flags
 208 member of the
 209 .Fa hints
 210 structure, then the returned socket address structure will be ready for a
 211 call to
 212 .Fn connect
 213 .Pq for a connection-oriented protocol
 214 or either
 215 .Fn connect ,
 216 .Fn sendto ,
 217 or
 218 .Fn sendmsg
 219 .Pq for a connectionless protocol .
 220 In this case, if the
 221 .Fa nodename
 222 argument is a null pointer, then the IP address portion of the
 223 socket address structure will be set to the loopback address.
 224 .Pp
 225 If the
 226 .Dv AI_CANONNAME
 227 bit is set in the
 228 .Fa ai_flags
 229 member of the
 230 .Fa hints
 231 structure, then upon successful return the
 232 .Fa ai_canonname
 233 member of the first
 234 .Li addrinfo
 235 structure in the linked list will point to a NUL-terminated string
 236 containing the canonical name of the specified
 237 .Fa nodename .
 238 .Pp
 239 If the
 240 .Dv AI_NUMERICHOST
 241 bit is set in the
 242 .Fa ai_flags
 243 member of the
 244 .Fa hints
 245 structure, then a non-null
 246 .Fa nodename
 247 string must be a numeric host address string.
 248 Otherwise an error of
 249 .Dv EAI_NONAME
 250 is returned.
 251 This flag prevents any type of name resolution service (e.g., the DNS)
 252 from being called.
 253 .Pp
 254 The arguments to
 255 .Fn getaddrinfo
 256 must sufficiently be consistent and unambiguous.
 257 Here are pitfall cases you may encounter:
 258 .Bl -bullet
 259 .It
 260 .Fn getaddrinfo
 261 will raise an error if members of the
 262 .Fa hints
 263 structure are not consistent.
 264 For example, for internet address families,
 265 .Fn getaddrinfo
 266 will raise an error if you specify
 267 .Dv SOCK_STREAM
 268 to
 269 .Fa ai_socktype
 270 while you specify
 271 .Dv IPPROTO_UDP
 272 to
 273 .Fa ai_protocol .
 274 .It
 275 If you specify a
 276 .Fa servname
 277 which is defined only for certain
 278 .Fa ai_socktype ,
 279 .Fn getaddrinfo
 280 will raise an error because the arguments are not consistent.
 281 For example,
 282 .Fn getaddrinfo
 283 will raise an error if you ask for
 284 .Dq Li tftp
 285 service on
 286 .Dv SOCK_STREAM .
 287 .It
 288 For internet address families, if you specify
 289 .Fa servname
 290 while you set
 291 .Fa ai_socktype
 292 to
 293 .Dv SOCK_RAW ,
 294 .Fn getaddrinfo
 295 will raise an error, because service names are not defined for the internet
 296 .Dv SOCK_RAW
 297 space.
 298 .It
 299 If you specify a numeric
 300 .Fa servname ,
 301 while leaving
 302 .Fa ai_socktype
 303 and
 304 .Fa ai_protocol
 305 unspecified,
 306 .Fn getaddrinfo
 307 will raise an error.
 308 This is because the numeric
 309 .Fa servname
 310 does not identify any socket type, and
 311 .Fn getaddrinfo
 312 is not allowed to glob the argument in such case.
 313 .El
 314 .Pp
 315 All of the information returned by
 316 .Fn getaddrinfo
 317 is dynamically allocated:
 318 the
 319 .Li addrinfo
 320 structures, the socket address structures, and canonical node name
 321 strings pointed to by the addrinfo structures.
 322 To return this information to the system the function
 323 .Fn freeaddrinfo
 324 is called.
 325 The
 326 .Fa addrinfo
 327 structure pointed to by the
 328 .Fa ai argument
 329 is freed, along with any dynamic storage pointed to by the structure.
 330 This operation is repeated until a
 331 .Dv NULL
 332 .Fa ai_next
 333 pointer is encountered.
 334 .Pp
 335 To aid applications in printing error messages based on the
 336 .Dv EAI_xxx
 337 codes returned by
 338 .Fn getaddrinfo ,
 339 .Fn gai_strerror
 340 is defined.
 341 The argument is one of the
 342 .Dv EAI_xxx
 343 values defined earlier and the return value points to a string describing
 344 the error.
 345 If the argument is not one of the
 346 .Dv EAI_xxx
 347 values, the function still returns a pointer to a string whose contents
 348 indicate an unknown error.
 349 .\"
 350 .Ss Extension for scoped IPv6 address
 351 The implementation allows experimental numeric IPv6 address notation with
 352 scope identifier.
 353 By appending the percent character and scope identifier to addresses,
 354 you can fill
 355 .Li sin6_scope_id
 356 field for addresses.
 357 This would make management of scoped address easier,
 358 and allows cut-and-paste input of scoped address.
 359 .Pp
 360 At this moment the code supports only link-local addresses with the format.
 361 Scope identifier is hardcoded to name of hardware interface associated
 362 with the link.
 363 .Po
 364 such as
 365 .Li ne0
 366 .Pc .
 367 Example would be like
 368 .Dq Li fe80::1%ne0 ,
 369 which means
 370 .Do
 371 .Li fe80::1
 372 on the link associated with
 373 .Li ne0
 374 interface
 375 .Dc .
 376 .Pp
 377 The implementation is still very experimental and non-standard.
 378 The current implementation assumes one-by-one relationship between
 379 interface and link, which is not necessarily true from the specification.
 380 .\"
 381 .Sh EXAMPLES
 382 The following code tries to connect to
 383 .Dq Li www.kame.net
 384 service
 385 .Dq Li http .
 386 via stream socket.
 387 It loops through all the addresses available, regardless from address family.
 388 If the destination resolves to IPv4 address, it will use
 389 .Dv AF_INET
 390 socket.
 391 Similarly, if it resolves to IPv6,
 392 .Dv AF_INET6
 393 socket is used.
 394 Observe that there is no hardcoded reference to particular address family.
 395 The code works even if
 396 .Nm getaddrinfo
 397 returns addresses that are not IPv4/v6.
 398 .Bd -literal -offset indent
 399 struct addrinfo hints, *res, *res0;
 400 int error;
 401 int s;
 402 const char *cause = NULL;
 403
 404 memset(&hints, 0, sizeof(hints));
 405 hints.ai_family = PF_UNSPEC;
 406 hints.ai_socktype = SOCK_STREAM;
 407 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
 408 if (error) {
 409         errx(1, "%s", gai_strerror(error));
 410         /*NOTREACHED*/
 411 }
 412 s = -1;
 413 for (res = res0; res; res = res->ai_next) {
 414         s = socket(res->ai_family, res->ai_socktype,
 415             res->ai_protocol);
 416         if (s < 0) {
 417                 cause = "socket";
 418                 continue;
 419         }
 420
 421         if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
 422                 cause = "connect";
 423                 close(s);
 424                 s = -1;
 425                 continue;
 426         }
 427
 428         break;  /* okay we got one */
 429 }
 430 if (s < 0) {
 431         err(1, cause);
 432         /*NOTREACHED*/
 433 }
 434 freeaddrinfo(res0);
 435 .Ed
 436 .Pp
 437 The following example tries to open a wildcard listening socket onto service
 438 .Dq Li http ,
 439 for all the address families available.
 440 .Bd -literal -offset indent
 441 struct addrinfo hints, *res, *res0;
 442 int error;
 443 int s[MAXSOCK];
 444 int nsock;
 445 const char *cause = NULL;
 446
 447 memset(&hints, 0, sizeof(hints));
 448 hints.ai_family = PF_UNSPEC;
 449 hints.ai_socktype = SOCK_STREAM;
 450 hints.ai_flags = AI_PASSIVE;
 451 error = getaddrinfo(NULL, "http", &hints, &res0);
 452 if (error) {
 453         errx(1, "%s", gai_strerror(error));
 454         /*NOTREACHED*/
 455 }
 456 nsock = 0;
 457 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
 458         s[nsock] = socket(res->ai_family, res->ai_socktype,
 459             res->ai_protocol);
 460         if (s[nsock] < 0) {
 461                 cause = "socket";
 462                 continue;
 463         }
 464
 465         if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
 466                 cause = "bind";
 467                 close(s[nsock]);
 468                 continue;
 469         }
 470         (void) listen(s[nsock], 5);
 471
 472         nsock++;
 473 }
 474 if (nsock == 0) {
 475         err(1, cause);
 476         /*NOTREACHED*/
 477 }
 478 freeaddrinfo(res0);
 479 .Ed
 480 .\"
 481 .Sh DIAGNOSTICS
 482 Error return status from
 483 .Fn getaddrinfo
 484 is zero on success and non-zero on errors.
 485 Non-zero error codes are defined in
 486 .Aq Pa netdb.h ,
 487 and as follows:
 488 .Pp
 489 .Bl -tag -width EAI_ADDRFAMILY -compact
 490 .It Dv EAI_ADDRFAMILY
 491 Address family for
 492 .Fa nodename
 493 not supported.
 494 .It Dv EAI_AGAIN
 495 Temporary failure in name resolution.
 496 .It Dv EAI_BADFLAGS
 497 Invalid value for
 498 .Fa ai_flags .
 499 .It Dv EAI_FAIL
 500 Non-recoverable failure in name resolution.
 501 .It Dv EAI_FAMILY
 502 .Fa ai_family
 503 not supported.
 504 .It Dv EAI_MEMORY
 505 Memory allocation failure.
 506 .It Dv EAI_NODATA
 507 No address associated with
 508 .Fa nodename .
 509 .It Dv EAI_NONAME
 510 .Fa nodename
 511 nor
 512 .Fa servname
 513 provided, or not known.
 514 .It Dv EAI_SERVICE
 515 .Fa servname
 516 not supported for
 517 .Fa ai_socktype .
 518 .It Dv EAI_SOCKTYPE
 519 .Fa ai_socktype
 520 not supported.
 521 .It Dv EAI_SYSTEM
 522 System error returned in
 523 .Va errno .
 524 .El
 525 .Pp
 526 If called with proper argument,
 527 .Fn gai_strerror
 528 returns a pointer to a string describing the given error code.
 529 If the argument is not one of the
 530 .Dv EAI_xxx
 531 values, the function still returns a pointer to a string whose contents
 532 indicate an unknown error.
 533 .\"
 534 .Sh SEE ALSO
 535 .Xr getnameinfo 3 ,
 536 .Xr gethostbyname 3 ,
 537 .Xr getservbyname 3 ,
 538 .Xr hosts 5 ,
 539 .Xr resolv.conf 5 ,
 540 .Xr services 5 ,
 541 .Xr hostname 7 ,
 542 .Xr named 8
 543 .Rs
 544 .%A R. Gilligan
 545 .%A S. Thomson
 546 .%A J. Bound
 547 .%A W. Stevens
 548 .%T Basic Socket Interface Extensions for IPv6
 549 .%R RFC2553
 550 .%D March 1999
 551 .Re
 552 .Rs
 553 .%A Tatsuya Jinmei
 554 .%A Atsushi Onoe
 555 .%T "An Extension of Format for IPv6 Scoped Addresses"
 556 .%R internet draft
 557 .%N draft-ietf-ipngwg-scopedaddr-format-02.txt
 558 .%O work in progress material
 559 .Re
 560 .Rs
 561 .%A Craig Metz
 562 .%T Protocol Independence Using the Sockets API
 563 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 564 .%D June 2000
 565 .Re
 566 .\"
 567 .Sh HISTORY
 568 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
 569 .\"
 570 .Sh STANDARDS
 571 The
 572 .Fn getaddrinfo
 573 function is defined in IEEE POSIX 1003.1g draft specification,
 574 and documented in
 575 .Dq Basic Socket Interface Extensions for IPv6
 576 .Pq RFC2553 .
 577 .\"
 578 .Sh BUGS
 579 The text was shamelessly copied from RFC2553.