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