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