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