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 .Dd June 27, 2022
  20 .Dt GETNAMEINFO 3
  21 .Os
  22 .Sh NAME
  23 .Nm getnameinfo
  24 .Nd socket address structure to hostname and service name
  25 .Sh SYNOPSIS
  26 .In sys/types.h
  27 .In sys/socket.h
  28 .In netdb.h
  29 .Ft int
  30 .Fo getnameinfo
  31 .Fa "const struct sockaddr *sa" "socklen_t salen" "char *host"
  32 .Fa "size_t hostlen" "char *serv" "size_t servlen" "int flags"
  33 .Fc
  34 .Sh DESCRIPTION
  35 The
  36 .Fn getnameinfo
  37 function is used to convert a
  38 .Li sockaddr
  39 structure to a pair of host name and service strings.
  40 It is a replacement for and provides more flexibility than the
  41 .Xr gethostbyaddr 3
  42 and
  43 .Xr getservbyport 3
  44 functions and is the converse of the
  45 .Xr getaddrinfo 3
  46 function.
  47 .Pp
  48 If a link-layer address or UNIX-domain address is passed to
  49 .Fn getnameinfo ,
  50 its ASCII representation will be stored in
  51 .Fa host .
  52 The string pointed to by
  53 .Fa serv
  54 will be set to the empty string if non-NULL;
  55 .Fa flags
  56 will always be ignored.
  57 For a link-layer address,
  58 this can be used as a replacement of the legacy
  59 .Xr link_ntoa 3
  60 function.
  61 .Pp
  62 The
  63 .Li sockaddr
  64 structure
  65 .Fa sa
  66 should point to either a
  67 .Li sockaddr_in ,
  68 .Li sockaddr_in6 ,
  69 .Li sockaddr_dl ,
  70 or
  71 .Li sockaddr_un
  72 structure
  73 .Po for IPv4 ,
  74 IPv6,
  75 link-layer,
  76 or UNIX-domain respectively
  77 .Pc
  78 that is
  79 .Fa salen
  80 bytes long.
  81 If
  82 .Fa salen
  83 is shorter than the length corresponding to the specified
  84 address family or longer than
  85 .Fn sizeof "struct sockaddr_storage" ,
  86 it returns
  87 .Er EAI_FAMILY .
  88 Note that
  89 .Va sa->sa_len
  90 should be consistent with
  91 .Fa salen
  92 though the value of
  93 .Va sa->sa_len
  94 is not directly used in this function.
  95 .Pp
  96 The host and service names associated with
  97 .Fa sa
  98 are stored in
  99 .Fa host
 100 and
 101 .Fa serv
 102 which have length parameters
 103 .Fa hostlen
 104 and
 105 .Fa servlen .
 106 The maximum value for
 107 .Fa hostlen
 108 is
 109 .Dv NI_MAXHOST
 110 and
 111 the maximum value for
 112 .Fa servlen
 113 is
 114 .Dv NI_MAXSERV ,
 115 as defined by
 116 .Aq Pa netdb.h .
 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.
 120 .Pp
 121 The
 122 .Fa flags
 123 argument is formed by
 124 .Tn OR Ns 'ing
 125 the following values:
 126 .Bl -tag -width "NI_NUMERICSCOPEXX"
 127 .It Dv NI_NOFQDN
 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
 132 .Xr inet_ntop 3 ,
 133 instead of a host name.
 134 .It Dv NI_NAMEREQD
 135 A name is required.
 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.
 140 .It NI_NUMERICSERV
 141 The service name is returned as a digit string representing the port number.
 142 .It NI_NUMERICSCOPE
 143 The scope identifier is returned as a digit string.
 144 .It NI_DGRAM
 145 Specifies that the service being looked up is a datagram
 146 service, and causes
 147 .Xr getservbyport 3
 148 to be called with a second argument of
 149 .Dq udp
 150 instead of its default of
 151 .Dq tcp .
 152 This is required for the few ports (512\-514) that have different services
 153 for
 154 .Tn UDP
 155 and
 156 .Tn TCP .
 157 .El
 158 .Pp
 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
 162 .Dq Li fe80::1%ne0 .
 163 Refer to
 164 .Xr getaddrinfo 3
 165 for more information.
 166 .Sh RETURN VALUES
 167 .Fn getnameinfo
 168 returns zero on success or one of the error codes listed in
 169 .Xr gai_strerror 3
 170 if an error occurs.
 171 .Sh EXAMPLES
 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];
 178
 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");
 182         /* NOTREACHED */
 183 }
 184 printf("host=%s, serv=%s\en", hbuf, sbuf);
 185 .Ed
 186 .Pp
 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];
 191
 192 if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
 193     NI_NAMEREQD)) {
 194         errx(1, "could not resolve hostname");
 195         /* NOTREACHED */
 196 }
 197 printf("host=%s\en", hbuf);
 198 .Ed
 199 .Sh SEE ALSO
 200 .Xr gai_strerror 3 ,
 201 .Xr getaddrinfo 3 ,
 202 .Xr gethostbyaddr 3 ,
 203 .Xr getservbyport 3 ,
 204 .Xr inet_ntop 3 ,
 205 .Xr link_ntoa 3 ,
 206 .Xr resolver 3 ,
 207 .Xr inet 4 ,
 208 .Xr inet6 4 ,
 209 .Xr unix 4 ,
 210 .Xr hosts 5 ,
 211 .Xr resolv.conf 5 ,
 212 .Xr services 5 ,
 213 .Xr hostname 7
 214 .Rs
 215 .%A R. Gilligan
 216 .%A S. Thomson
 217 .%A J. Bound
 218 .%A J. McCann
 219 .%A W. Stevens
 220 .%T Basic Socket Interface Extensions for IPv6
 221 .%R RFC 3493
 222 .%D February 2003
 223 .Re
 224 .Rs
 225 .%A S. Deering
 226 .%A B. Haberman
 227 .%A T. Jinmei
 228 .%A E. Nordmark
 229 .%A B. Zill
 230 .%T "IPv6 Scoped Address Architecture"
 231 .%R RFC 4007
 232 .%D March 2005
 233 .Re
 234 .Rs
 235 .%A Craig Metz
 236 .%T Protocol Independence Using the Sockets API
 237 .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
 238 .%D June 2000
 239 .Re
 240 .Sh STANDARDS
 241 The
 242 .Fn getnameinfo
 243 function is defined by the
 244 .St -p1003.1-2004
 245 specification and documented in
 246 .Tn "RFC 3493" ,
 247 .Dq Basic Socket Interface Extensions for IPv6 .
 248 .Sh CAVEATS
 249 .Fn getnameinfo
 250 can return both numeric and FQDN forms of the address specified in
 251 .Fa sa .
 252 There is no return value that indicates whether the string returned in
 253 .Fa host
 254 is a result of binary to numeric-text translation (like
 255 .Xr inet_ntop 3 ) ,
 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
 260 .Ed
 261 .Pp
 262 and trick the caller of
 263 .Fn getnameinfo
 264 into believing that
 265 .Fa sa
 266 is
 267 .Li 10.1.1.1
 268 when it is actually
 269 .Li 127.0.0.1 .
 270 .Pp
 271 To prevent such attacks, the use of
 272 .Dv NI_NAMEREQD
 273 is recommended when the result of
 274 .Fn getnameinfo
 275 is used
 276 for access control purposes:
 277 .Bd -literal -offset indent
 278 struct sockaddr *sa;
 279 socklen_t salen;
 280 char addr[NI_MAXHOST];
 281 struct addrinfo hints, *res;
 282 int error;
 283
 284 error = getnameinfo(sa, salen, addr, sizeof(addr),
 285     NULL, 0, NI_NAMEREQD);
 286 if (error == 0) {
 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 */
 292                 freeaddrinfo(res);
 293                 printf("bogus PTR record\en");
 294                 return -1;
 295         }
 296         /* addr is FQDN as a result of PTR lookup */
 297 } else {
 298         /* addr is numeric string */
 299         error = getnameinfo(sa, salen, addr, sizeof(addr),
 300             NULL, 0, NI_NUMERICHOST);
 301 }
 302 .Ed
 303 .\".Pp
 304 .\".Ox
 305 .\"intentionally uses a different
 306 .\".Dv NI_MAXHOST
 307 .\"value from what
 308 .\".Tn "RFC 2553"
 309 .\"suggests, to avoid buffer length handling mistakes.