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