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