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