1.\" $NetBSD: getaddrinfo.3,v 1.58 2015/12/13 14:54:17 christos Exp $ 2.\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $ 3.\" $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $ 4.\" 5.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") 6.\" Copyright (C) 2000, 2001 Internet Software Consortium. 7.\" 8.\" Permission to use, copy, modify, and distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 13.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 14.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 15.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 16.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 17.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 18.\" PERFORMANCE OF THIS SOFTWARE. 19.\" 20.Dd December 13, 2015 21.Dt GETADDRINFO 3 22.Os 23.Sh NAME 24.Nm getaddrinfo , 25.Nm freeaddrinfo , 26.Nm allocaddrinfo 27.Nd host and service name to socket address structure 28.Sh SYNOPSIS 29.In netdb.h 30.Ft int 31.Fn getaddrinfo "const char * restrict hostname" \ 32 "const char * restrict servname" \ 33 "const struct addrinfo * restrict hints" "struct addrinfo ** restrict res" 34.Ft void 35.Fn freeaddrinfo "struct addrinfo *ai" 36.Ft struct addrinfo * 37.Fn allocaddrinfo "socklen_t len" 38.Sh DESCRIPTION 39The 40.Fn getaddrinfo 41function is used to get a list of 42.Tn IP 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 or an IPv6 address. 62The 63.Fa servname 64is either a decimal port number or a service name listed in 65.Xr services 5 . 66At least one of 67.Fa hostname 68and 69.Fa servname 70must be non-null. 71.Pp 72.Fa hints 73is an optional pointer to a 74.Li struct addrinfo , 75as defined by 76.In netdb.h : 77.Bd -literal 78struct addrinfo { 79 int ai_flags; /* input flags */ 80 int ai_family; /* address family for socket */ 81 int ai_socktype; /* socket type */ 82 int ai_protocol; /* protocol for socket */ 83 socklen_t ai_addrlen; /* length of socket-address */ 84 struct sockaddr *ai_addr; /* socket-address for socket */ 85 char *ai_canonname; /* canonical name for service location */ 86 struct addrinfo *ai_next; /* pointer to next in list */ 87}; 88.Ed 89.Pp 90This structure can be used to provide hints concerning the type of socket 91that the caller supports or wishes to use. 92The caller can supply the following structure elements in 93.Fa hints : 94.Bl -tag -width "ai_socktypeXX" 95.It Fa ai_family 96The address 97.Pq and protocol 98family 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. 105Note that while address families 106.Pq Dv AF_* 107and protocol families 108.Pq Dv PF_* 109are theoretically distinct, in practice the distinction has been lost. 110.\" (.Dv !? Consistent with usage below though...) 111.Dv "RFC 3493" 112defines 113.Fn getaddrinfo 114in terms of the address family constants 115.Dv AF_* 116even though 117.Fa ai_family 118is to be passed as a protocol family to 119.Xr socket 2 . 120.It Fa ai_socktype 121Denotes the type of socket that is wanted: 122.Dv SOCK_STREAM , 123.Dv SOCK_DGRAM , 124or 125.Dv SOCK_RAW . 126When 127.Fa ai_socktype 128is zero the caller will accept any socket type. 129.It Fa ai_protocol 130Indicates which transport protocol is desired, 131.Dv IPPROTO_UDP 132or 133.Dv IPPROTO_TCP . 134If 135.Fa ai_protocol 136is zero the caller will accept any protocol. 137.It Fa ai_flags 138.Fa ai_flags 139is formed by 140.Tn OR Ns 'ing 141the following values: 142.Bl -tag -width "AI_CANONNAMEXX" 143.It Dv AI_CANONNAME 144If the 145.Dv AI_CANONNAME 146bit is set, a successful call to 147.Fn getaddrinfo 148will return a NUL-terminated string containing the canonical name 149of the specified hostname in the 150.Fa ai_canonname 151element of the first 152.Li addrinfo 153structure returned. 154.It Dv AI_NUMERICHOST 155If the 156.Dv AI_NUMERICHOST 157bit is set, it indicates that 158.Fa hostname 159should be treated as a numeric string defining an IPv4 or IPv6 address 160and no name resolution should be attempted. 161.It Dv AI_NUMERICSERV 162If the 163.Dv AI_NUMERICSERV 164bit is set, it indicates that the 165.Fa servname 166string contains a numeric port number. 167This is used to prevent service name resolution. 168.It Dv AI_PASSIVE 169If the 170.Dv AI_PASSIVE 171bit is set it indicates that the returned socket address structure 172is intended for use in a call to 173.Xr bind 2 . 174In this case, if the 175.Fa hostname 176argument is the null pointer, then the IP address portion of the 177socket address structure will be set to 178.Dv INADDR_ANY 179for an IPv4 address or 180.Dv IN6ADDR_ANY_INIT 181for an IPv6 address. 182.Pp 183If the 184.Dv AI_PASSIVE 185bit is not set, the returned socket address structure will be ready 186for use in a call to 187.Xr connect 2 188for a connection-oriented protocol or 189.Xr connect 2 , 190.Xr sendto 2 , 191or 192.Xr sendmsg 2 193if a connectionless protocol was chosen. 194The 195.Tn IP 196address portion of the socket address structure will be set to the 197loopback address if 198.Fa hostname 199is the null pointer and 200.Dv AI_PASSIVE 201is not set. 202.It Dv AI_SRV 203Perform SRV (RFC 2782) record lookups first. 204This is a non-portable extension. 205.El 206.El 207.Pp 208All other elements of the 209.Li addrinfo 210structure passed via 211.Fa hints 212must be zero or the null pointer. 213.Pp 214If 215.Fa hints 216is the null pointer, 217.Fn getaddrinfo 218behaves as if the caller provided a 219.Li struct addrinfo 220with 221.Fa ai_family 222set to 223.Dv AF_UNSPEC 224and all other elements set to zero or 225.Dv NULL . 226.Pp 227After a successful call to 228.Fn getaddrinfo , 229.Fa *res 230is a pointer to a linked list of one or more 231.Li addrinfo 232structures. 233The list can be traversed by following the 234.Fa ai_next 235pointer in each 236.Li addrinfo 237structure until a null pointer is encountered. 238The three members 239.Fa ai_family , 240.Fa ai_socktype , 241and 242.Fa ai_protocol 243in each returned 244.Li addrinfo 245structure are suitable for a call to 246.Xr socket 2 . 247For each 248.Li addrinfo 249structure in the list, the 250.Fa ai_addr 251member points to a filled-in socket address structure of length 252.Fa ai_addrlen . 253.Pp 254By default IPv6 address entries are ordered before IPv4 ones, but 255the order of the entries in the list can be controlled using 256.Xr ip6addrctl 8 . 257.Pp 258This implementation of 259.Fn getaddrinfo 260allows numeric IPv6 address notation with scope identifier, 261as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. 262By appending the percent character and scope identifier to addresses, 263one can fill the 264.Li sin6_scope_id 265field for addresses. 266This would make management of scoped addresses easier 267and allows cut-and-paste input of scoped addresses. 268.Pp 269At this moment the code supports only link-local addresses with the format. 270The scope identifier is hardcoded to the name of the hardware interface 271associated 272with the link 273.Po 274such as 275.Li ne0 276.Pc . 277An example is 278.Dq Li fe80::1%ne0 , 279which means 280.Do 281.Li fe80::1 282on the link associated with the 283.Li ne0 284interface 285.Dc . 286.Pp 287The current implementation assumes a one-to-one relationship between 288the interface and link, which is not necessarily true from the specification. 289.Pp 290All of the information returned by 291.Fn getaddrinfo 292is dynamically allocated: the 293.Li addrinfo 294structures themselves as well as the socket address structures and 295the canonical host name strings included in the 296.Li addrinfo 297structures. 298.Pp 299Memory allocated for the dynamically allocated structures created by 300a successful call to 301.Fn getaddrinfo 302is released by the 303.Fn freeaddrinfo 304function. 305The 306.Fa ai 307pointer should be an 308.Li addrinfo 309structure created by a call to 310.Fn getaddrinfo 311or 312.Fn allocaddrinfo . 313The 314.Fn allocaddrinfo 315function is intended primarily for authors of 316.Xr nsdispatch 3 317plugins implementing 318.Fn getaddrinfo 319backends. 320.Fn allocaddrinfo 321allocates a 322.Li struct addrinfo 323in a way that is compatible with being returned from 324.Fn getaddrinfo 325and being ultimately freed by 326.Fn freeaddrinfo . 327The returned structure is zeroed, except for the 328.Fa ai_addr 329field, which 330will point to 331.Fa len 332bytes of memory for storage of a socket address. 333It is safe to allocate memory separately for 334.Fa ai_canonname 335with 336.Xr malloc 3 , 337or in any other way that is compatible with deallocation by 338.Xr free 3 . 339.Sh RETURN VALUES 340.Fn getaddrinfo 341returns zero on success or one of the error codes listed in 342.Xr gai_strerror 3 343if an error occurs. 344.Sh EXAMPLES 345The following code tries to connect to 346.Dq Li www.kame.net 347service 348.Dq Li http 349via a stream socket. 350It loops through all the addresses available, regardless of address family. 351If the destination resolves to an IPv4 address, it will use an 352.Dv AF_INET 353socket. 354Similarly, if it resolves to IPv6, an 355.Dv AF_INET6 356socket is used. 357Observe that there is no hardcoded reference to a particular address family. 358The code works even if 359.Fn getaddrinfo 360returns addresses that are not IPv4/v6. 361.Bd -literal -offset indent 362struct addrinfo hints, *res, *res0; 363int error; 364int s; 365const char *cause = NULL; 366 367memset(\*[Am]hints, 0, sizeof(hints)); 368hints.ai_family = AF_UNSPEC; 369hints.ai_socktype = SOCK_STREAM; 370error = getaddrinfo("www.kame.net", "http", \*[Am]hints, \*[Am]res0); 371if (error) { 372 errx(1, "%s", gai_strerror(error)); 373 /*NOTREACHED*/ 374} 375s = -1; 376for (res = res0; res; res = res-\*[Gt]ai_next) { 377 s = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, 378 res-\*[Gt]ai_protocol); 379 if (s \*[Lt] 0) { 380 cause = "socket"; 381 continue; 382 } 383 384 if (connect(s, res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { 385 cause = "connect"; 386 close(s); 387 s = -1; 388 continue; 389 } 390 391 break; /* okay we got one */ 392} 393if (s \*[Lt] 0) { 394 err(1, "%s", cause); 395 /*NOTREACHED*/ 396} 397freeaddrinfo(res0); 398.Ed 399.Pp 400The following example tries to open a wildcard listening socket onto service 401.Dq Li http , 402for all the address families available. 403.Bd -literal -offset indent 404struct addrinfo hints, *res, *res0; 405int error; 406int s[MAXSOCK]; 407int nsock; 408const char *cause = NULL; 409 410memset(\*[Am]hints, 0, sizeof(hints)); 411hints.ai_family = AF_UNSPEC; 412hints.ai_socktype = SOCK_STREAM; 413hints.ai_flags = AI_PASSIVE; 414error = getaddrinfo(NULL, "http", \*[Am]hints, \*[Am]res0); 415if (error) { 416 errx(1, "%s", gai_strerror(error)); 417 /*NOTREACHED*/ 418} 419nsock = 0; 420for (res = res0; res \*[Am]\*[Am] nsock \*[Lt] MAXSOCK; res = res-\*[Gt]ai_next) { 421 s[nsock] = socket(res-\*[Gt]ai_family, res-\*[Gt]ai_socktype, 422 res-\*[Gt]ai_protocol); 423 if (s[nsock] \*[Lt] 0) { 424 cause = "socket"; 425 continue; 426 } 427 428 if (bind(s[nsock], res-\*[Gt]ai_addr, res-\*[Gt]ai_addrlen) \*[Lt] 0) { 429 cause = "bind"; 430 close(s[nsock]); 431 continue; 432 } 433 (void) listen(s[nsock], 5); 434 435 nsock++; 436} 437if (nsock == 0) { 438 err(1, "%s", cause); 439 /*NOTREACHED*/ 440} 441freeaddrinfo(res0); 442.Ed 443.Sh SEE ALSO 444.Xr bind 2 , 445.Xr connect 2 , 446.Xr send 2 , 447.Xr socket 2 , 448.Xr gai_strerror 3 , 449.Xr gethostbyname 3 , 450.Xr getnameinfo 3 , 451.Xr getservbyname 3 , 452.Xr resolver 3 , 453.Xr hosts 5 , 454.Xr resolv.conf 5 , 455.Xr services 5 , 456.Xr hostname 7 , 457.Xr ip6addrctl 8 , 458.Xr named 8 459.Rs 460.%A R. Gilligan 461.%A S. Thomson 462.%A J. Bound 463.%A J. McCann 464.%A W. Stevens 465.%T Basic Socket Interface Extensions for IPv6 466.%R RFC 3493 467.%D February 2003 468.Re 469.Rs 470.%A S. Deering 471.%A B. Haberman 472.%A T. Jinmei 473.%A E. Nordmark 474.%A B. Zill 475.%T "IPv6 Scoped Address Architecture" 476.%R internet draft 477.%N draft-ietf-ipv6-scoping-arch-02.txt 478.%O work in progress material 479.Re 480.Rs 481.%A Craig Metz 482.%T "Protocol Independence Using the Sockets API" 483.%I USENIX Association 484.%B Proceedings of the FREENIX Track: 2000 USENIX Annual Technical Conference 485.%D June 18-23, 2000 486.%P 99-108 487.%U http://www.usenix.org/events/usenix2000/freenix/metzprotocol/metzprotocol.pdf 488.Re 489.Sh STANDARDS 490The 491.Fn getaddrinfo 492function is defined by the 493.St -p1003.1g-2000 494draft specification and documented in 495.Dv "RFC 3493" , 496.Dq Basic Socket Interface Extensions for IPv6 . 497