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