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 LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.Fd #include <sys/types.h> 50.Fd #include <sys/socket.h> 51.Fd #include <netdb.h> 52.Ft int 53.Fn getaddrinfo "const char *nodename" "const char *servname" "const struct addrinfo *hints" "struct addrinfo **res" 54.Ft void 55.Fn freeaddrinfo "struct addrinfo *ai" 56.Ft "char *" 57.Fn gai_strerror "int ecode" 58.\" 59.Sh DESCRIPTION 60The 61.Fn getaddrinfo 62function is defined for protocol-independent nodename-to-address translation. 63It performs functionality of 64.Xr gethostbyname 3 65and 66.Xr getservbyname 3 , 67in more sophisticated manner. 68.Pp 69The addrinfo structure is defined as a result of including the 70.Li <netdb.h> 71header: 72.Bd -literal -offset 73struct addrinfo { * 74 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ 75 int ai_family; /* PF_xxx */ 76 int ai_socktype; /* SOCK_xxx */ 77 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 78 size_t ai_addrlen; /* length of ai_addr */ 79 char *ai_canonname; /* canonical name for nodename */ 80 struct sockaddr *ai_addr; /* binary address */ 81 struct addrinfo *ai_next; /* next structure in linked list */ 82}; 83.Ed 84.Pp 85The 86.Fa nodename 87and 88.Fa servname 89arguments are pointers to null-terminated strings or 90.Dv NULL . 91One or both of these two arguments must be a 92.Pf non Dv -NULL 93pointer. 94In the normal client scenario, both the 95.Fa nodename 96and 97.Fa servname 98are specified. 99In the normal server scenario, only the 100.Fa servname 101is specified. 102A 103.Pf non Dv -NULL 104.Fa nodename 105string can be either a node name or a numeric host address string 106.Po 107i.e., a dotted-decimal IPv4 address or an IPv6 hex address 108.Pc . 109A 110.Pf non Dv -NULL 111.Fa servname 112string can be either a service name or a decimal port number. 113.Pp 114The caller can optionally pass an 115.Li addrinfo 116structure, pointed to by the third argument, 117to provide hints concerning the type of socket that the caller supports. 118In this 119.Fa hints 120structure all members other than 121.Fa ai_flags , 122.Fa ai_family , 123.Fa ai_socktype , 124and 125.Fa ai_protocol 126must be zero or a 127.Dv NULL 128pointer. 129A value of 130.Dv PF_UNSPEC 131for 132.Fa ai_family 133means the caller will accept any protocol family. 134A value of 0 for 135.Fa ai_socktype 136means the caller will accept any socket type. 137A value of 0 for 138.Fa ai_protocol 139means the caller will accept any protocol. 140For example, if the caller handles only TCP and not UDP, then the 141.Fa ai_socktype 142member of the hints structure should be set to 143.Dv SOCK_STREAM 144when 145.Fn getaddrinfo 146is called. 147If the caller handles only IPv4 and not IPv6, then the 148.Fa ai_family 149member of the 150.Fa hints 151structure should be set to 152.Dv PF_INET 153when 154.Fn getaddrinfo 155is called. 156If the third argument to 157.Fn getaddrinfo 158is a 159.Dv NULL 160pointer, this is the same as if the caller had filled in an 161.Li addrinfo 162structure initialized to zero with 163.Fa ai_family 164set to PF_UNSPEC. 165.Pp 166Upon successful return a pointer to a linked list of one or more 167.Li addrinfo 168structures is returned through the final argument. 169The caller can process each 170.Li addrinfo 171structure in this list by following the 172.Fa ai_next 173pointer, until a 174.Dv NULL 175pointer is encountered. 176In each returned 177.Li addrinfo 178structure the three members 179.Fa ai_family , 180.Fa ai_socktype , 181and 182.Fa ai_protocol 183are the corresponding arguments for a call to the 184.Fn socket 185function. 186In each 187.Li addrinfo 188structure the 189.Fa ai_addr 190member points to a filled-in socket address structure whose length is 191specified by the 192.Fa ai_addrlen 193member. 194.Pp 195If the 196.Dv AI_PASSIVE 197bit is set in the 198.Fa ai_flags 199member of the 200.Fa hints 201structure, then the caller plans to use the returned socket address 202structure in a call to 203.Fn bind . 204In this case, if the 205.Fa nodename 206argument is a 207.Dv NULL 208pointer, then the IP address portion of the socket 209address structure will be set to 210.Dv INADDR_ANY 211for an IPv4 address or 212.Dv IN6ADDR_ANY_INIT 213for an IPv6 address. 214.Pp 215If the 216.Dv AI_PASSIVE 217bit is not set in the 218.Fa ai_flags 219member of the 220.Fa hints 221structure, then the returned socket address structure will be ready for a 222call to 223.Fn connect 224.Pq for a connection-oriented protocol 225or either 226.Fn connect , 227.Fn sendto , or 228.Fn sendmsg 229.Pq for a connectionless protocol . 230In this case, if the 231.Fa nodename 232argument is a 233.Dv NULL 234pointer, then the IP address portion of the 235socket address structure will be set to the loopback address. 236.Pp 237If the 238.Dv AI_CANONNAME 239bit is set in the 240.Fa ai_flags 241member of the 242.Fa hints 243structure, then upon successful return the 244.Fa ai_canonname 245member of the first 246.Li addrinfo 247structure in the linked list will point to a null-terminated string 248containing the canonical name of the specified 249.Fa nodename . 250.Pp 251If the 252.Dv AI_NUMERICHOST 253bit is set in the 254.Fa ai_flags 255member of the 256.Fa hints 257structure, then a 258.Pf non Dv -NULL 259.Fa nodename 260string must be a numeric host address string. 261Otherwise an error of 262.Dv EAI_NONAME 263is returned. 264This flag prevents any type of name resolution service (e.g., the DNS) 265from being called. 266.Pp 267All of the information returned by 268.Fn getaddrinfo 269is dynamically allocated: 270the 271.Li addrinfo 272structures, and the socket address structures and canonical node name 273strings pointed to by the addrinfo structures. 274To return this information to the system the function 275.Fn freeaddrinfo 276is called. 277The 278.Fa addrinfo 279structure pointed to by the 280.Fa ai argument 281is freed, along with any dynamic storage pointed to by the structure. 282This operation is repeated until a 283.Dv NULL 284.Fa ai_next 285pointer is encountered. 286.Pp 287To aid applications in printing error messages based on the 288.Dv EAI_xxx 289codes returned by 290.Fn getaddrinfo , 291.Fn gai_strerror 292is defined. 293The argument is one of the 294.Dv EAI_xxx 295values defined earlier and the return value points to a string describing 296the error. 297If the argument is not one of the 298.Dv EAI_xxx 299values, the function still returns a pointer to a string whose contents 300indicate an unknown error. 301.\" 302.Sh EXTENSION 303The implementation allows experimental numeric IPv6 address notation with 304scope identifier. 305By appending atmark and scope identifier to addresses, you can fill 306.Li sin6_scope_id 307field for addresses. 308This would make management of scoped address easier, 309and allows cut-and-paste input of scoped address. 310.Pp 311At this moment the code supports only link-local addresses with the format. 312Scope identifier is hardcoded to name of hardware interface associated 313with the link. 314.Po 315such as 316.Li ne0 317.Pc . 318Example would be like 319.Dq Li fe80::1@ne0 , 320which means 321.Do 322.Li fe80::1 323on the link associated with 324.Li ne0 325interface 326.Dc . 327.Pp 328The implementation is still very experimental and non-standard. 329The current implementation assumes one-by-one relationship between 330interface and link, which is not necessarily true from the specification. 331.\" 332.Sh FILES 333.Bl -tag -width /etc/resolv.conf -compact 334.It Pa /etc/hosts 335.It Pa /etc/host.conf 336.It Pa /etc/resolv.conf 337.El 338.\" 339.Sh DIAGNOSTICS 340Error return status from 341.Fn getaddrinfo 342is zero on success and non-zero on errors. 343Non-zero error codes are defined in 344.Li <netdb.h> , 345and as follows: 346.Pp 347.Bl -tag -width EAI_ADDRFAMILY -compact 348.It Dv EAI_ADDRFAMILY 349address family for nodename not supported 350.It Dv EAI_AGAIN 351temporary failure in name resolution 352.It Dv EAI_BADFLAGS 353invalid value for ai_flags 354.It Dv EAI_FAIL 355non-recoverable failure in name resolution 356.It Dv EAI_FAMILY 357ai_family not supported 358.It Dv EAI_MEMORY 359memory allocation failure 360.It Dv EAI_NODATA 361no address associated with nodename 362.It Dv EAI_NONAME 363nodename nor servname provided, or not known 364.It Dv EAI_SERVICE 365servname not supported for ai_socktype 366.It Dv EAI_SOCKTYPE 367ai_socktype not supported 368.It Dv EAI_SYSTEM 369system error returned in errno 370.El 371.Pp 372If called with proper argument, 373.Fn gai_strerror 374returns a pointer to a string describing the given error code. 375If the argument is not one of the 376.Dv EAI_xxx 377values, the function still returns a pointer to a string whose contents 378indicate an unknown error. 379.\" 380.Sh SEE ALSO 381.Xr getnameinfo 3 , 382.Xr gethostbyname 3 , 383.Xr getservbyname 3 , 384.Xr hosts 5 , 385.Xr services 5 , 386.Xr hostname 7 , 387.Xr named 8 . 388.Pp 389.Rs 390.%A R. Gilligan 391.%A S. Thomson 392.%A J. Bound 393.%A W. Stevens 394.%T Basic Socket Interface Extensions for IPv6 395.%R RFC2553 396.%D March 1999 397.Re 398.\" 399.Sh HISTORY 400The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. 401.\" 402.Sh STANDARDS 403The 404.Fn getaddrinfo 405function is defined IEEE POSIX 1003.1g draft specification, 406and documented in ``Basic Socket Interface Extensions for IPv6'' 407.Pq RFC2533 . 408.\" 409.Sh BUGS 410The text was shamelessly copied from RFC2553. 411