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 September 20, 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. 246The three members 247.Fa ai_family , 248.Fa ai_socktype , 249and 250.Fa ai_protocol 251in each returned 252.Li addrinfo 253structure are suitable for a call to 254.Xr socket 2 . 255For each 256.Li addrinfo 257structure in the list, the 258.Fa ai_addr 259member points to a filled-in socket address structure of length 260.Fa ai_addrlen . 261.Pp 262This implementation of 263.Fn getaddrinfo 264allows numeric IPv6 address notation with scope identifier, 265as documented in chapter 11 of RFC 4007. 266By appending the percent character and scope identifier to addresses, 267one can fill the 268.Li sin6_scope_id 269field for addresses. 270This would make management of scoped addresses easier 271and allows cut-and-paste input of scoped addresses. 272.Pp 273At this moment the code supports only link-local addresses with the format. 274The scope identifier is hardcoded to the name of the hardware interface 275associated 276with the link 277.Po 278such as 279.Li ne0 280.Pc . 281An example is 282.Dq Li fe80::1%ne0 , 283which means 284.Do 285.Li fe80::1 286on the link associated with the 287.Li ne0 288interface 289.Dc . 290.Pp 291The current implementation assumes a one-to-one relationship between 292the interface and link, which is not necessarily true from the specification. 293.Pp 294All of the information returned by 295.Fn getaddrinfo 296is dynamically allocated: the 297.Li addrinfo 298structures themselves as well as the socket address structures and 299the canonical host name strings included in the 300.Li addrinfo 301structures. 302.Pp 303Memory allocated for the dynamically allocated structures created by 304a successful call to 305.Fn getaddrinfo 306is released by the 307.Fn freeaddrinfo 308function. 309The 310.Fa ai 311pointer should be a 312.Li addrinfo 313structure created by a call to 314.Fn getaddrinfo . 315.Sh RETURN VALUES 316.Fn getaddrinfo 317returns zero on success or one of the error codes listed in 318.Xr gai_strerror 3 319if an error occurs. 320.Sh EXAMPLES 321The following code tries to connect to 322.Dq Li www.kame.net 323service 324.Dq Li http 325via a stream socket. 326It loops through all the addresses available, regardless of address family. 327If the destination resolves to an IPv4 address, it will use an 328.Dv AF_INET 329socket. 330Similarly, if it resolves to IPv6, an 331.Dv AF_INET6 332socket is used. 333Observe that there is no hardcoded reference to a particular address family. 334The code works even if 335.Fn getaddrinfo 336returns addresses that are not IPv4/v6. 337.Bd -literal -offset indent 338struct addrinfo hints, *res, *res0; 339int error; 340int s; 341const char *cause = NULL; 342 343memset(&hints, 0, sizeof(hints)); 344hints.ai_family = PF_UNSPEC; 345hints.ai_socktype = SOCK_STREAM; 346error = getaddrinfo("www.kame.net", "http", &hints, &res0); 347if (error) { 348 errx(1, "%s", gai_strerror(error)); 349 /* NOTREACHED */ 350} 351s = -1; 352for (res = res0; res; res = res->ai_next) { 353 s = socket(res->ai_family, res->ai_socktype, 354 res->ai_protocol); 355 if (s < 0) { 356 cause = "socket"; 357 continue; 358 } 359 360 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { 361 cause = "connect"; 362 close(s); 363 s = -1; 364 continue; 365 } 366 367 break; /* okay we got one */ 368} 369if (s < 0) { 370 err(1, "%s", cause); 371 /* NOTREACHED */ 372} 373freeaddrinfo(res0); 374.Ed 375.Pp 376The following example tries to open a wildcard listening socket onto service 377.Dq Li http , 378for all the address families available. 379.Bd -literal -offset indent 380struct addrinfo hints, *res, *res0; 381int error; 382int s[MAXSOCK]; 383int nsock; 384const char *cause = NULL; 385 386memset(&hints, 0, sizeof(hints)); 387hints.ai_family = PF_UNSPEC; 388hints.ai_socktype = SOCK_STREAM; 389hints.ai_flags = AI_PASSIVE; 390error = getaddrinfo(NULL, "http", &hints, &res0); 391if (error) { 392 errx(1, "%s", gai_strerror(error)); 393 /* NOTREACHED */ 394} 395nsock = 0; 396for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { 397 s[nsock] = socket(res->ai_family, res->ai_socktype, 398 res->ai_protocol); 399 if (s[nsock] < 0) { 400 cause = "socket"; 401 continue; 402 } 403 404 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { 405 cause = "bind"; 406 close(s[nsock]); 407 continue; 408 } 409 (void) listen(s[nsock], 5); 410 411 nsock++; 412} 413if (nsock == 0) { 414 err(1, "%s", cause); 415 /* NOTREACHED */ 416} 417freeaddrinfo(res0); 418.Ed 419.Sh SEE ALSO 420.Xr bind 2 , 421.Xr connect 2 , 422.Xr send 2 , 423.Xr socket 2 , 424.Xr gai_strerror 3 , 425.Xr gethostbyname 3 , 426.Xr getnameinfo 3 , 427.Xr getservbyname 3 , 428.Xr resolver 3 , 429.Xr inet 4 , 430.Xr inet6 4 , 431.Xr unix 4 , 432.Xr hosts 5 , 433.Xr resolv.conf 5 , 434.Xr services 5 , 435.Xr hostname 7 , 436.Xr named 8 437.Rs 438.%A R. Gilligan 439.%A S. Thomson 440.%A J. Bound 441.%A J. McCann 442.%A W. Stevens 443.%T Basic Socket Interface Extensions for IPv6 444.%R RFC 3493 445.%D February 2003 446.Re 447.Rs 448.%A S. Deering 449.%A B. Haberman 450.%A T. Jinmei 451.%A E. Nordmark 452.%A B. Zill 453.%T "IPv6 Scoped Address Architecture" 454.%R RFC 4007 455.%D March 2005 456.Re 457.Rs 458.%A Craig Metz 459.%T Protocol Independence Using the Sockets API 460.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 461.%D June 2000 462.Re 463.Sh STANDARDS 464The 465.Fn getaddrinfo 466function is defined by the 467.St -p1003.1-2004 468specification and documented in 469.Dv "RFC 3493" , 470.Dq Basic Socket Interface Extensions for IPv6 . 471