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