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$ 20.\" 21.Dd July 28, 2016 22.Dt GETNAMEINFO 3 23.Os 24.Sh NAME 25.Nm getnameinfo 26.Nd socket address structure to hostname and service name 27.Sh SYNOPSIS 28.In sys/types.h 29.In sys/socket.h 30.In netdb.h 31.Ft int 32.Fo getnameinfo 33.Fa "const struct sockaddr *sa" "socklen_t salen" "char *host" 34.Fa "size_t hostlen" "char *serv" "size_t servlen" "int flags" 35.Fc 36.Sh DESCRIPTION 37The 38.Fn getnameinfo 39function is used to convert a 40.Li sockaddr 41structure to a pair of host name and service strings. 42It is a replacement for and provides more flexibility than the 43.Xr gethostbyaddr 3 44and 45.Xr getservbyport 3 46functions and is the converse of the 47.Xr getaddrinfo 3 48function. 49.Pp 50If a link-layer address or UNIX-domain address is passed to 51.Fn getnameinfo , 52its ASCII representation will be stored in 53.Fa host . 54The string pointed to by 55.Fa serv 56will be set to the empty string if non-NULL; 57.Fa flags 58will always be ignored. 59For a link-layer address, 60this can be used as a replacement of the legacy 61.Xr link_ntoa 3 62function. 63.Pp 64The 65.Li sockaddr 66structure 67.Fa sa 68should point to either a 69.Li sockaddr_in , 70.Li sockaddr_in6 , 71.Li sockaddr_dl , 72or 73.Li sockaddr_un 74structure 75.Po for IPv4 , 76IPv6, 77link-layer, 78or UNIX-domain respectively 79.Pc 80that is 81.Fa salen 82bytes long. 83.Pp 84The host and service names associated with 85.Fa sa 86are stored in 87.Fa host 88and 89.Fa serv 90which have length parameters 91.Fa hostlen 92and 93.Fa servlen . 94The maximum value for 95.Fa hostlen 96is 97.Dv NI_MAXHOST 98and 99the maximum value for 100.Fa servlen 101is 102.Dv NI_MAXSERV , 103as defined by 104.Aq Pa netdb.h . 105If a length parameter is zero, no string will be stored. 106Otherwise, enough space must be provided to store the 107host name or service string plus a byte for the NUL terminator. 108.Pp 109The 110.Fa flags 111argument is formed by 112.Tn OR Ns 'ing 113the following values: 114.Bl -tag -width "NI_NUMERICSCOPEXX" 115.It Dv NI_NOFQDN 116A fully qualified domain name is not required for local hosts. 117The local part of the fully qualified domain name is returned instead. 118.It Dv NI_NUMERICHOST 119Return the address in numeric form, as if calling 120.Xr inet_ntop 3 , 121instead of a host name. 122.It Dv NI_NAMEREQD 123A name is required. 124If the host name cannot be found in DNS and this flag is set, 125a non-zero error code is returned. 126If the host name is not found and the flag is not set, the 127address is returned in numeric form. 128.It NI_NUMERICSERV 129The service name is returned as a digit string representing the port number. 130.It NI_NUMERICSCOPE 131The scope identifier is returned as a digit string. 132.It NI_DGRAM 133Specifies that the service being looked up is a datagram 134service, and causes 135.Xr getservbyport 3 136to be called with a second argument of 137.Dq udp 138instead of its default of 139.Dq tcp . 140This is required for the few ports (512\-514) that have different services 141for 142.Tn UDP 143and 144.Tn TCP . 145.El 146.Pp 147This implementation allows numeric IPv6 address notation with scope identifier, 148as documented in chapter 11 of RFC 4007. 149IPv6 link-local address will appear as a string like 150.Dq Li fe80::1%ne0 . 151Refer to 152.Xr getaddrinfo 3 153for more information. 154.Sh RETURN VALUES 155.Fn getnameinfo 156returns zero on success or one of the error codes listed in 157.Xr gai_strerror 3 158if an error occurs. 159.Sh EXAMPLES 160The following code tries to get a numeric host name, and service name, 161for a given socket address. 162Observe that there is no hardcoded reference to a particular address family. 163.Bd -literal -offset indent 164struct sockaddr *sa; /* input */ 165char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; 166 167if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, 168 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { 169 errx(1, "could not get numeric hostname"); 170 /* NOTREACHED */ 171} 172printf("host=%s, serv=%s\en", hbuf, sbuf); 173.Ed 174.Pp 175The following version checks if the socket address has a reverse address mapping: 176.Bd -literal -offset indent 177struct sockaddr *sa; /* input */ 178char hbuf[NI_MAXHOST]; 179 180if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, 181 NI_NAMEREQD)) { 182 errx(1, "could not resolve hostname"); 183 /* NOTREACHED */ 184} 185printf("host=%s\en", hbuf); 186.Ed 187.Sh SEE ALSO 188.Xr gai_strerror 3 , 189.Xr getaddrinfo 3 , 190.Xr gethostbyaddr 3 , 191.Xr getservbyport 3 , 192.Xr inet_ntop 3 , 193.Xr link_ntoa 3 , 194.Xr resolver 3 , 195.Xr inet 4 , 196.Xr inet6 4 , 197.Xr unix 4 , 198.Xr hosts 5 , 199.Xr resolv.conf 5 , 200.Xr services 5 , 201.Xr hostname 7 , 202.Xr named 8 203.Rs 204.%A R. Gilligan 205.%A S. Thomson 206.%A J. Bound 207.%A J. McCann 208.%A W. Stevens 209.%T Basic Socket Interface Extensions for IPv6 210.%R RFC 3493 211.%D February 2003 212.Re 213.Rs 214.%A S. Deering 215.%A B. Haberman 216.%A T. Jinmei 217.%A E. Nordmark 218.%A B. Zill 219.%T "IPv6 Scoped Address Architecture" 220.%R RFC 4007 221.%D March 2005 222.Re 223.Rs 224.%A Craig Metz 225.%T Protocol Independence Using the Sockets API 226.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 227.%D June 2000 228.Re 229.Sh STANDARDS 230The 231.Fn getnameinfo 232function is defined by the 233.St -p1003.1-2004 234specification and documented in 235.Tn "RFC 3493" , 236.Dq Basic Socket Interface Extensions for IPv6 . 237.Sh CAVEATS 238.Fn getnameinfo 239can return both numeric and FQDN forms of the address specified in 240.Fa sa . 241There is no return value that indicates whether the string returned in 242.Fa host 243is a result of binary to numeric-text translation (like 244.Xr inet_ntop 3 ) , 245or is the result of a DNS reverse lookup. 246Because of this, malicious parties could set up a PTR record as follows: 247.Bd -literal -offset indent 2481.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 249.Ed 250.Pp 251and trick the caller of 252.Fn getnameinfo 253into believing that 254.Fa sa 255is 256.Li 10.1.1.1 257when it is actually 258.Li 127.0.0.1 . 259.Pp 260To prevent such attacks, the use of 261.Dv NI_NAMEREQD 262is recommended when the result of 263.Fn getnameinfo 264is used 265for 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.\".Pp 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