1.\" $NetBSD: getaddrinfo.3,v 1.1.1.2 2012/09/09 16:07:46 christos Exp $ 2.\" 3.\" Copyright (C) 2009 Internet Systems Consortium, Inc. ("ISC") 4.\" 5.\" Permission to use, copy, modify, and/or distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15.\" PERFORMANCE OF THIS SOFTWARE. 16.\" 17.\" Id: getaddrinfo.3,v 1.3 2009/01/22 23:49:23 tbox Exp 18.\" 19.Dd May 25, 1995 20.Dt GETADDRINFO @LIB_NETWORK_EXT@ 21.Os KAME 22.Sh NAME 23.Nm getaddrinfo 24.Nm freeaddrinfo , 25.Nm gai_strerror 26.Nd nodename-to-address translation in protocol-independent manner 27.Sh SYNOPSIS 28.Fd #include <sys/socket.h> 29.Fd #include <netdb.h> 30.Ft int 31.Fn getaddrinfo "const char *nodename" "const char *servname" \ 32"const struct addrinfo *hints" "struct addrinfo **res" 33.Ft void 34.Fn freeaddrinfo "struct addrinfo *ai" 35.Ft "char *" 36.Fn gai_strerror "int ecode" 37.Sh DESCRIPTION 38The 39.Fn getaddrinfo 40function is defined for protocol-independent nodename-to-address translation. 41It performs functionality of 42.Xr gethostbyname @LIB_NETWORK_EXT@ 43and 44.Xr getservbyname @LIB_NETWORK_EXT@ , 45in more sophisticated manner. 46.Pp 47The addrinfo structure is defined as a result of including the 48.Li <netdb.h> 49header: 50.Bd -literal -offset 51struct addrinfo { * 52 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ 53 int ai_family; /* PF_xxx */ 54 int ai_socktype; /* SOCK_xxx */ 55 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 56 size_t ai_addrlen; /* length of ai_addr */ 57 char *ai_canonname; /* canonical name for nodename */ 58 struct sockaddr *ai_addr; /* binary address */ 59 struct addrinfo *ai_next; /* next structure in linked list */ 60}; 61.Ed 62.Pp 63The 64.Fa nodename 65and 66.Fa servname 67arguments are pointers to null-terminated strings or 68.Dv NULL . 69One or both of these two arguments must be a 70.Pf non Dv -NULL 71pointer. 72In the normal client scenario, both the 73.Fa nodename 74and 75.Fa servname 76are specified. 77In the normal server scenario, only the 78.Fa servname 79is specified. 80A 81.Pf non Dv -NULL 82.Fa nodename 83string can be either a node name or a numeric host address string 84(i.e., a dotted-decimal IPv4 address or an IPv6 hex address). 85A 86.Pf non Dv -NULL 87.Fa servname 88string can be either a service name or a decimal port number. 89.Pp 90The caller can optionally pass an 91.Li addrinfo 92structure, pointed to by the third argument, 93to provide hints concerning the type of socket that the caller supports. 94In this 95.Fa hints 96structure all members other than 97.Fa ai_flags , 98.Fa ai_family , 99.Fa ai_socktype , 100and 101.Fa ai_protocol 102must be zero or a 103.Dv NULL 104pointer. 105A value of 106.Dv PF_UNSPEC 107for 108.Fa ai_family 109means the caller will accept any protocol family. 110A value of 0 for 111.Fa ai_socktype 112means the caller will accept any socket type. 113A value of 0 for 114.Fa ai_protocol 115means the caller will accept any protocol. 116For example, if the caller handles only TCP and not UDP, then the 117.Fa ai_socktype 118member of the hints structure should be set to 119.Dv SOCK_STREAM 120when 121.Fn getaddrinfo 122is called. 123If the caller handles only IPv4 and not IPv6, then the 124.Fa ai_family 125member of the 126.Fa hints 127structure should be set to 128.Dv PF_INET 129when 130.Fn getaddrinfo 131is called. 132If the third argument to 133.Fn getaddrinfo 134is a 135.Dv NULL 136pointer, this is the same as if the caller had filled in an 137.Li addrinfo 138structure initialized to zero with 139.Fa ai_family 140set to PF_UNSPEC. 141.Pp 142Upon successful return a pointer to a linked list of one or more 143.Li addrinfo 144structures is returned through the final argument. 145The caller can process each 146.Li addrinfo 147structure in this list by following the 148.Fa ai_next 149pointer, until a 150.Dv NULL 151pointer is encountered. 152In each returned 153.Li addrinfo 154structure the three members 155.Fa ai_family , 156.Fa ai_socktype , 157and 158.Fa ai_protocol 159are the corresponding arguments for a call to the 160.Fn socket 161function. 162In each 163.Li addrinfo 164structure the 165.Fa ai_addr 166member points to a filled-in socket address structure whose length is 167specified by the 168.Fa ai_addrlen 169member. 170.Pp 171If the 172.Dv AI_PASSIVE 173bit is set in the 174.Fa ai_flags 175member of the 176.Fa hints 177structure, then the caller plans to use the returned socket address 178structure in a call to 179.Fn bind . 180In this case, if the 181.Fa nodename 182argument is a 183.Dv NULL 184pointer, then the IP address portion of the socket 185address structure will be set to 186.Dv INADDR_ANY 187for an IPv4 address or 188.Dv IN6ADDR_ANY_INIT 189for an IPv6 address. 190.Pp 191If the 192.Dv AI_PASSIVE 193bit is not set in the 194.Fa ai_flags 195member of the 196.Fa hints 197structure, then the returned socket address structure will be ready for a 198call to 199.Fn connect 200.Pq for a connection-oriented protocol 201or either 202.Fn connect , 203.Fn sendto , 204or 205.Fn sendmsg 206.Pq for a connectionless protocol . 207In this case, if the 208.Fa nodename 209argument is a 210.Dv NULL 211pointer, then the IP address portion of the 212socket address structure will be set to the loopback address. 213.Pp 214If the 215.Dv AI_CANONNAME 216bit is set in the 217.Fa ai_flags 218member of the 219.Fa hints 220structure, then upon successful return the 221.Fa ai_canonname 222member of the first 223.Li addrinfo 224structure in the linked list will point to a null-terminated string 225containing the canonical name of the specified 226.Fa nodename . 227.Pp 228If the 229.Dv AI_NUMERICHOST 230bit is set in the 231.Fa ai_flags 232member of the 233.Fa hints 234structure, then a 235.Pf non Dv -NULL 236.Fa nodename 237string must be a numeric host address string. 238Otherwise an error of 239.Dv EAI_NONAME 240is returned. 241This flag prevents any type of name resolution service (e.g., the DNS) 242from being called. 243.Pp 244All of the information returned by 245.Fn getaddrinfo 246is dynamically allocated: 247the 248.Li addrinfo 249structures, and the socket address structures and canonical node name 250strings pointed to by the addrinfo structures. 251To return this information to the system the function 252Fn freeaddrinfo 253is called. 254The 255.Fa addrinfo 256structure pointed to by the 257.Fa ai argument 258is freed, along with any dynamic storage pointed to by the structure. 259This operation is repeated until a 260.Dv NULL 261.Fa ai_next 262pointer is encountered. 263.Pp 264To aid applications in printing error messages based on the 265.Dv EAI_xxx 266codes returned by 267.Fn getaddrinfo , 268.Fn gai_strerror 269is defined. 270The argument is one of the 271.Dv EAI_xxx 272values defined earlier and the return value points to a string describing 273the error. 274If the argument is not one of the 275.Dv EAI_xxx 276values, the function still returns a pointer to a string whose contents 277indicate an unknown error. 278.Sh FILES 279.Bl -tag -width /etc/resolv.conf -compact 280.It Pa /etc/hosts 281.It Pa /etc/host.conf 282.It Pa /etc/resolv.conf 283.El 284.Sh DIAGNOSTICS 285Error return status from 286.Fn getaddrinfo 287is zero on success and non-zero on errors. 288Non-zero error codes are defined in 289.Li <netdb.h> , 290and as follows: 291.Pp 292.Bl -tag -width EAI_ADDRFAMILY -compact 293.It Dv EAI_ADDRFAMILY 294address family for nodename not supported 295.It Dv EAI_AGAIN 296temporary failure in name resolution 297.It Dv EAI_BADFLAGS 298invalid value for ai_flags 299.It Dv EAI_FAIL 300non-recoverable failure in name resolution 301.It Dv EAI_FAMILY 302ai_family not supported 303.It Dv EAI_MEMORY 304memory allocation failure 305.It Dv EAI_NODATA 306no address associated with nodename 307.It Dv EAI_NONAME 308nodename nor servname provided, or not known 309.It Dv EAI_SERVICE 310servname not supported for ai_socktype 311.It Dv EAI_SOCKTYPE 312ai_socktype not supported 313.It Dv EAI_SYSTEM 314system error returned in errno 315.El 316.Pp 317If called with proper argument, 318.Fn gai_strerror 319returns a pointer to a string describing the given error code. 320If the argument is not one of the 321.Dv EAI_xxx 322values, the function still returns a pointer to a string whose contents 323indicate an unknown error. 324.Sh SEE ALSO 325.Xr getnameinfo @LIB_NETWORK_EXT@ , 326.Xr gethostbyname @LIB_NETWORK_EXT@ , 327.Xr getservbyname @LIB_NETWORK_EXT@ , 328.Xr hosts @FORMAT_EXT@ , 329.Xr services @FORMAT_EXT@ , 330.Xr hostname @DESC_EXT@ 331.Pp 332R. Gilligan, S. Thomson, J. Bound, and W. Stevens, 333``Basic Socket Interface Extensions for IPv6,'' RFC2133, April 1997. 334.Sh HISTORY 335The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. 336.Sh STANDARDS 337The 338.Fn getaddrinfo 339function is defined IEEE POSIX 1003.1g draft specification, 340and documented in ``Basic Socket Interface Extensions for IPv6'' 341(RFC2133). 342.Sh BUGS 343The text was shamelessly copied from RFC2133. 344