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