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