1.\" $NetBSD: getaddrinfo.3,v 1.43 2005/03/21 13:35:04 kleink 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 March 21, 2005 21.Dt GETADDRINFO 3 22.Os 23.Sh NAME 24.Nm getaddrinfo , 25.Nm freeaddrinfo 26.Nd host and service name to socket address structure 27.Sh SYNOPSIS 28.In netdb.h 29.Ft int 30.Fn getaddrinfo "const char * restrict hostname" \ 31 "const char * restrict servname" \ 32 "const struct addrinfo * restrict hints" "struct addrinfo ** restrict res" 33.Ft void 34.Fn freeaddrinfo "struct addrinfo *ai" 35.Sh DESCRIPTION 36The 37.Fn getaddrinfo 38function is used to get a list of 39.Tn IP 40addresses and port numbers for host 41.Fa hostname 42and service 43.Fa servname . 44It is a replacement for and provides more flexibility than the 45.Xr gethostbyname 3 46and 47.Xr getservbyname 3 48functions. 49.Pp 50The 51.Fa hostname 52and 53.Fa servname 54arguments are either pointers to NUL-terminated strings or the null pointer. 55An acceptable value for 56.Fa hostname 57is either a valid host name or a numeric host address string consisting 58of a dotted decimal IPv4 address or an IPv6 address. 59The 60.Fa servname 61is either a decimal port number or a service name listed in 62.Xr services 5 . 63At least one of 64.Fa hostname 65and 66.Fa servname 67must be non-null. 68.Pp 69.Fa hints 70is an optional pointer to a 71.Li struct addrinfo , 72as defined by 73.Aq Pa netdb.h : 74.Bd -literal 75struct addrinfo { 76 int ai_flags; /* input flags */ 77 int ai_family; /* protocol family for socket */ 78 int ai_socktype; /* socket type */ 79 int ai_protocol; /* protocol for socket */ 80 socklen_t ai_addrlen; /* length of socket-address */ 81 struct sockaddr *ai_addr; /* socket-address for socket */ 82 char *ai_canonname; /* canonical name for service location */ 83 struct addrinfo *ai_next; /* pointer to next in list */ 84}; 85.Ed 86.Pp 87This structure can be used to provide hints concerning the type of socket 88that the caller supports or wishes to use. 89The caller can supply the following structure elements in 90.Fa hints : 91.Bl -tag -width "ai_socktypeXX" 92.It Fa ai_family 93The protocol family that should be used. 94When 95.Fa ai_family 96is set to 97.Dv PF_UNSPEC , 98it means the caller will accept any protocol family supported by the 99operating system. 100.It Fa ai_socktype 101Denotes the type of socket that is wanted: 102.Dv SOCK_STREAM , 103.Dv SOCK_DGRAM , 104or 105.Dv SOCK_RAW . 106When 107.Fa ai_socktype 108is zero the caller will accept any socket type. 109.It Fa ai_protocol 110Indicates which transport protocol is desired, 111.Dv IPPROTO_UDP 112or 113.Dv IPPROTO_TCP . 114If 115.Fa ai_protocol 116is zero the caller will accept any protocol. 117.It Fa ai_flags 118.Fa ai_flags 119is formed by 120.Tn OR Ns 'ing 121the following values: 122.Bl -tag -width "AI_CANONNAMEXX" 123.It Dv AI_CANONNAME 124If the 125.Dv AI_CANONNAME 126bit is set, a successful call to 127.Fn getaddrinfo 128will return a NUL-terminated string containing the canonical name 129of the specified hostname in the 130.Fa ai_canonname 131element of the first 132.Li addrinfo 133structure returned. 134.It Dv AI_NUMERICHOST 135If the 136.Dv AI_NUMERICHOST 137bit is set, it indicates that 138.Fa hostname 139should be treated as a numeric string defining an IPv4 or IPv6 address 140and no name resolution should be attempted. 141.It Dv AI_PASSIVE 142If the 143.Dv AI_PASSIVE 144bit is set it indicates that the returned socket address structure 145is intended for use in a call to 146.Xr bind 2 . 147In this case, if the 148.Fa hostname 149argument is the null pointer, then the IP address portion of the 150socket address structure will be set to 151.Dv INADDR_ANY 152for an IPv4 address or 153.Dv IN6ADDR_ANY_INIT 154for an IPv6 address. 155.Pp 156If the 157.Dv AI_PASSIVE 158bit is not set, the returned socket address structure will be ready 159for use in a call to 160.Xr connect 2 161for a connection-oriented protocol or 162.Xr connect 2 , 163.Xr sendto 2 , 164or 165.Xr sendmsg 2 166if a connectionless protocol was chosen. 167The 168.Tn IP 169address portion of the socket address structure will be set to the 170loopback address if 171.Fa hostname 172is the null pointer and 173.Dv AI_PASSIVE 174is not set. 175.El 176.El 177.Pp 178All other elements of the 179.Li addrinfo 180structure passed via 181.Fa hints 182must be zero or the null pointer. 183.Pp 184If 185.Fa hints 186is the null pointer, 187.Fn getaddrinfo 188behaves as if the caller provided a 189.Li struct addrinfo 190with 191.Fa ai_family 192set to 193.Dv PF_UNSPEC 194and all other elements set to zero or 195.Dv NULL . 196.Pp 197After a successful call to 198.Fn getaddrinfo , 199.Fa *res 200is a pointer to a linked list of one or more 201.Li addrinfo 202structures. 203The list can be traversed by following the 204.Fa ai_next 205pointer in each 206.Li addrinfo 207structure until a null pointer is encountered. 208The three members 209.Fa ai_family , 210.Fa ai_socktype , 211and 212.Fa ai_protocol 213in each returned 214.Li addrinfo 215structure are suitable for a call to 216.Xr socket 2 . 217For each 218.Li addrinfo 219structure in the list, the 220.Fa ai_addr 221member points to a filled-in socket address structure of length 222.Fa ai_addrlen . 223.Pp 224This implementation of 225.Fn getaddrinfo 226allows numeric IPv6 address notation with scope identifier, 227as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. 228By appending the percent character and scope identifier to addresses, 229one can fill the 230.Li sin6_scope_id 231field for addresses. 232This would make management of scoped addresses easier 233and allows cut-and-paste input of scoped addresses. 234.Pp 235At this moment the code supports only link-local addresses with the format. 236The scope identifier is hardcoded to the name of the hardware interface 237associated 238with the link 239.Po 240such as 241.Li ne0 242.Pc . 243An example is 244.Dq Li fe80::1%ne0 , 245which means 246.Do 247.Li fe80::1 248on the link associated with the 249.Li ne0 250interface 251.Dc . 252.Pp 253The current implementation assumes a one-to-one relationship between 254the interface and link, which is not necessarily true from the specification. 255.Pp 256All of the information returned by 257.Fn getaddrinfo 258is dynamically allocated: the 259.Li addrinfo 260structures themselves as well as the socket address structures and 261the canonical host name strings included in the 262.Li addrinfo 263structures. 264.Pp 265Memory allocated for the dynamically allocated structures created by 266a successful call to 267.Fn getaddrinfo 268is released by the 269.Fn freeaddrinfo 270function. 271The 272.Fa ai 273pointer should be a 274.Li addrinfo 275structure created by a call to 276.Fn getaddrinfo . 277.Sh RETURN VALUES 278.Fn getaddrinfo 279returns zero on success or one of the error codes listed in 280.Xr gai_strerror 3 281if an error occurs. 282.Sh EXAMPLES 283The following code tries to connect to 284.Dq Li www.kame.net 285service 286.Dq Li http 287via a stream socket. 288It loops through all the addresses available, regardless of address family. 289If the destination resolves to an IPv4 address, it will use an 290.Dv AF_INET 291socket. 292Similarly, if it resolves to IPv6, an 293.Dv AF_INET6 294socket is used. 295Observe that there is no hardcoded reference to a particular address family. 296The code works even if 297.Fn getaddrinfo 298returns addresses that are not IPv4/v6. 299.Bd -literal -offset indent 300struct addrinfo hints, *res, *res0; 301int error; 302int s; 303const char *cause = NULL; 304 305memset(\*[Am]hints, 0, sizeof(hints)); 306hints.ai_family = PF_UNSPEC; 307hints.ai_socktype = SOCK_STREAM; 308error = getaddrinfo("www.kame.net", "http", \*[Am]hints, \*[Am]res0); 309if (error) { 310 errx(1, "%s", gai_strerror(error)); 311 /*NOTREACHED*/ 312} 313s = -1; 314for (res = res0; res; res = res-\*[Gt]ai_next) { 315 s = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, 316 res-\*[Gt]ai_protocol); 317 if (s \*[Lt] 0) { 318 cause = "socket"; 319 continue; 320 } 321 322 if (connect(s, res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { 323 cause = "connect"; 324 close(s); 325 s = -1; 326 continue; 327 } 328 329 break; /* okay we got one */ 330} 331if (s \*[Lt] 0) { 332 err(1, "%s", cause); 333 /*NOTREACHED*/ 334} 335freeaddrinfo(res0); 336.Ed 337.Pp 338The following example tries to open a wildcard listening socket onto service 339.Dq Li http , 340for all the address families available. 341.Bd -literal -offset indent 342struct addrinfo hints, *res, *res0; 343int error; 344int s[MAXSOCK]; 345int nsock; 346const char *cause = NULL; 347 348memset(\*[Am]hints, 0, sizeof(hints)); 349hints.ai_family = PF_UNSPEC; 350hints.ai_socktype = SOCK_STREAM; 351hints.ai_flags = AI_PASSIVE; 352error = getaddrinfo(NULL, "http", \*[Am]hints, \*[Am]res0); 353if (error) { 354 errx(1, "%s", gai_strerror(error)); 355 /*NOTREACHED*/ 356} 357nsock = 0; 358for (res = res0; res \*[Am]\*[Am] nsock \*[Lt] MAXSOCK; res = res-\*[Gt]ai_next) { 359 s[nsock] = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, 360 res-\*[Gt]ai_protocol); 361 if (s[nsock] \*[Lt] 0) { 362 cause = "socket"; 363 continue; 364 } 365 366 if (bind(s[nsock], res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { 367 cause = "bind"; 368 close(s[nsock]); 369 continue; 370 } 371 (void) listen(s[nsock], 5); 372 373 nsock++; 374} 375if (nsock == 0) { 376 err(1, "%s", cause); 377 /*NOTREACHED*/ 378} 379freeaddrinfo(res0); 380.Ed 381.Sh SEE ALSO 382.Xr bind 2 , 383.Xr connect 2 , 384.Xr send 2 , 385.Xr socket 2 , 386.Xr gai_strerror 3 , 387.Xr gethostbyname 3 , 388.Xr getnameinfo 3 , 389.Xr getservbyname 3 , 390.Xr resolver 3 , 391.Xr hosts 5 , 392.Xr resolv.conf 5 , 393.Xr services 5 , 394.Xr hostname 7 , 395.Xr named 8 396.Rs 397.%A R. Gilligan 398.%A S. Thomson 399.%A J. Bound 400.%A J. McCann 401.%A W. Stevens 402.%T Basic Socket Interface Extensions for IPv6 403.%R RFC 3493 404.%D February 2003 405.Re 406.Rs 407.%A S. Deering 408.%A B. Haberman 409.%A T. Jinmei 410.%A E. Nordmark 411.%A B. Zill 412.%T "IPv6 Scoped Address Architecture" 413.%R internet draft 414.%N draft-ietf-ipv6-scoping-arch-02.txt 415.%O work in progress material 416.Re 417.Rs 418.%A Craig Metz 419.%T Protocol Independence Using the Sockets API 420.%B "Proceedings of the FREENIX track: 2000 USENIX annual technical conference" 421.%D June 2000 422.Re 423.Sh STANDARDS 424The 425.Fn getaddrinfo 426function is defined by the 427.St -p1003.1g-2000 428draft specification and documented in 429.Dv "RFC 3493" , 430.Dq Basic Socket Interface Extensions for IPv6 . 431.Sh BUGS 432The implementation of 433.Fn getaddrinfo 434is not thread-safe. 435