1.\" $KAME: getaddrinfo.3,v 1.31 2001/08/05 18:19:38 itojun Exp $ 2.\" 3.\" Copyright (c) 1983, 1987, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 35.\" $FreeBSD$ 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.In 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 277The 278.Fn getaddrinfo 279function 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.Vt addrinfo 346structure pointed to by the 347.Fa ai 348argument 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 EXTENSIONS 371This implementation supports numeric IPv6 address notation with the 372experimental scope identifier. 373By appending a percent sign and scope identifier to the address, you 374can specify the value of the 375.Li sin6_scope_id 376field of the socket address. 377This makes management of scoped address easier, 378and allows cut-and-paste input of scoped addresses. 379.Pp 380At the moment the code supports only link-local addresses in this format. 381The scope identifier is hardcoded to name of hardware interface associated 382with the link, 383(such as 384.Li ne0 ) . 385For example, 386.Dq Li fe80::1%ne0 , 387which means 388.Do 389.Li fe80::1 390on the link associated with the 391.Li ne0 392interface 393.Dc . 394.Pp 395This implementation is still very experimental and non-standard. 396The current implementation assumes a one-to-one relationship between 397interfaces and links, which is not necessarily true according to the 398specification. 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 of the address family. 407If the destination resolves to an IPv4 address, it will use an 408.Dv AF_INET 409socket. 410Similarly, if it resolves to IPv6, an 411.Dv AF_INET6 412socket is used. 413Observe that there is no hardcoded reference to particular address family. 414The code works even if 415.Fn 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 errx(1, "%s", gai_strerror(error)); 429 /*NOTREACHED*/ 430} 431s = -1; 432cause = "no addresses"; 433errno = EADDRNOTAVAIL; 434for (res = res0; res; res = res->ai_next) { 435 s = socket(res->ai_family, res->ai_socktype, 436 res->ai_protocol); 437 if (s < 0) { 438 cause = "socket"; 439 continue; 440 } 441 442 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { 443 cause = "connect"; 444 close(s); 445 s = -1; 446 continue; 447 } 448 449 break; /* okay we got one */ 450} 451if (s < 0) { 452 err(1, cause); 453 /*NOTREACHED*/ 454} 455freeaddrinfo(res0); 456.Ed 457.Pp 458The following example tries to open a wildcard listening socket onto service 459.Dq Li http , 460for all the address families available. 461.Bd -literal -offset indent 462struct addrinfo hints, *res, *res0; 463int error; 464int s[MAXSOCK]; 465int nsock; 466const char *cause = NULL; 467 468memset(&hints, 0, sizeof(hints)); 469hints.ai_family = PF_UNSPEC; 470hints.ai_socktype = SOCK_STREAM; 471hints.ai_flags = AI_PASSIVE; 472error = getaddrinfo(NULL, "http", &hints, &res0); 473if (error) { 474 errx(1, "%s", gai_strerror(error)); 475 /*NOTREACHED*/ 476} 477nsock = 0; 478for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { 479 s[nsock] = socket(res->ai_family, res->ai_socktype, 480 res->ai_protocol); 481 if (s[nsock] < 0) { 482 cause = "socket"; 483 continue; 484 } 485 486 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { 487 cause = "bind"; 488 close(s[nsock]); 489 continue; 490 } 491 492 if (listen(s[nsock], SOMAXCONN) < 0) { 493 cause = "listen"; 494 close(s[nsock]); 495 continue; 496 } 497 498 nsock++; 499} 500if (nsock == 0) { 501 err(1, cause); 502 /*NOTREACHED*/ 503} 504freeaddrinfo(res0); 505.Ed 506.\" 507.Sh FILES 508.Bl -tag -width /etc/nsswitch.conf -compact 509.It Pa /etc/hosts 510.It Pa /etc/nsswitch.conf 511.It Pa /etc/resolv.conf 512.El 513.\" 514.Sh DIAGNOSTICS 515Error return status from 516.Fn getaddrinfo 517is zero on success and non-zero on errors. 518Non-zero error codes are defined in 519.In netdb.h , 520and as follows: 521.Pp 522.Bl -tag -width EAI_ADDRFAMILY -compact 523.It Dv EAI_ADDRFAMILY 524Address family for 525.Fa nodename 526not supported. 527.It Dv EAI_AGAIN 528Temporary failure in name resolution. 529.It Dv EAI_BADFLAGS 530Invalid value for 531.Fa ai_flags . 532.It Dv EAI_FAIL 533Non-recoverable failure in name resolution. 534.It Dv EAI_FAMILY 535The 536.Fa ai_family 537address family is 538not supported. 539.It Dv EAI_MEMORY 540Memory allocation failure. 541.It Dv EAI_NODATA 542No address associated with 543.Fa nodename . 544.It Dv EAI_NONAME 545Neither 546.Fa nodename 547nor 548.Fa servname 549provided, or not known. 550.It Dv EAI_SERVICE 551The 552.Fa servname 553service name is 554not supported for 555.Fa ai_socktype . 556.It Dv EAI_SOCKTYPE 557The 558.Fa ai_socktype 559socket type is 560not supported. 561.It Dv EAI_SYSTEM 562System error returned in 563.Va errno . 564.It Dv EAI_BADHINTS 565Invalid value for 566.Fa hints . 567.It Dv EAI_PROTOCOL 568Resolved protocol is unknown. 569.It Dv EAI_MAX 570Unknown error. 571.El 572.Pp 573If called with an appropriate argument, 574.Fn gai_strerror 575returns a pointer to a string describing the given error code. 576If the argument is not one of the 577.Dv EAI_xxx 578values, the function still returns a pointer to a string whose contents 579indicate an unknown error. 580.\" 581.Sh SEE ALSO 582.Xr gethostbyname 3 , 583.Xr getnameinfo 3 , 584.Xr getservbyname 3 , 585.Xr hosts 5 , 586.Xr resolv.conf 5 , 587.Xr services 5 , 588.Xr hostname 7 , 589.Xr named 8 590.Pp 591.Rs 592.%A R. Gilligan 593.%A S. Thomson 594.%A J. Bound 595.%A W. Stevens 596.%T Basic Socket Interface Extensions for IPv6 597.%R RFC2553 598.%D March 1999 599.Re 600.Rs 601.%A Tatsuya Jinmei 602.%A Atsushi Onoe 603.%T "An Extension of Format for IPv6 Scoped Addresses" 604.%R internet draft 605.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 606.%O work in progress material 607.Re 608.Rs 609.%A Craig Metz 610.%T Protocol Independence Using the Sockets API 611.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 612.%D June 2000 613.Re 614.\" 615.Sh HISTORY 616The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. 617.\" 618.Sh STANDARDS 619The 620.Fn getaddrinfo 621function is defined in 622.St -p1003.1g-2000 , 623and documented in 624.Dq Basic Socket Interface Extensions for IPv6 625(RFC2553). 626.\" 627.Sh BUGS 628Though the current implementation should be thread-safe, using 629.Fn getaddrinfo 630in conjunction with 631.Fn gethostby* 632breaks thread-safeness. 633.Pp 634The text was shamelessly copied from RFC2553. 635