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