1 .\" Copyright (c) 2007, 2008 Michael Kerrisk <mtk.manpages@gmail.com>
2 .\" and Copyright (c) 2006 Ulrich Drepper <drepper@redhat.com>
3 .\" A few pieces of an earlier version remain:
4 .\" Copyright 2000, Sam Varshavchik <mrsam@courier-mta.com>
6 .\" %%%LICENSE_START(VERBATIM)
7 .\" Permission is granted to make and distribute verbatim copies of this
8 .\" manual provided the copyright notice and this permission notice are
9 .\" preserved on all copies.
11 .\" Permission is granted to copy and distribute modified versions of this
12 .\" manual under the conditions for verbatim copying, provided that the
13 .\" entire resulting derived work is distributed under the terms of a
14 .\" permission notice identical to this one.
16 .\" Since the Linux kernel and libraries are constantly changing, this
17 .\" manual page may be incorrect or out-of-date. The author(s) assume no
18 .\" responsibility for errors or omissions, or for damages resulting from
19 .\" the use of the information contained herein. The author(s) may not
20 .\" have taken the same level of care in the production of this manual,
21 .\" which is licensed free of charge, as they might when working
24 .\" Formatted or processed versions of this manual, if unaccompanied by
25 .\" the source, must acknowledge the copyright and authors of this work.
28 .\" References: RFC 2553
30 .\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED,
31 .\" and AI_NUMERICSERV.
32 .\" 2006-11-25, Ulrich Drepper <drepper@redhat.com>
33 .\" Add text describing Internationalized Domain Name extensions.
34 .\" 2007-06-08, mtk: added example programs
35 .\" 2008-02-26, mtk; clarify discussion of NULL 'hints' argument; other
37 .\" 2008-06-18, mtk: many parts rewritten
38 .\" 2008-12-04, Petr Baudis <pasky@suse.cz>
39 .\" Describe results ordering and reference /etc/gai.conf.
40 .\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support
41 .\" and is SCTP support now also there?
43 .TH GETADDRINFO 3 2014-04-06 "GNU" "Linux Programmer's Manual"
45 getaddrinfo, freeaddrinfo, gai_strerror \- network address and
49 .B #include <sys/types.h>
50 .B #include <sys/socket.h>
53 .BI "int getaddrinfo(const char *" "node" ", const char *" "service" ,
54 .BI " const struct addrinfo *" "hints" ,
55 .BI " struct addrinfo **" "res" );
57 .BI "void freeaddrinfo(struct addrinfo *" "res" );
59 .BI "const char *gai_strerror(int " "errcode" );
63 Feature Test Macro Requirements for glibc (see
64 .BR feature_test_macros (7)):
72 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
80 which identify an Internet host and a service,
84 structures, each of which contains an Internet address
85 that can be specified in a call to
91 function combines the functionality provided by the
92 .\" .BR getipnodebyname (3),
93 .\" .BR getipnodebyaddr (3),
97 functions into a single interface, but unlike the latter functions,
99 is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies.
105 contains the following fields:
114 socklen_t ai_addrlen;
115 struct sockaddr *ai_addr;
117 struct addrinfo *ai_next;
124 argument points to an
126 structure that specifies criteria for selecting the socket address
127 structures returned in the list pointed to by
131 is not NULL it points to an
138 specify criteria that limit the set of socket addresses returned by
143 This field specifies the desired address family for the returned addresses.
144 Valid values for this field include
152 should return socket addresses for any address family
153 (either IPv4 or IPv6, for example) that can be used with
159 This field specifies the preferred socket type, for example
163 Specifying 0 in this field indicates that socket addresses of any type
168 This field specifies the protocol for the returned socket addresses.
169 Specifying 0 in this field indicates that socket addresses with
170 any protocol can be returned by
174 This field specifies additional options, described below.
175 Multiple flags are specified by bitwise OR-ing them together.
177 All the other fields in the structure pointed to by
179 must contain either 0 or a null pointer, as appropriate.
183 as NULL is equivalent to setting
194 .BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)" .
195 (POSIX specifies different defaults for
199 specifies either a numerical network address
200 (for IPv4, numbers-and-dots notation as supported by
202 for IPv6, hexadecimal string format as supported by
204 or a network hostname, whose network addresses are looked up and resolved.
211 must be a numerical network address.
214 flag suppresses any potentially lengthy network host address lookups.
223 then the returned socket addresses will be suitable for
228 The returned socket address will contain the "wildcard address"
233 The wildcard address is used by applications (typically servers)
234 that intend to accept connections on any of the hosts's network addresses.
237 is not NULL, then the
245 then the returned socket addresses will be suitable for use with
253 then the network address will be set to the loopback interface address
254 .RB ( INADDR_LOOPBACK
256 .BR IN6ADDR_LOOPBACK_INIT
258 this is used by applications that intend to communicate
259 with peers running on the same host.
262 sets the port in each returned address structure.
263 If this argument is a service name (see
265 it is translated to the corresponding port number.
266 This argument can also be specified as a decimal number,
267 which is simply converted to binary.
270 is NULL, then the port number of the returned socket addresses
271 will be left uninitialized.
280 must point to a string containing a numeric port number.
281 This flag is used to inhibit the invocation of a name resolution service
282 in cases where it is known not to be required.
288 but not both, may be NULL.
292 function allocates and initializes a linked list of
294 structures, one for each network address that matches
298 subject to any restrictions imposed by
300 and returns a pointer to the start of the list in
302 The items in the linked list are linked by the
306 There are several reasons why
307 the linked list may have more than one
309 structure, including: the network host is multihomed, accessible
310 over multiple protocols (e.g., both
314 or the same service is available from multiple socket types (one
318 address, for example).
319 Normally, the application should try
320 using the addresses in the order in which they are returned.
321 The sorting function used within
323 is defined in RFC\ 3484; the order can be tweaked for a particular
326 (available since glibc 2.5).
334 field of the first of the
336 structures in the returned list is set to point to the
337 official name of the host.
338 .\" In glibc prior to 2.3.4, the ai_canonname of each addrinfo
339 .\" structure was set pointing to the canonical name; that was
340 .\" more than POSIX.1-2001 specified, or other implementations provided.
343 The remaining fields of each returned
345 structure are initialized as follows:
352 fields return the socket creation parameters (i.e., these fields have
353 the same meaning as the corresponding arguments of
368 returns the protocol for the socket.
370 A pointer to the socket address is placed in the
372 field, and the length of the socket address, in bytes,
381 flag, then IPv4 addresses are returned in the list pointed to by
383 only if the local system has at least one
384 IPv4 address configured, and IPv6 addresses are returned
385 only if the local system has at least one IPv6 address configured.
386 The loopback address is not considered for this case as valid
387 as a configured address.
388 This flag is useful on, for example,
389 IPv4-only systems, to ensure that
391 does not return IPv6 socket addresses that would always fail in
404 and no matching IPv6 addresses could be found,
405 then return IPv4-mapped IPv6 addresses in the list pointed to by
413 then return both IPv6 and IPv4-mapped IPv6 addresses
414 in the list pointed to by
419 is not also specified.
423 function frees the memory that was allocated
424 for the dynamically allocated linked list
426 .SS Extensions to getaddrinfo() for Internationalized Domain Names
428 Starting with glibc 2.3.4,
430 has been extended to selectively allow the incoming and outgoing
431 hostnames to be transparently converted to and from the
432 Internationalized Domain Name (IDN) format (see RFC 3490,
433 .IR "Internationalizing Domain Names in Applications (IDNA)" ).
434 Four new flags are defined:
437 If this flag is specified, then the node name given in
439 is converted to IDN format if necessary.
440 The source encoding is that of the current locale.
442 If the input name contains non-ASCII characters, then the IDN encoding
444 Those parts of the node name (delimited by dots) that contain
445 non-ASCII characters are encoded using ASCII Compatible Encoding (ACE)
446 before being passed to the name resolution functions.
447 .\" Implementation Detail:
448 .\" To minimize effects on system performance the implementation might
449 .\" want to check whether the input string contains any non-ASCII
450 .\" characters. If there are none the IDN step can be skipped completely.
451 .\" On systems which allow not-ASCII safe encodings for a locale this
452 .\" might be a problem.
455 After a successful name lookup, and if the
459 will return the canonical name of the
460 node corresponding to the
462 structure value passed back.
463 The return value is an exact copy of the value returned by the name
466 If the name is encoded using ACE, then it will contain the
468 prefix for one or more components of the name.
469 To convert these components into a readable form the
471 flag can be passed in addition to
473 The resulting string is encoded using the current locale's encoding.
475 .\"Implementation Detail:
476 .\"If no component of the returned name starts with xn\-\- the IDN
477 .\"step can be skipped, therefore avoiding unnecessary slowdowns.
479 .BR AI_IDN_ALLOW_UNASSIGNED ", " AI_IDN_USE_STD3_ASCII_RULES
480 Setting these flags will enable the
481 IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and
482 IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3
484 flags respectively to be used in the IDNA handling.
486 .\" FIXME glibc defines the following additional errors, some which
487 .\" can probably be returned by getaddrinfo(); they need to
490 .\" #define EAI_INPROGRESS -100 /* Processing request in progress. */
491 .\" #define EAI_CANCELED -101 /* Request canceled. */
492 .\" #define EAI_NOTCANCELED -102 /* Request not canceled. */
493 .\" #define EAI_ALLDONE -103 /* All requests done. */
494 .\" #define EAI_INTR -104 /* Interrupted by a signal. */
495 .\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */
498 returns 0 if it succeeds, or one of the following nonzero error codes:
502 The specified network host does not have any network addresses in the
503 requested address family.
506 The name server returned a temporary failure indication.
511 contains invalid flags; or,
520 The name server returned a permanent failure indication.
523 The requested address family is not supported.
530 The specified network host exists, but does not have any
531 network addresses defined.
538 is not known; or both
548 was not a numeric port-number string.
551 The requested service is not available for the requested socket type.
552 It may be available through another socket type.
553 For example, this error could occur if
555 was "shell" (a service available only on stream sockets), and either
563 or the error could occur if
569 (a socket type that does not support the concept of services).
572 The requested socket type is not supported.
573 This could occur, for example, if
577 are inconsistent (e.g.,
584 Other system error, check
590 function translates these error codes to a human readable string,
591 suitable for error reporting.
598 function is documented in RFC\ 2553.
602 .IB address % scope-id
603 notation for specifying the IPv6 scope-ID.
609 are available since glibc 2.3.3.
611 is available since glibc 2.3.4.
613 According to POSIX.1-2001, specifying
618 The GNU C library instead assumes a value of
619 .BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)"
621 since this value is considered an improvement on the specification.
623 .\" getnameinfo.3 refers to this example
624 .\" socket.2 refers to this example
625 .\" bind.2 refers to this example
626 .\" connect.2 refers to this example
627 .\" recvfrom.2 refers to this example
628 .\" sendto.2 refers to this example
629 The following programs demonstrate the use of
635 The programs are an echo server and client for UDP datagrams.
639 #include <sys/types.h>
644 #include <sys/socket.h>
650 main(int argc, char *argv[])
652 struct addrinfo hints;
653 struct addrinfo *result, *rp;
655 struct sockaddr_storage peer_addr;
656 socklen_t peer_addr_len;
661 fprintf(stderr, "Usage: %s port\\n", argv[0]);
665 memset(&hints, 0, sizeof(struct addrinfo));
666 hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */
667 hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
668 hints.ai_flags = AI_PASSIVE; /* For wildcard IP address */
669 hints.ai_protocol = 0; /* Any protocol */
670 hints.ai_canonname = NULL;
671 hints.ai_addr = NULL;
672 hints.ai_next = NULL;
674 s = getaddrinfo(NULL, argv[1], &hints, &result);
676 fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s));
680 /* getaddrinfo() returns a list of address structures.
681 Try each address until we successfully bind(2).
682 If socket(2) (or bind(2)) fails, we (close the socket
683 and) try the next address. */
685 for (rp = result; rp != NULL; rp = rp\->ai_next) {
686 sfd = socket(rp\->ai_family, rp\->ai_socktype,
691 if (bind(sfd, rp\->ai_addr, rp\->ai_addrlen) == 0)
697 if (rp == NULL) { /* No address succeeded */
698 fprintf(stderr, "Could not bind\\n");
702 freeaddrinfo(result); /* No longer needed */
704 /* Read datagrams and echo them back to sender */
707 peer_addr_len = sizeof(struct sockaddr_storage);
708 nread = recvfrom(sfd, buf, BUF_SIZE, 0,
709 (struct sockaddr *) &peer_addr, &peer_addr_len);
711 continue; /* Ignore failed request */
713 char host[NI_MAXHOST], service[NI_MAXSERV];
715 s = getnameinfo((struct sockaddr *) &peer_addr,
716 peer_addr_len, host, NI_MAXHOST,
717 service, NI_MAXSERV, NI_NUMERICSERV);
719 printf("Received %zd bytes from %s:%s\\n",
720 nread, host, service);
722 fprintf(stderr, "getnameinfo: %s\\n", gai_strerror(s));
724 if (sendto(sfd, buf, nread, 0,
725 (struct sockaddr *) &peer_addr,
726 peer_addr_len) != nread)
727 fprintf(stderr, "Error sending response\\n");
734 #include <sys/types.h>
735 #include <sys/socket.h>
745 main(int argc, char *argv[])
747 struct addrinfo hints;
748 struct addrinfo *result, *rp;
755 fprintf(stderr, "Usage: %s host port msg...\\n", argv[0]);
759 /* Obtain address(es) matching host/port */
761 memset(&hints, 0, sizeof(struct addrinfo));
762 hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */
763 hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
765 hints.ai_protocol = 0; /* Any protocol */
767 s = getaddrinfo(argv[1], argv[2], &hints, &result);
769 fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s));
773 /* getaddrinfo() returns a list of address structures.
774 Try each address until we successfully connect(2).
775 If socket(2) (or connect(2)) fails, we (close the socket
776 and) try the next address. */
778 for (rp = result; rp != NULL; rp = rp\->ai_next) {
779 sfd = socket(rp\->ai_family, rp\->ai_socktype,
784 if (connect(sfd, rp\->ai_addr, rp\->ai_addrlen) != \-1)
790 if (rp == NULL) { /* No address succeeded */
791 fprintf(stderr, "Could not connect\\n");
795 freeaddrinfo(result); /* No longer needed */
797 /* Send remaining command\-line arguments as separate
798 datagrams, and read responses from server */
800 for (j = 3; j < argc; j++) {
801 len = strlen(argv[j]) + 1;
802 /* +1 for terminating null byte */
804 if (len + 1 > BUF_SIZE) {
806 "Ignoring long message in argument %d\\n", j);
810 if (write(sfd, argv[j], len) != len) {
811 fprintf(stderr, "partial/failed write\\n");
815 nread = read(sfd, buf, BUF_SIZE);
821 printf("Received %zd bytes: %s\\n", nread, buf);
828 .\" .BR getipnodebyaddr (3),
829 .\" .BR getipnodebyname (3),
830 .BR getaddrinfo_a (3),
831 .BR gethostbyname (3),
838 This page is part of release 3.67 of the Linux
841 A description of the project,
842 information about reporting bugs,
843 and the latest version of this page,
845 \%http://www.kernel.org/doc/man\-pages/.