1.\" Copyright (c) 1983, 1987, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 33.\" $Id: getaddrinfo.3,v 1.3 1999/10/07 08:22:04 jinmei Exp $ 34.\" $FreeBSD$ 35.\" 36.Dd May 25, 1995 37.Dt GETADDRINFO 3 38.Os KAME 39.\" 40.Sh NAME 41.Nm getaddrinfo 42.Nm freeaddrinfo , 43.Nm gai_strerror 44.Nd nodename-to-address translation in protocol-independent manner 45.\" 46.Sh SYNOPSIS 47.Fd #include <sys/types.h> 48.Fd #include <sys/socket.h> 49.Fd #include <netdb.h> 50.Ft int 51.Fn getaddrinfo "const char *nodename" "const char *servname" "const struct addrinfo *hints" "struct addrinfo **res" 52.Ft void 53.Fn freeaddrinfo "struct addrinfo *ai" 54.Ft "char *" 55.Fn gai_strerror "int ecode" 56.\" 57.Sh DESCRIPTION 58The 59.Fn getaddrinfo 60function is defined for protocol-independent nodename-to-address translation. 61It performs functionality of 62.Xr gethostbyname 3 63and 64.Xr getservbyname 3 , 65in more sophisticated manner. 66.Pp 67The addrinfo structure is defined as a result of including the 68.Li <netdb.h> 69header: 70.Bd -literal -offset 71struct addrinfo { * 72 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ 73 int ai_family; /* PF_xxx */ 74 int ai_socktype; /* SOCK_xxx */ 75 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 76 size_t ai_addrlen; /* length of ai_addr */ 77 char *ai_canonname; /* canonical name for nodename */ 78 struct sockaddr *ai_addr; /* binary address */ 79 struct addrinfo *ai_next; /* next structure in linked list */ 80}; 81.Ed 82.Pp 83The 84.Fa nodename 85and 86.Fa servname 87arguments are pointers to null-terminated strings or 88.Dv NULL . 89One or both of these two arguments must be a 90.Pf non Dv -NULL 91pointer. 92In the normal client scenario, both the 93.Fa nodename 94and 95.Fa servname 96are specified. 97In the normal server scenario, only the 98.Fa servname 99is specified. 100A 101.Pf non Dv -NULL 102.Fa nodename 103string can be either a node name or a numeric host address string 104.Po 105i.e., a dotted-decimal IPv4 address or an IPv6 hex address 106.Pc . 107A 108.Pf non Dv -NULL 109.Fa servname 110string can be either a service name or a decimal port number. 111.Pp 112The caller can optionally pass an 113.Li addrinfo 114structure, pointed to by the third argument, 115to provide hints concerning the type of socket that the caller supports. 116In this 117.Fa hints 118structure all members other than 119.Fa ai_flags , 120.Fa ai_family , 121.Fa ai_socktype , 122and 123.Fa ai_protocol 124must be zero or a 125.Dv NULL 126pointer. 127A value of 128.Dv PF_UNSPEC 129for 130.Fa ai_family 131means the caller will accept any protocol family. 132A value of 0 for 133.Fa ai_socktype 134means the caller will accept any socket type. 135A value of 0 for 136.Fa ai_protocol 137means the caller will accept any protocol. 138For example, if the caller handles only TCP and not UDP, then the 139.Fa ai_socktype 140member of the hints structure should be set to 141.Dv SOCK_STREAM 142when 143.Fn getaddrinfo 144is called. 145If the caller handles only IPv4 and not IPv6, then the 146.Fa ai_family 147member of the 148.Fa hints 149structure should be set to 150.Dv PF_INET 151when 152.Fn getaddrinfo 153is called. 154If the third argument to 155.Fn getaddrinfo 156is a 157.Dv NULL 158pointer, this is the same as if the caller had filled in an 159.Li addrinfo 160structure initialized to zero with 161.Fa ai_family 162set to PF_UNSPEC. 163.Pp 164Upon successful return a pointer to a linked list of one or more 165.Li addrinfo 166structures is returned through the final argument. 167The caller can process each 168.Li addrinfo 169structure in this list by following the 170.Fa ai_next 171pointer, until a 172.Dv NULL 173pointer is encountered. 174In each returned 175.Li addrinfo 176structure the three members 177.Fa ai_family , 178.Fa ai_socktype , 179and 180.Fa ai_protocol 181are the corresponding arguments for a call to the 182.Fn socket 183function. 184In each 185.Li addrinfo 186structure the 187.Fa ai_addr 188member points to a filled-in socket address structure whose length is 189specified by the 190.Fa ai_addrlen 191member. 192.Pp 193If the 194.Dv AI_PASSIVE 195bit is set in the 196.Fa ai_flags 197member of the 198.Fa hints 199structure, then the caller plans to use the returned socket address 200structure in a call to 201.Fn bind . 202In this case, if the 203.Fa nodename 204argument is a 205.Dv NULL 206pointer, then the IP address portion of the socket 207address structure will be set to 208.Dv INADDR_ANY 209for an IPv4 address or 210.Dv IN6ADDR_ANY_INIT 211for an IPv6 address. 212.Pp 213If the 214.Dv AI_PASSIVE 215bit is not set in the 216.Fa ai_flags 217member of the 218.Fa hints 219structure, then the returned socket address structure will be ready for a 220call to 221.Fn connect 222.Pq for a connection-oriented protocol 223or either 224.Fn connect , 225.Fn sendto , or 226.Fn sendmsg 227.Pq for a connectionless protocol . 228In this case, if the 229.Fa nodename 230argument is a 231.Dv NULL 232pointer, then the IP address portion of the 233socket address structure will be set to the loopback address. 234.Pp 235If the 236.Dv AI_CANONNAME 237bit is set in the 238.Fa ai_flags 239member of the 240.Fa hints 241structure, then upon successful return the 242.Fa ai_canonname 243member of the first 244.Li addrinfo 245structure in the linked list will point to a null-terminated string 246containing the canonical name of the specified 247.Fa nodename . 248.Pp 249If the 250.Dv AI_NUMERICHOST 251bit is set in the 252.Fa ai_flags 253member of the 254.Fa hints 255structure, then a 256.Pf non Dv -NULL 257.Fa nodename 258string must be a numeric host address string. 259Otherwise an error of 260.Dv EAI_NONAME 261is returned. 262This flag prevents any type of name resolution service (e.g., the DNS) 263from being called. 264.Pp 265All of the information returned by 266.Fn getaddrinfo 267is dynamically allocated: 268the 269.Li addrinfo 270structures, and the socket address structures and canonical node name 271strings pointed to by the addrinfo structures. 272To return this information to the system the function 273.Fn freeaddrinfo 274is called. 275The 276.Fa addrinfo 277structure pointed to by the 278.Fa ai argument 279is freed, along with any dynamic storage pointed to by the structure. 280This operation is repeated until a 281.Dv NULL 282.Fa ai_next 283pointer is encountered. 284.Pp 285To aid applications in printing error messages based on the 286.Dv EAI_xxx 287codes returned by 288.Fn getaddrinfo , 289.Fn gai_strerror 290is defined. 291The argument is one of the 292.Dv EAI_xxx 293values defined earlier and the return value points to a string describing 294the error. 295If the argument is not one of the 296.Dv EAI_xxx 297values, the function still returns a pointer to a string whose contents 298indicate an unknown error. 299.\" 300.Sh EXTENSION 301The implementation allows experimental numeric IPv6 address notation with 302scope identifier. 303By appending atmark and scope identifier to addresses, you can fill 304.Li sin6_scope_id 305field for addresses. 306This would make management of scoped address easier, 307and allows cut-and-paste input of scoped address. 308.Pp 309At this moment the code supports only link-local addresses with the format. 310Scope identifier is hardcoded to name of hardware interface associated 311with the link. 312.Po 313such as 314.Li ne0 315.Pc . 316Example would be like 317.Dq Li fe80::1@ne0 , 318which means 319.Do 320.Li fe80::1 321on the link associated with 322.Li ne0 323interface 324.Dc . 325.Pp 326The implementation is still very experimental and non-standard. 327The current implementation assumes one-by-one relationship between 328interface and link, which is not necessarily true from the specification. 329.\" 330.Sh FILES 331.Bl -tag -width /etc/resolv.conf -compact 332.It Pa /etc/hosts 333.It Pa /etc/host.conf 334.It Pa /etc/resolv.conf 335.El 336.\" 337.Sh DIAGNOSTICS 338Error return status from 339.Fn getaddrinfo 340is zero on success and non-zero on errors. 341Non-zero error codes are defined in 342.Li <netdb.h> , 343and as follows: 344.Pp 345.Bl -tag -width EAI_ADDRFAMILY -compact 346.It Dv EAI_ADDRFAMILY 347address family for nodename not supported 348.It Dv EAI_AGAIN 349temporary failure in name resolution 350.It Dv EAI_BADFLAGS 351invalid value for ai_flags 352.It Dv EAI_FAIL 353non-recoverable failure in name resolution 354.It Dv EAI_FAMILY 355ai_family not supported 356.It Dv EAI_MEMORY 357memory allocation failure 358.It Dv EAI_NODATA 359no address associated with nodename 360.It Dv EAI_NONAME 361nodename nor servname provided, or not known 362.It Dv EAI_SERVICE 363servname not supported for ai_socktype 364.It Dv EAI_SOCKTYPE 365ai_socktype not supported 366.It Dv EAI_SYSTEM 367system error returned in errno 368.El 369.Pp 370If called with proper argument, 371.Fn gai_strerror 372returns a pointer to a string describing the given error code. 373If the argument is not one of the 374.Dv EAI_xxx 375values, the function still returns a pointer to a string whose contents 376indicate an unknown error. 377.\" 378.Sh SEE ALSO 379.Xr getnameinfo 3 , 380.Xr gethostbyname 3 , 381.Xr getservbyname 3 , 382.Xr hosts 5 , 383.Xr services 5 , 384.Xr hostname 7 , 385.Xr named 8 . 386.Pp 387.Rs 388.%A R. Gilligan 389.%A S. Thomson 390.%A J. Bound 391.%A W. Stevens 392.%T Basic Socket Interface Extensions for IPv6 393.%R RFC2553 394.%D March 1999 395.Re 396.\" 397.Sh HISTORY 398The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. 399.\" 400.Sh STANDARDS 401The 402.Fn getaddrinfo 403function is defined IEEE POSIX 1003.1g draft specification, 404and documented in ``Basic Socket Interface Extensions for IPv6'' 405.Pq RFC2533 . 406.\" 407.Sh BUGS 408The text was shamelessly copied from RFC2553. 409