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