summaryrefslogtreecommitdiff
path: root/src/lib/libc/net/getnameinfo.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/net/getnameinfo.3')
-rw-r--r--src/lib/libc/net/getnameinfo.3343
1 files changed, 0 insertions, 343 deletions
diff --git a/src/lib/libc/net/getnameinfo.3 b/src/lib/libc/net/getnameinfo.3
deleted file mode 100644
index c01646c8a7..0000000000
--- a/src/lib/libc/net/getnameinfo.3
+++ /dev/null
@@ -1,343 +0,0 @@
1.\" $OpenBSD: getnameinfo.3,v 1.28 2004/12/06 10:46:35 jmc Exp $
2.\" $KAME: getnameinfo.3,v 1.20 2001/01/05 13:37:37 itojun Exp $
3.\"
4.\" Copyright (c) 1983, 1987, 1991, 1993
5.\" The Regents of the University of California. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\" may be used to endorse or promote products derived from this software
17.\" without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
32.\"
33.Dd May 25, 1995
34.Dt GETNAMEINFO 3
35.Os
36.\"
37.Sh NAME
38.Nm getnameinfo
39.Nd address-to-nodename translation in protocol-independent manner
40.\"
41.Sh SYNOPSIS
42.Fd #include <sys/types.h>
43.Fd #include <sys/socket.h>
44.Fd #include <netdb.h>
45.Ft int
46.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \
47"char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags"
48.\"
49.Sh DESCRIPTION
50The
51.Fn getnameinfo
52function is defined for protocol-independent address-to-nodename translation.
53Its functionality is a reverse conversion of
54.Xr getaddrinfo 3 ,
55and implements similar functionality to
56.Xr gethostbyaddr 3
57and
58.Xr getservbyport 3
59in a more sophisticated manner.
60.Pp
61This function looks up an IP address and port number provided by the
62caller in the DNS and system-specific database, and returns text
63strings for both in buffers provided by the caller.
64The function indicates successful completion by a zero return value;
65a non-zero return value indicates failure.
66.Pp
67To aid applications in printing error messages based on the
68.Dv EAI_xxx
69codes returned by
70.Fn getnameinfo ,
71.Fn gai_strerror
72is defined.
73See
74.Xr gai_strerror 3
75for more information.
76.Pp
77The implementation allows experimental numeric IPv6 address notation with
78scope identifier.
79IPv6 link-local address will appear as a string like
80.Dq Li fe80::1%ne0 .
81Refer to
82.Xr getaddrinfo 3
83for the notation.
84.Pp
85The first argument,
86.Fa sa ,
87points to either a
88.Li sockaddr_in
89structure (for IPv4) or a
90.Li sockaddr_in6
91structure (for IPv6) that holds the IP address and port number.
92The
93.Fa salen
94argument gives the length of the
95.Li sockaddr_in
96or
97.Li sockaddr_in6
98structure.
99.Pp
100The function returns the nodename associated with the IP address in
101the buffer pointed to by the
102.Fa host
103argument.
104The caller provides the size of this buffer via the
105.Fa hostlen
106argument.
107The service name associated with the port number is returned in the buffer
108pointed to by
109.Fa serv ,
110and the
111.Fa servlen
112argument gives the length of this buffer.
113The caller specifies not to return either string by providing a zero
114value for the
115.Fa hostlen
116or
117.Fa servlen
118arguments.
119Otherwise, the caller must provide buffers large enough to hold the
120nodename and the service name, including the terminating null characters.
121.Pp
122Unfortunately most systems do not provide constants that specify the
123maximum size of either a fully-qualified domain name or a service name.
124Therefore to aid the application in allocating buffers for these two
125returned strings the following constants are defined in
126.Aq Pa netdb.h :
127.Bd -literal -offset indent
128#define NI_MAXHOST MAXHOSTNAMELEN
129#define NI_MAXSERV 32
130.Ed
131.Pp
132The first value is actually defined as the constant
133.Dv MAXDNAME
134in recent versions of BIND's
135.Aq Pa arpa/nameser.h
136header (older versions of BIND define this constant to be 256)
137and the second is a guess based on the services listed in the current
138Assigned Numbers RFC.
139.Pp
140The final argument is a
141.Fa flag
142that changes the default actions of this function.
143The flags are defined in
144.Aq Pa netdb.h
145and are as follows:
146.Bl -tag -width "NI_NUMERICHOSTXX"
147.It Dv NI_NOFQDN
148By default the fully-qualified domain name (FQDN) for the host is
149looked up using DNS and returned.
150If the flag bit
151.Dv NI_NOFQDN
152is set, only the nodename portion of the FQDN is returned for local hosts.
153.It Dv NI_NUMERICHOST
154If the
155.Fa flag
156bit
157.Dv NI_NUMERICHOST
158is set, or if the host's name cannot be located using DNS,
159the numeric form of the host's address is returned instead of its name
160.Po
161e.g., by calling
162.Xr inet_ntop 3
163instead of
164.Xr gethostbyaddr 3
165.Pc .
166The two
167.Dv NI_NUMERICxxx
168flags are required to support the
169.Fl n
170flag that many commands provide.
171.It Dv NI_NAMEREQD
172If the
173.Fa flag
174bit
175.Dv NI_NAMEREQD
176is set, an error is returned if the host's name cannot be located using DNS.
177.It Dv NI_NUMERICSERV
178If the flag bit
179.Dv NI_NUMERICSERV
180is set, the numeric form of the service address is returned
181.Pq e.g., its port number
182instead of its name.
183The two
184.Dv NI_NUMERICxxx
185flags are required to support the
186.Fl n
187flag that many commands provide.
188.It Dv NI_DGRAM
189A fifth flag bit,
190.Dv NI_DGRAM ,
191specifies that the service is a datagram service, and causes
192.Xr getservbyport 3
193to be called with a second argument of
194.Qq udp
195instead of its default of
196.Qq tcp .
197This is required for the few ports (512-514)
198that have different services for UDP and TCP.
199.El
200.\"
201.Sh RETURN VALUES
202.Fn getnameinfo
203returns zero on success, and non-zero on errors.
204See
205.Xr gai_strerror 3
206for a description of the non-zero error codes.
207.\"
208.Sh EXAMPLES
209The following code tries to get a numeric hostname, and service name,
210for a given socket address.
211Observe that there is no hardcoded reference to a particular address family.
212.Bd -literal -offset indent
213struct sockaddr *sa; /* input */
214char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
215
216if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
217 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
218 errx(1, "could not get numeric hostname");
219 /*NOTREACHED*/
220}
221printf("host=%s, serv=%s\en", hbuf, sbuf);
222.Ed
223.Pp
224The following version checks if the socket address has reverse address mapping:
225.Bd -literal -offset indent
226struct sockaddr *sa; /* input */
227char hbuf[NI_MAXHOST];
228
229if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
230 NI_NAMEREQD)) {
231 errx(1, "could not resolve hostname");
232 /*NOTREACHED*/
233}
234printf("host=%s\en", hbuf);
235.Ed
236.\"
237.Sh SEE ALSO
238.Xr gai_strerror 3 ,
239.Xr getaddrinfo 3 ,
240.Xr gethostbyaddr 3 ,
241.Xr getservbyport 3 ,
242.Xr hosts 5 ,
243.Xr resolv.conf 5 ,
244.Xr services 5 ,
245.Xr hostname 7 ,
246.Xr named 8
247.Rs
248.%A R. Gilligan
249.%A S. Thomson
250.%A J. Bound
251.%A W. Stevens
252.%T Basic Socket Interface Extensions for IPv6
253.%R RFC 2553
254.%D March 1999
255.Re
256.Rs
257.%A Tatsuya Jinmei
258.%A Atsushi Onoe
259.%T "An Extension of Format for IPv6 Scoped Addresses"
260.%R internet draft
261.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
262.%O work in progress material
263.Re
264.Rs
265.%A Craig Metz
266.%T Protocol Independence Using the Sockets API
267.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
268.%D June 2000
269.Re
270.\"
271.Sh STANDARDS
272The
273.Fn getnameinfo
274function is defined in IEEE POSIX 1003.1g draft specification,
275and documented in
276.Dq Basic Socket Interface Extensions for IPv6
277.Pq RFC 2553 .
278.\"
279.Sh HISTORY
280The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
281.\"
282.Sh CAVEATS
283.Fn getnameinfo
284returns both numeric and FQDN notation of the address specified in
285.Fa sa .
286There is no return value that indicates if the string returned in
287.Fa host
288is a result of binary to numeric-text translation (like
289.Xr inet_ntop 3 ) ,
290or the result of DNS reverse lookup.
291Therefore, malicious parties could set up a PTR record as below:
292.Bd -literal -offset indent
2931.0.0.127.in-addr.arpa. IN PTR 10.1.1.1
294.Ed
295.Pp
296and trick the caller of
297.Fn getnameinfo
298into believing that
299.Fa sa
300is
301.Li 10.1.1.1
302when it actually is
303.Li 127.0.0.1 .
304.Pp
305To prevent such attacks, the use of
306.Dv NI_NAMEREQD
307is recommended when you use the result of
308.Fn getnameinfo
309for access control purposes:
310.Bd -literal -offset indent
311struct sockaddr *sa;
312socklen_t salen;
313char addr[NI_MAXHOST];
314struct addrinfo hints, *res;
315int error;
316
317error = getnameinfo(sa, salen, addr, sizeof(addr),
318 NULL, 0, NI_NAMEREQD);
319if (error == 0) {
320 memset(&hints, 0, sizeof(hints));
321 hints.ai_socktype = SOCK_DGRAM; /*dummy*/
322 hints.ai_flags = AI_NUMERICHOST;
323 if (getaddrinfo(addr, "0", &hints, &res) == 0) {
324 /* malicious PTR record */
325 freeaddrinfo(res);
326 printf("bogus PTR record\\n");
327 return -1;
328 }
329 /* addr is FQDN as a result of PTR lookup */
330} else {
331 /* addr is numeric string */
332 error = getnameinfo(sa, salen, addr, sizeof(addr),
333 NULL, 0, NI_NUMERICHOST);
334}
335.Ed
336.\"
337.Sh BUGS
338The current implementation is not thread-safe.
339.Pp
340.Ox
341intentionally uses a different
342.Dv NI_MAXHOST
343value from what RFC 2553 suggests, to avoid buffer length handling mistakes.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-01-03 18:28:38 +0000