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