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