1.\" $OpenBSD: getaddrinfo.3,v 1.50 2012/04/20 16:37:07 sthen 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 20 2012 $ 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.Fd #include <sys/types.h> 28.Fd #include <sys/socket.h> 29.Fd #include <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.Aq Pa 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_CANONNAME 124If the 125.Dv AI_CANONNAME 126bit is set, a successful call to 127.Fn getaddrinfo 128will return a NUL-terminated string containing the canonical name 129of the specified host name in the 130.Fa ai_canonname 131element of the first 132.Li addrinfo 133structure returned. 134.It Dv AI_FQDN 135If the 136.Dv AI_FQDN 137bit is set, a successful call to 138.Fn getaddrinfo 139will return a NUL-terminated string containing the fully qualified domain name 140of the specified host name in the 141.Fa ai_canonname 142element of the first 143.Li addrinfo 144structure returned. 145.Pp 146This is different from the 147.Dv AI_CANONNAME 148bit flag that returns the canonical name registered in DNS, 149which may be different from the fully qualified domain name 150that the host name resolved to. 151Only one of the 152.Dv AI_FQDN 153and 154.Dv AI_CANONNAME 155bits can be set. 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, it indicates that 167.Fa servname 168should be treated as a numeric port string 169and no service name resolution should be attempted. 170.It Dv AI_PASSIVE 171If the 172.Dv AI_PASSIVE 173bit is set it indicates that the returned socket address structure 174is intended for use in a call to 175.Xr bind 2 . 176In this case, if the 177.Fa hostname 178argument is the null pointer, then the IP address portion of the 179socket address structure will be set to 180.Dv INADDR_ANY 181for an IPv4 address or 182.Dv IN6ADDR_ANY_INIT 183for an IPv6 address. 184.Pp 185If the 186.Dv AI_PASSIVE 187bit is not set, the returned socket address structure will be ready 188for use in a call to 189.Xr connect 2 190for a connection-oriented protocol or 191.Xr connect 2 , 192.Xr sendto 2 , 193or 194.Xr sendmsg 2 195if a connectionless protocol was chosen. 196The 197.Tn IP 198address portion of the socket address structure will be set to the 199loopback address if 200.Fa hostname 201is the null pointer and 202.Dv AI_PASSIVE 203is not set. 204.El 205.El 206.Pp 207All other elements of the 208.Li addrinfo 209structure passed via 210.Fa hints 211must be zero or the null pointer. 212.Pp 213If 214.Fa hints 215is the null pointer, 216.Fn getaddrinfo 217behaves as if the caller provided a 218.Li struct addrinfo 219with 220.Fa ai_family 221set to 222.Dv PF_UNSPEC 223and all other elements set to zero or 224.Dv NULL . 225.Pp 226After a successful call to 227.Fn getaddrinfo , 228.Fa *res 229is a pointer to a linked list of one or more 230.Li addrinfo 231structures. 232The list can be traversed by following the 233.Fa ai_next 234pointer in each 235.Li addrinfo 236structure until a null pointer is encountered. 237The three members 238.Fa ai_family , 239.Fa ai_socktype , 240and 241.Fa ai_protocol 242in each returned 243.Li addrinfo 244structure are suitable for a call to 245.Xr socket 2 . 246For each 247.Li addrinfo 248structure in the list, the 249.Fa ai_addr 250member points to a filled-in socket address structure of length 251.Fa ai_addrlen . 252.Pp 253This implementation of 254.Fn getaddrinfo 255allows numeric IPv6 address notation with scope identifier, 256as documented in RFC 4007. 257By appending the percent character and scope identifier to addresses, 258one can fill the 259.Li sin6_scope_id 260field for addresses. 261This would make management of scoped addresses easier 262and allows cut-and-paste input of scoped addresses. 263.Pp 264At this moment the code supports only link-local addresses with the format. 265The scope identifier is hardcoded to the name of the hardware interface 266associated 267with the link 268.Po 269such as 270.Li ne0 271.Pc . 272An example is 273.Dq Li fe80::1%ne0 , 274which means 275.Do 276.Li fe80::1 277on the link associated with the 278.Li ne0 279interface 280.Dc . 281.Pp 282The current implementation assumes a one-to-one relationship between 283the interface and link, which is not necessarily true from the specification. 284.Pp 285All of the information returned by 286.Fn getaddrinfo 287is dynamically allocated: the 288.Li addrinfo 289structures themselves as well as the socket address structures and 290the canonical host name strings included in the 291.Li addrinfo 292structures. 293.Pp 294Memory allocated for the dynamically allocated structures created by 295a successful call to 296.Fn getaddrinfo 297is released by the 298.Fn freeaddrinfo 299function. 300The 301.Fa ai 302pointer should be an 303.Li addrinfo 304structure created by a call to 305.Fn getaddrinfo . 306.Sh RETURN VALUES 307.Fn getaddrinfo 308returns zero on success or one of the error codes listed in 309.Xr gai_strerror 3 310if an error occurs. 311If an error occurs, no memory is allocated by 312.Fn getaddrinfo , 313therefore it is not necessary to release the 314.Li addrinfo 315structure(s). 316.Sh EXAMPLES 317The following code tries to connect to 318.Dq Li www.kame.net 319service 320.Dq Li www 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 save_errno; 337int s; 338const char *cause = NULL; 339 340memset(&hints, 0, sizeof(hints)); 341hints.ai_family = PF_UNSPEC; 342hints.ai_socktype = SOCK_STREAM; 343error = getaddrinfo("www.kame.net", "www", &hints, &res0); 344if (error) 345 errx(1, "%s", gai_strerror(error)); 346s = -1; 347for (res = res0; res; res = res->ai_next) { 348 s = socket(res->ai_family, res->ai_socktype, 349 res->ai_protocol); 350 if (s == -1) { 351 cause = "socket"; 352 continue; 353 } 354 355 if (connect(s, res->ai_addr, res->ai_addrlen) == -1) { 356 cause = "connect"; 357 save_errno = errno; 358 close(s); 359 errno = save_errno; 360 s = -1; 361 continue; 362 } 363 364 break; /* okay we got one */ 365} 366if (s == -1) 367 err(1, "%s", cause); 368freeaddrinfo(res0); 369.Ed 370.Pp 371The following example tries to open a wildcard listening socket onto service 372.Dq Li www , 373for all the address families available. 374.Bd -literal -offset indent 375struct addrinfo hints, *res, *res0; 376int error; 377int save_errno; 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, "www", &hints, &res0); 387if (error) 388 errx(1, "%s", gai_strerror(error)); 389nsock = 0; 390for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { 391 s[nsock] = socket(res->ai_family, res->ai_socktype, 392 res->ai_protocol); 393 if (s[nsock] == -1) { 394 cause = "socket"; 395 continue; 396 } 397 398 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) == -1) { 399 cause = "bind"; 400 save_errno = errno; 401 close(s[nsock]); 402 errno = save_errno; 403 continue; 404 } 405 (void) listen(s[nsock], 5); 406 407 nsock++; 408} 409if (nsock == 0) 410 err(1, "%s", cause); 411freeaddrinfo(res0); 412.Ed 413.Sh SEE ALSO 414.Xr bind 2 , 415.Xr connect 2 , 416.Xr send 2 , 417.Xr socket 2 , 418.Xr gai_strerror 3 , 419.Xr gethostbyname 3 , 420.Xr getnameinfo 3 , 421.Xr getservbyname 3 , 422.Xr resolver 3 , 423.Xr hosts 5 , 424.Xr resolv.conf 5 , 425.Xr services 5 , 426.Xr hostname 7 , 427.Xr named 8 428.Rs 429.%A R. Gilligan 430.%A S. Thomson 431.%A J. Bound 432.%A J. McCann 433.%A W. Stevens 434.%T Basic Socket Interface Extensions for IPv6 435.%R RFC 3493 436.%D February 2003 437.Re 438.Rs 439.%A S. Deering 440.%A B. Haberman 441.%A T. Jinmei 442.%A E. Nordmark 443.%A B. Zill 444.%T "IPv6 Scoped Address Architecture" 445.%R RFC 4007 446.%D March 2005 447.Re 448.Rs 449.%A Craig Metz 450.%T Protocol Independence Using the Sockets API 451.%B "Proceedings of the Freenix Track: 2000 USENIX Annual Technical Conference" 452.%D June 2000 453.Re 454.Sh STANDARDS 455The 456.Fn getaddrinfo 457function is defined by the 458.St -p1003.1g-2000 459draft specification and documented in 460.Dv "RFC 3493" , 461.Dq Basic Socket Interface Extensions for IPv6 . 462.Pp 463The 464.Dv AI_FQDN 465flag bit first appeared in Windows 7. 466.Sh BUGS 467The implementation of 468.Fn getaddrinfo 469is not thread-safe. 470