2 .\" Copyright (c) 2007, 2008 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" and Copyright (c) 2006 Ulrich Drepper <drepper@redhat.com>
4 .\" A few pieces of an earlier version remain:
5 .\" Copyright 2000, Sam Varshavchik <mrsam@courier-mta.com>
7 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
9 .\" References: RFC 2553
11 .\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED,
12 .\" and AI_NUMERICSERV.
13 .\" 2006-11-25, Ulrich Drepper <drepper@redhat.com>
14 .\" Add text describing Internationalized Domain Name extensions.
15 .\" 2007-06-08, mtk: added example programs
16 .\" 2008-02-26, mtk; clarify discussion of NULL 'hints' argument; other
18 .\" 2008-06-18, mtk: many parts rewritten
19 .\" 2008-12-04, Petr Baudis <pasky@suse.cz>
20 .\" Describe results ordering and reference /etc/gai.conf.
22 .\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support
23 .\" and is SCTP support now also there?
25 .TH getaddrinfo 3 (date) "Linux man-pages (unreleased)"
27 getaddrinfo, freeaddrinfo, gai_strerror \- network address and
31 .RI ( libc ", " \-lc )
34 .B #include <sys/types.h>
35 .B #include <sys/socket.h>
38 .BI "int getaddrinfo(const char *restrict " node ,
39 .BI " const char *restrict " service ,
40 .BI " const struct addrinfo *restrict " hints ,
41 .BI " struct addrinfo **restrict " res );
43 .BI "void freeaddrinfo(struct addrinfo *" res );
45 .BI "const char *gai_strerror(int " errcode );
49 Feature Test Macro Requirements for glibc (see
50 .BR feature_test_macros (7)):
58 _POSIX_C_SOURCE >= 200112L
59 glibc 2.21 and earlier:
67 which identify an Internet host and a service,
71 structures, each of which contains an Internet address
72 that can be specified in a call to
78 function combines the functionality provided by the
79 .\" .BR getipnodebyname (3),
80 .\" .BR getipnodebyaddr (3),
84 functions into a single interface, but unlike the latter functions,
86 is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies.
92 contains the following fields:
101 socklen_t ai_addrlen;
102 struct sockaddr *ai_addr;
104 struct addrinfo *ai_next;
111 argument points to an
113 structure that specifies criteria for selecting the socket address
114 structures returned in the list pointed to by
118 is not NULL it points to an
125 specify criteria that limit the set of socket addresses returned by
130 This field specifies the desired address family for the returned addresses.
131 Valid values for this field include
139 should return socket addresses for any address family
140 (either IPv4 or IPv6, for example) that can be used with
146 This field specifies the preferred socket type, for example
150 Specifying 0 in this field indicates that socket addresses of any type
155 This field specifies the protocol for the returned socket addresses.
156 Specifying 0 in this field indicates that socket addresses with
157 any protocol can be returned by
161 This field specifies additional options, described below.
162 Multiple flags are specified by bitwise OR-ing them together.
164 All the other fields in the structure pointed to by
166 must contain either 0 or a null pointer, as appropriate.
170 as NULL is equivalent to setting
181 .BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)" .
182 (POSIX specifies different defaults for
186 specifies either a numerical network address
187 (for IPv4, numbers-and-dots notation as supported by
189 for IPv6, hexadecimal string format as supported by
191 or a network hostname, whose network addresses are looked up and resolved.
198 must be a numerical network address.
201 flag suppresses any potentially lengthy network host address lookups.
210 then the returned socket addresses will be suitable for
215 The returned socket address will contain the "wildcard address"
220 The wildcard address is used by applications (typically servers)
221 that intend to accept connections on any of the host's network addresses.
224 is not NULL, then the
232 then the returned socket addresses will be suitable for use with
240 then the network address will be set to the loopback interface address
241 .RB ( INADDR_LOOPBACK
243 .B IN6ADDR_LOOPBACK_INIT
245 this is used by applications that intend to communicate
246 with peers running on the same host.
249 sets the port in each returned address structure.
250 If this argument is a service name (see
252 it is translated to the corresponding port number.
253 This argument can also be specified as a decimal number,
254 which is simply converted to binary.
257 is NULL, then the port number of the returned socket addresses
258 will be left uninitialized.
267 must point to a string containing a numeric port number.
268 This flag is used to inhibit the invocation of a name resolution service
269 in cases where it is known not to be required.
275 but not both, may be NULL.
279 function allocates and initializes a linked list of
281 structures, one for each network address that matches
285 subject to any restrictions imposed by
287 and returns a pointer to the start of the list in
289 The items in the linked list are linked by the
293 There are several reasons why
294 the linked list may have more than one
296 structure, including: the network host is multihomed, accessible
297 over multiple protocols (e.g., both
301 or the same service is available from multiple socket types (one
305 address, for example).
306 Normally, the application should try
307 using the addresses in the order in which they are returned.
308 The sorting function used within
310 is defined in RFC\ 3484; the order can be tweaked for a particular
313 (available since glibc 2.5).
321 field of the first of the
323 structures in the returned list is set to point to the
324 official name of the host.
325 .\" Prior to glibc 2.3.4, the ai_canonname of each addrinfo
326 .\" structure was set pointing to the canonical name; that was
327 .\" more than POSIX.1-2001 specified, or other implementations provided.
330 The remaining fields of each returned
332 structure are initialized as follows:
339 fields return the socket creation parameters (i.e., these fields have
340 the same meaning as the corresponding arguments of
355 returns the protocol for the socket.
357 A pointer to the socket address is placed in the
359 field, and the length of the socket address, in bytes,
368 flag, then IPv4 addresses are returned in the list pointed to by
370 only if the local system has at least one
371 IPv4 address configured, and IPv6 addresses are returned
372 only if the local system has at least one IPv6 address configured.
373 The loopback address is not considered for this case as valid
374 as a configured address.
375 This flag is useful on, for example,
376 IPv4-only systems, to ensure that
378 does not return IPv6 socket addresses that would always fail in
391 and no matching IPv6 addresses could be found,
392 then return IPv4-mapped IPv6 addresses in the list pointed to by
400 then return both IPv6 and IPv4-mapped IPv6 addresses
401 in the list pointed to by
406 is not also specified.
410 function frees the memory that was allocated
411 for the dynamically allocated linked list
413 .SS Extensions to getaddrinfo() for Internationalized Domain Names
414 Starting with glibc 2.3.4,
416 has been extended to selectively allow the incoming and outgoing
417 hostnames to be transparently converted to and from the
418 Internationalized Domain Name (IDN) format (see RFC 3490,
419 .IR "Internationalizing Domain Names in Applications (IDNA)" ).
420 Four new flags are defined:
423 If this flag is specified, then the node name given in
425 is converted to IDN format if necessary.
426 The source encoding is that of the current locale.
428 If the input name contains non-ASCII characters, then the IDN encoding
430 Those parts of the node name (delimited by dots) that contain
431 non-ASCII characters are encoded using ASCII Compatible Encoding (ACE)
432 before being passed to the name resolution functions.
433 .\" Implementation Detail:
434 .\" To minimize effects on system performance the implementation might
435 .\" want to check whether the input string contains any non-ASCII
436 .\" characters. If there are none the IDN step can be skipped completely.
437 .\" On systems which allow not-ASCII safe encodings for a locale this
438 .\" might be a problem.
441 After a successful name lookup, and if the
445 will return the canonical name of the
446 node corresponding to the
448 structure value passed back.
449 The return value is an exact copy of the value returned by the name
452 If the name is encoded using ACE, then it will contain the
454 prefix for one or more components of the name.
455 To convert these components into a readable form the
457 flag can be passed in addition to
459 The resulting string is encoded using the current locale's encoding.
461 .\"Implementation Detail:
462 .\"If no component of the returned name starts with xn\-\- the IDN
463 .\"step can be skipped, therefore avoiding unnecessary slowdowns.
465 .B AI_IDN_ALLOW_UNASSIGNED
467 .B AI_IDN_USE_STD3_ASCII_RULES
468 Setting these flags will enable the
469 IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and
470 IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3
472 flags respectively to be used in the IDNA handling.
474 .\" FIXME glibc defines the following additional errors, some which
475 .\" can probably be returned by getaddrinfo(); they need to
478 .\" #define EAI_INPROGRESS -100 /* Processing request in progress. */
479 .\" #define EAI_CANCELED -101 /* Request canceled. */
480 .\" #define EAI_NOTCANCELED -102 /* Request not canceled. */
481 .\" #define EAI_ALLDONE -103 /* All requests done. */
482 .\" #define EAI_INTR -104 /* Interrupted by a signal. */
483 .\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */
486 returns 0 if it succeeds, or one of the following nonzero error codes:
490 The specified network host does not have any network addresses in the
491 requested address family.
494 The name server returned a temporary failure indication.
499 contains invalid flags; or,
508 The name server returned a permanent failure indication.
511 The requested address family is not supported.
518 The specified network host exists, but does not have any
519 network addresses defined.
526 is not known; or both
536 was not a numeric port-number string.
539 The requested service is not available for the requested socket type.
540 It may be available through another socket type.
541 For example, this error could occur if
543 was "shell" (a service available only on stream sockets), and either
551 or the error could occur if
557 (a socket type that does not support the concept of services).
560 The requested socket type is not supported.
561 This could occur, for example, if
565 are inconsistent (e.g.,
574 is set to indicate the error.
578 function translates these error codes to a human readable string,
579 suitable for error reporting.
583 For an explanation of the terms used in this section, see
589 Interface Attribute Value
594 T} Thread safety MT-Safe env locale
600 T} Thread safety MT-Safe
603 According to POSIX.1, specifying
604 .\" POSIX.1-2001, POSIX.1-2008
609 The GNU C library instead assumes a value of
610 .B (AI_V4MAPPED\~|\~AI_ADDRCONFIG)
612 since this value is considered an improvement on the specification.
633 .IB address % scope-id
634 notation for specifying the IPv6 scope-ID.
636 .\" getnameinfo.3 refers to this example
637 .\" socket.2 refers to this example
638 .\" bind.2 refers to this example
639 .\" connect.2 refers to this example
640 .\" recvfrom.2 refers to this example
641 .\" sendto.2 refers to this example
642 The following programs demonstrate the use of
648 The programs are an echo server and client for UDP datagrams.
651 .\" SRC BEGIN (server.c)
657 #include <sys/socket.h>
658 #include <sys/types.h>
664 main(int argc, char *argv[])
669 socklen_t peer_addrlen;
670 struct addrinfo hints;
671 struct addrinfo *result, *rp;
672 struct sockaddr_storage peer_addr;
675 fprintf(stderr, "Usage: %s port\en", argv[0]);
679 memset(&hints, 0, sizeof(hints));
680 hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */
681 hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
682 hints.ai_flags = AI_PASSIVE; /* For wildcard IP address */
683 hints.ai_protocol = 0; /* Any protocol */
684 hints.ai_canonname = NULL;
685 hints.ai_addr = NULL;
686 hints.ai_next = NULL;
688 s = getaddrinfo(NULL, argv[1], &hints, &result);
690 fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s));
694 /* getaddrinfo() returns a list of address structures.
695 Try each address until we successfully bind(2).
696 If socket(2) (or bind(2)) fails, we (close the socket
697 and) try the next address. */
699 for (rp = result; rp != NULL; rp = rp\->ai_next) {
700 sfd = socket(rp\->ai_family, rp\->ai_socktype,
705 if (bind(sfd, rp\->ai_addr, rp\->ai_addrlen) == 0)
711 freeaddrinfo(result); /* No longer needed */
713 if (rp == NULL) { /* No address succeeded */
714 fprintf(stderr, "Could not bind\en");
718 /* Read datagrams and echo them back to sender. */
721 char host[NI_MAXHOST], service[NI_MAXSERV];
723 peer_addrlen = sizeof(peer_addr);
724 nread = recvfrom(sfd, buf, BUF_SIZE, 0,
725 (struct sockaddr *) &peer_addr, &peer_addrlen);
727 continue; /* Ignore failed request */
729 s = getnameinfo((struct sockaddr *) &peer_addr,
730 peer_addrlen, host, NI_MAXHOST,
731 service, NI_MAXSERV, NI_NUMERICSERV);
733 printf("Received %zd bytes from %s:%s\en",
734 nread, host, service);
736 fprintf(stderr, "getnameinfo: %s\en", gai_strerror(s));
738 if (sendto(sfd, buf, nread, 0, (struct sockaddr *) &peer_addr,
739 peer_addrlen) != nread)
741 fprintf(stderr, "Error sending response\en");
749 .\" SRC BEGIN (client.c)
755 #include <sys/socket.h>
756 #include <sys/types.h>
762 main(int argc, char *argv[])
768 struct addrinfo hints;
769 struct addrinfo *result, *rp;
772 fprintf(stderr, "Usage: %s host port msg...\en", argv[0]);
776 /* Obtain address(es) matching host/port. */
778 memset(&hints, 0, sizeof(hints));
779 hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */
780 hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
782 hints.ai_protocol = 0; /* Any protocol */
784 s = getaddrinfo(argv[1], argv[2], &hints, &result);
786 fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s));
790 /* getaddrinfo() returns a list of address structures.
791 Try each address until we successfully connect(2).
792 If socket(2) (or connect(2)) fails, we (close the socket
793 and) try the next address. */
795 for (rp = result; rp != NULL; rp = rp\->ai_next) {
796 sfd = socket(rp\->ai_family, rp\->ai_socktype,
801 if (connect(sfd, rp\->ai_addr, rp\->ai_addrlen) != \-1)
807 freeaddrinfo(result); /* No longer needed */
809 if (rp == NULL) { /* No address succeeded */
810 fprintf(stderr, "Could not connect\en");
814 /* Send remaining command\-line arguments as separate
815 datagrams, and read responses from server. */
817 for (size_t j = 3; j < argc; j++) {
818 len = strlen(argv[j]) + 1;
819 /* +1 for terminating null byte */
821 if (len > BUF_SIZE) {
823 "Ignoring long message in argument %zu\en", j);
827 if (write(sfd, argv[j], len) != len) {
828 fprintf(stderr, "partial/failed write\en");
832 nread = read(sfd, buf, BUF_SIZE);
838 printf("Received %zd bytes: %s\en", nread, buf);
846 .\" .BR getipnodebyaddr (3),
847 .\" .BR getipnodebyname (3),
848 .BR getaddrinfo_a (3),
849 .BR gethostbyname (3),