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