1.\" Copyright (c) 1983, 1987, 1991, 1993 2.\" $FreeBSD$ 3.\" $KAME: getaddrinfo.3,v 1.16 2000/07/05 08:18:42 itojun Exp $ 4.\" 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 KAME 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 273All of the information returned by 274.Fn getaddrinfo 275is dynamically allocated: 276the 277.Li addrinfo 278structures, the socket address structures, and canonical node name 279strings pointed to by the addrinfo structures. 280To return this information to the system the function 281.Fn freeaddrinfo 282is called. 283The 284.Fa addrinfo 285structure pointed to by the 286.Fa ai argument 287is freed, along with any dynamic storage pointed to by the structure. 288This operation is repeated until a 289.Dv NULL 290.Fa ai_next 291pointer is encountered. 292.Pp 293To aid applications in printing error messages based on the 294.Dv EAI_xxx 295codes returned by 296.Fn getaddrinfo , 297.Fn gai_strerror 298is defined. 299The argument is one of the 300.Dv EAI_xxx 301values defined earlier and the return value points to a string describing 302the error. 303If the argument is not one of the 304.Dv EAI_xxx 305values, the function still returns a pointer to a string whose contents 306indicate an unknown error. 307.\" 308.Sh EXTENSION 309The implementation allows experimental numeric IPv6 address notation with 310scope identifier. 311By appending atmark and scope identifier to addresses, you can fill 312.Li sin6_scope_id 313field for addresses. 314This would make management of scoped address easier, 315and allows cut-and-paste input of scoped address. 316.Pp 317At this moment the code supports only link-local addresses with the format. 318Scope identifier is hardcoded to name of hardware interface associated 319with the link. 320.Po 321such as 322.Li ne0 323.Pc . 324Example would be like 325.Dq Li fe80::1%ne0 , 326which means 327.Do 328.Li fe80::1 329on the link associated with 330.Li ne0 331interface 332.Dc . 333.Pp 334The implementation is still very experimental and non-standard. 335The current implementation assumes one-by-one relationship between 336interface and link, which is not necessarily true from the specification. 337.\" 338.Sh EXAMPLES 339The following code tries to connect to 340.Dq Li www.kame.net 341service 342.Dq Li http . 343via stream socket. 344It loops through all the addresses available, regardless from address family. 345If the destination resolves to IPv4 address, it will use 346.Dv AF_INET 347socket. 348Similarly, if it resolves to IPv6, 349.Dv AF_INET6 350socket is used. 351Observe that there is no hardcoded reference to particular address family. 352The code works even if 353.Nm getaddrinfo 354returns addresses that are not IPv4/v6. 355.Bd -literal -offset indent 356struct addrinfo hints, *res, *res0; 357int error; 358int s; 359const char *cause = NULL; 360 361memset(&hints, 0, sizeof(hints)); 362hints.ai_family = PF_UNSPEC; 363hints.ai_socktype = SOCK_STREAM; 364error = getaddrinfo("www.kame.net", "http", &hints, &res0); 365if (error) { 366 err1(1, "%s", gai_strerror(error)); 367 /*NOTREACHED*/ 368} 369s = -1; 370for (res = res0; res; res = res->ai_next) { 371 s = socket(res->ai_family, res->ai_socktype, 372 res->ai_protocol); 373 if (s < 0) { 374 cause = "socket"; 375 continue; 376 } 377 378 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { 379 cause = "connect"; 380 close(s); 381 s = -1; 382 continue; 383 } 384 385 break; /* okay we got one */ 386} 387if (s < 0) { 388 err(1, cause); 389 /*NOTREACHED*/ 390} 391freeaddrinfo(res0); 392.Ed 393.Pp 394The following example tries to open wildcard listening socket onto service 395.Dq Li http , 396for all the address families available. 397.Bd -literal -offset indent 398struct addrinfo hints, *res, *res0; 399int error; 400int s[MAXSOCK]; 401int nsock; 402const char *cause = NULL; 403 404memset(&hints, 0, sizeof(hints)); 405hints.ai_family = PF_UNSPEC; 406hints.ai_socktype = SOCK_STREAM; 407hints.ai_flags = AI_PASSIVE; 408error = getaddrinfo(NULL, "http", &hints, &res0); 409if (error) { 410 err1(1, "%s", gai_strerror(error)); 411 /*NOTREACHED*/ 412} 413nsock = 0; 414for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { 415 s[nsock] = socket(res->ai_family, res->ai_socktype, 416 res->ai_protocol); 417 if (s[nsock] < 0) { 418 cause = "socket"; 419 continue; 420 } 421 422 if (connect(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { 423 cause = "connect"; 424 close(s[nsock]); 425 continue; 426 } 427 428 nsock++; 429} 430if (nsock == 0) { 431 err(1, cause); 432 /*NOTREACHED*/ 433} 434freeaddrinfo(res0); 435.Ed 436.\" 437.Sh FILES 438.Bl -tag -width /etc/resolv.conf -compact 439.It Pa /etc/hosts 440.It Pa /etc/host.conf 441.It Pa /etc/resolv.conf 442.El 443.\" 444.Sh DIAGNOSTICS 445Error return status from 446.Fn getaddrinfo 447is zero on success and non-zero on errors. 448Non-zero error codes are defined in 449.Aq Pa netdb.h , 450and as follows: 451.Pp 452.Bl -tag -width EAI_ADDRFAMILY -compact 453.It Dv EAI_ADDRFAMILY 454Address family for 455.Fa nodename 456not supported. 457.It Dv EAI_AGAIN 458Temporary failure in name resolution. 459.It Dv EAI_BADFLAGS 460Invalid value for 461.Fa ai_flags . 462.It Dv EAI_FAIL 463Non-recoverable failure in name resolution. 464.It Dv EAI_FAMILY 465.Fa ai_family 466not supported. 467.It Dv EAI_MEMORY 468Memory allocation failure. 469.It Dv EAI_NODATA 470No address associated with 471.Fa nodename . 472.It Dv EAI_NONAME 473.Fa nodename 474nor 475.Fa servname 476provided, or not known. 477.It Dv EAI_SERVICE 478.Fa servname 479not supported for 480.Fa ai_socktype . 481.It Dv EAI_SOCKTYPE 482.Fa ai_socktype 483not supported. 484.It Dv EAI_SYSTEM 485System error returned in 486.Va errno . 487.El 488.Pp 489If called with proper argument, 490.Fn gai_strerror 491returns a pointer to a string describing the given error code. 492If the argument is not one of the 493.Dv EAI_xxx 494values, the function still returns a pointer to a string whose contents 495indicate an unknown error. 496.\" 497.Sh SEE ALSO 498.Xr getnameinfo 3 , 499.Xr gethostbyname 3 , 500.Xr getservbyname 3 , 501.Xr hosts 5 , 502.Xr services 5 , 503.Xr hostname 7 , 504.Xr named 8 505.Pp 506.Rs 507.%A R. Gilligan 508.%A S. Thomson 509.%A J. Bound 510.%A W. Stevens 511.%T Basic Socket Interface Extensions for IPv6 512.%R RFC2553 513.%D March 1999 514.Re 515.Rs 516.%A Tatsuya Jinmei 517.%A Atsushi Onoe 518.%T "An Extension of Format for IPv6 Scoped Addresses" 519.%R internet draft 520.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 521.%O work in progress material 522.Re 523.Rs 524.%A Craig Metz 525.%T Protocol Independence Using the Sockets API 526.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 527.%D June 2000 528.Re 529.\" 530.Sh HISTORY 531The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. 532.\" 533.Sh STANDARDS 534The 535.Fn getaddrinfo 536function is defined IEEE POSIX 1003.1g draft specification, 537and documented in 538.Dq Basic Socket Interface Extensions for IPv6 539.Pq RFC2553 . 540.\" 541.Sh BUGS 542The text was shamelessly copied from RFC2553. 543