1.\" $NetBSD: getaddrinfo.3,v 1.46 2006/12/23 07:42:30 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 November 24, 2006 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_NUMERICSERV 142If the 143.Dv AI_NUMERICSERV 144bit is set, it indicates that the 145.Fa servname 146string contains a numeric port number. 147This is used to prevent service name resolution. 148.It Dv AI_PASSIVE 149If the 150.Dv AI_PASSIVE 151bit is set it indicates that the returned socket address structure 152is intended for use in a call to 153.Xr bind 2 . 154In this case, if the 155.Fa hostname 156argument is the null pointer, then the IP address portion of the 157socket address structure will be set to 158.Dv INADDR_ANY 159for an IPv4 address or 160.Dv IN6ADDR_ANY_INIT 161for an IPv6 address. 162.Pp 163If the 164.Dv AI_PASSIVE 165bit is not set, the returned socket address structure will be ready 166for use in a call to 167.Xr connect 2 168for a connection-oriented protocol or 169.Xr connect 2 , 170.Xr sendto 2 , 171or 172.Xr sendmsg 2 173if a connectionless protocol was chosen. 174The 175.Tn IP 176address portion of the socket address structure will be set to the 177loopback address if 178.Fa hostname 179is the null pointer and 180.Dv AI_PASSIVE 181is not set. 182.El 183.El 184.Pp 185All other elements of the 186.Li addrinfo 187structure passed via 188.Fa hints 189must be zero or the null pointer. 190.Pp 191If 192.Fa hints 193is the null pointer, 194.Fn getaddrinfo 195behaves as if the caller provided a 196.Li struct addrinfo 197with 198.Fa ai_family 199set to 200.Dv PF_UNSPEC 201and all other elements set to zero or 202.Dv NULL . 203.Pp 204After a successful call to 205.Fn getaddrinfo , 206.Fa *res 207is a pointer to a linked list of one or more 208.Li addrinfo 209structures. 210The list can be traversed by following the 211.Fa ai_next 212pointer in each 213.Li addrinfo 214structure until a null pointer is encountered. 215The three members 216.Fa ai_family , 217.Fa ai_socktype , 218and 219.Fa ai_protocol 220in each returned 221.Li addrinfo 222structure are suitable for a call to 223.Xr socket 2 . 224For each 225.Li addrinfo 226structure in the list, the 227.Fa ai_addr 228member points to a filled-in socket address structure of length 229.Fa ai_addrlen . 230.Pp 231This implementation of 232.Fn getaddrinfo 233allows numeric IPv6 address notation with scope identifier, 234as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. 235By appending the percent character and scope identifier to addresses, 236one can fill the 237.Li sin6_scope_id 238field for addresses. 239This would make management of scoped addresses easier 240and allows cut-and-paste input of scoped addresses. 241.Pp 242At this moment the code supports only link-local addresses with the format. 243The scope identifier is hardcoded to the name of the hardware interface 244associated 245with the link 246.Po 247such as 248.Li ne0 249.Pc . 250An example is 251.Dq Li fe80::1%ne0 , 252which means 253.Do 254.Li fe80::1 255on the link associated with the 256.Li ne0 257interface 258.Dc . 259.Pp 260The current implementation assumes a one-to-one relationship between 261the interface and link, which is not necessarily true from the specification. 262.Pp 263All of the information returned by 264.Fn getaddrinfo 265is dynamically allocated: the 266.Li addrinfo 267structures themselves as well as the socket address structures and 268the canonical host name strings included in the 269.Li addrinfo 270structures. 271.Pp 272Memory allocated for the dynamically allocated structures created by 273a successful call to 274.Fn getaddrinfo 275is released by the 276.Fn freeaddrinfo 277function. 278The 279.Fa ai 280pointer should be a 281.Li addrinfo 282structure created by a call to 283.Fn getaddrinfo . 284.Sh RETURN VALUES 285.Fn getaddrinfo 286returns zero on success or one of the error codes listed in 287.Xr gai_strerror 3 288if an error occurs. 289.Sh EXAMPLES 290The following code tries to connect to 291.Dq Li www.kame.net 292service 293.Dq Li http 294via a stream socket. 295It loops through all the addresses available, regardless of address family. 296If the destination resolves to an IPv4 address, it will use an 297.Dv AF_INET 298socket. 299Similarly, if it resolves to IPv6, an 300.Dv AF_INET6 301socket is used. 302Observe that there is no hardcoded reference to a particular address family. 303The code works even if 304.Fn getaddrinfo 305returns addresses that are not IPv4/v6. 306.Bd -literal -offset indent 307struct addrinfo hints, *res, *res0; 308int error; 309int s; 310const char *cause = NULL; 311 312memset(\*[Am]hints, 0, sizeof(hints)); 313hints.ai_family = PF_UNSPEC; 314hints.ai_socktype = SOCK_STREAM; 315error = getaddrinfo("www.kame.net", "http", \*[Am]hints, \*[Am]res0); 316if (error) { 317 errx(1, "%s", gai_strerror(error)); 318 /*NOTREACHED*/ 319} 320s = -1; 321for (res = res0; res; res = res-\*[Gt]ai_next) { 322 s = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, 323 res-\*[Gt]ai_protocol); 324 if (s \*[Lt] 0) { 325 cause = "socket"; 326 continue; 327 } 328 329 if (connect(s, res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { 330 cause = "connect"; 331 close(s); 332 s = -1; 333 continue; 334 } 335 336 break; /* okay we got one */ 337} 338if (s \*[Lt] 0) { 339 err(1, "%s", cause); 340 /*NOTREACHED*/ 341} 342freeaddrinfo(res0); 343.Ed 344.Pp 345The following example tries to open a wildcard listening socket onto service 346.Dq Li http , 347for all the address families available. 348.Bd -literal -offset indent 349struct addrinfo hints, *res, *res0; 350int error; 351int s[MAXSOCK]; 352int nsock; 353const char *cause = NULL; 354 355memset(\*[Am]hints, 0, sizeof(hints)); 356hints.ai_family = PF_UNSPEC; 357hints.ai_socktype = SOCK_STREAM; 358hints.ai_flags = AI_PASSIVE; 359error = getaddrinfo(NULL, "http", \*[Am]hints, \*[Am]res0); 360if (error) { 361 errx(1, "%s", gai_strerror(error)); 362 /*NOTREACHED*/ 363} 364nsock = 0; 365for (res = res0; res \*[Am]\*[Am] nsock \*[Lt] MAXSOCK; res = res-\*[Gt]ai_next) { 366 s[nsock] = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, 367 res-\*[Gt]ai_protocol); 368 if (s[nsock] \*[Lt] 0) { 369 cause = "socket"; 370 continue; 371 } 372 373 if (bind(s[nsock], res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { 374 cause = "bind"; 375 close(s[nsock]); 376 continue; 377 } 378 (void) listen(s[nsock], 5); 379 380 nsock++; 381} 382if (nsock == 0) { 383 err(1, "%s", cause); 384 /*NOTREACHED*/ 385} 386freeaddrinfo(res0); 387.Ed 388.Sh SEE ALSO 389.Xr bind 2 , 390.Xr connect 2 , 391.Xr send 2 , 392.Xr socket 2 , 393.Xr gai_strerror 3 , 394.Xr gethostbyname 3 , 395.Xr getnameinfo 3 , 396.Xr getservbyname 3 , 397.Xr resolver 3 , 398.Xr hosts 5 , 399.Xr resolv.conf 5 , 400.Xr services 5 , 401.Xr hostname 7 , 402.Xr named 8 403.Rs 404.%A R. Gilligan 405.%A S. Thomson 406.%A J. Bound 407.%A J. McCann 408.%A W. Stevens 409.%T Basic Socket Interface Extensions for IPv6 410.%R RFC 3493 411.%D February 2003 412.Re 413.Rs 414.%A S. Deering 415.%A B. Haberman 416.%A T. Jinmei 417.%A E. Nordmark 418.%A B. Zill 419.%T "IPv6 Scoped Address Architecture" 420.%R internet draft 421.%N draft-ietf-ipv6-scoping-arch-02.txt 422.%O work in progress material 423.Re 424.Rs 425.%A Craig Metz 426.%T Protocol Independence Using the Sockets API 427.%B "Proceedings of the FREENIX track: 2000 USENIX annual technical conference" 428.%D June 2000 429.Re 430.Sh STANDARDS 431The 432.Fn getaddrinfo 433function is defined by the 434.St -p1003.1g-2000 435draft specification and documented in 436.Dv "RFC 3493" , 437.Dq Basic Socket Interface Extensions for IPv6 . 438