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