1.\" $OpenBSD: getnameinfo.3,v 1.41 2008/12/22 12:18:56 jacekm 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: December 22 2008 $ 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.Fd #include <sys/types.h> 27.Fd #include <sys/socket.h> 28.Fd #include <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.Aq Pa 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 chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. 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.Xr named 8 167.Rs 168.%A R. Gilligan 169.%A S. Thomson 170.%A J. Bound 171.%A W. Stevens 172.%T Basic Socket Interface Extensions for IPv6 173.%R RFC 2553 174.%D March 1999 175.Re 176.Rs 177.%A S. Deering 178.%A B. Haberman 179.%A T. Jinmei 180.%A E. Nordmark 181.%A B. Zill 182.%T "IPv6 Scoped Address Architecture" 183.%R internet draft 184.%N draft-ietf-ipv6-scoping-arch-02.txt 185.%O work in progress material 186.Re 187.Rs 188.%A Craig Metz 189.%T Protocol Independence Using the Sockets API 190.%B "Proceedings of the Freenix Track: 2000 USENIX Annual Technical Conference" 191.%D June 2000 192.Re 193.Sh STANDARDS 194The 195.Fn getnameinfo 196function is defined by the 197.St -p1003.1g-2000 198draft specification and documented in 199.Tn "RFC 2553" , 200.Dq Basic Socket Interface Extensions for IPv6 . 201.Sh CAVEATS 202.Fn getnameinfo 203can return both numeric and FQDN forms of the address specified in 204.Fa sa . 205There is no return value that indicates whether the string returned in 206.Fa host 207is a result of binary to numeric-text translation (like 208.Xr inet_ntop 3 ) , 209or is the result of a DNS reverse lookup. 210Because of this, malicious parties could set up a PTR record as follows: 211.Bd -literal -offset indent 2121.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 213.Ed 214.Pp 215and trick the caller of 216.Fn getnameinfo 217into believing that 218.Fa sa 219is 220.Li 10.1.1.1 221when it is actually 222.Li 127.0.0.1 . 223.Pp 224To prevent such attacks, the use of 225.Dv NI_NAMEREQD 226is recommended when the result of 227.Fn getnameinfo 228is used 229for access control purposes: 230.Bd -literal -offset indent 231struct sockaddr *sa; 232char addr[NI_MAXHOST]; 233struct addrinfo hints, *res; 234int error; 235 236error = getnameinfo(sa, sa->sa_len, addr, sizeof(addr), 237 NULL, 0, NI_NAMEREQD); 238if (error == 0) { 239 memset(&hints, 0, sizeof(hints)); 240 hints.ai_socktype = SOCK_DGRAM; /*dummy*/ 241 hints.ai_flags = AI_NUMERICHOST; 242 if (getaddrinfo(addr, "0", &hints, &res) == 0) { 243 /* malicious PTR record */ 244 freeaddrinfo(res); 245 printf("bogus PTR record\en"); 246 return -1; 247 } 248 /* addr is FQDN as a result of PTR lookup */ 249} else { 250 /* addr is numeric string */ 251 error = getnameinfo(sa, sa->sa_len, addr, sizeof(addr), 252 NULL, 0, NI_NUMERICHOST); 253} 254.Ed 255.Sh BUGS 256The implementation of 257.Fn getnameinfo 258is not thread-safe. 259.Pp 260.Ox 261intentionally uses a different 262.Dv NI_MAXHOST 263value from what 264.Tn "RFC 2553" 265suggests, to avoid buffer length handling mistakes. 266