1.\" $NetBSD: getnameinfo.3,v 1.34 2005/01/12 14:44:11 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 December 20, 2004 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 sys/types.h 28.In sys/socket.h 29.In netdb.h 30.Ft int 31.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" "char *host" \ 32 "size_t hostlen" "char *serv" "size_t servlen" "int flags" 33.Sh DESCRIPTION 34The 35.Fn getnameinfo 36function is used to convert a 37.Li sockaddr 38structure to a pair of host name and service strings. 39It is a replacement for and provides more flexibility than the 40.Xr gethostbyaddr 3 41and 42.Xr getservbyport 3 43functions and is the converse of the 44.Xr getaddrinfo 3 45function. 46.Pp 47The 48.Li sockaddr 49structure 50.Fa sa 51should point to either a 52.Li sockaddr_in 53or 54.Li sockaddr_in6 55structure (for IPv4 or IPv6 respectively) that is 56.Fa salen 57bytes long. 58.Pp 59The host and service names associated with 60.Fa sa 61are stored in 62.Fa host 63and 64.Fa serv 65which have length parameters 66.Fa hostlen 67and 68.Fa servlen . 69The maximum value for 70.Fa hostlen 71is 72.Dv NI_MAXHOST 73and the 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.Sy 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-\*[Gt]sa_len, hbuf, sizeof(hbuf), sbuf, 140 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { 141 errx(1, "could not get numeric hostname"); 142 /*NOTREACHED*/ 143} 144printf("host=%s, serv=%s\en", hbuf, sbuf); 145.Ed 146.Pp 147The following version checks if the socket address has a reverse address mapping: 148.Bd -literal -offset indent 149struct sockaddr *sa; /* input */ 150char hbuf[NI_MAXHOST]; 151 152if (getnameinfo(sa, sa-\*[Gt]sa_len, hbuf, sizeof(hbuf), NULL, 0, 153 NI_NAMEREQD)) { 154 errx(1, "could not resolve hostname"); 155 /*NOTREACHED*/ 156} 157printf("host=%s\en", hbuf); 158.Ed 159.Sh SEE ALSO 160.Xr gai_strerror 3 , 161.Xr getaddrinfo 3 , 162.Xr gethostbyaddr 3 , 163.Xr getservbyport 3 , 164.Xr inet_ntop 3 , 165.Xr resolver 3 , 166.Xr hosts 5 , 167.Xr resolv.conf 5 , 168.Xr services 5 , 169.Xr hostname 7 , 170.Xr named 8 171.Rs 172.%A R. Gilligan 173.%A S. Thomson 174.%A J. Bound 175.%A W. Stevens 176.%T Basic Socket Interface Extensions for IPv6 177.%R RFC 2553 178.%D March 1999 179.Re 180.Rs 181.%A S. Deering 182.%A B. Haberman 183.%A T. Jinmei 184.%A E. Nordmark 185.%A B. Zill 186.%T "IPv6 Scoped Address Architecture" 187.%R internet draft 188.%N draft-ietf-ipv6-scoping-arch-02.txt 189.%O work in progress material 190.Re 191.Rs 192.%A Craig Metz 193.%T Protocol Independence Using the Sockets API 194.%B "Proceedings of the FREENIX track: 2000 USENIX annual technical conference" 195.%D June 2000 196.Re 197.Sh STANDARDS 198The 199.Fn getnameinfo 200function is defined by the 201.St -p1003.1g-2000 202draft specification and documented in 203.Sy "RFC 2553" , 204.Dq Basic Socket Interface Extensions for IPv6 . 205.Sh CAVEATS 206.Fn getnameinfo 207can return both numeric and FQDN forms of the address specified in 208.Fa sa . 209There is no return value that indicates whether the string returned in 210.Fa host 211is a result of binary to numeric-text translation (like 212.Xr inet_ntop 3 ) , 213or is the result of a DNS reverse lookup. 214Because of this, malicious parties could set up a PTR record as follows: 215.Bd -literal -offset indent 2161.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 217.Ed 218.Pp 219and trick the caller of 220.Fn getnameinfo 221into believing that 222.Fa sa 223is 224.Li 10.1.1.1 225when it is actually 226.Li 127.0.0.1 . 227.Pp 228To prevent such attacks, the use of 229.Dv NI_NAMEREQD 230is recommended when the result of 231.Fn getnameinfo 232is used for access control purposes: 233.Bd -literal -offset indent 234struct sockaddr *sa; 235socklen_t salen; 236char addr[NI_MAXHOST]; 237struct addrinfo hints, *res; 238int error; 239 240error = getnameinfo(sa, salen, addr, sizeof(addr), 241 NULL, 0, NI_NAMEREQD); 242if (error == 0) { 243 memset(\*[Am]hints, 0, sizeof(hints)); 244 hints.ai_socktype = SOCK_DGRAM; /*dummy*/ 245 hints.ai_flags = AI_NUMERICHOST; 246 if (getaddrinfo(addr, "0", \*[Am]hints, \*[Am]res) == 0) { 247 /* malicious PTR record */ 248 freeaddrinfo(res); 249 printf("bogus PTR record\en"); 250 return -1; 251 } 252 /* addr is FQDN as a result of PTR lookup */ 253} else { 254 /* addr is numeric string */ 255 error = getnameinfo(sa, salen, addr, sizeof(addr), 256 NULL, 0, NI_NUMERICHOST); 257} 258.Ed 259.Sh BUGS 260The implementation of 261.Fn getnameinfo 262is not thread-safe. 263.\".Pp 264.\".Ox 265.\"intentionally uses a different 266.\".Dv NI_MAXHOST 267.\"value from what 268.\".Tn "RFC 2553" 269.\"suggests, to avoid buffer length handling mistakes. 270