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 "GNU" "Linux Programmer's Manual"
12 getnameinfo \- address-to-name translation in protocol-independent manner
15 .B #include <sys/socket.h>
18 .BI "int getnameinfo(const struct sockaddr *restrict " addr \
19 ", socklen_t " addrlen ,
20 .BI " char *restrict " host ", socklen_t " hostlen ,
21 .BI " char *restrict " serv ", socklen_t " servlen \
26 Feature Test Macro Requirements for glibc (see
27 .BR feature_test_macros (7)):
33 _POSIX_C_SOURCE >= 200112L
34 Glibc 2.21 and earlier:
40 function is the inverse of
42 it converts a socket address to a corresponding host and service,
43 in a protocol-independent manner.
44 It combines the functionality of
47 .BR getservbyport (3),
48 but unlike those functions,
50 is reentrant and allows programs to eliminate
51 IPv4-versus-IPv6 dependencies.
55 argument is a pointer to a generic socket address structure
62 that holds the input IP address and port number.
67 are pointers to caller-allocated buffers (of size
71 respectively) into which
73 places null-terminated strings containing the host and
74 service names respectively.
76 The caller can specify that no hostname (or no service name)
77 is required by providing a NULL
86 However, at least one of hostname or service name
91 argument modifies the behavior of
96 If set, then an error is returned if the hostname cannot be determined.
99 If set, then the service is datagram (UDP) based rather than
101 This is required for the few ports (512\(en514)
102 that have different services for UDP and TCP.
105 If set, return only the hostname part of the fully qualified domain name
109 If set, then the numeric form of the hostname is returned.
110 .\" For example, by calling
113 .\" .BR gethostbyaddr ().
114 (When not set, this will still happen in case the node's name
115 cannot be determined.)
116 .\" POSIX.1-2001 TC1 has NI_NUMERICSCOPE, but glibc doesn't have it.
119 If set, then the numeric form of the service address is returned.
120 (When not set, this will still happen in case the service's name
121 cannot be determined.)
122 .SS Extensions to getnameinfo() for Internationalized Domain Names
123 Starting with glibc 2.3.4,
125 has been extended to selectively allow
126 hostnames to be transparently converted to and from the
127 Internationalized Domain Name (IDN) format (see RFC 3490,
128 .IR "Internationalizing Domain Names in Applications (IDNA)" ).
129 Three new flags are defined:
132 If this flag is used, then the name found in the lookup process is
133 converted from IDN format to the locale's encoding if necessary.
134 ASCII-only names are not affected by the conversion, which
135 makes this flag usable in existing programs and environments.
137 .BR NI_IDN_ALLOW_UNASSIGNED ", " NI_IDN_USE_STD3_ASCII_RULES
138 Setting these flags will enable the
139 IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and
140 IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3
142 flags respectively to be used in the IDNA handling.
144 .\" FIXME glibc defines the following additional errors, some which
145 .\" can probably be returned by getnameinfo(); they need to
149 .\" #define EAI_INPROGRESS -100 /* Processing request in progress. */
150 .\" #define EAI_CANCELED -101 /* Request canceled. */
151 .\" #define EAI_NOTCANCELED -102 /* Request not canceled. */
152 .\" #define EAI_ALLDONE -103 /* All requests done. */
153 .\" #define EAI_INTR -104 /* Interrupted by a signal. */
154 .\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */
156 On success, 0 is returned, and node and service names, if requested,
157 are filled with null-terminated strings, possibly truncated to fit
158 the specified buffer lengths.
159 On error, one of the following nonzero error codes is returned:
162 The name could not be resolved at this time.
168 argument has an invalid value.
171 A nonrecoverable error occurred.
174 The address family was not recognized,
175 or the address length was invalid for the specified family.
181 The name does not resolve for the supplied arguments.
183 is set and the host's name cannot be located,
184 or neither hostname nor service name were requested.
187 The buffer pointed to by
194 A system error occurred.
195 The error code can be found in
200 function translates these error codes to a human readable string,
201 suitable for error reporting.
205 .I /etc/nsswitch.conf
210 is provided in glibc since version 2.1.
212 For an explanation of the terms used in this section, see
220 Interface Attribute Value
223 T} Thread safety MT-Safe env locale
229 POSIX.1-2001, POSIX.1-2008, RFC\ 2553.
231 In order to assist the programmer in choosing reasonable sizes
232 for the supplied buffers,
234 defines the constants
238 #define NI_MAXHOST 1025
239 #define NI_MAXSERV 32
244 these definitions are exposed only if suitable
245 feature test macros are defined, namely:
249 or (in glibc versions up to and including 2.19)
254 The former is the constant
256 in recent versions of BIND's
259 The latter is a guess based on the services listed
260 in the current Assigned Numbers RFC.
262 Before glibc version 2.2, the
266 arguments were typed as
269 The following code tries to get the numeric hostname and service name,
270 for a given socket address.
271 Note that there is no hardcoded reference to
272 a particular address family.
276 struct sockaddr *addr; /* input */
277 socklen_t addrlen; /* input */
278 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
280 if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf,
281 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
282 printf("host=%s, serv=%s\en", hbuf, sbuf);
286 The following version checks if the socket address has a
287 reverse address mapping.
291 struct sockaddr *addr; /* input */
292 socklen_t addrlen; /* input */
293 char hbuf[NI_MAXHOST];
295 if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf),
296 NULL, 0, NI_NAMEREQD))
297 printf("could not resolve hostname");
299 printf("host=%s\en", hbuf);
303 An example program using
314 .BR gethostbyaddr (3),
315 .BR getservbyname (3),
316 .BR getservbyport (3),
323 R.\& Gilligan, S.\& Thomson, J.\& Bound and W.\& Stevens,
324 .IR "Basic Socket Interface Extensions for IPv6" ,
325 RFC\ 2553, March 1999.
327 Tatsuya Jinmei and Atsushi Onoe,
328 .IR "An Extension of Format for IPv6 Scoped Addresses" ,
329 internet draft, work in progress
330 .UR ftp://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt
334 .IR "Protocol Independence Using the Sockets API" ,
335 Proceedings of the freenix track:
336 2000 USENIX annual technical conference, June 2000
338 .UR http://www.usenix.org\:/publications\:/library\:/proceedings\:/usenix2000\:/freenix\:/metzprotocol.html