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