1.\" $NetBSD: getaddrinfo.3,v 1.17 2000/11/16 07:28:15 lukem Exp $ 2.\" $KAME: getaddrinfo.3,v 1.22 2000/08/09 21:16:17 itojun Exp $ 3.\" 4.\" Copyright (c) 1983, 1987, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 36.\" 37.Dd May 25, 1995 38.Dt GETADDRINFO 3 39.Os 40.\" 41.Sh NAME 42.Nm getaddrinfo , 43.Nm freeaddrinfo , 44.Nm gai_strerror 45.Nd nodename-to-address translation in protocol-independent manner 46.\" 47.Sh LIBRARY 48.Lb libc 49.\" 50.Sh SYNOPSIS 51.Fd #include <sys/types.h> 52.Fd #include <sys/socket.h> 53.Fd #include <netdb.h> 54.Ft int 55.Fn getaddrinfo "const char *nodename" "const char *servname" \ 56"const struct addrinfo *hints" "struct addrinfo **res" 57.Ft void 58.Fn freeaddrinfo "struct addrinfo *ai" 59.Ft "char *" 60.Fn gai_strerror "int ecode" 61.\" 62.Sh DESCRIPTION 63The 64.Fn getaddrinfo 65function is defined for protocol-independent nodename-to-address translation. 66It performs the functionality of 67.Xr gethostbyname 3 68and 69.Xr getservbyname 3 , 70but in a more sophisticated manner. 71.Pp 72The 73.Li addrinfo 74structure is defined as a result of including the 75.Aq Pa netdb.h 76header: 77.Bd -literal -offset 78struct addrinfo { * 79 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ 80 int ai_family; /* PF_xxx */ 81 int ai_socktype; /* SOCK_xxx */ 82 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 83 size_t ai_addrlen; /* length of ai_addr */ 84 char *ai_canonname; /* canonical name for nodename */ 85 struct sockaddr *ai_addr; /* binary address */ 86 struct addrinfo *ai_next; /* next structure in linked list */ 87}; 88.Ed 89.Pp 90The 91.Fa nodename 92and 93.Fa servname 94arguments are pointers to null-terminated strings or 95.Dv NULL . 96One or both of these two arguments must be a 97.Pf non Dv -NULL 98pointer. 99In the normal client scenario, both the 100.Fa nodename 101and 102.Fa servname 103are specified. 104In the normal server scenario, only the 105.Fa servname 106is specified. 107A 108.Pf non Dv -NULL 109.Fa nodename 110string can be either a node name or a numeric host address string 111.Po 112i.e., a dotted-decimal IPv4 address or an IPv6 hex address 113.Pc . 114A 115.Pf non Dv -NULL 116.Fa servname 117string can be either a service name or a decimal port number. 118.Pp 119The caller can optionally pass an 120.Li addrinfo 121structure, pointed to by the third argument, 122to provide hints concerning the type of socket that the caller supports. 123In this 124.Fa hints 125structure all members other than 126.Fa ai_flags , 127.Fa ai_family , 128.Fa ai_socktype , 129and 130.Fa ai_protocol 131must be zero or a 132.Dv NULL 133pointer. 134A value of 135.Dv PF_UNSPEC 136for 137.Fa ai_family 138means the caller will accept any protocol family. 139A value of 0 for 140.Fa ai_socktype 141means the caller will accept any socket type. 142A value of 0 for 143.Fa ai_protocol 144means the caller will accept any protocol. 145For example, if the caller handles only TCP and not UDP, then the 146.Fa ai_socktype 147member of the hints structure should be set to 148.Dv SOCK_STREAM 149when 150.Fn getaddrinfo 151is called. 152If the caller handles only IPv4 and not IPv6, then the 153.Fa ai_family 154member of the 155.Fa hints 156structure should be set to 157.Dv PF_INET 158when 159.Fn getaddrinfo 160is called. 161If the third argument to 162.Fn getaddrinfo 163is a 164.Dv NULL 165pointer, this is the same as if the caller had filled in an 166.Li addrinfo 167structure initialized to zero with 168.Fa ai_family 169set to 170.Dv PF_UNSPEC . 171.Pp 172Upon successful return a pointer to a linked list of one or more 173.Li addrinfo 174structures is returned through the final argument. 175The caller can process each 176.Li addrinfo 177structure in this list by following the 178.Fa ai_next 179pointer, until a 180.Dv NULL 181pointer is encountered. 182In each returned 183.Li addrinfo 184structure the three members 185.Fa ai_family , 186.Fa ai_socktype , 187and 188.Fa ai_protocol 189are the corresponding arguments for a call to the 190.Fn socket 191function. 192In each 193.Li addrinfo 194structure the 195.Fa ai_addr 196member points to a filled-in socket address structure whose length is 197specified by the 198.Fa ai_addrlen 199member. 200.Pp 201If the 202.Dv AI_PASSIVE 203bit is set in the 204.Fa ai_flags 205member of the 206.Fa hints 207structure, then the caller plans to use the returned socket address 208structure in a call to 209.Fn bind . 210In this case, if the 211.Fa nodename 212argument is a 213.Dv NULL 214pointer, then the IP address portion of the socket 215address structure will be set to 216.Dv INADDR_ANY 217for an IPv4 address or 218.Dv IN6ADDR_ANY_INIT 219for an IPv6 address. 220.Pp 221If the 222.Dv AI_PASSIVE 223bit is not set in the 224.Fa ai_flags 225member of the 226.Fa hints 227structure, then the returned socket address structure will be ready for a 228call to 229.Fn connect 230.Pq for a connection-oriented protocol 231or either 232.Fn connect , 233.Fn sendto , 234or 235.Fn sendmsg 236.Pq for a connectionless protocol . 237In this case, if the 238.Fa nodename 239argument is a 240.Dv NULL 241pointer, then the IP address portion of the 242socket address structure will be set to the loopback address. 243.Pp 244If the 245.Dv AI_CANONNAME 246bit is set in the 247.Fa ai_flags 248member of the 249.Fa hints 250structure, then upon successful return the 251.Fa ai_canonname 252member of the first 253.Li addrinfo 254structure in the linked list will point to a null-terminated string 255containing the canonical name of the specified 256.Fa nodename . 257.Pp 258If the 259.Dv AI_NUMERICHOST 260bit is set in the 261.Fa ai_flags 262member of the 263.Fa hints 264structure, then a 265.Pf non Dv -NULL 266.Fa nodename 267string must be a numeric host address string. 268Otherwise an error of 269.Dv EAI_NONAME 270is returned. 271This flag prevents any type of name resolution service (e.g., the DNS) 272from being called. 273.Pp 274The arguments to 275.Fn getaddrinfo 276must sufficiently be consistent and unambiguous. 277Here are pitfall cases you may encounter: 278.Bl -bullet 279.It 280.Fn getaddrinfo 281will raise an error if members of the 282.Fa hints 283structure are not consistent. 284For example, for internet address families, 285.Fn getaddrinfo 286will raise an error if you specify 287.Dv SOCK_STREAM 288to 289.Fa ai_socktype 290while you specify 291.Dv IPPROTO_UDP 292to 293.Fa ai_protocol . 294.It 295If you specify a 296.Fa servname 297which is defined only for certain 298.Fa ai_socktype , 299.Fn getaddrinfo 300will raise an error because the arguments are not consistent. 301For example, 302.Fn getaddrinfo 303will raise an error if you ask for 304.Dq Li tftp 305service on 306.Dv SOCK_STREAM . 307.It 308For internet address families, if you specify 309.Fa servname 310while you set 311.Fa ai_socktype 312to 313.Dv SOCK_RAW , 314.Fn getaddrinfo 315will raise an error, because service names are not defined for the internet 316.Dv SOCK_RAW 317space. 318.It 319If you specify a numeric 320.Fa servname , 321while leaving 322.Fa ai_socktype 323and 324.Fa ai_protocol 325unspecified, 326.Fn getaddrinfo 327will raise an error. 328This is because the numeric 329.Fa servname 330does not identify any socket type, and 331.Fn getaddrinfo 332is not allowed to glob the argument in such case. 333.El 334.Pp 335All of the information returned by 336.Fn getaddrinfo 337is dynamically allocated: 338the 339.Li addrinfo 340structures, the socket address structures, and canonical node name 341strings pointed to by the addrinfo structures. 342To return this information to the system the function 343.Fn freeaddrinfo 344is called. 345The 346.Fa addrinfo 347structure pointed to by the 348.Fa ai argument 349is freed, along with any dynamic storage pointed to by the structure. 350This operation is repeated until a 351.Dv NULL 352.Fa ai_next 353pointer is encountered. 354.Pp 355To aid applications in printing error messages based on the 356.Dv EAI_xxx 357codes returned by 358.Fn getaddrinfo , 359.Fn gai_strerror 360is defined. 361The argument is one of the 362.Dv EAI_xxx 363values defined earlier and the return value points to a string describing 364the error. 365If the argument is not one of the 366.Dv EAI_xxx 367values, the function still returns a pointer to a string whose contents 368indicate an unknown error. 369.\" 370.Sh EXTENSION 371The implementation allows experimental numeric IPv6 address notation with 372scope identifier. 373By appending atmark and scope identifier to addresses, you can fill 374.Li sin6_scope_id 375field for addresses. 376This would make management of scoped address easier, 377and allows cut-and-paste input of scoped address. 378.Pp 379At this moment the code supports only link-local addresses with the format. 380Scope identifier is hardcoded to name of hardware interface associated 381with the link. 382.Po 383such as 384.Li ne0 385.Pc . 386Example would be like 387.Dq Li fe80::1%ne0 , 388which means 389.Do 390.Li fe80::1 391on the link associated with 392.Li ne0 393interface 394.Dc . 395.Pp 396The implementation is still very experimental and non-standard. 397The current implementation assumes one-by-one relationship between 398interface and link, which is not necessarily true from the specification. 399.\" 400.Sh EXAMPLES 401The following code tries to connect to 402.Dq Li www.kame.net 403service 404.Dq Li http . 405via stream socket. 406It loops through all the addresses available, regardless from address family. 407If the destination resolves to IPv4 address, it will use 408.Dv AF_INET 409socket. 410Similarly, if it resolves to IPv6, 411.Dv AF_INET6 412socket is used. 413Observe that there is no hardcoded reference to particular address family. 414The code works even if 415.Nm getaddrinfo 416returns addresses that are not IPv4/v6. 417.Bd -literal -offset indent 418struct addrinfo hints, *res, *res0; 419int error; 420int s; 421const char *cause = NULL; 422 423memset(&hints, 0, sizeof(hints)); 424hints.ai_family = PF_UNSPEC; 425hints.ai_socktype = SOCK_STREAM; 426error = getaddrinfo("www.kame.net", "http", &hints, &res0); 427if (error) { 428 err1(1, "%s", gai_strerror(error)); 429 /*NOTREACHED*/ 430} 431s = -1; 432for (res = res0; res; res = res->ai_next) { 433 s = socket(res->ai_family, res->ai_socktype, 434 res->ai_protocol); 435 if (s < 0) { 436 cause = "socket"; 437 continue; 438 } 439 440 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { 441 cause = "connect"; 442 close(s); 443 s = -1; 444 continue; 445 } 446 447 break; /* okay we got one */ 448} 449if (s < 0) { 450 err(1, cause); 451 /*NOTREACHED*/ 452} 453freeaddrinfo(res0); 454.Ed 455.Pp 456The following example tries to open wildcard listening socket onto service 457.Dq Li http , 458for all the address families available. 459.Bd -literal -offset indent 460struct addrinfo hints, *res, *res0; 461int error; 462int s[MAXSOCK]; 463int nsock; 464const char *cause = NULL; 465 466memset(&hints, 0, sizeof(hints)); 467hints.ai_family = PF_UNSPEC; 468hints.ai_socktype = SOCK_STREAM; 469hints.ai_flags = AI_PASSIVE; 470error = getaddrinfo(NULL, "http", &hints, &res0); 471if (error) { 472 err1(1, "%s", gai_strerror(error)); 473 /*NOTREACHED*/ 474} 475nsock = 0; 476for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { 477 s[nsock] = socket(res->ai_family, res->ai_socktype, 478 res->ai_protocol); 479 if (s[nsock] < 0) { 480 cause = "socket"; 481 continue; 482 } 483 484 if (connect(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { 485 cause = "connect"; 486 close(s[nsock]); 487 continue; 488 } 489 490 nsock++; 491} 492if (nsock == 0) { 493 err(1, cause); 494 /*NOTREACHED*/ 495} 496freeaddrinfo(res0); 497.Ed 498.\" 499.Sh FILES 500.Bl -tag -width /etc/resolv.conf -compact 501.It Pa /etc/hosts 502.It Pa /etc/host.conf 503.It Pa /etc/resolv.conf 504.El 505.\" 506.Sh DIAGNOSTICS 507Error return status from 508.Fn getaddrinfo 509is zero on success and non-zero on errors. 510Non-zero error codes are defined in 511.Aq Pa netdb.h , 512and as follows: 513.Pp 514.Bl -tag -width EAI_ADDRFAMILY -compact 515.It Dv EAI_ADDRFAMILY 516Address family for 517.Fa nodename 518not supported. 519.It Dv EAI_AGAIN 520Temporary failure in name resolution. 521.It Dv EAI_BADFLAGS 522Invalid value for 523.Fa ai_flags . 524.It Dv EAI_FAIL 525Non-recoverable failure in name resolution. 526.It Dv EAI_FAMILY 527.Fa ai_family 528not supported. 529.It Dv EAI_MEMORY 530Memory allocation failure. 531.It Dv EAI_NODATA 532No address associated with 533.Fa nodename . 534.It Dv EAI_NONAME 535.Fa nodename 536nor 537.Fa servname 538provided, or not known. 539.It Dv EAI_SERVICE 540.Fa servname 541not supported for 542.Fa ai_socktype . 543.It Dv EAI_SOCKTYPE 544.Fa ai_socktype 545not supported. 546.It Dv EAI_SYSTEM 547System error returned in 548.Va errno . 549.El 550.Pp 551If called with proper argument, 552.Fn gai_strerror 553returns a pointer to a string describing the given error code. 554If the argument is not one of the 555.Dv EAI_xxx 556values, the function still returns a pointer to a string whose contents 557indicate an unknown error. 558.\" 559.Sh SEE ALSO 560.Xr getnameinfo 3 , 561.Xr gethostbyname 3 , 562.Xr getservbyname 3 , 563.Xr hosts 5 , 564.Xr services 5 , 565.Xr hostname 7 , 566.Xr named 8 567.Pp 568.Rs 569.%A R. Gilligan 570.%A S. Thomson 571.%A J. Bound 572.%A W. Stevens 573.%T Basic Socket Interface Extensions for IPv6 574.%R RFC2553 575.%D March 1999 576.Re 577.Rs 578.%A Tatsuya Jinmei 579.%A Atsushi Onoe 580.%T "An Extension of Format for IPv6 Scoped Addresses" 581.%R internet draft 582.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 583.%O work in progress material 584.Re 585.Rs 586.%A Craig Metz 587.%T Protocol Independence Using the Sockets API 588.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 589.%D June 2000 590.Re 591.\" 592.Sh HISTORY 593The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. 594.\" 595.Sh STANDARDS 596The 597.Fn getaddrinfo 598function is defined IEEE POSIX 1003.1g draft specification, 599and documented in 600.Dq Basic Socket Interface Extensions for IPv6 601.Pq RFC2553 . 602.\" 603.Sh BUGS 604The current implementation is not thread-safe. 605.Pp 606The text was shamelessly copied from RFC2553. 607