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.
41 .\" FIXME . glibc's 2.9 NEWS file documents DCCP and UDP-lite support
42 .\" and is SCTP support now also there?
44 .TH GETADDRINFO 3 2014-04-06 "GNU" "Linux Programmer's Manual"
46 getaddrinfo, freeaddrinfo, gai_strerror \- network address and
50 .B #include <sys/types.h>
51 .B #include <sys/socket.h>
54 .BI "int getaddrinfo(const char *" "node" ", const char *" "service" ,
55 .BI " const struct addrinfo *" "hints" ,
56 .BI " struct addrinfo **" "res" );
58 .BI "void freeaddrinfo(struct addrinfo *" "res" );
60 .BI "const char *gai_strerror(int " "errcode" );
64 Feature Test Macro Requirements for glibc (see
65 .BR feature_test_macros (7)):
73 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
81 which identify an Internet host and a service,
85 structures, each of which contains an Internet address
86 that can be specified in a call to
92 function combines the functionality provided by the
93 .\" .BR getipnodebyname (3),
94 .\" .BR getipnodebyaddr (3),
98 functions into a single interface, but unlike the latter functions,
100 is reentrant and allows programs to eliminate IPv4-versus-IPv6 dependencies.
106 contains the following fields:
115 socklen_t ai_addrlen;
116 struct sockaddr *ai_addr;
118 struct addrinfo *ai_next;
125 argument points to an
127 structure that specifies criteria for selecting the socket address
128 structures returned in the list pointed to by
132 is not NULL it points to an
139 specify criteria that limit the set of socket addresses returned by
144 This field specifies the desired address family for the returned addresses.
145 Valid values for this field include
153 should return socket addresses for any address family
154 (either IPv4 or IPv6, for example) that can be used with
160 This field specifies the preferred socket type, for example
164 Specifying 0 in this field indicates that socket addresses of any type
169 This field specifies the protocol for the returned socket addresses.
170 Specifying 0 in this field indicates that socket addresses with
171 any protocol can be returned by
175 This field specifies additional options, described below.
176 Multiple flags are specified by bitwise OR-ing them together.
178 All the other fields in the structure pointed to by
180 must contain either 0 or a null pointer, as appropriate.
184 as NULL is equivalent to setting
195 .BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)" .
196 (POSIX specifies different defaults for
200 specifies either a numerical network address
201 (for IPv4, numbers-and-dots notation as supported by
203 for IPv6, hexadecimal string format as supported by
205 or a network hostname, whose network addresses are looked up and resolved.
212 must be a numerical network address.
215 flag suppresses any potentially lengthy network host address lookups.
224 then the returned socket addresses will be suitable for
229 The returned socket address will contain the "wildcard address"
234 The wildcard address is used by applications (typically servers)
235 that intend to accept connections on any of the hosts's network addresses.
238 is not NULL, then the
246 then the returned socket addresses will be suitable for use with
254 then the network address will be set to the loopback interface address
255 .RB ( INADDR_LOOPBACK
257 .BR IN6ADDR_LOOPBACK_INIT
259 this is used by applications that intend to communicate
260 with peers running on the same host.
263 sets the port in each returned address structure.
264 If this argument is a service name (see
266 it is translated to the corresponding port number.
267 This argument can also be specified as a decimal number,
268 which is simply converted to binary.
271 is NULL, then the port number of the returned socket addresses
272 will be left uninitialized.
281 must point to a string containing a numeric port number.
282 This flag is used to inhibit the invocation of a name resolution service
283 in cases where it is known not to be required.
289 but not both, may be NULL.
293 function allocates and initializes a linked list of
295 structures, one for each network address that matches
299 subject to any restrictions imposed by
301 and returns a pointer to the start of the list in
303 The items in the linked list are linked by the
307 There are several reasons why
308 the linked list may have more than one
310 structure, including: the network host is multihomed, accessible
311 over multiple protocols (e.g., both
315 or the same service is available from multiple socket types (one
319 address, for example).
320 Normally, the application should try
321 using the addresses in the order in which they are returned.
322 The sorting function used within
324 is defined in RFC\ 3484; the order can be tweaked for a particular
327 (available since glibc 2.5).
335 field of the first of the
337 structures in the returned list is set to point to the
338 official name of the host.
339 .\" In glibc prior to 2.3.4, the ai_canonname of each addrinfo
340 .\" structure was set pointing to the canonical name; that was
341 .\" more than POSIX.1-2001 specified, or other implementations provided.
344 The remaining fields of each returned
346 structure are initialized as follows:
353 fields return the socket creation parameters (i.e., these fields have
354 the same meaning as the corresponding arguments of
369 returns the protocol for the socket.
371 A pointer to the socket address is placed in the
373 field, and the length of the socket address, in bytes,
382 flag, then IPv4 addresses are returned in the list pointed to by
384 only if the local system has at least one
385 IPv4 address configured, and IPv6 addresses are returned
386 only if the local system has at least one IPv6 address configured.
387 The loopback address is not considered for this case as valid
388 as a configured address.
389 This flag is useful on, for example,
390 IPv4-only systems, to ensure that
392 does not return IPv6 socket addresses that would always fail in
405 and no matching IPv6 addresses could be found,
406 then return IPv4-mapped IPv6 addresses in the list pointed to by
414 then return both IPv6 and IPv4-mapped IPv6 addresses
415 in the list pointed to by
420 is not also specified.
424 function frees the memory that was allocated
425 for the dynamically allocated linked list
427 .SS Extensions to getaddrinfo() for Internationalized Domain Names
429 Starting with glibc 2.3.4,
431 has been extended to selectively allow the incoming and outgoing
432 hostnames to be transparently converted to and from the
433 Internationalized Domain Name (IDN) format (see RFC 3490,
434 .IR "Internationalizing Domain Names in Applications (IDNA)" ).
435 Four new flags are defined:
438 If this flag is specified, then the node name given in
440 is converted to IDN format if necessary.
441 The source encoding is that of the current locale.
443 If the input name contains non-ASCII characters, then the IDN encoding
445 Those parts of the node name (delimited by dots) that contain
446 non-ASCII characters are encoded using ASCII Compatible Encoding (ACE)
447 before being passed to the name resolution functions.
448 .\" Implementation Detail:
449 .\" To minimize effects on system performance the implementation might
450 .\" want to check whether the input string contains any non-ASCII
451 .\" characters. If there are none the IDN step can be skipped completely.
452 .\" On systems which allow not-ASCII safe encodings for a locale this
453 .\" might be a problem.
456 After a successful name lookup, and if the
460 will return the canonical name of the
461 node corresponding to the
463 structure value passed back.
464 The return value is an exact copy of the value returned by the name
467 If the name is encoded using ACE, then it will contain the
469 prefix for one or more components of the name.
470 To convert these components into a readable form the
472 flag can be passed in addition to
474 The resulting string is encoded using the current locale's encoding.
476 .\"Implementation Detail:
477 .\"If no component of the returned name starts with xn\-\- the IDN
478 .\"step can be skipped, therefore avoiding unnecessary slowdowns.
480 .BR AI_IDN_ALLOW_UNASSIGNED ", " AI_IDN_USE_STD3_ASCII_RULES
481 Setting these flags will enable the
482 IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and
483 IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3
485 flags respectively to be used in the IDNA handling.
487 .\" FIXME glibc defines the following additional errors, some which
488 .\" can probably be returned by getaddrinfo(); they need to
491 .\" #define EAI_INPROGRESS -100 /* Processing request in progress. */
492 .\" #define EAI_CANCELED -101 /* Request canceled. */
493 .\" #define EAI_NOTCANCELED -102 /* Request not canceled. */
494 .\" #define EAI_ALLDONE -103 /* All requests done. */
495 .\" #define EAI_INTR -104 /* Interrupted by a signal. */
496 .\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */
499 returns 0 if it succeeds, or one of the following nonzero error codes:
503 The specified network host does not have any network addresses in the
504 requested address family.
507 The name server returned a temporary failure indication.
512 contains invalid flags; or,
521 The name server returned a permanent failure indication.
524 The requested address family is not supported.
531 The specified network host exists, but does not have any
532 network addresses defined.
539 is not known; or both
549 was not a numeric port-number string.
552 The requested service is not available for the requested socket type.
553 It may be available through another socket type.
554 For example, this error could occur if
556 was "shell" (a service available only on stream sockets), and either
564 or the error could occur if
570 (a socket type that does not support the concept of services).
573 The requested socket type is not supported.
574 This could occur, for example, if
578 are inconsistent (e.g.,
585 Other system error, check
591 function translates these error codes to a human readable string,
592 suitable for error reporting.
599 function is documented in RFC\ 2553.
603 .IB address % scope-id
604 notation for specifying the IPv6 scope-ID.
610 are available since glibc 2.3.3.
612 is available since glibc 2.3.4.
614 According to POSIX.1-2001, specifying
619 The GNU C library instead assumes a value of
620 .BR "(AI_V4MAPPED\ |\ AI_ADDRCONFIG)"
622 since this value is considered an improvement on the specification.
624 .\" getnameinfo.3 refers to this example
625 .\" socket.2 refers to this example
626 .\" bind.2 refers to this example
627 .\" connect.2 refers to this example
628 .\" recvfrom.2 refers to this example
629 .\" sendto.2 refers to this example
630 The following programs demonstrate the use of
636 The programs are an echo server and client for UDP datagrams.
640 #include <sys/types.h>
645 #include <sys/socket.h>
651 main(int argc, char *argv[])
653 struct addrinfo hints;
654 struct addrinfo *result, *rp;
656 struct sockaddr_storage peer_addr;
657 socklen_t peer_addr_len;
662 fprintf(stderr, "Usage: %s port\\n", argv[0]);
666 memset(&hints, 0, sizeof(struct addrinfo));
667 hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */
668 hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
669 hints.ai_flags = AI_PASSIVE; /* For wildcard IP address */
670 hints.ai_protocol = 0; /* Any protocol */
671 hints.ai_canonname = NULL;
672 hints.ai_addr = NULL;
673 hints.ai_next = NULL;
675 s = getaddrinfo(NULL, argv[1], &hints, &result);
677 fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s));
681 /* getaddrinfo() returns a list of address structures.
682 Try each address until we successfully bind(2).
683 If socket(2) (or bind(2)) fails, we (close the socket
684 and) try the next address. */
686 for (rp = result; rp != NULL; rp = rp\->ai_next) {
687 sfd = socket(rp\->ai_family, rp\->ai_socktype,
692 if (bind(sfd, rp\->ai_addr, rp\->ai_addrlen) == 0)
698 if (rp == NULL) { /* No address succeeded */
699 fprintf(stderr, "Could not bind\\n");
703 freeaddrinfo(result); /* No longer needed */
705 /* Read datagrams and echo them back to sender */
708 peer_addr_len = sizeof(struct sockaddr_storage);
709 nread = recvfrom(sfd, buf, BUF_SIZE, 0,
710 (struct sockaddr *) &peer_addr, &peer_addr_len);
712 continue; /* Ignore failed request */
714 char host[NI_MAXHOST], service[NI_MAXSERV];
716 s = getnameinfo((struct sockaddr *) &peer_addr,
717 peer_addr_len, host, NI_MAXHOST,
718 service, NI_MAXSERV, NI_NUMERICSERV);
720 printf("Received %zd bytes from %s:%s\\n",
721 nread, host, service);
723 fprintf(stderr, "getnameinfo: %s\\n", gai_strerror(s));
725 if (sendto(sfd, buf, nread, 0,
726 (struct sockaddr *) &peer_addr,
727 peer_addr_len) != nread)
728 fprintf(stderr, "Error sending response\\n");
735 #include <sys/types.h>
736 #include <sys/socket.h>
746 main(int argc, char *argv[])
748 struct addrinfo hints;
749 struct addrinfo *result, *rp;
756 fprintf(stderr, "Usage: %s host port msg...\\n", argv[0]);
760 /* Obtain address(es) matching host/port */
762 memset(&hints, 0, sizeof(struct addrinfo));
763 hints.ai_family = AF_UNSPEC; /* Allow IPv4 or IPv6 */
764 hints.ai_socktype = SOCK_DGRAM; /* Datagram socket */
766 hints.ai_protocol = 0; /* Any protocol */
768 s = getaddrinfo(argv[1], argv[2], &hints, &result);
770 fprintf(stderr, "getaddrinfo: %s\\n", gai_strerror(s));
774 /* getaddrinfo() returns a list of address structures.
775 Try each address until we successfully connect(2).
776 If socket(2) (or connect(2)) fails, we (close the socket
777 and) try the next address. */
779 for (rp = result; rp != NULL; rp = rp\->ai_next) {
780 sfd = socket(rp\->ai_family, rp\->ai_socktype,
785 if (connect(sfd, rp\->ai_addr, rp\->ai_addrlen) != \-1)
791 if (rp == NULL) { /* No address succeeded */
792 fprintf(stderr, "Could not connect\\n");
796 freeaddrinfo(result); /* No longer needed */
798 /* Send remaining command\-line arguments as separate
799 datagrams, and read responses from server */
801 for (j = 3; j < argc; j++) {
802 len = strlen(argv[j]) + 1;
803 /* +1 for terminating null byte */
805 if (len + 1 > BUF_SIZE) {
807 "Ignoring long message in argument %d\\n", j);
811 if (write(sfd, argv[j], len) != len) {
812 fprintf(stderr, "partial/failed write\\n");
816 nread = read(sfd, buf, BUF_SIZE);
822 printf("Received %zd bytes: %s\\n", nread, buf);
829 .\" .BR getipnodebyaddr (3),
830 .\" .BR getipnodebyname (3),
831 .BR getaddrinfo_a (3),
832 .BR gethostbyname (3),
839 This page is part of release 3.78 of the Linux
842 A description of the project,
843 information about reporting bugs,
844 and the latest version of this page,
846 \%http://www.kernel.org/doc/man\-pages/.