1.\" $NetBSD: getnameinfo.3,v 1.44 2024/02/16 22:50:33 uwe Exp $ 2.\" $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $ 3.\" $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc Exp $ 4.\" 5.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") 6.\" Copyright (C) 2000, 2001 Internet Software Consortium. 7.\" 8.\" Permission to use, copy, modify, and distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 13.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 14.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 15.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 16.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 17.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 18.\" PERFORMANCE OF THIS SOFTWARE. 19.\" 20.Dd February 15, 2024 21.Dt GETNAMEINFO 3 22.Os 23.Sh NAME 24.Nm getnameinfo 25.Nd socket address structure to hostname and service name 26. 27.Sh SYNOPSIS 28.In netdb.h 29. 30.Ft int 31.Fo getnameinfo 32.Fa "const struct sockaddr * restrict sa" 33.Fa "socklen_t salen" 34.Fa "char * restrict host" 35.Fa "socklen_t hostlen" 36.Fa "char * restrict serv" 37.Fa "socklen_t servlen" "int flags" 38.Fc 39. 40.Sh DESCRIPTION 41The 42.Fn getnameinfo 43function is used to convert a 44.Vt sockaddr 45structure to a pair of host name and service strings. 46It is a replacement for and provides more flexibility than the 47.Xr gethostbyaddr 3 48and 49.Xr getservbyport 3 50functions and is the converse of the 51.Xr getaddrinfo 3 52function. 53.Pp 54The 55.Vt sockaddr 56structure 57.Fa sa 58should point to a 59.Vt sockaddr_in 60(for IPv4), 61.Vt sockaddr_in6 62(for IPv6), 63.Vt sockaddr_atalk 64(for AppleTalk), 65.Vt sockaddr_link 66(for link layer), 67or 68.Vt sockaddr_local 69(for local/unix) 70structures that are 71.Fa salen 72bytes long. 73.Pp 74The host and service names associated with 75.Fa sa 76are stored in 77.Fa host 78and 79.Fa serv 80which have length parameters 81.Fa hostlen 82and 83.Fa servlen . 84The maximum value for 85.Fa hostlen 86is 87.Dv NI_MAXHOST 88and the maximum value for 89.Fa servlen 90is 91.Dv NI_MAXSERV , 92as defined by 93.In netdb.h . 94If a length parameter is zero, no string will be stored. 95Otherwise, enough space must be provided to store the 96host name or service string plus a byte for the 97.Tn NUL 98terminator. 99.Pp 100The 101.Fa flags 102argument is formed by 103.Em or Ap ing 104the following values: 105.Bl -tag -width Dv 106.It Dv NI_NOFQDN 107A fully qualified domain name is not required for local hosts. 108The local part of the fully qualified domain name is returned instead. 109.It Dv NI_NUMERICHOST 110Return the address in numeric form, as if calling 111.Xr inet_ntop 3 , 112instead of a host name. 113.It Dv NI_NAMEREQD 114A name is required. 115If the host name cannot be found in DNS and this flag is set, 116a non-zero error code is returned. 117If the host name is not found and the flag is not set, the 118address is returned in numeric form. 119.It Dv NI_NUMERICSCOPE 120For IPv6 addresses the numeric form of the IPv6 scope identifier is 121returned. 122This flag is ignored for non-IPv6 addresses. 123.It Dv NI_NUMERICSERV 124The service name is returned as a digit string representing the port number. 125.It Dv NI_DGRAM 126Specifies that the service being looked up is a datagram 127service, and causes 128.Xr getservbyport 3 129to be called with a second argument of 130.Li \*qudp\*q 131instead of its default of 132.Li \*qtcp\*q . 133This is required for the few ports 134.Pq 512\(en514 135that have different services 136for 137.Tn UDP 138and 139.Tn TCP . 140.El 141.Pp 142This implementation allows numeric IPv6 address notation with scope identifier, 143as documented in chapter\~11 of draft-ietf-ipv6-scoping-arch-02.txt. 144IPv6 link-local address will appear as a string like 145.Ql fe80::1%ne0 . 146Refer to 147.Xr getaddrinfo 3 148for more information. 149. 150.Sh RETURN VALUES 151.Fn getnameinfo 152returns zero on success or one of the error codes listed in 153.Xr gai_strerror 3 154if an error occurs. 155. 156.Sh EXAMPLES 157The following code tries to get a numeric host name, and service name, 158for a given socket address. 159Observe that there is no hardcoded reference to a particular address family. 160.Bd -literal -offset indent 161struct sockaddr *sa; /* input */ 162char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; 163 164if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, 165 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { 166 errx(1, "could not get numeric hostname"); 167 /*NOTREACHED*/ 168} 169printf("host=%s, serv=%s\en", hbuf, sbuf); 170.Ed 171.Pp 172The following version checks if the socket address has a reverse address mapping: 173.Bd -literal -offset indent 174struct sockaddr *sa; /* input */ 175char hbuf[NI_MAXHOST]; 176 177if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, 178 NI_NAMEREQD)) { 179 errx(1, "could not resolve hostname"); 180 /*NOTREACHED*/ 181} 182printf("host=%s\en", hbuf); 183.Ed 184. 185.Sh SEE ALSO 186.Xr gai_strerror 3 , 187.Xr getaddrinfo 3 , 188.Xr gethostbyaddr 3 , 189.Xr getservbyport 3 , 190.Xr inet_ntop 3 , 191.Xr resolver 3 , 192.Xr hosts 5 , 193.Xr resolv.conf 5 , 194.Xr services 5 , 195.Xr hostname 7 , 196.Xr named 8 197.Rs 198.%A R. Gilligan 199.%A S. Thomson 200.%A J. Bound 201.%A W. Stevens 202.%T Basic Socket Interface Extensions for IPv6 203.%R RFC 2553 204.%D March 1999 205.Re 206.Rs 207.%A S. Deering 208.%A B. Haberman 209.%A T. Jinmei 210.%A E. Nordmark 211.%A B. Zill 212.%T "IPv6 Scoped Address Architecture" 213.%R internet draft 214.%N draft-ietf-ipv6-scoping-arch-02.txt 215.%O work in progress material 216.Re 217.Rs 218.%A Craig Metz 219.%T Protocol Independence Using the Sockets API 220.%B "Proceedings of the FREENIX track: 2000 USENIX annual technical conference" 221.%D June 2000 222.Re 223. 224.Sh STANDARDS 225The 226.Fn getnameinfo 227function is defined by the 228.St -p1003.1g-2000 229draft specification and documented in 230.Sy "RFC 2553" , 231.Dq Basic Socket Interface Extensions for IPv6 . 232. 233.Sh CAVEATS 234.Fn getnameinfo 235can return both numeric and 236.Tn FQDN 237forms of the address specified in 238.Fa sa . 239There is no return value that indicates whether the string returned in 240.Fa host 241is a result of binary to numeric-text translation 242.Pq like Xr inet_ntop 3 , 243or is the result of a 244.Tn DNS 245reverse lookup. 246Because of this, malicious parties could set up a 247.Tn PTR 248record as follows: 249.Pp 250.Dl 1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 251.Pp 252and trick the caller of 253.Fn getnameinfo 254into believing that 255.Fa sa 256is 257.Li 10.1.1.1 258when it is actually 259.Li 127.0.0.1 . 260.Pp 261To prevent such attacks, the use of 262.Dv NI_NAMEREQD 263is recommended when the result of 264.Fn getnameinfo 265is used for access control purposes: 266.Bd -literal -offset indent 267struct sockaddr *sa; 268socklen_t salen; 269char addr[NI_MAXHOST]; 270struct addrinfo hints, *res; 271int error; 272 273error = getnameinfo(sa, salen, addr, sizeof(addr), 274 NULL, 0, NI_NAMEREQD); 275if (error == 0) { 276 memset(&hints, 0, sizeof(hints)); 277 hints.ai_socktype = SOCK_DGRAM; /*dummy*/ 278 hints.ai_flags = AI_NUMERICHOST; 279 if (getaddrinfo(addr, "0", &hints, &res) == 0) { 280 /* malicious PTR record */ 281 freeaddrinfo(res); 282 printf("bogus PTR record\en"); 283 return -1; 284 } 285 /* addr is FQDN as a result of PTR lookup */ 286} else { 287 /* addr is numeric string */ 288 error = getnameinfo(sa, salen, addr, sizeof(addr), 289 NULL, 0, NI_NUMERICHOST); 290} 291.Ed 292.\".Sh BUGS 293.\".Ox 294.\"intentionally uses a different 295.\".Dv NI_MAXHOST 296.\"value from what 297.\".Tn "RFC 2553" 298.\"suggests, to avoid buffer length handling mistakes. 299