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