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