Debian Codegraph @

upstream/debian-unstable/man3/getnameinfo.3

raw
1 '\" t
2 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
3 .\" This page is in the public domain.
4 .\" %%%LICENSE_END
5 .\"
6 .TH getnameinfo 3 2025-12-25 "Linux man-pages 6.18"
7 .SH NAME
8 getnameinfo \- address-to-name translation in protocol-independent manner
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/socket.h>
15 .B #include <netdb.h>
16 .P
17 .BR "int getnameinfo(" "socklen_t hostlen, socklen_t servlen;"
18 .BI " const struct sockaddr *restrict " addr \
19 ", socklen_t " addrlen ,
20 .BI " char " host "[_Nullable restrict " hostlen ],
21 .BI " socklen_t " hostlen ,
22 .BI " char " serv "[_Nullable restrict " servlen ],
23 .BI " socklen_t " servlen ,
24 .BI " int " flags );
25 .fi
26 .P
27 .RS -4
28 Feature Test Macro Requirements for glibc (see
29 .BR feature_test_macros (7)):
30 .RE
31 .P
32 .BR getnameinfo ():
33 .nf
34 Since glibc 2.22:
35 _POSIX_C_SOURCE >= 200112L
36 glibc 2.21 and earlier:
37 _POSIX_C_SOURCE
38 .fi
39 .SH DESCRIPTION
40 The
41 .BR getnameinfo ()
42 function is the inverse of
43 .BR getaddrinfo (3):
44 it converts a socket address to a corresponding host and service,
45 in a protocol-independent manner.
46 It combines the functionality of
47 .BR gethostbyaddr (3)
48 and
49 .BR getservbyport (3),
50 but unlike those functions,
51 .BR getnameinfo ()
52 is reentrant and allows programs to eliminate
53 IPv4-versus-IPv6 dependencies.
54 .P
55 The
56 .I addr
57 argument is a pointer to a generic socket address structure
58 (of type
59 .I sockaddr_in
60 or
61 .IR sockaddr_in6 )
62 of size
63 .I addrlen
64 that holds the input IP address and port number.
65 The arguments
66 .I host
67 and
68 .I serv
69 are pointers to caller-allocated buffers (of size
70 .I hostlen
71 and
72 .I servlen
73 respectively) into which
74 .BR getnameinfo ()
75 places null-terminated strings containing the host and
76 service names respectively.
77 .P
78 The caller can specify that no hostname (or no service name)
79 is required by providing a NULL
80 .I host
81 (or
82 .IR serv )
83 argument or a zero
84 .I hostlen
85 (or
86 .IR servlen )
87 argument.
88 However, at least one of hostname or service name
89 must be requested.
90 .P
91 The
92 .I flags
93 argument modifies the behavior of
94 .BR getnameinfo ()
95 as follows:
96 .TP
97 .B NI_NAMEREQD
98 If set, then an error is returned if the hostname cannot be determined.
99 .TP
100 .B NI_DGRAM
101 If set, then the service is datagram (UDP) based rather than
102 stream (TCP) based.
103 This is required for the few ports (512\[en]514)
104 that have different services for UDP and TCP.
105 .TP
106 .B NI_NOFQDN
107 If set, return only the hostname part of the fully qualified domain name
108 for local hosts.
109 .TP
110 .B NI_NUMERICHOST
111 If set, then the numeric form of the hostname is returned.
112 .\" For example, by calling
113 .\" .BR inet_ntop ()
114 .\" instead of
115 .\" .BR gethostbyaddr ().
116 (When not set, this will still happen in case the node's name
117 cannot be determined.)
118 .\" POSIX.1-2001 TC1 has NI_NUMERICSCOPE, but glibc doesn't have it.
119 .TP
120 .B NI_NUMERICSERV
121 If set, then the numeric form of the service address is returned.
122 (When not set, this will still happen in case the service's name
123 cannot be determined.)
124 .SS Extensions to getnameinfo() for Internationalized Domain Names
125 Starting with glibc 2.3.4,
126 .BR getnameinfo ()
127 has been extended to selectively allow
128 hostnames to be transparently converted to and from the
129 Internationalized Domain Name (IDN) format (see RFC 3490,
130 .IR "Internationalizing Domain Names in Applications (IDNA)" ).
131 Three new flags are defined:
132 .TP
133 .B NI_IDN
134 If this flag is used, then the name found in the lookup process is
135 converted from IDN format to the locale's encoding if necessary.
136 ASCII-only names are not affected by the conversion, which
137 makes this flag usable in existing programs and environments.
138 .TP
139 .B NI_IDN_ALLOW_UNASSIGNED
140 .TQ
141 .B NI_IDN_USE_STD3_ASCII_RULES
142 Setting these flags will enable the
143 IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and
144 IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3
145 conforming hostname)
146 flags respectively to be used in the IDNA handling.
147 .SH RETURN VALUE
148 .\" FIXME glibc defines the following additional errors, some which
149 .\" can probably be returned by getnameinfo(); they need to
150 .\" be documented.
151 .\"
152 .\" #ifdef __USE_GNU
153 .\" #define EAI_INPROGRESS -100 /* Processing request in progress. */
154 .\" #define EAI_CANCELED -101 /* Request canceled. */
155 .\" #define EAI_NOTCANCELED -102 /* Request not canceled. */
156 .\" #define EAI_ALLDONE -103 /* All requests done. */
157 .\" #define EAI_INTR -104 /* Interrupted by a signal. */
158 .\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */
159 .\" #endif
160 On success, 0 is returned, and node and service names, if requested,
161 are filled with null-terminated strings, possibly truncated to fit
162 the specified buffer lengths.
163 On error, one of the following nonzero error codes is returned:
164 .TP
165 .B EAI_AGAIN
166 The name could not be resolved at this time.
167 Try again later.
168 .TP
169 .B EAI_BADFLAGS
170 The
171 .I flags
172 argument has an invalid value.
173 .TP
174 .B EAI_FAIL
175 A nonrecoverable error occurred.
176 .TP
177 .B EAI_FAMILY
178 The address family was not recognized,
179 or the address length was invalid for the specified family.
180 .TP
181 .B EAI_MEMORY
182 Out of memory.
183 .TP
184 .B EAI_NONAME
185 The name does not resolve for the supplied arguments.
186 .B NI_NAMEREQD
187 is set and the host's name cannot be located,
188 or neither hostname nor service name were requested.
189 .TP
190 .B EAI_OVERFLOW
191 The buffer pointed to by
192 .I host
193 or
194 .I serv
195 was too small.
196 .TP
197 .B EAI_SYSTEM
198 A system error occurred.
199 The error code can be found in
200 .IR errno .
201 .P
202 The
203 .BR gai_strerror (3)
204 function translates these error codes to a human readable string,
205 suitable for error reporting.
206 .SH FILES
207 .I /etc/hosts
208 .br
209 .I /etc/nsswitch.conf
210 .br
211 .I /etc/resolv.conf
212 .SH ATTRIBUTES
213 For an explanation of the terms used in this section, see
214 .BR attributes (7).
215 .TS
216 allbox;
217 lbx lb lb
218 l l l.
219 Interface Attribute Value
220 T{
221 .na
222 .nh
223 .BR getnameinfo ()
224 T} Thread safety MT-Safe env locale
225 .TE
226 .SH STANDARDS
227 POSIX.1-2008.
228 RFC\ 2553.
229 .SH HISTORY
230 glibc 2.1.
231 POSIX.1-2001.
232 .P
233 Before glibc 2.2, the
234 .I hostlen
235 and
236 .I servlen
237 arguments were typed as
238 .IR size_t .
239 .SH NOTES
240 In order to assist the programmer in choosing reasonable sizes
241 for the supplied buffers,
242 .I <netdb.h>
243 defines the constants
244 .P
245 .in +4n
246 .EX
247 #define NI_MAXHOST 1025
248 #define NI_MAXSERV 32
249 .EE
250 .in
251 .P
252 Since glibc 2.8,
253 these definitions are exposed only if suitable
254 feature test macros are defined, namely:
255 .BR _GNU_SOURCE ,
256 .B _DEFAULT_SOURCE
257 (since glibc 2.19),
258 or (in glibc versions up to and including 2.19)
259 .B _BSD_SOURCE
260 or
261 .BR _SVID_SOURCE .
262 .P
263 The former is the constant
264 .B MAXDNAME
265 in recent versions of BIND's
266 .I <arpa/nameser.h>
267 header file.
268 The latter is a guess based on the services listed
269 in the current Assigned Numbers RFC.
270 .SH EXAMPLES
271 The following code tries to get the numeric hostname and service name,
272 for a given socket address.
273 Note that there is no hardcoded reference to
274 a particular address family.
275 .P
276 .in +4n
277 .EX
278 struct sockaddr *addr; /* input */
279 socklen_t addrlen; /* input */
280 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
281 \&
282 if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf,
283 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
284 printf("host=%s, serv=%s\[rs]n", hbuf, sbuf);
285 .EE
286 .in
287 .P
288 The following version checks if the socket address has a
289 reverse address mapping.
290 .P
291 .in +4n
292 .EX
293 struct sockaddr *addr; /* input */
294 socklen_t addrlen; /* input */
295 char hbuf[NI_MAXHOST];
296 \&
297 if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf),
298 NULL, 0, NI_NAMEREQD))
299 printf("could not resolve hostname");
300 else
301 printf("host=%s\[rs]n", hbuf);
302 .EE
303 .in
304 .P
305 An example program using
306 .BR getnameinfo ()
307 can be found in
308 .BR getaddrinfo (3).
309 .SH SEE ALSO
310 .BR accept (2),
311 .BR getpeername (2),
312 .BR getsockname (2),
313 .BR recvfrom (2),
314 .BR socket (2),
315 .BR getaddrinfo (3),
316 .BR gethostbyaddr (3),
317 .BR getservbyname (3),
318 .BR getservbyport (3),
319 .BR inet_ntop (3),
320 .BR hosts (5),
321 .BR services (5),
322 .BR hostname (7),
323 .BR named (8)
324 .P
325 R.\& Gilligan, S.\& Thomson, J.\& Bound and W.\& Stevens,
326 .IR "Basic Socket Interface Extensions for IPv6" ,
327 RFC\ 2553, March 1999.
328 .P
329 Tatsuya Jinmei and Atsushi Onoe,
330 .IR "An Extension of Format for IPv6 Scoped Addresses" ,
331 internet draft, work in progress
332 .UR ftp:\://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt
333 .UE .
334 .P
335 Craig Metz,
336 .IR "Protocol Independence Using the Sockets API" ,
337 Proceedings of the freenix track:
338 2000 USENIX annual technical conference, June 2000
339 .ad l
340 .UR http:\://www.usenix.org\:/publications\:/library\:/proceedings\:/usenix2000\:/freenix\:/metzprotocol.html
341 .UE .