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, getname‐
26 info() is reentrant and allows programs to eliminate IPv4-versus-IPv6
27 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 getnameinfo() 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 nonzero 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 nonrecoverable 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 Since glibc 2.8, these definitions are exposed only if one of the fea‐
140 ture test macros _BSD_SOURCE, _SVID_SOURCE, or _GNU_SOURCE is defined.
141 The former is the constant MAXDNAME in recent versions of BIND's
143 <arpa/nameser.h> header file. The latter is a guess based on the ser‐
144 vices listed in the current Assigned Numbers RFC.
145
147 The following code tries to get the numeric hostname and service name,
148 for a given socket address. Note that there is no hardcoded reference
149 to a particular address family.
150 struct sockaddr *sa; /* input */
152 socklen_t len; /* input */
153 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
154 if (getnameinfo(sa, len, hbuf, sizeof(hbuf), sbuf,
156 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
157 printf("host=%s, serv=%s\n", hbuf, sbuf);
158 The following version checks if the socket address has a reverse
160 address mapping.
161 struct sockaddr *sa; /* input */
163 socklen_t len; /* input */
164 char hbuf[NI_MAXHOST];
165 if (getnameinfo(sa, len, hbuf, sizeof(hbuf),
167 NULL, 0, NI_NAMEREQD))
168 printf("could not resolve hostname");
169 else
170 printf("host=%s\n", hbuf);
171 An example program using getnameinfo() can be found in getaddrinfo(3).
173
175 accept(2), getpeername(2), getsockname(2), recvfrom(2), socket(2),
176 getaddrinfo(3), gethostbyaddr(3), getservbyname(3), getservbyport(3),
177 inet_ntop(3), hosts(5), services(5), hostname(7), named(8)
178 R. Gilligan, S. Thomson, J. Bound and W. Stevens, Basic Socket Inter‐
180 face Extensions for IPv6, RFC 2553, March 1999.
181 Tatsuya Jinmei and Atsushi Onoe, An Extension of Format for IPv6 Scoped
183 Addresses, internet draft, work in progress ⟨ftp://ftp.ietf.org
184 /internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt⟩.
185 Craig Metz, Protocol Independence Using the Sockets API, Proceedings of
187 the freenix track: 2000 USENIX annual technical conference, June 2000
188 ⟨http://www.usenix.org/publications/library/proceedings/usenix2000
189 /freenix/metzprotocol.html⟩.
190
192 This page is part of release 3.53 of the Linux man-pages project. A
193 description of the project, and information about reporting bugs, can
194 be found at http://www.kernel.org/doc/man-pages/.
195GNU 2013-01-15 GETNAMEINFO(3)