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 $
4 .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
5 .\" Copyright (C) 2000, 2001 Internet Software Consortium.
7 .\" Permission to use, copy, modify, and distribute this software for any
8 .\" purpose with or without fee is hereby granted, provided that the above
9 .\" copyright notice and this permission notice appear in all copies.
11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
12 .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
13 .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
14 .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15 .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
16 .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17 .\" PERFORMANCE OF THIS SOFTWARE.
19 .\" $FreeBSD: src/lib/libc/net/getnameinfo.3,v 1.25 2007/02/28 21:28:33 bms Exp $
20 .\" $DragonFly: src/lib/libc/net/getnameinfo.3,v 1.5 2007/08/18 20:48:47 swildner Exp $
27 .Nd socket address structure to hostname and service name
36 .Fa "const struct sockaddr *sa" "socklen_t salen" "char *host"
37 .Fa "size_t hostlen" "char *serv" "size_t servlen" "int flags"
42 function is used to convert a
44 structure to a pair of host name and service strings.
45 It is a replacement for and provides more flexibility than the
49 functions and is the converse of the
53 If a link-layer address is passed to
55 its ASCII representation will be stored in
57 The string pointed to by
59 will be set to the empty string if non-NULL;
61 will always be ignored.
62 This is intended as a replacement for the legacy
70 should point to either a
75 structure (for IPv4, IPv6 or link-layer respectively) that is
79 The host and service names associated with
85 which have length parameters
100 If a length parameter is zero, no string will be stored.
101 Otherwise, enough space must be provided to store the
102 host name or service string plus a byte for the NUL terminator.
106 argument is formed by
108 the following values:
109 .Bl -tag -width "NI_NUMERICHOSTXX"
111 A fully qualified domain name is not required for local hosts.
112 The local part of the fully qualified domain name is returned instead.
113 .It Dv NI_NUMERICHOST
114 Return the address in numeric form, as if calling
116 instead of a host name.
119 If the host name cannot be found in DNS and this flag is set,
120 a non-zero error code is returned.
121 If the host name is not found and the flag is not set, the
122 address is returned in numeric form.
124 The service name is returned as a digit string representing the port number.
126 Specifies that the service being looked up is a datagram
129 to be called with a second argument of
131 instead of its default of
133 This is required for the few ports (512\-514) that have different services
140 This implementation allows numeric IPv6 address notation with scope identifier,
141 as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
142 IPv6 link-local address will appear as a string like
146 for more information.
149 returns zero on success or one of the error codes listed in
153 The following code tries to get a numeric host name, and service name,
154 for a given socket address.
155 Observe that there is no hardcoded reference to a particular address family.
156 .Bd -literal -offset indent
157 struct sockaddr *sa; /* input */
158 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
160 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
161 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
162 errx(1, "could not get numeric hostname");
165 printf("host=%s, serv=%s\en", hbuf, sbuf);
168 The following version checks if the socket address has a reverse address mapping:
169 .Bd -literal -offset indent
170 struct sockaddr *sa; /* input */
171 char hbuf[NI_MAXHOST];
173 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
175 errx(1, "could not resolve hostname");
178 printf("host=%s\en", hbuf);
183 .Xr gethostbyaddr 3 ,
184 .Xr getservbyport 3 ,
198 .%T Basic Socket Interface Extensions for IPv6
208 .%T "IPv6 Scoped Address Architecture"
210 .%N draft-ietf-ipv6-scoping-arch-02.txt
211 .%O work in progress material
215 .%T Protocol Independence Using the Sockets API
216 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
222 function is defined by the
224 draft specification and documented in
226 .Dq Basic Socket Interface Extensions for IPv6 .
229 can return both numeric and FQDN forms of the address specified in
231 There is no return value that indicates whether the string returned in
233 is a result of binary to numeric-text translation (like
235 or is the result of a DNS reverse lookup.
236 Because of this, malicious parties could set up a PTR record as follows:
237 .Bd -literal -offset indent
238 1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1
241 and trick the caller of
250 To prevent such attacks, the use of
252 is recommended when the result of
255 for access control purposes:
256 .Bd -literal -offset indent
259 char addr[NI_MAXHOST];
260 struct addrinfo hints, *res;
263 error = getnameinfo(sa, salen, addr, sizeof(addr),
264 NULL, 0, NI_NAMEREQD);
266 memset(&hints, 0, sizeof(hints));
267 hints.ai_socktype = SOCK_DGRAM; /*dummy*/
268 hints.ai_flags = AI_NUMERICHOST;
269 if (getaddrinfo(addr, "0", &hints, &res) == 0) {
270 /* malicious PTR record */
272 printf("bogus PTR record\en");
275 /* addr is FQDN as a result of PTR lookup */
277 /* addr is numeric string */
278 error = getnameinfo(sa, salen, addr, sizeof(addr),
279 NULL, 0, NI_NUMERICHOST);
284 .\"intentionally uses a different
288 .\"suggests, to avoid buffer length handling mistakes.