- Uniformly use .In for header file references.
[dragonfly.git] / lib / libc / net / getnameinfo.3
CommitLineData
f35d325e
HS
1.\" $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $
2.\" $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc Exp $
3.\" $FreeBSD: src/lib/libc/net/getnameinfo.3,v 1.21 2005/01/23 16:02:48 gnn Exp $
44cb301e 4.\" $DragonFly: src/lib/libc/net/getnameinfo.3,v 1.4 2006/05/26 19:39:37 swildner Exp $
984263bc 5.\"
f35d325e
HS
6.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
7.\" Copyright (C) 2000, 2001 Internet Software Consortium.
984263bc 8.\"
f35d325e
HS
9.\" Permission to use, copy, modify, and distribute this software for any
10.\" purpose with or without fee is hereby granted, provided that the above
11.\" copyright notice and this permission notice appear in all copies.
984263bc 12.\"
f35d325e
HS
13.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
14.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
15.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
16.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
17.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
18.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
19.\" PERFORMANCE OF THIS SOFTWARE.
984263bc 20.\"
f35d325e 21.Dd December 20, 2004
984263bc
MD
22.Dt GETNAMEINFO 3
23.Os
984263bc
MD
24.Sh NAME
25.Nm getnameinfo
f35d325e 26.Nd socket address structure to hostname and service name
984263bc 27.Sh SYNOPSIS
44cb301e
SW
28.In sys/types.h
29.In sys/socket.h
30.In netdb.h
984263bc 31.Ft int
f35d325e
HS
32.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" "char *host" \
33 "size_t hostlen" "char *serv" "size_t servlen" "int flags"
984263bc
MD
34.Sh DESCRIPTION
35The
36.Fn getnameinfo
f35d325e
HS
37function is used to convert a
38.Li sockaddr
39structure to a pair of host name and service strings.
40It is a replacement for and provides more flexibility than the
984263bc
MD
41.Xr gethostbyaddr 3
42and
43.Xr getservbyport 3
f35d325e
HS
44functions and is the converse of the
45.Xr getaddrinfo 3
46function.
984263bc 47.Pp
984263bc 48The
f35d325e
HS
49.Li sockaddr
50structure
51.Fa sa
52should point to either a
984263bc
MD
53.Li sockaddr_in
54or
55.Li sockaddr_in6
f35d325e
HS
56structure (for IPv4 or IPv6 respectively) that is
57.Fa salen
58bytes long.
984263bc 59.Pp
f35d325e
HS
60The host and service names associated with
61.Fa sa
62are stored in
984263bc 63.Fa host
f35d325e
HS
64and
65.Fa serv
66which have length parameters
984263bc 67.Fa hostlen
f35d325e
HS
68and
69.Fa servlen .
70The maximum value for
984263bc 71.Fa hostlen
f35d325e
HS
72is
73.Dv NI_MAXHOST
74and
75the maximum value for
984263bc 76.Fa servlen
f35d325e
HS
77is
78.Dv NI_MAXSERV ,
79as defined by
44cb301e 80.In netdb.h .
f35d325e
HS
81If a length parameter is zero, no string will be stored.
82Otherwise, enough space must be provided to store the
83host name or service string plus a byte for the NUL terminator.
984263bc 84.Pp
f35d325e
HS
85The
86.Fa flags
87argument is formed by
88.Tn OR Ns 'ing
89the following values:
90.Bl -tag -width "NI_NUMERICHOSTXX"
91.It Dv NI_NOFQDN
92A fully qualified domain name is not required for local hosts.
93The local part of the fully qualified domain name is returned instead.
94.It Dv NI_NUMERICHOST
95Return the address in numeric form, as if calling
96.Xr inet_ntop 3 ,
97instead of a host name.
98.It Dv NI_NAMEREQD
99A name is required.
100If the host name cannot be found in DNS and this flag is set,
101a non-zero error code is returned.
102If the host name is not found and the flag is not set, the
103address is returned in numeric form.
104.It NI_NUMERICSERV
105The service name is returned as a digit string representing the port number.
106.It NI_DGRAM
107Specifies that the service being looked up is a datagram
108service, and causes
109.Xr getservbyport 3
984263bc
MD
110to be called with a second argument of
111.Dq udp
112instead of its default of
113.Dq tcp .
f35d325e
HS
114This is required for the few ports (512\-514) that have different services
115for
116.Tn UDP
117and
118.Tn TCP .
119.El
984263bc 120.Pp
f35d325e
HS
121This implementation allows numeric IPv6 address notation with scope identifier,
122as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
123IPv6 link-local address will appear as a string like
124.Dq Li fe80::1%ne0 .
984263bc
MD
125Refer to
126.Xr getaddrinfo 3
f35d325e
HS
127for more information.
128.Sh RETURN VALUES
129.Fn getnameinfo
130returns zero on success or one of the error codes listed in
131.Xr gai_strerror 3
132if an error occurs.
984263bc 133.Sh EXAMPLES
f35d325e
HS
134The following code tries to get a numeric host name, and service name,
135for a given socket address.
136Observe that there is no hardcoded reference to a particular address family.
984263bc
MD
137.Bd -literal -offset indent
138struct sockaddr *sa; /* input */
139char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
140
141if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
142 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
143 errx(1, "could not get numeric hostname");
144 /*NOTREACHED*/
145}
f35d325e 146printf("host=%s, serv=%s\en", hbuf, sbuf);
984263bc
MD
147.Ed
148.Pp
f35d325e 149The following version checks if the socket address has a reverse address mapping:
984263bc
MD
150.Bd -literal -offset indent
151struct sockaddr *sa; /* input */
152char hbuf[NI_MAXHOST];
153
154if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
155 NI_NAMEREQD)) {
156 errx(1, "could not resolve hostname");
157 /*NOTREACHED*/
158}
f35d325e 159printf("host=%s\en", hbuf);
984263bc 160.Ed
984263bc 161.Sh SEE ALSO
f35d325e 162.Xr gai_strerror 3 ,
984263bc
MD
163.Xr getaddrinfo 3 ,
164.Xr gethostbyaddr 3 ,
165.Xr getservbyport 3 ,
f35d325e
HS
166.Xr inet_ntop 3 ,
167.Xr resolver 3 ,
984263bc 168.Xr hosts 5 ,
f35d325e 169.Xr resolv.conf 5 ,
984263bc
MD
170.Xr services 5 ,
171.Xr hostname 7 ,
172.Xr named 8
984263bc
MD
173.Rs
174.%A R. Gilligan
175.%A S. Thomson
176.%A J. Bound
177.%A W. Stevens
178.%T Basic Socket Interface Extensions for IPv6
f35d325e 179.%R RFC 2553
984263bc
MD
180.%D March 1999
181.Re
182.Rs
f35d325e
HS
183.%A S. Deering
184.%A B. Haberman
185.%A T. Jinmei
186.%A E. Nordmark
187.%A B. Zill
188.%T "IPv6 Scoped Address Architecture"
984263bc 189.%R internet draft
f35d325e 190.%N draft-ietf-ipv6-scoping-arch-02.txt
984263bc
MD
191.%O work in progress material
192.Re
193.Rs
194.%A Craig Metz
195.%T Protocol Independence Using the Sockets API
196.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
197.%D June 2000
198.Re
984263bc
MD
199.Sh STANDARDS
200The
f35d325e
HS
201.Fn getnameinfo
202function is defined by the
203.St -p1003.1g-2000
204draft specification and documented in
205.Tn "RFC 2553" ,
206.Dq Basic Socket Interface Extensions for IPv6 .
207.Sh CAVEATS
208.Fn getnameinfo
209can return both numeric and FQDN forms of the address specified in
210.Fa sa .
211There is no return value that indicates whether the string returned in
212.Fa host
213is a result of binary to numeric-text translation (like
214.Xr inet_ntop 3 ) ,
215or is the result of a DNS reverse lookup.
216Because of this, malicious parties could set up a PTR record as follows:
217.Bd -literal -offset indent
2181.0.0.127.in-addr.arpa. IN PTR 10.1.1.1
219.Ed
984263bc 220.Pp
f35d325e
HS
221and trick the caller of
222.Fn getnameinfo
223into believing that
224.Fa sa
225is
226.Li 10.1.1.1
227when it is actually
228.Li 127.0.0.1 .
984263bc 229.Pp
f35d325e
HS
230To prevent such attacks, the use of
231.Dv NI_NAMEREQD
232is recommended when the result of
233.Fn getnameinfo
234is used
235for access control purposes:
236.Bd -literal -offset indent
237struct sockaddr *sa;
238socklen_t salen;
239char addr[NI_MAXHOST];
240struct addrinfo hints, *res;
241int error;
242
243error = getnameinfo(sa, salen, addr, sizeof(addr),
244 NULL, 0, NI_NAMEREQD);
245if (error == 0) {
246 memset(&hints, 0, sizeof(hints));
247 hints.ai_socktype = SOCK_DGRAM; /*dummy*/
248 hints.ai_flags = AI_NUMERICHOST;
249 if (getaddrinfo(addr, "0", &hints, &res) == 0) {
250 /* malicious PTR record */
251 freeaddrinfo(res);
252 printf("bogus PTR record\en");
253 return -1;
254 }
255 /* addr is FQDN as a result of PTR lookup */
256} else {
257 /* addr is numeric string */
258 error = getnameinfo(sa, salen, addr, sizeof(addr),
259 NULL, 0, NI_NUMERICHOST);
260}
261.Ed
262.Sh BUGS
263The implementation of
264.Fn getnameinfo
265is not thread-safe.
266.\".Pp
267.\".Ox
268.\"intentionally uses a different
269.\".Dv NI_MAXHOST
270.\"value from what
271.\".Tn "RFC 2553"
272.\"suggests, to avoid buffer length handling mistakes.