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