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.
26 .Nd socket address structure to hostname and service name
33 .Fa "const struct sockaddr *sa" "socklen_t salen" "char *host"
34 .Fa "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
50 If a link-layer address or UNIX-domain address is passed to
52 its ASCII representation will be stored in
54 The string pointed to by
56 will be set to the empty string if non-NULL;
58 will always be ignored.
59 For a link-layer address,
60 this can be used as a replacement of the legacy
68 should point to either a
78 or UNIX-domain respectively
85 is shorter than the length corresponding to the specified
86 address family or longer than
87 .Fn sizeof "struct sockaddr_storage" ,
92 should be consistent with
96 is not directly used in this function.
98 The host and service names associated with
104 which have length parameters
108 The maximum value for
113 the maximum value for
119 If a length parameter is zero, no string will be stored.
120 Otherwise, enough space must be provided to store the
121 host name or service string plus a byte for the NUL terminator.
125 argument is formed by
127 the following values:
128 .Bl -tag -width "NI_NUMERICSCOPEXX"
130 A fully qualified domain name is not required for local hosts.
131 The local part of the fully qualified domain name is returned instead.
132 .It Dv NI_NUMERICHOST
133 Return the address in numeric form, as if calling
135 instead of a host name.
138 If the host name cannot be found in DNS and this flag is set,
139 a non-zero error code is returned.
140 If the host name is not found and the flag is not set, the
141 address is returned in numeric form.
143 The service name is returned as a digit string representing the port number.
145 The scope identifier is returned as a digit string.
147 Specifies that the service being looked up is a datagram
150 to be called with a second argument of
152 instead of its default of
154 This is required for the few ports (512\-514) that have different services
161 This implementation allows numeric IPv6 address notation with scope identifier,
162 as documented in chapter 11 of RFC 4007.
163 IPv6 link-local address will appear as a string like
167 for more information.
170 returns zero on success or one of the error codes listed in
174 The following code tries to get a numeric host name, and service name,
175 for a given socket address.
176 Observe that there is no hardcoded reference to a particular address family.
177 .Bd -literal -offset indent
178 struct sockaddr *sa; /* input */
179 char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
181 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
182 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
183 errx(1, "could not get numeric hostname");
186 printf("host=%s, serv=%s\en", hbuf, sbuf);
189 The following version checks if the socket address has a reverse address mapping:
190 .Bd -literal -offset indent
191 struct sockaddr *sa; /* input */
192 char hbuf[NI_MAXHOST];
194 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
196 errx(1, "could not resolve hostname");
199 printf("host=%s\en", hbuf);
204 .Xr gethostbyaddr 3 ,
205 .Xr getservbyport 3 ,
222 .%T Basic Socket Interface Extensions for IPv6
232 .%T "IPv6 Scoped Address Architecture"
238 .%T Protocol Independence Using the Sockets API
239 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
245 function is defined by the
247 specification and documented in
249 .Dq Basic Socket Interface Extensions for IPv6 .
252 can return both numeric and FQDN forms of the address specified in
254 There is no return value that indicates whether the string returned in
256 is a result of binary to numeric-text translation (like
258 or is the result of a DNS reverse lookup.
259 Because of this, malicious parties could set up a PTR record as follows:
260 .Bd -literal -offset indent
261 1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1
264 and trick the caller of
273 To prevent such attacks, the use of
275 is recommended when the result of
278 for access control purposes:
279 .Bd -literal -offset indent
282 char addr[NI_MAXHOST];
283 struct addrinfo hints, *res;
286 error = getnameinfo(sa, salen, addr, sizeof(addr),
287 NULL, 0, NI_NAMEREQD);
289 memset(&hints, 0, sizeof(hints));
290 hints.ai_socktype = SOCK_DGRAM; /*dummy*/
291 hints.ai_flags = AI_NUMERICHOST;
292 if (getaddrinfo(addr, "0", &hints, &res) == 0) {
293 /* malicious PTR record */
295 printf("bogus PTR record\en");
298 /* addr is FQDN as a result of PTR lookup */
300 /* addr is numeric string */
301 error = getnameinfo(sa, salen, addr, sizeof(addr),
302 NULL, 0, NI_NUMERICHOST);
307 .\"intentionally uses a different
311 .\"suggests, to avoid buffer length handling mistakes.