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 September 20, 2015 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_NUMERICHOSTXX" 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_DGRAM 131Specifies that the service being looked up is a datagram 132service, and causes 133.Xr getservbyport 3 134to be called with a second argument of 135.Dq udp 136instead of its default of 137.Dq tcp . 138This is required for the few ports (512\-514) that have different services 139for 140.Tn UDP 141and 142.Tn TCP . 143.El 144.Pp 145This implementation allows numeric IPv6 address notation with scope identifier, 146as documented in chapter 11 of RFC 4007. 147IPv6 link-local address will appear as a string like 148.Dq Li fe80::1%ne0 . 149Refer to 150.Xr getaddrinfo 3 151for more information. 152.Sh RETURN VALUES 153.Fn getnameinfo 154returns zero on success or one of the error codes listed in 155.Xr gai_strerror 3 156if an error occurs. 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.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 link_ntoa 3 , 192.Xr resolver 3 , 193.Xr inet 4 , 194.Xr inet6 4 , 195.Xr unix 4 , 196.Xr hosts 5 , 197.Xr resolv.conf 5 , 198.Xr services 5 , 199.Xr hostname 7 , 200.Xr named 8 201.Rs 202.%A R. Gilligan 203.%A S. Thomson 204.%A J. Bound 205.%A J. McCann 206.%A W. Stevens 207.%T Basic Socket Interface Extensions for IPv6 208.%R RFC 3493 209.%D February 2003 210.Re 211.Rs 212.%A S. Deering 213.%A B. Haberman 214.%A T. Jinmei 215.%A E. Nordmark 216.%A B. Zill 217.%T "IPv6 Scoped Address Architecture" 218.%R RFC 4007 219.%D March 2005 220.Re 221.Rs 222.%A Craig Metz 223.%T Protocol Independence Using the Sockets API 224.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 225.%D June 2000 226.Re 227.Sh STANDARDS 228The 229.Fn getnameinfo 230function is defined by the 231.St -p1003.1-2004 232specification and documented in 233.Tn "RFC 3493" , 234.Dq Basic Socket Interface Extensions for IPv6 . 235.Sh CAVEATS 236.Fn getnameinfo 237can return both numeric and FQDN forms 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 (like 242.Xr inet_ntop 3 ) , 243or is the result of a DNS reverse lookup. 244Because of this, malicious parties could set up a PTR record as follows: 245.Bd -literal -offset indent 2461.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 247.Ed 248.Pp 249and trick the caller of 250.Fn getnameinfo 251into believing that 252.Fa sa 253is 254.Li 10.1.1.1 255when it is actually 256.Li 127.0.0.1 . 257.Pp 258To prevent such attacks, the use of 259.Dv NI_NAMEREQD 260is recommended when the result of 261.Fn getnameinfo 262is used 263for access control purposes: 264.Bd -literal -offset indent 265struct sockaddr *sa; 266socklen_t salen; 267char addr[NI_MAXHOST]; 268struct addrinfo hints, *res; 269int error; 270 271error = getnameinfo(sa, salen, addr, sizeof(addr), 272 NULL, 0, NI_NAMEREQD); 273if (error == 0) { 274 memset(&hints, 0, sizeof(hints)); 275 hints.ai_socktype = SOCK_DGRAM; /*dummy*/ 276 hints.ai_flags = AI_NUMERICHOST; 277 if (getaddrinfo(addr, "0", &hints, &res) == 0) { 278 /* malicious PTR record */ 279 freeaddrinfo(res); 280 printf("bogus PTR record\en"); 281 return -1; 282 } 283 /* addr is FQDN as a result of PTR lookup */ 284} else { 285 /* addr is numeric string */ 286 error = getnameinfo(sa, salen, addr, sizeof(addr), 287 NULL, 0, NI_NUMERICHOST); 288} 289.Ed 290.\".Pp 291.\".Ox 292.\"intentionally uses a different 293.\".Dv NI_MAXHOST 294.\"value from what 295.\".Tn "RFC 2553" 296.\"suggests, to avoid buffer length handling mistakes. 297