1 .\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $
2 .\" $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $
4 .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
5 .\" Copyright (C) 2000, 2001 Internet Software Consortium.
7 .\" Permission to use, copy, modify, and distribute this software for any
8 .\" purpose with or without fee is hereby granted, provided that the above
9 .\" copyright notice and this permission notice appear in all copies.
11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
12 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
13 .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
14 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
16 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17 .\" PERFORMANCE OF THIS SOFTWARE.
19 .\" $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.34 2008/07/01 22:59:20 danger Exp $
27 .Nd socket address structure to host and service name
29 .Fd #include <sys/types.h>
30 .Fd #include <sys/socket.h>
31 .Fd #include <netdb.h>
34 .Fa "const char *hostname" "const char *servname"
35 .Fa "const struct addrinfo *hints" "struct addrinfo **res"
38 .Fn freeaddrinfo "struct addrinfo *ai"
42 function is used to get a list of
44 addresses and port numbers for host
48 It is a replacement for and provides more flexibility than the
58 arguments are either pointers to NUL-terminated strings or the null pointer.
59 An acceptable value for
61 is either a valid host name or a numeric host address string consisting
62 of a dotted decimal IPv4 address or an IPv6 address.
65 is either a decimal port number or a service name listed in
74 is an optional pointer to a
80 int ai_flags; /* input flags */
81 int ai_family; /* protocol family for socket */
82 int ai_socktype; /* socket type */
83 int ai_protocol; /* protocol for socket */
84 socklen_t ai_addrlen; /* length of socket-address */
85 struct sockaddr *ai_addr; /* socket-address for socket */
86 char *ai_canonname; /* canonical name for service location */
87 struct addrinfo *ai_next; /* pointer to next in list */
91 This structure can be used to provide hints concerning the type of socket
92 that the caller supports or wishes to use.
93 The caller can supply the following structure elements in
95 .Bl -tag -width "ai_socktypeXX"
97 The protocol family that should be used.
102 it means the caller will accept any protocol family supported by the
105 Denotes the type of socket that is wanted:
112 is zero the caller will accept any socket type.
114 Indicates which transport protocol is desired,
120 is zero the caller will accept any protocol.
126 parameter points shall be set to zero
127 or be the bitwise-inclusive OR of one or more of the values
135 .Dv AI_V4MAPPED_CFG ,
138 .Bl -tag -width "AI_CANONNAMEXX"
142 bit is set, IPv4 addresses shall be returned only if
143 an IPv4 address is configured on the local system,
144 and IPv6 addresses shall be returned only if
145 an IPv6 address is configured on the local system.
153 shall return all matching IPv6 and IPv4 addresses.
162 bit is set, a successful call to
164 will return a NUL-terminated string containing the canonical name
165 of the specified hostname in the
170 .It Dv AI_NUMERICHOST
173 bit is set, it indicates that
175 should be treated as a numeric string defining an IPv4 or IPv6 address
176 and no name resolution should be attempted.
177 .It Dv AI_NUMERICSERV
183 string supplied shall be a numeric port string.
186 error shall be returned.
187 This bit shall prevent any type of name resolution service
188 (for example, NIS+) from being invoked.
192 bit is set it indicates that the returned socket address structure
193 is intended for use in a call to
197 argument is the null pointer, then the IP address portion of the
198 socket address structure will be set to
200 for an IPv4 address or
206 bit is not set, the returned socket address structure will be ready
209 for a connection-oriented protocol or
214 if a connectionless protocol was chosen.
217 address portion of the socket address structure will be set to the
220 is the null pointer and
226 flag is specified along with an
232 shall return IPv4-mapped IPv6 addresses
233 on finding no matching IPv6 addresses (
238 flag shall be ignored unless
242 .It Dv AI_V4MAPPED_CFG
245 flag behaves exactly like the
247 flag if the kernel supports IPv4-mapped IPv6 addresses. Otherwise it is ignored.
258 All other elements of the
262 must be zero or the null pointer.
268 behaves as if the caller provided a
274 and all other elements set to zero or
277 After a successful call to
280 is a pointer to a linked list of one or more
283 The list can be traversed by following the
287 structure until a null pointer is encountered.
295 structure are suitable for a call to
299 structure in the list, the
301 member points to a filled-in socket address structure of length
304 This implementation of
306 allows numeric IPv6 address notation with scope identifier,
307 as documented in section 11 of RFC 4007.
308 By appending the percent character and scope identifier to addresses,
312 This would make management of scoped addresses easier
313 and allows cut-and-paste input of scoped addresses.
315 At this moment the code supports only link-local addresses with the format.
316 The scope identifier is hardcoded to the name of the hardware interface
328 on the link associated with the
333 The current implementation assumes a one-to-one relationship between
334 the interface and link, which is not necessarily true from the specification.
336 All of the information returned by
338 is dynamically allocated: the
340 structures themselves as well as the socket address structures and
341 the canonical host name strings included in the
345 Memory allocated for the dynamically allocated structures created by
355 structure created by a call to
358 The current implementation supports synthesis of NAT64 mapped IPv6 addresses.
361 is a numeric string defining an IPv4 address (for example,
370 will synthesize the appropriate IPv6 address(es) (for example,
371 .Dq Li 64:ff9b::192.0.2.1
372 ) if the current interface supports IPv6, NAT64 and DNS64
373 and does not support IPv4. If the
375 flag is set, the IPv4 address will be suppressed on those interfaces.
376 On non-qualifying interfaces,
378 is guaranteed to return immediately without attempting any resolution, and will
379 return the IPv4 address if
385 NAT64 address synthesis can be disabled by setting the
387 flag. To best support NAT64 networks, it is recommended to resolve all
388 IP address literals with
397 Note that NAT64 address synthesis is always disabled for IPv4 addresses
398 in the following ranges:
406 Additionally, NAT64 address synthesis is disabled when the network uses
407 the well-known prefix (64:ff9b::/96)
408 for IPv4 addresses in the following ranges:
414 Historically, passing a host's own hostname to
417 technique for determining that host's IP address(es), but this is fragile,
418 and doesn't work reliably in all cases. The appropriate way for software to
419 discover the IP address(es) of the host it is running on is to use
424 implementations on all versions of OS X and iOS are now, and always have been,
425 thread-safe. Previous versions of this man page incorrectly reported that
430 returns zero on success or one of the error codes listed in
434 The following code tries to connect to
439 It loops through all the addresses available, regardless of address family.
440 If the destination resolves to an IPv4 address, it will use an
443 Similarly, if it resolves to IPv6, an
446 Observe that there is no hardcoded reference to a particular address family.
447 The code works even if
449 returns addresses that are not IPv4/v6.
450 .Bd -literal -offset indent
451 struct addrinfo hints, *res, *res0;
454 const char *cause = NULL;
456 memset(&hints, 0, sizeof(hints));
457 hints.ai_family = PF_UNSPEC;
458 hints.ai_socktype = SOCK_STREAM;
459 error = getaddrinfo("www.kame.net", "http", &hints, &res0);
461 errx(1, "%s", gai_strerror(error));
465 for (res = res0; res; res = res->ai_next) {
466 s = socket(res->ai_family, res->ai_socktype,
473 if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
480 break; /* okay we got one */
489 The following example tries to open a wildcard listening socket onto service
491 for all the address families available.
492 .Bd -literal -offset indent
493 struct addrinfo hints, *res, *res0;
497 const char *cause = NULL;
499 memset(&hints, 0, sizeof(hints));
500 hints.ai_family = PF_UNSPEC;
501 hints.ai_socktype = SOCK_STREAM;
502 hints.ai_flags = AI_PASSIVE;
503 error = getaddrinfo(NULL, "http", &hints, &res0);
505 errx(1, "%s", gai_strerror(error));
509 for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
510 s[nsock] = socket(res->ai_family, res->ai_socktype,
517 if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
522 (void) listen(s[nsock], 5);
538 .Xr gethostbyname 3 ,
540 .Xr getservbyname 3 ,
553 .%T Basic Socket Interface Extensions for IPv6
563 .%T "IPv6 Scoped Address Architecture"
569 .%T Protocol Independence Using the Sockets API
570 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
576 .\"function as implemented in
578 .\"currently does not support
584 .\"if one of them is specified.
588 function is defined by the
590 specification and documented in
592 .Dq Basic Socket Interface Extensions for IPv6 .