1GETNAMEINFO(3) Linux Programmer's Manual GETNAMEINFO(3)
2
6 getnameinfo - address-to-name translation in protocol-independent man‐
7 ner
8
10 #include <sys/socket.h>
11 #include <netdb.h>
12 int getnameinfo(const struct sockaddr *restrict sa,
14 socklen_t salen, char *restrict host,
15 socklen_t hostlen, char *restrict serv,
16 socklen_t servlen, int flags);
17 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19 getnameinfo(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _POSIX_SOURCE
21
23 The getnameinfo() function is the inverse of getaddrinfo(3): it con‐
24 verts a socket address to a corresponding host and service, in a proto‐
25 col-independent manner. It combines the functionality of gethost‐
26 byaddr(3) and getservbyport(3), but unlike those functions, getad‐
27 drinfo(3) is reentrant and allows programs to eliminate IPv4-versus-
28 IPv6 dependencies.
29 The sa argument is a pointer to a generic socket address structure (of
31 type sockaddr_in or sockaddr_in6) of size salen that holds the input IP
32 address and port number. The arguments host and serv are pointers to
33 caller-allocated buffers (of size hostlen and servlen respectively)
34 into which getnameinfo() places null-terminated strings containing the
35 host and service names respectively.
36 The caller can specify that no hostname (or no service name) is
38 required by providing a NULL host (or serv) argument or a zero hostlen
39 (or servlen) argument. However, at least one of hostname or service
40 name must be requested.
41 The flags argument modifies the behavior of getnameinfo() as follows:
43 NI_NAMEREQD
45 If set, then an error is returned if the hostname cannot be
46 determined.
47 NI_DGRAM
49 If set, then the service is datagram (UDP) based rather than
50 stream (TCP) based. This is required for the few ports
51 (512-514) that have different services for UDP and TCP.
52 NI_NOFQDN
54 If set, return only the hostname part of the fully qualified
55 domain name for local hosts.
56 NI_NUMERICHOST
58 If set, then the numeric form of the hostname is returned.
59 (When not set, this will still happen in case the node's name
60 cannot be determined.)
61 NI_NUMERICSERV
63 If set, then the numeric form of the service address is
64 returned. (When not set, this will still happen in case the
65 service's name cannot be determined.)
66 Extensions to getaddrinfo() for Internationalized Domain Names
68 Starting with glibc 2.3.4, getnameinfo() has been extended to selec‐
69 tively allow hostnames to be transparently converted to and from the
70 Internationalized Domain Name (IDN) format (see RFC 3490, Internation‐
71 alizing Domain Names in Applications (IDNA)). Three new flags are
72 defined:
73 NI_IDN If this flag is used, then the name found in the lookup process
75 is converted from IDN format to the locale's encoding if neces‐
76 sary. ASCII-only names are not affected by the conversion,
77 which makes this flag usable in existing programs and environ‐
78 ments.
79 NI_IDN_ALLOW_UNASSIGNED, NI_IDN_USE_STD3_ASCII_RULES
81 Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow
82 unassigned Unicode code points) and IDNA_USE_STD3_ASCII_RULES
83 (check output to make sure it is a STD3 conforming hostname)
84 flags respectively to be used in the IDNA handling.
85
87 On success 0 is returned, and node and service names, if requested, are
88 filled with null-terminated strings, possibly truncated to fit the
89 specified buffer lengths. On error one of the following nonzero error
90 codes is returned:
91 EAI_AGAIN
93 The name could not be resolved at this time. Try again later.
94 EAI_BADFLAGS
96 The flags argument has an invalid value.
97 EAI_FAIL
99 A nonrecoverable error occurred.
100 EAI_FAMILY
102 The address family was not recognized, or the address length was
103 invalid for the specified family.
104 EAI_MEMORY
106 Out of memory.
107 EAI_NONAME
109 The name does not resolve for the supplied arguments.
110 NI_NAMEREQD is set and the host's name cannot be located, or
111 neither hostname nor service name were requested.
112 EAI_OVERFLOW
114 The buffer pointed to by host or serv was too small.
115 EAI_SYSTEM
117 A system error occurred. The error code can be found in errno.
118 The gai_strerror(3) function translates these error codes to a human
120 readable string, suitable for error reporting.
121
123 /etc/hosts
124 /etc/nsswitch.conf
125 /etc/resolv.conf
126
128 getnameinfo() is provided in glibc since version 2.1.
129
131 RFC 2553, POSIX.1-2001.
132
134 In order to assist the programmer in choosing reasonable sizes for the
135 supplied buffers, <netdb.h> defines the constants
136 #define NI_MAXHOST 1025
138 #define NI_MAXSERV 32
139 Since glibc 2.8, these definitions are exposed only if one of the fea‐
141 ture test macros _BSD_SOURCE, _SVID_SOURCE, or _GNU_SOURCE is defined.
142 The former is the constant MAXDNAME in recent versions of BIND's
144 <arpa/nameser.h> header file. The latter is a guess based on the ser‐
145 vices listed in the current Assigned Numbers RFC.
146
148 The following code tries to get the numeric hostname and service name,
149 for a given socket address. Note that there is no hardcoded reference
150 to a particular address family.
151 struct sockaddr *sa; /* input */
153 socklen_t len; /* input */
154 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
155 if (getnameinfo(sa, len, hbuf, sizeof(hbuf), sbuf,
157 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
158 printf("host=%s, serv=%s\n", hbuf, sbuf);
159 The following version checks if the socket address has a reverse
161 address mapping.
162 struct sockaddr *sa; /* input */
164 socklen_t len; /* input */
165 char hbuf[NI_MAXHOST];
166 if (getnameinfo(sa, len, hbuf, sizeof(hbuf),
168 NULL, 0, NI_NAMEREQD))
169 printf("could not resolve hostname");
170 else
171 printf("host=%s\n", hbuf);
172 An example program using getnameinfo() can be found in getaddrinfo(3).
174
176 accept(2), getpeername(2), getsockname(2), recvfrom(2), socket(2),
177 getaddrinfo(3), gethostbyaddr(3), getservbyname(3), getservbyport(3),
178 inet_ntop(3), hosts(5), services(5), hostname(7), named(8)
179 R. Gilligan, S. Thomson, J. Bound and W. Stevens, Basic Socket Inter‐
181 face Extensions for IPv6, RFC 2553, March 1999.
182 Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
184 Addresses, internet draft, work in progress. ftp://ftp.ietf.org/inter‐
185 net-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt
186 Craig Metz, Protocol Independence Using the Sockets API, Proceedings of
188 the freenix track: 2000 USENIX annual technical conference, June 2000.
189 http://www.usenix.org/publications/library/proceed‐
190 ings/usenix2000/freenix/metzprotocol.html
191
193 This page is part of release 3.25 of the Linux man-pages project. A
194 description of the project, and information about reporting bugs, can
195 be found at http://www.kernel.org/doc/man-pages/.
196GNU 2009-12-03 GETNAMEINFO(3)