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