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