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 October 12, 2017 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_NUMERICSCOPE" 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_NUMERICSCOPE 125For IPv6 addresses, scope identifier is returned as a digit string instead 126of its name. 127.It Dv NI_DGRAM 128Specifies that the service being looked up is a datagram 129service, and causes 130.Xr getservbyport 3 131to be called with a second argument of 132.Dq udp 133instead of its default of 134.Dq tcp . 135This is required for the few ports (512\-514) that have different services 136for 137.Tn UDP 138and 139.Tn TCP . 140.El 141.Pp 142This implementation allows numeric IPv6 address notation with scope identifier, 143as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. 144IPv6 link-local address will appear as a string like 145.Dq Li fe80::1%ne0 . 146Refer to 147.Xr getaddrinfo 3 148for more information. 149.Sh RETURN VALUES 150.Fn getnameinfo 151returns zero on success or one of the error codes listed in 152.Xr gai_strerror 3 153if an error occurs. 154.Sh EXAMPLES 155The following code tries to get a numeric host name, and service name, 156for a given socket address. 157Observe that there is no hardcoded reference to a particular address family. 158.Bd -literal -offset indent 159struct sockaddr *sa; /* input */ 160char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; 161 162if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, 163 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { 164 errx(1, "could not get numeric hostname"); 165 /*NOTREACHED*/ 166} 167printf("host=%s, serv=%s\en", hbuf, sbuf); 168.Ed 169.Pp 170The following version checks if the socket address has a reverse address mapping: 171.Bd -literal -offset indent 172struct sockaddr *sa; /* input */ 173char hbuf[NI_MAXHOST]; 174 175if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, 176 NI_NAMEREQD)) { 177 errx(1, "could not resolve hostname"); 178 /*NOTREACHED*/ 179} 180printf("host=%s\en", hbuf); 181.Ed 182.Sh SEE ALSO 183.Xr gai_strerror 3 , 184.Xr getaddrinfo 3 , 185.Xr gethostbyaddr 3 , 186.Xr getservbyport 3 , 187.Xr inet_ntop 3 , 188.Xr link_ntoa 3 , 189.Xr resolver 3 , 190.Xr hosts 5 , 191.Xr resolv.conf 5 , 192.Xr services 5 , 193.Xr hostname 7 , 194.Xr named 8 195.Rs 196.%A R. Gilligan 197.%A S. Thomson 198.%A J. Bound 199.%A W. Stevens 200.%T Basic Socket Interface Extensions for IPv6 201.%R RFC 2553 202.%D March 1999 203.Re 204.Rs 205.%A S. Deering 206.%A B. Haberman 207.%A T. Jinmei 208.%A E. Nordmark 209.%A B. Zill 210.%T "IPv6 Scoped Address Architecture" 211.%R internet draft 212.%N draft-ietf-ipv6-scoping-arch-02.txt 213.%O work in progress material 214.Re 215.Rs 216.%A Craig Metz 217.%T Protocol Independence Using the Sockets API 218.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 219.%D June 2000 220.Re 221.Sh STANDARDS 222The 223.Fn getnameinfo 224function is defined by the 225.St -p1003.1g-2000 226draft specification and documented in 227.Tn "RFC 2553" , 228.Dq Basic Socket Interface Extensions for IPv6 . 229.Sh CAVEATS 230.Fn getnameinfo 231can return both numeric and FQDN forms of the address specified in 232.Fa sa . 233There is no return value that indicates whether the string returned in 234.Fa host 235is a result of binary to numeric-text translation (like 236.Xr inet_ntop 3 ) , 237or is the result of a DNS reverse lookup. 238Because of this, malicious parties could set up a PTR record as follows: 239.Bd -literal -offset indent 2401.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 241.Ed 242.Pp 243and trick the caller of 244.Fn getnameinfo 245into believing that 246.Fa sa 247is 248.Li 10.1.1.1 249when it is actually 250.Li 127.0.0.1 . 251.Pp 252To prevent such attacks, the use of 253.Dv NI_NAMEREQD 254is recommended when the result of 255.Fn getnameinfo 256is used 257for access control purposes: 258.Bd -literal -offset indent 259struct sockaddr *sa; 260socklen_t salen; 261char addr[NI_MAXHOST]; 262struct addrinfo hints, *res; 263int error; 264 265error = getnameinfo(sa, salen, addr, sizeof(addr), 266 NULL, 0, NI_NAMEREQD); 267if (error == 0) { 268 memset(&hints, 0, sizeof(hints)); 269 hints.ai_socktype = SOCK_DGRAM; /*dummy*/ 270 hints.ai_flags = AI_NUMERICHOST; 271 if (getaddrinfo(addr, "0", &hints, &res) == 0) { 272 /* malicious PTR record */ 273 freeaddrinfo(res); 274 printf("bogus PTR record\en"); 275 return -1; 276 } 277 /* addr is FQDN as a result of PTR lookup */ 278} else { 279 /* addr is numeric string */ 280 error = getnameinfo(sa, salen, addr, sizeof(addr), 281 NULL, 0, NI_NUMERICHOST); 282} 283.Ed 284.\".Pp 285.\".Ox 286.\"intentionally uses a different 287.\".Dv NI_MAXHOST 288.\"value from what 289.\".Tn "RFC 2553" 290.\"suggests, to avoid buffer length handling mistakes. 291