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