1.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") 2.\" 3.\" Permission to use, copy, modify, and distribute this software for any 4.\" purpose with or without fee is hereby granted, provided that the above 5.\" copyright notice and this permission notice appear in all copies. 6.\" 7.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES 8.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 9.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR 10.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 11.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 12.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT 13.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 14.\" 15.\" Copyright (c) 1983, 1987, 1991, 1993 16.\" The Regents of the University of California. All rights reserved. 17.\" 18.\" Redistribution and use in source and binary forms, with or without 19.\" modification, are permitted provided that the following conditions 20.\" are met: 21.\" 1. Redistributions of source code must retain the above copyright 22.\" notice, this list of conditions and the following disclaimer. 23.\" 2. Redistributions in binary form must reproduce the above copyright 24.\" notice, this list of conditions and the following disclaimer in the 25.\" documentation and/or other materials provided with the distribution. 26.\" 3. All advertising materials mentioning features or use of this software 27.\" must display the following acknowledgement: 28.\" This product includes software developed by the University of 29.\" California, Berkeley and its contributors. 30.\" 4. Neither the name of the University nor the names of its contributors 31.\" may be used to endorse or promote products derived from this software 32.\" without specific prior written permission. 33.\" 34.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 35.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 36.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 37.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 38.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 39.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 40.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 41.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 42.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 43.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 44.\" SUCH DAMAGE. 45.\" 46.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 47.\" Id: getaddrinfo.man3,v 1.2 2009/01/21 00:12:34 each Exp 48.\" 49.Dd May 25, 1995 50.Dt GETADDRINFO 3 51.Os KAME 52.Sh NAME 53.Nm getaddrinfo 54.Nm freeaddrinfo , 55.Nm gai_strerror 56.Nd nodename-to-address translation in protocol-independent manner 57.Sh SYNOPSIS 58.Fd #include <sys/socket.h> 59.Fd #include <netdb.h> 60.Ft int 61.Fn getaddrinfo "const char *nodename" "const char *servname" \ 62"const struct addrinfo *hints" "struct addrinfo **res" 63.Ft void 64.Fn freeaddrinfo "struct addrinfo *ai" 65.Ft "char *" 66.Fn gai_strerror "int ecode" 67.Sh DESCRIPTION 68The 69.Fn getaddrinfo 70function is defined for protocol-independent nodename-to-address translation. 71It performs functionality of 72.Xr gethostbyname 3 73and 74.Xr getservbyname 3 , 75in more sophisticated manner. 76.Pp 77The addrinfo structure is defined as a result of including the 78.Li <netdb.h> 79header: 80.Bd -literal -offset 81struct addrinfo { * 82 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ 83 int ai_family; /* PF_xxx */ 84 int ai_socktype; /* SOCK_xxx */ 85 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 86 size_t ai_addrlen; /* length of ai_addr */ 87 char *ai_canonname; /* canonical name for nodename */ 88 struct sockaddr *ai_addr; /* binary address */ 89 struct addrinfo *ai_next; /* next structure in linked list */ 90}; 91.Ed 92.Pp 93The 94.Fa nodename 95and 96.Fa servname 97arguments are pointers to null-terminated strings or 98.Dv NULL . 99One or both of these two arguments must be a 100.Pf non Dv -NULL 101pointer. 102In the normal client scenario, both the 103.Fa nodename 104and 105.Fa servname 106are specified. 107In the normal server scenario, only the 108.Fa servname 109is specified. 110A 111.Pf non Dv -NULL 112.Fa nodename 113string can be either a node name or a numeric host address string 114(i.e., a dotted-decimal IPv4 address or an IPv6 hex address). 115A 116.Pf non Dv -NULL 117.Fa servname 118string can be either a service name or a decimal port number. 119.Pp 120The caller can optionally pass an 121.Li addrinfo 122structure, pointed to by the third argument, 123to provide hints concerning the type of socket that the caller supports. 124In this 125.Fa hints 126structure all members other than 127.Fa ai_flags , 128.Fa ai_family , 129.Fa ai_socktype , 130and 131.Fa ai_protocol 132must be zero or a 133.Dv NULL 134pointer. 135A value of 136.Dv PF_UNSPEC 137for 138.Fa ai_family 139means the caller will accept any protocol family. 140A value of 0 for 141.Fa ai_socktype 142means the caller will accept any socket type. 143A value of 0 for 144.Fa ai_protocol 145means the caller will accept any protocol. 146For example, if the caller handles only TCP and not UDP, then the 147.Fa ai_socktype 148member of the hints structure should be set to 149.Dv SOCK_STREAM 150when 151.Fn getaddrinfo 152is called. 153If the caller handles only IPv4 and not IPv6, then the 154.Fa ai_family 155member of the 156.Fa hints 157structure should be set to 158.Dv PF_INET 159when 160.Fn getaddrinfo 161is called. 162If the third argument to 163.Fn getaddrinfo 164is a 165.Dv NULL 166pointer, this is the same as if the caller had filled in an 167.Li addrinfo 168structure initialized to zero with 169.Fa ai_family 170set to 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 274All of the information returned by 275.Fn getaddrinfo 276is dynamically allocated: 277the 278.Li addrinfo 279structures, and the socket address structures and canonical node name 280strings pointed to by the addrinfo structures. 281To return this information to the system the function 282Fn freeaddrinfo 283is called. 284The 285.Fa addrinfo 286structure pointed to by the 287.Fa ai argument 288is freed, along with any dynamic storage pointed to by the structure. 289This operation is repeated until a 290.Dv NULL 291.Fa ai_next 292pointer is encountered. 293.Pp 294To aid applications in printing error messages based on the 295.Dv EAI_xxx 296codes returned by 297.Fn getaddrinfo , 298.Fn gai_strerror 299is defined. 300The argument is one of the 301.Dv EAI_xxx 302values defined earlier and the return value points to a string describing 303the error. 304If the argument is not one of the 305.Dv EAI_xxx 306values, the function still returns a pointer to a string whose contents 307indicate an unknown error. 308.Sh FILES 309.Bl -tag -width /etc/resolv.conf -compact 310.It Pa /etc/hosts 311.It Pa /etc/host.conf 312.It Pa /etc/resolv.conf 313.El 314.Sh DIAGNOSTICS 315Error return status from 316.Fn getaddrinfo 317is zero on success and non-zero on errors. 318Non-zero error codes are defined in 319.Li <netdb.h> , 320and as follows: 321.Pp 322.Bl -tag -width EAI_ADDRFAMILY -compact 323.It Dv EAI_ADDRFAMILY 324address family for nodename not supported 325.It Dv EAI_AGAIN 326temporary failure in name resolution 327.It Dv EAI_BADFLAGS 328invalid value for ai_flags 329.It Dv EAI_FAIL 330non-recoverable failure in name resolution 331.It Dv EAI_FAMILY 332ai_family not supported 333.It Dv EAI_MEMORY 334memory allocation failure 335.It Dv EAI_NODATA 336no address associated with nodename 337.It Dv EAI_NONAME 338nodename nor servname provided, or not known 339.It Dv EAI_SERVICE 340servname not supported for ai_socktype 341.It Dv EAI_SOCKTYPE 342ai_socktype not supported 343.It Dv EAI_SYSTEM 344system error returned in errno 345.El 346.Pp 347If called with proper argument, 348.Fn gai_strerror 349returns a pointer to a string describing the given error code. 350If the argument is not one of the 351.Dv EAI_xxx 352values, the function still returns a pointer to a string whose contents 353indicate an unknown error. 354.Sh SEE ALSO 355.Xr getnameinfo 3 , 356.Xr gethostbyname 3 , 357.Xr getservbyname 3 , 358.Xr hosts 5 , 359.Xr services 5 , 360.Xr hostname 7 361.Pp 362R. Gilligan, S. Thomson, J. Bound, and W. Stevens, 363``Basic Socket Interface Extensions for IPv6,'' RFC2133, April 1997. 364.Sh HISTORY 365The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. 366.Sh STANDARDS 367The 368.Fn getaddrinfo 369function is defined IEEE POSIX 1003.1g draft specification, 370and documented in ``Basic Socket Interface Extensions for IPv6'' 371(RFC2133). 372.Sh BUGS 373The text was shamelessly copied from RFC2133. 374