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