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 $
4 .\" $DragonFly: src/lib/libc/net/getnameinfo.3,v 1.5 2007/08/18 20:48:47 swildner Exp $
6 .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
7 .\" Copyright (C) 2000, 2001 Internet Software Consortium.
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.
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.
26 .Nd socket address structure to hostname and service name
34 .Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" "char *host" \
35 "size_t hostlen" "char *serv" "size_t servlen" "int flags"
39 function is used to convert a
41 structure to a pair of host name and service strings.
42 It is a replacement for and provides more flexibility than the
46 functions and is the converse of the
54 should point to either a
58 structure (for IPv4 or IPv6 respectively) that is
62 The host and service names associated with
68 which have length parameters
83 If a length parameter is zero, no string will be stored.
84 Otherwise, enough space must be provided to store the
85 host name or service string plus a byte for the NUL terminator.
92 .Bl -tag -width "NI_NUMERICHOSTXX"
94 A fully qualified domain name is not required for local hosts.
95 The local part of the fully qualified domain name is returned instead.
97 Return the address in numeric form, as if calling
99 instead of a host name.
102 If the host name cannot be found in DNS and this flag is set,
103 a non-zero error code is returned.
104 If the host name is not found and the flag is not set, the
105 address is returned in numeric form.
107 The service name is returned as a digit string representing the port number.
109 Specifies that the service being looked up is a datagram
112 to be called with a second argument of
114 instead of its default of
116 This is required for the few ports (512\-514) that have different services
123 This implementation allows numeric IPv6 address notation with scope identifier,
124 as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
125 IPv6 link-local address will appear as a string like
129 for more information.
132 returns zero on success or one of the error codes listed in
136 The following code tries to get a numeric host name, and service name,
137 for a given socket address.
138 Observe that there is no hardcoded reference to a particular address family.
139 .Bd -literal -offset indent
140 struct sockaddr *sa; /* input */
141 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
143 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
144 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
145 errx(1, "could not get numeric hostname");
148 printf("host=%s, serv=%s\en", hbuf, sbuf);
151 The following version checks if the socket address has a reverse address mapping:
152 .Bd -literal -offset indent
153 struct sockaddr *sa; /* input */
154 char hbuf[NI_MAXHOST];
156 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
158 errx(1, "could not resolve hostname");
161 printf("host=%s\en", hbuf);
166 .Xr gethostbyaddr 3 ,
167 .Xr getservbyport 3 ,
180 .%T Basic Socket Interface Extensions for IPv6
190 .%T "IPv6 Scoped Address Architecture"
192 .%N draft-ietf-ipv6-scoping-arch-02.txt
193 .%O work in progress material
197 .%T Protocol Independence Using the Sockets API
198 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
204 function is defined by the
206 draft specification and documented in
208 .Dq Basic Socket Interface Extensions for IPv6 .
211 can return both numeric and FQDN forms of the address specified in
213 There is no return value that indicates whether the string returned in
215 is a result of binary to numeric-text translation (like
217 or is the result of a DNS reverse lookup.
218 Because of this, malicious parties could set up a PTR record as follows:
219 .Bd -literal -offset indent
220 1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1
223 and trick the caller of
232 To prevent such attacks, the use of
234 is recommended when the result of
237 for access control purposes:
238 .Bd -literal -offset indent
241 char addr[NI_MAXHOST];
242 struct addrinfo hints, *res;
245 error = getnameinfo(sa, salen, addr, sizeof(addr),
246 NULL, 0, NI_NAMEREQD);
248 memset(&hints, 0, sizeof(hints));
249 hints.ai_socktype = SOCK_DGRAM; /*dummy*/
250 hints.ai_flags = AI_NUMERICHOST;
251 if (getaddrinfo(addr, "0", &hints, &res) == 0) {
252 /* malicious PTR record */
254 printf("bogus PTR record\en");
257 /* addr is FQDN as a result of PTR lookup */
259 /* addr is numeric string */
260 error = getnameinfo(sa, salen, addr, sizeof(addr),
261 NULL, 0, NI_NUMERICHOST);
265 The implementation of
270 .\"intentionally uses a different
274 .\"suggests, to avoid buffer length handling mistakes.