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