lib/libc/net/getnameinfo.3

   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 $
   5 .\"
   6 .\" Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   7 .\" Copyright (C) 2000, 2001  Internet Software Consortium.
   8 .\"
   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.
  12 .\"
  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.
  20 .\"
  21 .Dd December 20, 2004
  22 .Dt GETNAMEINFO 3
  23 .Os
  24 .Sh NAME
  25 .Nm getnameinfo
  26 .Nd socket address structure to hostname and service name
  27 .Sh LIBRARY
  28 .Lb libc
  29 .Sh SYNOPSIS
  30 .In sys/types.h
  31 .In sys/socket.h
  32 .In netdb.h
  33 .Ft int
  34 .Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" "char *host" \
  35     "size_t hostlen" "char *serv" "size_t servlen" "int flags"
  36 .Sh DESCRIPTION
  37 The
  38 .Fn getnameinfo
  39 function is used to convert a
  40 .Li sockaddr
  41 structure to a pair of host name and service strings.
  42 It is a replacement for and provides more flexibility than the
  43 .Xr gethostbyaddr 3
  44 and
  45 .Xr getservbyport 3
  46 functions and is the converse of the
  47 .Xr getaddrinfo 3
  48 function.
  49 .Pp
  50 The
  51 .Li sockaddr
  52 structure
  53 .Fa sa
  54 should point to either a
  55 .Li sockaddr_in
  56 or
  57 .Li sockaddr_in6
  58 structure (for IPv4 or IPv6 respectively) that is
  59 .Fa salen
  60 bytes long.
  61 .Pp
  62 The host and service names associated with
  63 .Fa sa
  64 are stored in
  65 .Fa host
  66 and
  67 .Fa serv
  68 which have length parameters
  69 .Fa hostlen
  70 and
  71 .Fa servlen .
  72 The maximum value for
  73 .Fa hostlen
  74 is
  75 .Dv NI_MAXHOST
  76 and
  77 the maximum value for
  78 .Fa servlen
  79 is
  80 .Dv NI_MAXSERV ,
  81 as defined by
  82 .In netdb.h .
  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.
  86 .Pp
  87 The
  88 .Fa flags
  89 argument is formed by
  90 .Tn OR Ns 'ing
  91 the following values:
  92 .Bl -tag -width "NI_NUMERICHOSTXX"
  93 .It Dv NI_NOFQDN
  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.
  96 .It Dv NI_NUMERICHOST
  97 Return the address in numeric form, as if calling
  98 .Xr inet_ntop 3 ,
  99 instead of a host name.
 100 .It Dv NI_NAMEREQD
 101 A name is required.
 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.
 106 .It NI_NUMERICSERV
 107 The service name is returned as a digit string representing the port number.
 108 .It NI_DGRAM
 109 Specifies that the service being looked up is a datagram
 110 service, and causes
 111 .Xr getservbyport 3
 112 to be called with a second argument of
 113 .Dq udp
 114 instead of its default of
 115 .Dq tcp .
 116 This is required for the few ports (512\-514) that have different services
 117 for
 118 .Tn UDP
 119 and
 120 .Tn TCP .
 121 .El
 122 .Pp
 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
 126 .Dq Li fe80::1%ne0 .
 127 Refer to
 128 .Xr getaddrinfo 3
 129 for more information.
 130 .Sh RETURN VALUES
 131 .Fn getnameinfo
 132 returns zero on success or one of the error codes listed in
 133 .Xr gai_strerror 3
 134 if an error occurs.
 135 .Sh EXAMPLES
 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];
 142
 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");
 146         /*NOTREACHED*/
 147 }
 148 printf("host=%s, serv=%s\en", hbuf, sbuf);
 149 .Ed
 150 .Pp
 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];
 155
 156 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
 157     NI_NAMEREQD)) {
 158         errx(1, "could not resolve hostname");
 159         /*NOTREACHED*/
 160 }
 161 printf("host=%s\en", hbuf);
 162 .Ed
 163 .Sh SEE ALSO
 164 .Xr gai_strerror 3 ,
 165 .Xr getaddrinfo 3 ,
 166 .Xr gethostbyaddr 3 ,
 167 .Xr getservbyport 3 ,
 168 .Xr inet_ntop 3 ,
 169 .Xr resolver 3 ,
 170 .Xr hosts 5 ,
 171 .Xr resolv.conf 5 ,
 172 .Xr services 5 ,
 173 .Xr hostname 7 ,
 174 .Xr named 8
 175 .Rs
 176 .%A R. Gilligan
 177 .%A S. Thomson
 178 .%A J. Bound
 179 .%A W. Stevens
 180 .%T Basic Socket Interface Extensions for IPv6
 181 .%R RFC 2553
 182 .%D March 1999
 183 .Re
 184 .Rs
 185 .%A S. Deering
 186 .%A B. Haberman
 187 .%A T. Jinmei
 188 .%A E. Nordmark
 189 .%A B. Zill
 190 .%T "IPv6 Scoped Address Architecture"
 191 .%R internet draft
 192 .%N draft-ietf-ipv6-scoping-arch-02.txt
 193 .%O work in progress material
 194 .Re
 195 .Rs
 196 .%A Craig Metz
 197 .%T Protocol Independence Using the Sockets API
 198 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 199 .%D June 2000
 200 .Re
 201 .Sh STANDARDS
 202 The
 203 .Fn getnameinfo
 204 function is defined by the
 205 .St -p1003.1g-2000
 206 draft specification and documented in
 207 .Tn "RFC 2553" ,
 208 .Dq Basic Socket Interface Extensions for IPv6 .
 209 .Sh CAVEATS
 210 .Fn getnameinfo
 211 can return both numeric and FQDN forms of the address specified in
 212 .Fa sa .
 213 There is no return value that indicates whether the string returned in
 214 .Fa host
 215 is a result of binary to numeric-text translation (like
 216 .Xr inet_ntop 3 ) ,
 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
 221 .Ed
 222 .Pp
 223 and trick the caller of
 224 .Fn getnameinfo
 225 into believing that
 226 .Fa sa
 227 is
 228 .Li 10.1.1.1
 229 when it is actually
 230 .Li 127.0.0.1 .
 231 .Pp
 232 To prevent such attacks, the use of
 233 .Dv NI_NAMEREQD
 234 is recommended when the result of
 235 .Fn getnameinfo
 236 is used
 237 for access control purposes:
 238 .Bd -literal -offset indent
 239 struct sockaddr *sa;
 240 socklen_t salen;
 241 char addr[NI_MAXHOST];
 242 struct addrinfo hints, *res;
 243 int error;
 244
 245 error = getnameinfo(sa, salen, addr, sizeof(addr),
 246     NULL, 0, NI_NAMEREQD);
 247 if (error == 0) {
 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 */
 253                 freeaddrinfo(res);
 254                 printf("bogus PTR record\en");
 255                 return -1;
 256         }
 257         /* addr is FQDN as a result of PTR lookup */
 258 } else {
 259         /* addr is numeric string */
 260         error = getnameinfo(sa, salen, addr, sizeof(addr),
 261             NULL, 0, NI_NUMERICHOST);
 262 }
 263 .Ed
 264 .Sh BUGS
 265 The implementation of
 266 .Fn getnameinfo
 267 is not thread-safe.
 268 .\".Pp
 269 .\".Ox
 270 .\"intentionally uses a different
 271 .\".Dv NI_MAXHOST
 272 .\"value from what
 273 .\".Tn "RFC 2553"
 274 .\"suggests, to avoid buffer length handling mistakes.