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