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 *addr, socklen_t addrlen,
14 char *host, socklen_t hostlen,
15 char *serv, socklen_t servlen, int flags);
16 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
18 getnameinfo():
20 Since glibc 2.22: _POSIX_C_SOURCE >= 201112L
21 Glibc 2.21 and earlier: _POSIX_C_SOURCE
22
24 The getnameinfo() function is the inverse of getaddrinfo(3): it con‐
25 verts a socket address to a corresponding host and service, in a proto‐
26 col-independent manner. It combines the functionality of gethost‐
27 byaddr(3) and getservbyport(3), but unlike those functions, getname‐
28 info() is reentrant and allows programs to eliminate IPv4-versus-IPv6
29 dependencies.
30 The addr argument is a pointer to a generic socket address structure
32 (of type sockaddr_in or sockaddr_in6) of size addrlen that holds the
33 input IP address and port number. The arguments host and serv are
34 pointers to caller-allocated buffers (of size hostlen and servlen
35 respectively) into which getnameinfo() places null-terminated strings
36 containing the host and service names respectively.
37 The caller can specify that no hostname (or no service name) is
39 required by providing a NULL host (or serv) argument or a zero hostlen
40 (or servlen) argument. However, at least one of hostname or service
41 name must be requested.
42 The flags argument modifies the behavior of getnameinfo() as follows:
44 NI_NAMEREQD
46 If set, then an error is returned if the hostname cannot be
47 determined.
48 NI_DGRAM
50 If set, then the service is datagram (UDP) based rather than
51 stream (TCP) based. This is required for the few ports
52 (512–514) that have different services for UDP and TCP.
53 NI_NOFQDN
55 If set, return only the hostname part of the fully qualified
56 domain name for local hosts.
57 NI_NUMERICHOST
59 If set, then the numeric form of the hostname is returned.
60 (When not set, this will still happen in case the node's name
61 cannot be determined.)
62 NI_NUMERICSERV
64 If set, then the numeric form of the service address is
65 returned. (When not set, this will still happen in case the
66 service's name cannot be determined.)
67 Extensions to getnameinfo() for Internationalized Domain Names
69 Starting with glibc 2.3.4, getnameinfo() has been extended to selec‐
70 tively allow hostnames to be transparently converted to and from the
71 Internationalized Domain Name (IDN) format (see RFC 3490, Internation‐
72 alizing Domain Names in Applications (IDNA)). Three new flags are
73 defined:
74 NI_IDN If this flag is used, then the name found in the lookup process
76 is converted from IDN format to the locale's encoding if neces‐
77 sary. ASCII-only names are not affected by the conversion,
78 which makes this flag usable in existing programs and environ‐
79 ments.
80 NI_IDN_ALLOW_UNASSIGNED, NI_IDN_USE_STD3_ASCII_RULES
82 Setting these flags will enable the IDNA_ALLOW_UNASSIGNED (allow
83 unassigned Unicode code points) and IDNA_USE_STD3_ASCII_RULES
84 (check output to make sure it is a STD3 conforming hostname)
85 flags respectively to be used in the IDNA handling.
86
88 On success, 0 is returned, and node and service names, if requested,
89 are filled with null-terminated strings, possibly truncated to fit the
90 specified buffer lengths. On error, one of the following nonzero error
91 codes is returned:
92 EAI_AGAIN
94 The name could not be resolved at this time. Try again later.
95 EAI_BADFLAGS
97 The flags argument has an invalid value.
98 EAI_FAIL
100 A nonrecoverable error occurred.
101 EAI_FAMILY
103 The address family was not recognized, or the address length was
104 invalid for the specified family.
105 EAI_MEMORY
107 Out of memory.
108 EAI_NONAME
110 The name does not resolve for the supplied arguments.
111 NI_NAMEREQD is set and the host's name cannot be located, or
112 neither hostname nor service name were requested.
113 EAI_OVERFLOW
115 The buffer pointed to by host or serv was too small.
116 EAI_SYSTEM
118 A system error occurred. The error code can be found in errno.
119 The gai_strerror(3) function translates these error codes to a human
121 readable string, suitable for error reporting.
122
124 /etc/hosts
125 /etc/nsswitch.conf
126 /etc/resolv.conf
127
129 getnameinfo() is provided in glibc since version 2.1.
130
132 For an explanation of the terms used in this section, see
133 attributes(7).
134 ┌──────────────┬───────────────┬────────────────────┐
136 │Interface │ Attribute │ Value │
137 ├──────────────┼───────────────┼────────────────────┤
138 │getnameinfo() │ Thread safety │ MT-Safe env locale │
139 └──────────────┴───────────────┴────────────────────┘
140
142 POSIX.1-2001, POSIX.1-2008, RFC 2553.
143
145 In order to assist the programmer in choosing reasonable sizes for the
146 supplied buffers, <netdb.h> defines the constants
147 #define NI_MAXHOST 1025
149 #define NI_MAXSERV 32
150 Since glibc 2.8, these definitions are exposed only if suitable feature
152 test macros are defined, namely: _GNU_SOURCE, _DEFAULT_SOURCE (since
153 glibc 2.19), or (in glibc versions up to and including 2.19)
154 _BSD_SOURCE or _SVID_SOURCE.
155 The former is the constant MAXDNAME in recent versions of BIND's
157 <arpa/nameser.h> header file. The latter is a guess based on the ser‐
158 vices listed in the current Assigned Numbers RFC.
159 Before glibc version 2.2, the hostlen and servlen arguments were typed
161 as size_t.
162
164 The following code tries to get the numeric hostname and service name,
165 for a given socket address. Note that there is no hardcoded reference
166 to a particular address family.
167 struct sockaddr *addr; /* input */
169 socklen_t addrlen; /* input */
170 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
171 if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf,
173 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
174 printf("host=%s, serv=%s\n", hbuf, sbuf);
175 The following version checks if the socket address has a reverse
177 address mapping.
178 struct sockaddr *addr; /* input */
180 socklen_t addrlen; /* input */
181 char hbuf[NI_MAXHOST];
182 if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf),
184 NULL, 0, NI_NAMEREQD))
185 printf("could not resolve hostname");
186 else
187 printf("host=%s\n", hbuf);
188 An example program using getnameinfo() can be found in getaddrinfo(3).
190
192 accept(2), getpeername(2), getsockname(2), recvfrom(2), socket(2),
193 getaddrinfo(3), gethostbyaddr(3), getservbyname(3), getservbyport(3),
194 inet_ntop(3), hosts(5), services(5), hostname(7), named(8)
195 R. Gilligan, S. Thomson, J. Bound and W. Stevens, Basic Socket Inter‐
197 face Extensions for IPv6, RFC 2553, March 1999.
198 Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
200 Addresses, internet draft, work in progress ⟨ftp://ftp.ietf.org
201 /internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt⟩.
202 Craig Metz, Protocol Independence Using the Sockets API, Proceedings of
204 the freenix track: 2000 USENIX annual technical conference, June 2000
205 ⟨http://www.usenix.org/publications/library/proceedings/usenix2000
206 /freenix/metzprotocol.html⟩.
207
209 This page is part of release 5.02 of the Linux man-pages project. A
210 description of the project, information about reporting bugs, and the
211 latest version of this page, can be found at
212 https://www.kernel.org/doc/man-pages/.
213GNU 2019-03-06 GETNAMEINFO(3)