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 February 10, 2019 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; /* AI_PASSIVE, AI_CANONNAME, .. */ 82 int ai_family; /* AF_xxx */ 83 int ai_socktype; /* SOCK_xxx */ 84 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 85 socklen_t ai_addrlen; /* length of ai_addr */ 86 char *ai_canonname; /* canonical name for hostname */ 87 struct sockaddr *ai_addr; /* binary address */ 88 struct addrinfo *ai_next; /* next structure in linked 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 IMPLEMENTATION NOTES 355The behavior of 356.Li freeadrinfo(NULL) 357is left unspecified by both 358.St -susv4 359and 360.Dv "RFC 3493" . 361The current implementation ignores a 362.Dv NULL 363argument for compatibility with programs that rely on the implementation 364details of other operating systems. 365.Sh RETURN VALUES 366.Fn getaddrinfo 367returns zero on success or one of the error codes listed in 368.Xr gai_strerror 3 369if an error occurs. 370.Sh EXAMPLES 371The following code tries to connect to 372.Dq Li www.kame.net 373service 374.Dq Li http 375via a stream socket. 376It loops through all the addresses available, regardless of address family. 377If the destination resolves to an IPv4 address, it will use an 378.Dv AF_INET 379socket. 380Similarly, if it resolves to IPv6, an 381.Dv AF_INET6 382socket is used. 383Observe that there is no hardcoded reference to a particular address family. 384The code works even if 385.Fn getaddrinfo 386returns addresses that are not IPv4/v6. 387.Bd -literal -offset indent 388struct addrinfo hints, *res, *res0; 389int error; 390int s; 391const char *cause = NULL; 392 393memset(&hints, 0, sizeof(hints)); 394hints.ai_family = AF_UNSPEC; 395hints.ai_socktype = SOCK_STREAM; 396error = getaddrinfo("www.kame.net", "http", &hints, &res0); 397if (error) { 398 errx(1, "%s", gai_strerror(error)); 399 /* NOTREACHED */ 400} 401s = -1; 402for (res = res0; res; res = res->ai_next) { 403 s = socket(res->ai_family, res->ai_socktype, 404 res->ai_protocol); 405 if (s < 0) { 406 cause = "socket"; 407 continue; 408 } 409 410 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { 411 cause = "connect"; 412 close(s); 413 s = -1; 414 continue; 415 } 416 417 break; /* okay we got one */ 418} 419if (s < 0) { 420 err(1, "%s", cause); 421 /* NOTREACHED */ 422} 423freeaddrinfo(res0); 424.Ed 425.Pp 426The following example tries to open a wildcard listening socket onto service 427.Dq Li http , 428for all the address families available. 429.Bd -literal -offset indent 430struct addrinfo hints, *res, *res0; 431int error; 432int s[MAXSOCK]; 433int nsock; 434const char *cause = NULL; 435 436memset(&hints, 0, sizeof(hints)); 437hints.ai_family = AF_UNSPEC; 438hints.ai_socktype = SOCK_STREAM; 439hints.ai_flags = AI_PASSIVE; 440error = getaddrinfo(NULL, "http", &hints, &res0); 441if (error) { 442 errx(1, "%s", gai_strerror(error)); 443 /* NOTREACHED */ 444} 445nsock = 0; 446for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { 447 s[nsock] = socket(res->ai_family, res->ai_socktype, 448 res->ai_protocol); 449 if (s[nsock] < 0) { 450 cause = "socket"; 451 continue; 452 } 453 454 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { 455 cause = "bind"; 456 close(s[nsock]); 457 continue; 458 } 459 (void) listen(s[nsock], 5); 460 461 nsock++; 462} 463if (nsock == 0) { 464 err(1, "%s", cause); 465 /* NOTREACHED */ 466} 467freeaddrinfo(res0); 468.Ed 469.Sh SEE ALSO 470.Xr bind 2 , 471.Xr connect 2 , 472.Xr send 2 , 473.Xr socket 2 , 474.Xr gai_strerror 3 , 475.Xr gethostbyname 3 , 476.Xr getnameinfo 3 , 477.Xr getservbyname 3 , 478.Xr resolver 3 , 479.Xr inet 4 , 480.Xr inet6 4 , 481.Xr unix 4 , 482.Xr hosts 5 , 483.Xr resolv.conf 5 , 484.Xr services 5 , 485.Xr hostname 7 , 486.Xr named 8 487.Rs 488.%A R. Gilligan 489.%A S. Thomson 490.%A J. Bound 491.%A J. McCann 492.%A W. Stevens 493.%T Basic Socket Interface Extensions for IPv6 494.%R RFC 3493 495.%D February 2003 496.Re 497.Rs 498.%A S. Deering 499.%A B. Haberman 500.%A T. Jinmei 501.%A E. Nordmark 502.%A B. Zill 503.%T "IPv6 Scoped Address Architecture" 504.%R RFC 4007 505.%D March 2005 506.Re 507.Rs 508.%A Craig Metz 509.%T Protocol Independence Using the Sockets API 510.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 511.%D June 2000 512.Re 513.Sh STANDARDS 514The 515.Fn getaddrinfo 516function is defined by the 517.St -p1003.1-2004 518specification and documented in 519.Dv "RFC 3493" , 520.Dq Basic Socket Interface Extensions for IPv6 . 521