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.
24 .Nd socket address structure to hostname and service name
31 .Fa "const struct sockaddr *sa" "socklen_t salen" "char *host"
32 .Fa "size_t hostlen" "char *serv" "size_t servlen" "int flags"
37 function is used to convert a
39 structure to a pair of host name and service strings.
40 It is a replacement for and provides more flexibility than the
44 functions and is the converse of the
48 If a link-layer address or UNIX-domain address is passed to
50 its ASCII representation will be stored in
52 The string pointed to by
54 will be set to the empty string if non-NULL;
56 will always be ignored.
57 For a link-layer address,
58 this can be used as a replacement of the legacy
66 should point to either a
76 or UNIX-domain respectively
83 is shorter than the length corresponding to the specified
84 address family or longer than
85 .Fn sizeof "struct sockaddr_storage" ,
90 should be consistent with
94 is not directly used in this function.
96 The host and service names associated with
102 which have length parameters
106 The maximum value for
111 the maximum value for
117 If a length parameter is zero, no string will be stored.
118 Otherwise, enough space must be provided to store the
119 host name or service string plus a byte for the NUL terminator.
123 argument is formed by
125 the following values:
126 .Bl -tag -width "NI_NUMERICSCOPEXX"
128 A fully qualified domain name is not required for local hosts.
129 The local part of the fully qualified domain name is returned instead.
130 .It Dv NI_NUMERICHOST
131 Return the address in numeric form, as if calling
133 instead of a host name.
136 If the host name cannot be found in DNS and this flag is set,
137 a non-zero error code is returned.
138 If the host name is not found and the flag is not set, the
139 address is returned in numeric form.
141 The service name is returned as a digit string representing the port number.
143 The scope identifier is returned as a digit string.
145 Specifies that the service being looked up is a datagram
148 to be called with a second argument of
150 instead of its default of
152 This is required for the few ports (512\-514) that have different services
159 This implementation allows numeric IPv6 address notation with scope identifier,
160 as documented in chapter 11 of RFC 4007.
161 IPv6 link-local address will appear as a string like
165 for more information.
168 returns zero on success or one of the error codes listed in
172 The following code tries to get a numeric host name, and service name,
173 for a given socket address.
174 Observe that there is no hardcoded reference to a particular address family.
175 .Bd -literal -offset indent
176 struct sockaddr *sa; /* input */
177 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
179 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
180 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
181 errx(1, "could not get numeric hostname");
184 printf("host=%s, serv=%s\en", hbuf, sbuf);
187 The following version checks if the socket address has a reverse address mapping:
188 .Bd -literal -offset indent
189 struct sockaddr *sa; /* input */
190 char hbuf[NI_MAXHOST];
192 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
194 errx(1, "could not resolve hostname");
197 printf("host=%s\en", hbuf);
202 .Xr gethostbyaddr 3 ,
203 .Xr getservbyport 3 ,
220 .%T Basic Socket Interface Extensions for IPv6
230 .%T "IPv6 Scoped Address Architecture"
236 .%T Protocol Independence Using the Sockets API
237 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
243 function is defined by the
245 specification and documented in
247 .Dq Basic Socket Interface Extensions for IPv6 .
250 can return both numeric and FQDN forms of the address specified in
252 There is no return value that indicates whether the string returned in
254 is a result of binary to numeric-text translation (like
256 or is the result of a DNS reverse lookup.
257 Because of this, malicious parties could set up a PTR record as follows:
258 .Bd -literal -offset indent
259 1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1
262 and trick the caller of
271 To prevent such attacks, the use of
273 is recommended when the result of
276 for access control purposes:
277 .Bd -literal -offset indent
280 char addr[NI_MAXHOST];
281 struct addrinfo hints, *res;
284 error = getnameinfo(sa, salen, addr, sizeof(addr),
285 NULL, 0, NI_NAMEREQD);
287 memset(&hints, 0, sizeof(hints));
288 hints.ai_socktype = SOCK_DGRAM; /*dummy*/
289 hints.ai_flags = AI_NUMERICHOST;
290 if (getaddrinfo(addr, "0", &hints, &res) == 0) {
291 /* malicious PTR record */
293 printf("bogus PTR record\en");
296 /* addr is FQDN as a result of PTR lookup */
298 /* addr is numeric string */
299 error = getnameinfo(sa, salen, addr, sizeof(addr),
300 NULL, 0, NI_NUMERICHOST);
305 .\"intentionally uses a different
309 .\"suggests, to avoid buffer length handling mistakes.