1 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
2 .\" This page is in the public domain.
5 .\" Almost all details are from RFC 2553.
7 .\" 2004-12-14, mtk, Added EAI_OVERFLOW error
8 .\" 2004-12-14 Fixed description of error return
10 .TH GETNAMEINFO 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
12 getnameinfo \- address-to-name translation in protocol-independent manner
15 .RI ( libc ", " \-lc )
18 .B #include <sys/socket.h>
21 .BI "int getnameinfo(const struct sockaddr *restrict " addr \
22 ", socklen_t " addrlen ,
23 .BI " char *restrict " host ", socklen_t " hostlen ,
24 .BI " char *restrict " serv ", socklen_t " servlen \
29 Feature Test Macro Requirements for glibc (see
30 .BR feature_test_macros (7)):
36 _POSIX_C_SOURCE >= 200112L
37 Glibc 2.21 and earlier:
43 function is the inverse of
45 it converts a socket address to a corresponding host and service,
46 in a protocol-independent manner.
47 It combines the functionality of
50 .BR getservbyport (3),
51 but unlike those functions,
53 is reentrant and allows programs to eliminate
54 IPv4-versus-IPv6 dependencies.
58 argument is a pointer to a generic socket address structure
65 that holds the input IP address and port number.
70 are pointers to caller-allocated buffers (of size
74 respectively) into which
76 places null-terminated strings containing the host and
77 service names respectively.
79 The caller can specify that no hostname (or no service name)
80 is required by providing a NULL
89 However, at least one of hostname or service name
94 argument modifies the behavior of
99 If set, then an error is returned if the hostname cannot be determined.
102 If set, then the service is datagram (UDP) based rather than
104 This is required for the few ports (512\(en514)
105 that have different services for UDP and TCP.
108 If set, return only the hostname part of the fully qualified domain name
112 If set, then the numeric form of the hostname is returned.
113 .\" For example, by calling
116 .\" .BR gethostbyaddr ().
117 (When not set, this will still happen in case the node's name
118 cannot be determined.)
119 .\" POSIX.1-2001 TC1 has NI_NUMERICSCOPE, but glibc doesn't have it.
122 If set, then the numeric form of the service address is returned.
123 (When not set, this will still happen in case the service's name
124 cannot be determined.)
125 .SS Extensions to getnameinfo() for Internationalized Domain Names
126 Starting with glibc 2.3.4,
128 has been extended to selectively allow
129 hostnames to be transparently converted to and from the
130 Internationalized Domain Name (IDN) format (see RFC 3490,
131 .IR "Internationalizing Domain Names in Applications (IDNA)" ).
132 Three new flags are defined:
135 If this flag is used, then the name found in the lookup process is
136 converted from IDN format to the locale's encoding if necessary.
137 ASCII-only names are not affected by the conversion, which
138 makes this flag usable in existing programs and environments.
140 .BR NI_IDN_ALLOW_UNASSIGNED ", " NI_IDN_USE_STD3_ASCII_RULES
141 Setting these flags will enable the
142 IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and
143 IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3
145 flags respectively to be used in the IDNA handling.
147 .\" FIXME glibc defines the following additional errors, some which
148 .\" can probably be returned by getnameinfo(); they need to
152 .\" #define EAI_INPROGRESS -100 /* Processing request in progress. */
153 .\" #define EAI_CANCELED -101 /* Request canceled. */
154 .\" #define EAI_NOTCANCELED -102 /* Request not canceled. */
155 .\" #define EAI_ALLDONE -103 /* All requests done. */
156 .\" #define EAI_INTR -104 /* Interrupted by a signal. */
157 .\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */
159 On success, 0 is returned, and node and service names, if requested,
160 are filled with null-terminated strings, possibly truncated to fit
161 the specified buffer lengths.
162 On error, one of the following nonzero error codes is returned:
165 The name could not be resolved at this time.
171 argument has an invalid value.
174 A nonrecoverable error occurred.
177 The address family was not recognized,
178 or the address length was invalid for the specified family.
184 The name does not resolve for the supplied arguments.
186 is set and the host's name cannot be located,
187 or neither hostname nor service name were requested.
190 The buffer pointed to by
197 A system error occurred.
198 The error code can be found in
203 function translates these error codes to a human readable string,
204 suitable for error reporting.
208 .I /etc/nsswitch.conf
213 is provided in glibc since version 2.1.
215 For an explanation of the terms used in this section, see
223 Interface Attribute Value
226 T} Thread safety MT-Safe env locale
232 POSIX.1-2001, POSIX.1-2008, RFC\ 2553.
234 In order to assist the programmer in choosing reasonable sizes
235 for the supplied buffers,
237 defines the constants
241 #define NI_MAXHOST 1025
242 #define NI_MAXSERV 32
247 these definitions are exposed only if suitable
248 feature test macros are defined, namely:
252 or (in glibc versions up to and including 2.19)
257 The former is the constant
259 in recent versions of BIND's
262 The latter is a guess based on the services listed
263 in the current Assigned Numbers RFC.
265 Before glibc version 2.2, the
269 arguments were typed as
272 The following code tries to get the numeric hostname and service name,
273 for a given socket address.
274 Note that there is no hardcoded reference to
275 a particular address family.
279 struct sockaddr *addr; /* input */
280 socklen_t addrlen; /* input */
281 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
283 if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf,
284 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
285 printf("host=%s, serv=%s\en", hbuf, sbuf);
289 The following version checks if the socket address has a
290 reverse address mapping.
294 struct sockaddr *addr; /* input */
295 socklen_t addrlen; /* input */
296 char hbuf[NI_MAXHOST];
298 if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf),
299 NULL, 0, NI_NAMEREQD))
300 printf("could not resolve hostname");
302 printf("host=%s\en", hbuf);
306 An example program using
317 .BR gethostbyaddr (3),
318 .BR getservbyname (3),
319 .BR getservbyport (3),
326 R.\& Gilligan, S.\& Thomson, J.\& Bound and W.\& Stevens,
327 .IR "Basic Socket Interface Extensions for IPv6" ,
328 RFC\ 2553, March 1999.
330 Tatsuya Jinmei and Atsushi Onoe,
331 .IR "An Extension of Format for IPv6 Scoped Addresses" ,
332 internet draft, work in progress
333 .UR ftp://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt
337 .IR "Protocol Independence Using the Sockets API" ,
338 Proceedings of the freenix track:
339 2000 USENIX annual technical conference, June 2000
341 .UR http://www.usenix.org\:/publications\:/library\:/proceedings\:/usenix2000\:/freenix\:/metzprotocol.html