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 February 14, 2013 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 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. 59This is intended as a replacement for the legacy 60.Xr link_ntoa 3 61function. 62.Pp 63The 64.Li sockaddr 65structure 66.Fa sa 67should point to either a 68.Li sockaddr_in , 69.Li sockaddr_in6 70or 71.Li sockaddr_dl 72structure (for IPv4, IPv6 or link-layer respectively) that is 73.Fa salen 74bytes long. 75.Pp 76The host and service names associated with 77.Fa sa 78are stored in 79.Fa host 80and 81.Fa serv 82which have length parameters 83.Fa hostlen 84and 85.Fa servlen . 86The maximum value for 87.Fa hostlen 88is 89.Dv NI_MAXHOST 90and 91the maximum value for 92.Fa servlen 93is 94.Dv NI_MAXSERV , 95as defined by 96.Aq Pa netdb.h . 97If a length parameter is zero, no string will be stored. 98Otherwise, enough space must be provided to store the 99host name or service string plus a byte for the NUL terminator. 100.Pp 101The 102.Fa flags 103argument is formed by 104.Tn OR Ns 'ing 105the following values: 106.Bl -tag -width "NI_NUMERICHOSTXX" 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 NI_NUMERICSERV 121The service name is returned as a digit string representing the port number. 122.It NI_DGRAM 123Specifies that the service being looked up is a datagram 124service, and causes 125.Xr getservbyport 3 126to be called with a second argument of 127.Dq udp 128instead of its default of 129.Dq tcp . 130This is required for the few ports (512\-514) that have different services 131for 132.Tn UDP 133and 134.Tn TCP . 135.El 136.Pp 137This implementation allows numeric IPv6 address notation with scope identifier, 138as documented in chapter 11 of RFC 4007. 139IPv6 link-local address will appear as a string like 140.Dq Li fe80::1%ne0 . 141Refer to 142.Xr getaddrinfo 3 143for more information. 144.Sh RETURN VALUES 145.Fn getnameinfo 146returns zero on success or one of the error codes listed in 147.Xr gai_strerror 3 148if an error occurs. 149.Sh EXAMPLES 150The following code tries to get a numeric host name, and service name, 151for a given socket address. 152Observe that there is no hardcoded reference to a particular address family. 153.Bd -literal -offset indent 154struct sockaddr *sa; /* input */ 155char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; 156 157if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, 158 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { 159 errx(1, "could not get numeric hostname"); 160 /* NOTREACHED */ 161} 162printf("host=%s, serv=%s\en", hbuf, sbuf); 163.Ed 164.Pp 165The following version checks if the socket address has a reverse address mapping: 166.Bd -literal -offset indent 167struct sockaddr *sa; /* input */ 168char hbuf[NI_MAXHOST]; 169 170if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, 171 NI_NAMEREQD)) { 172 errx(1, "could not resolve hostname"); 173 /* NOTREACHED */ 174} 175printf("host=%s\en", hbuf); 176.Ed 177.Sh SEE ALSO 178.Xr gai_strerror 3 , 179.Xr getaddrinfo 3 , 180.Xr gethostbyaddr 3 , 181.Xr getservbyport 3 , 182.Xr inet_ntop 3 , 183.Xr link_ntoa 3 , 184.Xr resolver 3 , 185.Xr hosts 5 , 186.Xr resolv.conf 5 , 187.Xr services 5 , 188.Xr hostname 7 , 189.Xr named 8 190.Rs 191.%A R. Gilligan 192.%A S. Thomson 193.%A J. Bound 194.%A J. McCann 195.%A W. Stevens 196.%T Basic Socket Interface Extensions for IPv6 197.%R RFC 3493 198.%D February 2003 199.Re 200.Rs 201.%A S. Deering 202.%A B. Haberman 203.%A T. Jinmei 204.%A E. Nordmark 205.%A B. Zill 206.%T "IPv6 Scoped Address Architecture" 207.%R RFC 4007 208.%D March 2005 209.Re 210.Rs 211.%A Craig Metz 212.%T Protocol Independence Using the Sockets API 213.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 214.%D June 2000 215.Re 216.Sh STANDARDS 217The 218.Fn getnameinfo 219function is defined by the 220.St -p1003.1-2004 221specification and documented in 222.Tn "RFC 3493" , 223.Dq Basic Socket Interface Extensions for IPv6 . 224.Sh CAVEATS 225.Fn getnameinfo 226can return both numeric and FQDN forms of the address specified in 227.Fa sa . 228There is no return value that indicates whether the string returned in 229.Fa host 230is a result of binary to numeric-text translation (like 231.Xr inet_ntop 3 ) , 232or is the result of a DNS reverse lookup. 233Because of this, malicious parties could set up a PTR record as follows: 234.Bd -literal -offset indent 2351.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 236.Ed 237.Pp 238and trick the caller of 239.Fn getnameinfo 240into believing that 241.Fa sa 242is 243.Li 10.1.1.1 244when it is actually 245.Li 127.0.0.1 . 246.Pp 247To prevent such attacks, the use of 248.Dv NI_NAMEREQD 249is recommended when the result of 250.Fn getnameinfo 251is used 252for access control purposes: 253.Bd -literal -offset indent 254struct sockaddr *sa; 255socklen_t salen; 256char addr[NI_MAXHOST]; 257struct addrinfo hints, *res; 258int error; 259 260error = getnameinfo(sa, salen, addr, sizeof(addr), 261 NULL, 0, NI_NAMEREQD); 262if (error == 0) { 263 memset(&hints, 0, sizeof(hints)); 264 hints.ai_socktype = SOCK_DGRAM; /*dummy*/ 265 hints.ai_flags = AI_NUMERICHOST; 266 if (getaddrinfo(addr, "0", &hints, &res) == 0) { 267 /* malicious PTR record */ 268 freeaddrinfo(res); 269 printf("bogus PTR record\en"); 270 return -1; 271 } 272 /* addr is FQDN as a result of PTR lookup */ 273} else { 274 /* addr is numeric string */ 275 error = getnameinfo(sa, salen, addr, sizeof(addr), 276 NULL, 0, NI_NUMERICHOST); 277} 278.Ed 279.\".Pp 280.\".Ox 281.\"intentionally uses a different 282.\".Dv NI_MAXHOST 283.\"value from what 284.\".Tn "RFC 2553" 285.\"suggests, to avoid buffer length handling mistakes. 286