Debian Codegraph @

upstream/debian-trixie/man3/getnameinfo.3

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