1.\" $NetBSD: getaddrinfo.3,v 1.55 2010/04/17 20:28:47 wiz Exp $ 2.\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $ 3.\" $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $ 4.\" 5.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") 6.\" Copyright (C) 2000, 2001 Internet Software Consortium. 7.\" 8.\" Permission to use, copy, modify, and distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 13.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 14.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 15.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 16.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 17.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 18.\" PERFORMANCE OF THIS SOFTWARE. 19.\" 20.Dd April 17, 2010 21.Dt GETADDRINFO 3 22.Os 23.Sh NAME 24.Nm getaddrinfo , 25.Nm freeaddrinfo , 26.Nm allocaddrinfo 27.Nd host and service name to socket address structure 28.Sh SYNOPSIS 29.In netdb.h 30.Ft int 31.Fn getaddrinfo "const char * restrict hostname" \ 32 "const char * restrict servname" \ 33 "const struct addrinfo * restrict hints" "struct addrinfo ** restrict res" 34.Ft void 35.Fn freeaddrinfo "struct addrinfo *ai" 36.Ft struct addrinfo * 37.Fn allocaddrinfo "socklen_t len" 38.Sh DESCRIPTION 39The 40.Fn getaddrinfo 41function is used to get a list of 42.Tn IP 43addresses and port numbers for host 44.Fa hostname 45and service 46.Fa servname . 47It is a replacement for and provides more flexibility than the 48.Xr gethostbyname 3 49and 50.Xr getservbyname 3 51functions. 52.Pp 53The 54.Fa hostname 55and 56.Fa servname 57arguments are either pointers to NUL-terminated strings or the null pointer. 58An acceptable value for 59.Fa hostname 60is either a valid host name or a numeric host address string consisting 61of a dotted decimal IPv4 address or an IPv6 address. 62The 63.Fa servname 64is either a decimal port number or a service name listed in 65.Xr services 5 . 66At least one of 67.Fa hostname 68and 69.Fa servname 70must be non-null. 71.Pp 72.Fa hints 73is an optional pointer to a 74.Li struct addrinfo , 75as defined by 76.In netdb.h : 77.Bd -literal 78struct addrinfo { 79 int ai_flags; /* input flags */ 80 int ai_family; /* address family for socket */ 81 int ai_socktype; /* socket type */ 82 int ai_protocol; /* protocol for socket */ 83 socklen_t ai_addrlen; /* length of socket-address */ 84 struct sockaddr *ai_addr; /* socket-address for socket */ 85 char *ai_canonname; /* canonical name for service location */ 86 struct addrinfo *ai_next; /* pointer to next in list */ 87}; 88.Ed 89.Pp 90This structure can be used to provide hints concerning the type of socket 91that the caller supports or wishes to use. 92The caller can supply the following structure elements in 93.Fa hints : 94.Bl -tag -width "ai_socktypeXX" 95.It Fa ai_family 96The address 97.Pq and protocol 98family that should be used. 99When 100.Fa ai_family 101is set to 102.Dv AF_UNSPEC , 103it means the caller will accept any address family supported by the 104operating system. 105Note that while address families 106.Pq Dv AF_* 107and protocol families 108.Pq Dv PF_* 109are theoretically distinct, in practice the distinction has been lost. 110.\" (.Dv !? Consistent with usage below though...) 111.Dv "RFC 3493" 112defines 113.Fn getaddrinfo 114in terms of the address family constants 115.Dv AF_* 116even though 117.Fa ai_family 118is to be passed as a protocol family to 119.Xr socket 2 . 120.It Fa ai_socktype 121Denotes the type of socket that is wanted: 122.Dv SOCK_STREAM , 123.Dv SOCK_DGRAM , 124or 125.Dv SOCK_RAW . 126When 127.Fa ai_socktype 128is zero the caller will accept any socket type. 129.It Fa ai_protocol 130Indicates which transport protocol is desired, 131.Dv IPPROTO_UDP 132or 133.Dv IPPROTO_TCP . 134If 135.Fa ai_protocol 136is zero the caller will accept any protocol. 137.It Fa ai_flags 138.Fa ai_flags 139is formed by 140.Tn OR Ns 'ing 141the following values: 142.Bl -tag -width "AI_CANONNAMEXX" 143.It Dv AI_CANONNAME 144If the 145.Dv AI_CANONNAME 146bit is set, a successful call to 147.Fn getaddrinfo 148will return a NUL-terminated string containing the canonical name 149of the specified hostname in the 150.Fa ai_canonname 151element of the first 152.Li addrinfo 153structure returned. 154.It Dv AI_NUMERICHOST 155If the 156.Dv AI_NUMERICHOST 157bit is set, it indicates that 158.Fa hostname 159should be treated as a numeric string defining an IPv4 or IPv6 address 160and no name resolution should be attempted. 161.It Dv AI_NUMERICSERV 162If the 163.Dv AI_NUMERICSERV 164bit is set, it indicates that the 165.Fa servname 166string contains a numeric port number. 167This is used to prevent service name resolution. 168.It Dv AI_PASSIVE 169If the 170.Dv AI_PASSIVE 171bit is set it indicates that the returned socket address structure 172is intended for use in a call to 173.Xr bind 2 . 174In this case, if the 175.Fa hostname 176argument is the null pointer, then the IP address portion of the 177socket address structure will be set to 178.Dv INADDR_ANY 179for an IPv4 address or 180.Dv IN6ADDR_ANY_INIT 181for an IPv6 address. 182.Pp 183If the 184.Dv AI_PASSIVE 185bit is not set, the returned socket address structure will be ready 186for use in a call to 187.Xr connect 2 188for a connection-oriented protocol or 189.Xr connect 2 , 190.Xr sendto 2 , 191or 192.Xr sendmsg 2 193if a connectionless protocol was chosen. 194The 195.Tn IP 196address portion of the socket address structure will be set to the 197loopback address if 198.Fa hostname 199is the null pointer and 200.Dv AI_PASSIVE 201is not set. 202.El 203.El 204.Pp 205All other elements of the 206.Li addrinfo 207structure passed via 208.Fa hints 209must be zero or the null pointer. 210.Pp 211If 212.Fa hints 213is the null pointer, 214.Fn getaddrinfo 215behaves as if the caller provided a 216.Li struct addrinfo 217with 218.Fa ai_family 219set to 220.Dv AF_UNSPEC 221and all other elements set to zero or 222.Dv NULL . 223.Pp 224After a successful call to 225.Fn getaddrinfo , 226.Fa *res 227is a pointer to a linked list of one or more 228.Li addrinfo 229structures. 230The list can be traversed by following the 231.Fa ai_next 232pointer in each 233.Li addrinfo 234structure until a null pointer is encountered. 235The three members 236.Fa ai_family , 237.Fa ai_socktype , 238and 239.Fa ai_protocol 240in each returned 241.Li addrinfo 242structure are suitable for a call to 243.Xr socket 2 . 244For each 245.Li addrinfo 246structure in the list, the 247.Fa ai_addr 248member points to a filled-in socket address structure of length 249.Fa ai_addrlen . 250.Pp 251This implementation of 252.Fn getaddrinfo 253allows numeric IPv6 address notation with scope identifier, 254as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. 255By appending the percent character and scope identifier to addresses, 256one can fill the 257.Li sin6_scope_id 258field for addresses. 259This would make management of scoped addresses easier 260and allows cut-and-paste input of scoped addresses. 261.Pp 262At this moment the code supports only link-local addresses with the format. 263The scope identifier is hardcoded to the name of the hardware interface 264associated 265with the link 266.Po 267such as 268.Li ne0 269.Pc . 270An example is 271.Dq Li fe80::1%ne0 , 272which means 273.Do 274.Li fe80::1 275on the link associated with the 276.Li ne0 277interface 278.Dc . 279.Pp 280The current implementation assumes a one-to-one relationship between 281the interface and link, which is not necessarily true from the specification. 282.Pp 283All of the information returned by 284.Fn getaddrinfo 285is dynamically allocated: the 286.Li addrinfo 287structures themselves as well as the socket address structures and 288the canonical host name strings included in the 289.Li addrinfo 290structures. 291.Pp 292Memory allocated for the dynamically allocated structures created by 293a successful call to 294.Fn getaddrinfo 295is released by the 296.Fn freeaddrinfo 297function. 298The 299.Fa ai 300pointer should be an 301.Li addrinfo 302structure created by a call to 303.Fn getaddrinfo 304or 305.Fn allocaddrinfo . 306The 307.Fn allocaddrinfo 308function is intended primarily for authors of 309.Xr nsdispatch 3 310plugins implementing 311.Fn getaddrinfo 312backends. 313.Fn allocaddrinfo 314allocates a 315.Li struct addrinfo 316in a way that is compatible with being returned from 317.Fn getaddrinfo 318and being ultimately freed by 319.Fn freeaddrinfo . 320The returned structure is zeroed, except for the 321.Fa ai_addr 322field, which 323will point to 324.Fa len 325bytes of memory for storage of a socket address. 326It is safe to allocate memory separately for 327.Fa ai_canonname 328with 329.Xr malloc 3 , 330or in any other way that is compatible with deallocation by 331.Xr free 3 . 332.Sh RETURN VALUES 333.Fn getaddrinfo 334returns zero on success or one of the error codes listed in 335.Xr gai_strerror 3 336if an error occurs. 337.Sh EXAMPLES 338The following code tries to connect to 339.Dq Li www.kame.net 340service 341.Dq Li http 342via a stream socket. 343It loops through all the addresses available, regardless of address family. 344If the destination resolves to an IPv4 address, it will use an 345.Dv AF_INET 346socket. 347Similarly, if it resolves to IPv6, an 348.Dv AF_INET6 349socket is used. 350Observe that there is no hardcoded reference to a particular address family. 351The code works even if 352.Fn getaddrinfo 353returns addresses that are not IPv4/v6. 354.Bd -literal -offset indent 355struct addrinfo hints, *res, *res0; 356int error; 357int s; 358const char *cause = NULL; 359 360memset(\*[Am]hints, 0, sizeof(hints)); 361hints.ai_family = AF_UNSPEC; 362hints.ai_socktype = SOCK_STREAM; 363error = getaddrinfo("www.kame.net", "http", \*[Am]hints, \*[Am]res0); 364if (error) { 365 errx(1, "%s", gai_strerror(error)); 366 /*NOTREACHED*/ 367} 368s = -1; 369for (res = res0; res; res = res-\*[Gt]ai_next) { 370 s = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, 371 res-\*[Gt]ai_protocol); 372 if (s \*[Lt] 0) { 373 cause = "socket"; 374 continue; 375 } 376 377 if (connect(s, res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { 378 cause = "connect"; 379 close(s); 380 s = -1; 381 continue; 382 } 383 384 break; /* okay we got one */ 385} 386if (s \*[Lt] 0) { 387 err(1, "%s", cause); 388 /*NOTREACHED*/ 389} 390freeaddrinfo(res0); 391.Ed 392.Pp 393The following example tries to open a wildcard listening socket onto service 394.Dq Li http , 395for all the address families available. 396.Bd -literal -offset indent 397struct addrinfo hints, *res, *res0; 398int error; 399int s[MAXSOCK]; 400int nsock; 401const char *cause = NULL; 402 403memset(\*[Am]hints, 0, sizeof(hints)); 404hints.ai_family = AF_UNSPEC; 405hints.ai_socktype = SOCK_STREAM; 406hints.ai_flags = AI_PASSIVE; 407error = getaddrinfo(NULL, "http", \*[Am]hints, \*[Am]res0); 408if (error) { 409 errx(1, "%s", gai_strerror(error)); 410 /*NOTREACHED*/ 411} 412nsock = 0; 413for (res = res0; res \*[Am]\*[Am] nsock \*[Lt] MAXSOCK; res = res-\*[Gt]ai_next) { 414 s[nsock] = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, 415 res-\*[Gt]ai_protocol); 416 if (s[nsock] \*[Lt] 0) { 417 cause = "socket"; 418 continue; 419 } 420 421 if (bind(s[nsock], res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { 422 cause = "bind"; 423 close(s[nsock]); 424 continue; 425 } 426 (void) listen(s[nsock], 5); 427 428 nsock++; 429} 430if (nsock == 0) { 431 err(1, "%s", cause); 432 /*NOTREACHED*/ 433} 434freeaddrinfo(res0); 435.Ed 436.Sh SEE ALSO 437.Xr bind 2 , 438.Xr connect 2 , 439.Xr send 2 , 440.Xr socket 2 , 441.Xr gai_strerror 3 , 442.Xr gethostbyname 3 , 443.Xr getnameinfo 3 , 444.Xr getservbyname 3 , 445.Xr resolver 3 , 446.Xr hosts 5 , 447.Xr resolv.conf 5 , 448.Xr services 5 , 449.Xr hostname 7 , 450.Xr named 8 451.Rs 452.%A R. Gilligan 453.%A S. Thomson 454.%A J. Bound 455.%A J. McCann 456.%A W. Stevens 457.%T Basic Socket Interface Extensions for IPv6 458.%R RFC 3493 459.%D February 2003 460.Re 461.Rs 462.%A S. Deering 463.%A B. Haberman 464.%A T. Jinmei 465.%A E. Nordmark 466.%A B. Zill 467.%T "IPv6 Scoped Address Architecture" 468.%R internet draft 469.%N draft-ietf-ipv6-scoping-arch-02.txt 470.%O work in progress material 471.Re 472.Rs 473.%A Craig Metz 474.%T "Protocol Independence Using the Sockets API" 475.%I USENIX Association 476.%B Proceedings of the FREENIX Track: 2000 USENIX Annual Technical Conference 477.%D June 18-23, 2000 478.%P 99-108 479.%U http://www.usenix.org/events/usenix2000/freenix/metzprotocol/metzprotocol.pdf 480.Re 481.Sh STANDARDS 482The 483.Fn getaddrinfo 484function is defined by the 485.St -p1003.1g-2000 486draft specification and documented in 487.Dv "RFC 3493" , 488.Dq Basic Socket Interface Extensions for IPv6 . 489