1 .\" $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.2.2.10 2002/04/28 05:40:24 suz Exp $
2 .\" $DragonFly: src/lib/libcr/net/Attic/getaddrinfo.3,v 1.2 2003/06/17 04:26:44 dillon Exp $
3 .\" $KAME: getaddrinfo.3,v 1.31 2001/08/05 18:19:38 itojun Exp $
5 .\" Copyright (c) 1983, 1987, 1991, 1993
6 .\" The Regents of the University of California. All rights reserved.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed by the University of
19 .\" California, Berkeley and its contributors.
20 .\" 4. Neither the name of the University nor the names of its contributors
21 .\" may be used to endorse or promote products derived from this software
22 .\" without specific prior written permission.
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
46 .Nd nodename-to-address translation in protocol-independent manner
55 .Fn getaddrinfo "const char *nodename" "const char *servname" \
56 "const struct addrinfo *hints" "struct addrinfo **res"
58 .Fn freeaddrinfo "struct addrinfo *ai"
60 .Fn gai_strerror "int ecode"
65 function is defined for protocol-independent nodename-to-address translation.
66 It performs the functionality of
70 but in a more sophisticated manner.
74 structure is defined as a result of including the
79 int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
80 int ai_family; /* PF_xxx */
81 int ai_socktype; /* SOCK_xxx */
82 int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
83 size_t ai_addrlen; /* length of ai_addr */
84 char *ai_canonname; /* canonical name for nodename */
85 struct sockaddr *ai_addr; /* binary address */
86 struct addrinfo *ai_next; /* next structure in linked list */
94 arguments are pointers to null-terminated strings or
96 One or both of these two arguments must be a
99 In the normal client scenario, both the
104 In the normal server scenario, only the
110 string can be either a node name or a numeric host address string
111 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
115 string can be either a service name or a decimal port number.
117 The caller can optionally pass an
119 structure, pointed to by the third argument,
120 to provide hints concerning the type of socket that the caller supports.
123 structure all members other than
136 means the caller will accept any protocol family.
139 means the caller will accept any socket type.
142 means the caller will accept any protocol.
143 For example, if the caller handles only TCP and not UDP, then the
145 member of the hints structure should be set to
150 If the caller handles only IPv4 and not IPv6, then the
154 structure should be set to
159 If the third argument to
163 pointer, this is the same as if the caller had filled in an
165 structure initialized to zero with
170 Upon successful return a pointer to a linked list of one or more
172 structures is returned through the final argument.
173 The caller can process each
175 structure in this list by following the
179 pointer is encountered.
182 structure the three members
187 are the corresponding arguments for a call to the
194 member points to a filled-in socket address structure whose length is
205 structure, then the caller plans to use the returned socket address
206 structure in a call to
212 pointer, then the IP address portion of the socket
213 address structure will be set to
215 for an IPv4 address or
221 bit is not set in the
225 structure, then the returned socket address structure will be ready for a
228 (for a connection-oriented protocol)
234 (for a connectionless protocol).
239 pointer, then the IP address portion of the
240 socket address structure will be set to the loopback address.
248 structure, then upon successful return the
252 structure in the linked list will point to a null-terminated string
253 containing the canonical name of the specified
265 string must be a numeric host address string.
266 Otherwise an error of
269 This flag prevents any type of name resolution service (e.g., the DNS)
274 must be sufficiently consistent and unambiguous.
275 Here are some problem cases you may encounter:
279 will fail if the members in the
281 structure are not consistent.
282 For example, for internet address families,
284 will fail if you specify
295 which is defined only for certain
298 will fail because the arguments are not consistent.
301 will return an error if you ask for
306 For internet address families, if you specify
313 will fail, because service names are not defined for the internet
317 If you specify numeric
326 This is because the numeric
328 does not identify any socket type, and
330 is not allowed to glob the argument in such case.
333 All of the information returned by
335 is dynamically allocated:
338 structures, the socket address structures, and canonical node name
339 strings pointed to by the addrinfo structures.
340 To return this information to the system the function
345 structure pointed to by the
347 is freed, along with any dynamic storage pointed to by the structure.
348 This operation is repeated until a
351 pointer is encountered.
353 To aid applications in printing error messages based on the
359 The argument is one of the
361 values defined earlier and the return value points to a string describing
363 If the argument is not one of the
365 values, the function still returns a pointer to a string whose contents
366 indicate an unknown error.
369 This implementation supports numeric IPv6 address notation with the
370 experimental scope identifier.
371 By appending a percent sign and scope identifier to the address, you
372 can specify the value of the
374 field of the socket address.
375 This makes management of scoped address easier,
376 and allows cut-and-paste input of scoped addresses.
378 At the moment the code supports only link-local addresses in this format.
379 The scope identifier is hardcoded to name of hardware interface associated
388 on the link associated with the
393 This implementation is still very experimental and non-standard.
394 The current implementation assumes a one-to-one relationship between
395 interfaces and links, which is not necessarily true according to the
399 The following code tries to connect to
404 It loops through all the addresses available, regardless of the address family.
405 If the destination resolves to an IPv4 address, it will use an
408 Similarly, if it resolves to IPv6, an
411 Observe that there is no hardcoded reference to particular address family.
412 The code works even if
414 returns addresses that are not IPv4/v6.
415 .Bd -literal -offset indent
416 struct addrinfo hints, *res, *res0;
419 const char *cause = NULL;
421 memset(&hints, 0, sizeof(hints));
422 hints.ai_family = PF_UNSPEC;
423 hints.ai_socktype = SOCK_STREAM;
424 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
426 errx(1, "%s", gai_strerror(error));
430 cause = "no addresses";
431 errno = EADDRNOTAVAIL;
432 for (res = res0; res; res = res->ai_next) {
433 s = socket(res->ai_family, res->ai_socktype,
440 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
447 break; /* okay we got one */
456 The following example tries to open a wildcard listening socket onto service
458 for all the address families available.
459 .Bd -literal -offset indent
460 struct addrinfo hints, *res, *res0;
464 const char *cause = NULL;
466 memset(&hints, 0, sizeof(hints));
467 hints.ai_family = PF_UNSPEC;
468 hints.ai_socktype = SOCK_STREAM;
469 hints.ai_flags = AI_PASSIVE;
470 error = getaddrinfo(NULL, "http", &hints, &res0);
472 errx(1, "%s", gai_strerror(error));
476 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
477 s[nsock] = socket(res->ai_family, res->ai_socktype,
484 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
490 if (listen(s[nsock], SOMAXCONN) < 0) {
506 .Bl -tag -width /etc/resolv.conf -compact
508 .It Pa /etc/host.conf
509 .It Pa /etc/resolv.conf
513 Error return status from
515 is zero on success and non-zero on errors.
516 Non-zero error codes are defined in
520 .Bl -tag -width EAI_ADDRFAMILY -compact
521 .It Dv EAI_ADDRFAMILY
526 Temporary failure in name resolution.
531 Non-recoverable failure in name resolution.
536 Memory allocation failure.
538 No address associated with
544 provided, or not known.
553 System error returned in
557 If called with an appropriate argument,
559 returns a pointer to a string describing the given error code.
560 If the argument is not one of the
562 values, the function still returns a pointer to a string whose contents
563 indicate an unknown error.
566 .Xr gethostbyname 3 ,
568 .Xr getservbyname 3 ,
580 .%T Basic Socket Interface Extensions for IPv6
587 .%T "An Extension of Format for IPv6 Scoped Addresses"
589 .%N draft-ietf-ipngwg-scopedaddr-format-02.txt
590 .%O work in progress material
594 .%T Protocol Independence Using the Sockets API
595 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
600 The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
605 function is defined in
608 .Dq Basic Socket Interface Extensions for IPv6
612 The current implementation is not thread-safe.
614 The text was shamelessly copied from RFC2553.