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