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 2014-05-28 "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 *" "sa" ", socklen_t " "salen" ,
19 .BI " char *" "host" ", socklen_t " "hostlen" ,
20 .BI " char *" "serv" ", socklen_t " "servlen" ", int " "flags" );
24 Feature Test Macro Requirements for glibc (see
25 .BR feature_test_macros (7)):
30 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE
35 function is the inverse of
37 it converts a socket address to a corresponding host and service,
38 in a protocol-independent manner.
39 It combines the functionality of
42 .BR getservbyport (3),
43 but unlike those functions,
45 is reentrant and allows programs to eliminate
46 IPv4-versus-IPv6 dependencies.
50 argument is a pointer to a generic socket address structure
57 that holds the input IP address and port number.
62 are pointers to caller-allocated buffers (of size
66 respectively) into which
68 places null-terminated strings containing the host and
69 service names respectively.
71 The caller can specify that no hostname (or no service name)
72 is required by providing a NULL
81 However, at least one of hostname or service name
86 argument modifies the behavior of
91 If set, then an error is returned if the hostname cannot be determined.
94 If set, then the service is datagram (UDP) based rather than
96 This is required for the few ports (512-514)
97 that have different services for UDP and TCP.
100 If set, return only the hostname part of the fully qualified domain name
104 If set, then the numeric form of the hostname is returned.
105 .\" For example, by calling
108 .\" .BR gethostbyaddr ().
109 (When not set, this will still happen in case the node's name
110 cannot be determined.)
111 .\" POSIX.1-2003 has NI_NUMERICSCOPE, but glibc doesn't have it.
114 If set, then the numeric form of the service address is returned.
115 (When not set, this will still happen in case the service's name
116 cannot be determined.)
117 .SS Extensions to getnameinfo() for Internationalized Domain Names
119 Starting with glibc 2.3.4,
121 has been extended to selectively allow
122 hostnames to be transparently converted to and from the
123 Internationalized Domain Name (IDN) format (see RFC 3490,
124 .IR "Internationalizing Domain Names in Applications (IDNA)" ).
125 Three new flags are defined:
128 If this flag is used, then the name found in the lookup process is
129 converted from IDN format to the locale's encoding if necessary.
130 ASCII-only names are not affected by the conversion, which
131 makes this flag usable in existing programs and environments.
133 .BR NI_IDN_ALLOW_UNASSIGNED ", " NI_IDN_USE_STD3_ASCII_RULES
134 Setting these flags will enable the
135 IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and
136 IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3
138 flags respectively to be used in the IDNA handling.
140 .\" FIXME glibc defines the following additional errors, some which
141 .\" can probably be returned by getnameinfo(); they need to
144 .\" #define EAI_INPROGRESS -100 /* Processing request in progress. */
145 .\" #define EAI_CANCELED -101 /* Request canceled. */
146 .\" #define EAI_NOTCANCELED -102 /* Request not canceled. */
147 .\" #define EAI_ALLDONE -103 /* All requests done. */
148 .\" #define EAI_INTR -104 /* Interrupted by a signal. */
149 .\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */
151 On success 0 is returned, and node and service names, if requested,
152 are filled with null-terminated strings, possibly truncated to fit
153 the specified buffer lengths.
154 On error, one of the following nonzero error codes is returned:
157 The name could not be resolved at this time.
163 argument has an invalid value.
166 A nonrecoverable error occurred.
169 The address family was not recognized,
170 or the address length was invalid for the specified family.
176 The name does not resolve for the supplied arguments.
178 is set and the host's name cannot be located,
179 or neither hostname nor service name were requested.
182 The buffer pointed to by
189 A system error occurred.
190 The error code can be found in
195 function translates these error codes to a human readable string,
196 suitable for error reporting.
205 is provided in glibc since version 2.1.
207 RFC\ 2553, POSIX.1-2001.
209 In order to assist the programmer in choosing reasonable sizes
210 for the supplied buffers,
212 defines the constants
216 #define NI_MAXHOST 1025
217 #define NI_MAXSERV 32
222 these definitions are exposed only if one of the feature test macros
229 The former is the constant
231 in recent versions of BIND's
234 The latter is a guess based on the services listed
235 in the current Assigned Numbers RFC.
237 Before glibc version 2.2, the
241 arguments were typed as
244 The following code tries to get the numeric hostname and service name,
245 for a given socket address.
246 Note that there is no hardcoded reference to
247 a particular address family.
251 struct sockaddr *sa; /* input */
252 socklen_t len; /* input */
253 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
255 if (getnameinfo(sa, len, hbuf, sizeof(hbuf), sbuf,
256 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
257 printf("host=%s, serv=%s\en", hbuf, sbuf);
261 The following version checks if the socket address has a
262 reverse address mapping.
266 struct sockaddr *sa; /* input */
267 socklen_t len; /* input */
268 char hbuf[NI_MAXHOST];
270 if (getnameinfo(sa, len, hbuf, sizeof(hbuf),
271 NULL, 0, NI_NAMEREQD))
272 printf("could not resolve hostname");
274 printf("host=%s\en", hbuf);
278 An example program using
289 .BR gethostbyaddr (3),
290 .BR getservbyname (3),
291 .BR getservbyport (3),
298 R. Gilligan, S. Thomson, J. Bound and W. Stevens,
299 .IR "Basic Socket Interface Extensions for IPv6" ,
300 RFC\ 2553, March 1999.
302 Tatsuya Jinmei and Atsushi Onoe,
303 .IR "An Extension of Format for IPv6 Scoped Addresses" ,
304 internet draft, work in progress
305 .UR ftp://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt
309 .IR "Protocol Independence Using the Sockets API" ,
310 Proceedings of the freenix track:
311 2000 USENIX annual technical conference, June 2000
313 .UR http://www.usenix.org\:/publications\:/library\:/proceedings\:/usenix2000\:/freenix\:/metzprotocol.html
316 This page is part of release 3.79 of the Linux
319 A description of the project,
320 information about reporting bugs,
321 and the latest version of this page,
323 \%http://www.kernel.org/doc/man\-pages/.