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