1.\" $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $ 2.\" $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc Exp $ 3.\" $FreeBSD: src/lib/libc/net/getnameinfo.3,v 1.21 2005/01/23 16:02:48 gnn Exp $ 4.\" $DragonFly: src/lib/libc/net/getnameinfo.3,v 1.4 2006/05/26 19:39:37 swildner Exp $ 5.\" 6.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") 7.\" Copyright (C) 2000, 2001 Internet Software Consortium. 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 14.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 15.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 16.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 17.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 18.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 19.\" PERFORMANCE OF THIS SOFTWARE. 20.\" 21.Dd December 20, 2004 22.Dt GETNAMEINFO 3 23.Os 24.Sh NAME 25.Nm getnameinfo 26.Nd socket address structure to hostname and service name 27.Sh SYNOPSIS 28.In sys/types.h 29.In sys/socket.h 30.In netdb.h 31.Ft int 32.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" "char *host" \ 33 "size_t hostlen" "char *serv" "size_t servlen" "int flags" 34.Sh DESCRIPTION 35The 36.Fn getnameinfo 37function is used to convert a 38.Li sockaddr 39structure to a pair of host name and service strings. 40It is a replacement for and provides more flexibility than the 41.Xr gethostbyaddr 3 42and 43.Xr getservbyport 3 44functions and is the converse of the 45.Xr getaddrinfo 3 46function. 47.Pp 48The 49.Li sockaddr 50structure 51.Fa sa 52should point to either a 53.Li sockaddr_in 54or 55.Li sockaddr_in6 56structure (for IPv4 or IPv6 respectively) that is 57.Fa salen 58bytes long. 59.Pp 60The host and service names associated with 61.Fa sa 62are stored in 63.Fa host 64and 65.Fa serv 66which have length parameters 67.Fa hostlen 68and 69.Fa servlen . 70The maximum value for 71.Fa hostlen 72is 73.Dv NI_MAXHOST 74and 75the maximum value for 76.Fa servlen 77is 78.Dv NI_MAXSERV , 79as defined by 80.In netdb.h . 81If a length parameter is zero, no string will be stored. 82Otherwise, enough space must be provided to store the 83host name or service string plus a byte for the NUL terminator. 84.Pp 85The 86.Fa flags 87argument is formed by 88.Tn OR Ns 'ing 89the following values: 90.Bl -tag -width "NI_NUMERICHOSTXX" 91.It Dv NI_NOFQDN 92A fully qualified domain name is not required for local hosts. 93The local part of the fully qualified domain name is returned instead. 94.It Dv NI_NUMERICHOST 95Return the address in numeric form, as if calling 96.Xr inet_ntop 3 , 97instead of a host name. 98.It Dv NI_NAMEREQD 99A name is required. 100If the host name cannot be found in DNS and this flag is set, 101a non-zero error code is returned. 102If the host name is not found and the flag is not set, the 103address is returned in numeric form. 104.It NI_NUMERICSERV 105The service name is returned as a digit string representing the port number. 106.It NI_DGRAM 107Specifies that the service being looked up is a datagram 108service, and causes 109.Xr getservbyport 3 110to be called with a second argument of 111.Dq udp 112instead of its default of 113.Dq tcp . 114This is required for the few ports (512\-514) that have different services 115for 116.Tn UDP 117and 118.Tn TCP . 119.El 120.Pp 121This implementation allows numeric IPv6 address notation with scope identifier, 122as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. 123IPv6 link-local address will appear as a string like 124.Dq Li fe80::1%ne0 . 125Refer to 126.Xr getaddrinfo 3 127for more information. 128.Sh RETURN VALUES 129.Fn getnameinfo 130returns zero on success or one of the error codes listed in 131.Xr gai_strerror 3 132if an error occurs. 133.Sh EXAMPLES 134The following code tries to get a numeric host name, and service name, 135for a given socket address. 136Observe that there is no hardcoded reference to a particular address family. 137.Bd -literal -offset indent 138struct sockaddr *sa; /* input */ 139char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; 140 141if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, 142 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { 143 errx(1, "could not get numeric hostname"); 144 /*NOTREACHED*/ 145} 146printf("host=%s, serv=%s\en", hbuf, sbuf); 147.Ed 148.Pp 149The following version checks if the socket address has a reverse address mapping: 150.Bd -literal -offset indent 151struct sockaddr *sa; /* input */ 152char hbuf[NI_MAXHOST]; 153 154if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, 155 NI_NAMEREQD)) { 156 errx(1, "could not resolve hostname"); 157 /*NOTREACHED*/ 158} 159printf("host=%s\en", hbuf); 160.Ed 161.Sh SEE ALSO 162.Xr gai_strerror 3 , 163.Xr getaddrinfo 3 , 164.Xr gethostbyaddr 3 , 165.Xr getservbyport 3 , 166.Xr inet_ntop 3 , 167.Xr resolver 3 , 168.Xr hosts 5 , 169.Xr resolv.conf 5 , 170.Xr services 5 , 171.Xr hostname 7 , 172.Xr named 8 173.Rs 174.%A R. Gilligan 175.%A S. Thomson 176.%A J. Bound 177.%A W. Stevens 178.%T Basic Socket Interface Extensions for IPv6 179.%R RFC 2553 180.%D March 1999 181.Re 182.Rs 183.%A S. Deering 184.%A B. Haberman 185.%A T. Jinmei 186.%A E. Nordmark 187.%A B. Zill 188.%T "IPv6 Scoped Address Architecture" 189.%R internet draft 190.%N draft-ietf-ipv6-scoping-arch-02.txt 191.%O work in progress material 192.Re 193.Rs 194.%A Craig Metz 195.%T Protocol Independence Using the Sockets API 196.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 197.%D June 2000 198.Re 199.Sh STANDARDS 200The 201.Fn getnameinfo 202function is defined by the 203.St -p1003.1g-2000 204draft specification and documented in 205.Tn "RFC 2553" , 206.Dq Basic Socket Interface Extensions for IPv6 . 207.Sh CAVEATS 208.Fn getnameinfo 209can return both numeric and FQDN forms of the address specified in 210.Fa sa . 211There is no return value that indicates whether the string returned in 212.Fa host 213is a result of binary to numeric-text translation (like 214.Xr inet_ntop 3 ) , 215or is the result of a DNS reverse lookup. 216Because of this, malicious parties could set up a PTR record as follows: 217.Bd -literal -offset indent 2181.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 219.Ed 220.Pp 221and trick the caller of 222.Fn getnameinfo 223into believing that 224.Fa sa 225is 226.Li 10.1.1.1 227when it is actually 228.Li 127.0.0.1 . 229.Pp 230To prevent such attacks, the use of 231.Dv NI_NAMEREQD 232is recommended when the result of 233.Fn getnameinfo 234is used 235for access control purposes: 236.Bd -literal -offset indent 237struct sockaddr *sa; 238socklen_t salen; 239char addr[NI_MAXHOST]; 240struct addrinfo hints, *res; 241int error; 242 243error = getnameinfo(sa, salen, addr, sizeof(addr), 244 NULL, 0, NI_NAMEREQD); 245if (error == 0) { 246 memset(&hints, 0, sizeof(hints)); 247 hints.ai_socktype = SOCK_DGRAM; /*dummy*/ 248 hints.ai_flags = AI_NUMERICHOST; 249 if (getaddrinfo(addr, "0", &hints, &res) == 0) { 250 /* malicious PTR record */ 251 freeaddrinfo(res); 252 printf("bogus PTR record\en"); 253 return -1; 254 } 255 /* addr is FQDN as a result of PTR lookup */ 256} else { 257 /* addr is numeric string */ 258 error = getnameinfo(sa, salen, addr, sizeof(addr), 259 NULL, 0, NI_NUMERICHOST); 260} 261.Ed 262.Sh BUGS 263The implementation of 264.Fn getnameinfo 265is not thread-safe. 266.\".Pp 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