16617cf57SGeorge V. Neville-Neil.\" $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $ 26617cf57SGeorge V. Neville-Neil.\" $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc Exp $ 36617cf57SGeorge V. Neville-Neil.\" 46617cf57SGeorge V. Neville-Neil.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") 56617cf57SGeorge V. Neville-Neil.\" Copyright (C) 2000, 2001 Internet Software Consortium. 66617cf57SGeorge V. Neville-Neil.\" 76617cf57SGeorge V. Neville-Neil.\" Permission to use, copy, modify, and distribute this software for any 86617cf57SGeorge V. Neville-Neil.\" purpose with or without fee is hereby granted, provided that the above 96617cf57SGeorge V. Neville-Neil.\" copyright notice and this permission notice appear in all copies. 106617cf57SGeorge V. Neville-Neil.\" 116617cf57SGeorge V. Neville-Neil.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 126617cf57SGeorge V. Neville-Neil.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 136617cf57SGeorge V. Neville-Neil.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 146617cf57SGeorge V. Neville-Neil.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 156617cf57SGeorge V. Neville-Neil.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 166617cf57SGeorge V. Neville-Neil.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 176617cf57SGeorge V. Neville-Neil.\" PERFORMANCE OF THIS SOFTWARE. 186617cf57SGeorge V. Neville-Neil.\" 196b806d21SRuslan Ermilov.\" $FreeBSD$ 206b806d21SRuslan Ermilov.\" 21160a2e55SBruce M Simpson.Dd February 28, 2007 226617cf57SGeorge V. Neville-Neil.Dt GETNAMEINFO 3 236617cf57SGeorge V. Neville-Neil.Os 246617cf57SGeorge V. Neville-Neil.Sh NAME 256617cf57SGeorge V. Neville-Neil.Nm getnameinfo 266617cf57SGeorge V. Neville-Neil.Nd socket address structure to hostname and service name 276617cf57SGeorge V. Neville-Neil.Sh SYNOPSIS 286617cf57SGeorge V. Neville-Neil.Fd #include <sys/types.h> 296617cf57SGeorge V. Neville-Neil.Fd #include <sys/socket.h> 306617cf57SGeorge V. Neville-Neil.Fd #include <netdb.h> 316617cf57SGeorge V. Neville-Neil.Ft int 32f789cb82SRuslan Ermilov.Fo getnameinfo 33f789cb82SRuslan Ermilov.Fa "const struct sockaddr *sa" "socklen_t salen" "char *host" 34f789cb82SRuslan Ermilov.Fa "size_t hostlen" "char *serv" "size_t servlen" "int flags" 35f789cb82SRuslan Ermilov.Fc 366617cf57SGeorge V. Neville-Neil.Sh DESCRIPTION 376617cf57SGeorge V. Neville-NeilThe 386617cf57SGeorge V. Neville-Neil.Fn getnameinfo 396617cf57SGeorge V. Neville-Neilfunction is used to convert a 406617cf57SGeorge V. Neville-Neil.Li sockaddr 416617cf57SGeorge V. Neville-Neilstructure to a pair of host name and service strings. 426617cf57SGeorge V. Neville-NeilIt is a replacement for and provides more flexibility than the 436617cf57SGeorge V. Neville-Neil.Xr gethostbyaddr 3 446617cf57SGeorge V. Neville-Neiland 456617cf57SGeorge V. Neville-Neil.Xr getservbyport 3 466617cf57SGeorge V. Neville-Neilfunctions and is the converse of the 476617cf57SGeorge V. Neville-Neil.Xr getaddrinfo 3 486617cf57SGeorge V. Neville-Neilfunction. 496617cf57SGeorge V. Neville-Neil.Pp 50160a2e55SBruce M SimpsonIf a link-layer address is passed to 51160a2e55SBruce M Simpson.Fn getnameinfo , 52160a2e55SBruce M Simpsonits ASCII representation will be stored in 53160a2e55SBruce M Simpson.Fa host . 54160a2e55SBruce M SimpsonThe string pointed to by 55160a2e55SBruce M Simpson.Fa serv 56160a2e55SBruce M Simpsonwill be set to the empty string if non-NULL; 57160a2e55SBruce M Simpson.Fa flags 58160a2e55SBruce M Simpsonwill always be ignored. 59160a2e55SBruce M SimpsonThis is intended as a replacement for the legacy 60160a2e55SBruce M Simpson.Xr link_ntoa 3 61160a2e55SBruce M Simpsonfunction. 62160a2e55SBruce M Simpson.Pp 636617cf57SGeorge V. Neville-NeilThe 646617cf57SGeorge V. Neville-Neil.Li sockaddr 656617cf57SGeorge V. Neville-Neilstructure 666617cf57SGeorge V. Neville-Neil.Fa sa 676617cf57SGeorge V. Neville-Neilshould point to either a 68160a2e55SBruce M Simpson.Li sockaddr_in , 696617cf57SGeorge V. Neville-Neil.Li sockaddr_in6 70160a2e55SBruce M Simpsonor 71160a2e55SBruce M Simpson.Li sockaddr_dl 72160a2e55SBruce M Simpsonstructure (for IPv4, IPv6 or link-layer respectively) that is 736617cf57SGeorge V. Neville-Neil.Fa salen 746617cf57SGeorge V. Neville-Neilbytes long. 756617cf57SGeorge V. Neville-Neil.Pp 766617cf57SGeorge V. Neville-NeilThe host and service names associated with 776617cf57SGeorge V. Neville-Neil.Fa sa 786617cf57SGeorge V. Neville-Neilare stored in 796617cf57SGeorge V. Neville-Neil.Fa host 806617cf57SGeorge V. Neville-Neiland 816617cf57SGeorge V. Neville-Neil.Fa serv 826617cf57SGeorge V. Neville-Neilwhich have length parameters 836617cf57SGeorge V. Neville-Neil.Fa hostlen 846617cf57SGeorge V. Neville-Neiland 856617cf57SGeorge V. Neville-Neil.Fa servlen . 866617cf57SGeorge V. Neville-NeilThe maximum value for 876617cf57SGeorge V. Neville-Neil.Fa hostlen 886617cf57SGeorge V. Neville-Neilis 896617cf57SGeorge V. Neville-Neil.Dv NI_MAXHOST 906617cf57SGeorge V. Neville-Neiland 916617cf57SGeorge V. Neville-Neilthe maximum value for 926617cf57SGeorge V. Neville-Neil.Fa servlen 936617cf57SGeorge V. Neville-Neilis 946617cf57SGeorge V. Neville-Neil.Dv NI_MAXSERV , 956617cf57SGeorge V. Neville-Neilas defined by 966617cf57SGeorge V. Neville-Neil.Aq Pa netdb.h . 976617cf57SGeorge V. Neville-NeilIf a length parameter is zero, no string will be stored. 986617cf57SGeorge V. Neville-NeilOtherwise, enough space must be provided to store the 996617cf57SGeorge V. Neville-Neilhost name or service string plus a byte for the NUL terminator. 1006617cf57SGeorge V. Neville-Neil.Pp 1016617cf57SGeorge V. Neville-NeilThe 1026617cf57SGeorge V. Neville-Neil.Fa flags 1036617cf57SGeorge V. Neville-Neilargument is formed by 1046617cf57SGeorge V. Neville-Neil.Tn OR Ns 'ing 1056617cf57SGeorge V. Neville-Neilthe following values: 1066617cf57SGeorge V. Neville-Neil.Bl -tag -width "NI_NUMERICHOSTXX" 1076617cf57SGeorge V. Neville-Neil.It Dv NI_NOFQDN 1086617cf57SGeorge V. Neville-NeilA fully qualified domain name is not required for local hosts. 1096617cf57SGeorge V. Neville-NeilThe local part of the fully qualified domain name is returned instead. 1106617cf57SGeorge V. Neville-Neil.It Dv NI_NUMERICHOST 1116617cf57SGeorge V. Neville-NeilReturn the address in numeric form, as if calling 1126617cf57SGeorge V. Neville-Neil.Xr inet_ntop 3 , 1136617cf57SGeorge V. Neville-Neilinstead of a host name. 1146617cf57SGeorge V. Neville-Neil.It Dv NI_NAMEREQD 1156617cf57SGeorge V. Neville-NeilA name is required. 1166617cf57SGeorge V. Neville-NeilIf the host name cannot be found in DNS and this flag is set, 1176617cf57SGeorge V. Neville-Neila non-zero error code is returned. 1186617cf57SGeorge V. Neville-NeilIf the host name is not found and the flag is not set, the 1196617cf57SGeorge V. Neville-Neiladdress is returned in numeric form. 1206617cf57SGeorge V. Neville-Neil.It NI_NUMERICSERV 1216617cf57SGeorge V. Neville-NeilThe service name is returned as a digit string representing the port number. 1226617cf57SGeorge V. Neville-Neil.It NI_DGRAM 1236617cf57SGeorge V. Neville-NeilSpecifies that the service being looked up is a datagram 1246617cf57SGeorge V. Neville-Neilservice, and causes 1256617cf57SGeorge V. Neville-Neil.Xr getservbyport 3 1266617cf57SGeorge V. Neville-Neilto be called with a second argument of 1276617cf57SGeorge V. Neville-Neil.Dq udp 1286617cf57SGeorge V. Neville-Neilinstead of its default of 1296617cf57SGeorge V. Neville-Neil.Dq tcp . 1306617cf57SGeorge V. Neville-NeilThis is required for the few ports (512\-514) that have different services 1316617cf57SGeorge V. Neville-Neilfor 1326617cf57SGeorge V. Neville-Neil.Tn UDP 1336617cf57SGeorge V. Neville-Neiland 1346617cf57SGeorge V. Neville-Neil.Tn TCP . 1356617cf57SGeorge V. Neville-Neil.El 1366617cf57SGeorge V. Neville-Neil.Pp 1376617cf57SGeorge V. Neville-NeilThis implementation allows numeric IPv6 address notation with scope identifier, 13862101061SEitan Adleras documented in chapter 11 of RFC 4007. 1396617cf57SGeorge V. Neville-NeilIPv6 link-local address will appear as a string like 1406617cf57SGeorge V. Neville-Neil.Dq Li fe80::1%ne0 . 1416617cf57SGeorge V. Neville-NeilRefer to 1426617cf57SGeorge V. Neville-Neil.Xr getaddrinfo 3 1436617cf57SGeorge V. Neville-Neilfor more information. 1446617cf57SGeorge V. Neville-Neil.Sh RETURN VALUES 1456617cf57SGeorge V. Neville-Neil.Fn getnameinfo 1466617cf57SGeorge V. Neville-Neilreturns zero on success or one of the error codes listed in 1476617cf57SGeorge V. Neville-Neil.Xr gai_strerror 3 1486617cf57SGeorge V. Neville-Neilif an error occurs. 1496617cf57SGeorge V. Neville-Neil.Sh EXAMPLES 1506617cf57SGeorge V. Neville-NeilThe following code tries to get a numeric host name, and service name, 1516617cf57SGeorge V. Neville-Neilfor a given socket address. 1526617cf57SGeorge V. Neville-NeilObserve that there is no hardcoded reference to a particular address family. 1536617cf57SGeorge V. Neville-Neil.Bd -literal -offset indent 1546617cf57SGeorge V. Neville-Neilstruct sockaddr *sa; /* input */ 1556617cf57SGeorge V. Neville-Neilchar hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; 1566617cf57SGeorge V. Neville-Neil 1576617cf57SGeorge V. Neville-Neilif (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, 1586617cf57SGeorge V. Neville-Neil sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { 1596617cf57SGeorge V. Neville-Neil errx(1, "could not get numeric hostname"); 1606617cf57SGeorge V. Neville-Neil /*NOTREACHED*/ 1616617cf57SGeorge V. Neville-Neil} 1626617cf57SGeorge V. Neville-Neilprintf("host=%s, serv=%s\en", hbuf, sbuf); 1636617cf57SGeorge V. Neville-Neil.Ed 1646617cf57SGeorge V. Neville-Neil.Pp 1656617cf57SGeorge V. Neville-NeilThe following version checks if the socket address has a reverse address mapping: 1666617cf57SGeorge V. Neville-Neil.Bd -literal -offset indent 1676617cf57SGeorge V. Neville-Neilstruct sockaddr *sa; /* input */ 1686617cf57SGeorge V. Neville-Neilchar hbuf[NI_MAXHOST]; 1696617cf57SGeorge V. Neville-Neil 1706617cf57SGeorge V. Neville-Neilif (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, 1716617cf57SGeorge V. Neville-Neil NI_NAMEREQD)) { 1726617cf57SGeorge V. Neville-Neil errx(1, "could not resolve hostname"); 1736617cf57SGeorge V. Neville-Neil /*NOTREACHED*/ 1746617cf57SGeorge V. Neville-Neil} 1756617cf57SGeorge V. Neville-Neilprintf("host=%s\en", hbuf); 1766617cf57SGeorge V. Neville-Neil.Ed 1776617cf57SGeorge V. Neville-Neil.Sh SEE ALSO 1786617cf57SGeorge V. Neville-Neil.Xr gai_strerror 3 , 1796617cf57SGeorge V. Neville-Neil.Xr getaddrinfo 3 , 1806617cf57SGeorge V. Neville-Neil.Xr gethostbyaddr 3 , 1816617cf57SGeorge V. Neville-Neil.Xr getservbyport 3 , 1826617cf57SGeorge V. Neville-Neil.Xr inet_ntop 3 , 183160a2e55SBruce M Simpson.Xr link_ntoa 3 , 1846617cf57SGeorge V. Neville-Neil.Xr resolver 3 , 1856617cf57SGeorge V. Neville-Neil.Xr hosts 5 , 1866617cf57SGeorge V. Neville-Neil.Xr resolv.conf 5 , 1876617cf57SGeorge V. Neville-Neil.Xr services 5 , 1886617cf57SGeorge V. Neville-Neil.Xr hostname 7 , 1896617cf57SGeorge V. Neville-Neil.Xr named 8 1906617cf57SGeorge V. Neville-Neil.Rs 1916617cf57SGeorge V. Neville-Neil.%A R. Gilligan 1926617cf57SGeorge V. Neville-Neil.%A S. Thomson 1936617cf57SGeorge V. Neville-Neil.%A J. Bound 1946617cf57SGeorge V. Neville-Neil.%A W. Stevens 1956617cf57SGeorge V. Neville-Neil.%T Basic Socket Interface Extensions for IPv6 1966617cf57SGeorge V. Neville-Neil.%R RFC 2553 1976617cf57SGeorge V. Neville-Neil.%D March 1999 1986617cf57SGeorge V. Neville-Neil.Re 1996617cf57SGeorge V. Neville-Neil.Rs 2006617cf57SGeorge V. Neville-Neil.%A S. Deering 2016617cf57SGeorge V. Neville-Neil.%A B. Haberman 2026617cf57SGeorge V. Neville-Neil.%A T. Jinmei 2036617cf57SGeorge V. Neville-Neil.%A E. Nordmark 2046617cf57SGeorge V. Neville-Neil.%A B. Zill 2056617cf57SGeorge V. Neville-Neil.%T "IPv6 Scoped Address Architecture" 2066617cf57SGeorge V. Neville-Neil.%R internet draft 2076617cf57SGeorge V. Neville-Neil.%N draft-ietf-ipv6-scoping-arch-02.txt 2086617cf57SGeorge V. Neville-Neil.%O work in progress material 2096617cf57SGeorge V. Neville-Neil.Re 2106617cf57SGeorge V. Neville-Neil.Rs 2116617cf57SGeorge V. Neville-Neil.%A Craig Metz 2126617cf57SGeorge V. Neville-Neil.%T Protocol Independence Using the Sockets API 2136617cf57SGeorge V. Neville-Neil.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 2146617cf57SGeorge V. Neville-Neil.%D June 2000 2156617cf57SGeorge V. Neville-Neil.Re 2166617cf57SGeorge V. Neville-Neil.Sh STANDARDS 2176617cf57SGeorge V. Neville-NeilThe 2186617cf57SGeorge V. Neville-Neil.Fn getnameinfo 2196617cf57SGeorge V. Neville-Neilfunction is defined by the 2206617cf57SGeorge V. Neville-Neil.St -p1003.1g-2000 2216617cf57SGeorge V. Neville-Neildraft specification and documented in 2226617cf57SGeorge V. Neville-Neil.Tn "RFC 2553" , 2236617cf57SGeorge V. Neville-Neil.Dq Basic Socket Interface Extensions for IPv6 . 2246617cf57SGeorge V. Neville-Neil.Sh CAVEATS 2256617cf57SGeorge V. Neville-Neil.Fn getnameinfo 2266617cf57SGeorge V. Neville-Neilcan return both numeric and FQDN forms of the address specified in 2276617cf57SGeorge V. Neville-Neil.Fa sa . 2286617cf57SGeorge V. Neville-NeilThere is no return value that indicates whether the string returned in 2296617cf57SGeorge V. Neville-Neil.Fa host 2306617cf57SGeorge V. Neville-Neilis a result of binary to numeric-text translation (like 2316617cf57SGeorge V. Neville-Neil.Xr inet_ntop 3 ) , 2326617cf57SGeorge V. Neville-Neilor is the result of a DNS reverse lookup. 2336617cf57SGeorge V. Neville-NeilBecause of this, malicious parties could set up a PTR record as follows: 2346617cf57SGeorge V. Neville-Neil.Bd -literal -offset indent 2356617cf57SGeorge V. Neville-Neil1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 2366617cf57SGeorge V. Neville-Neil.Ed 2376617cf57SGeorge V. Neville-Neil.Pp 2386617cf57SGeorge V. Neville-Neiland trick the caller of 2396617cf57SGeorge V. Neville-Neil.Fn getnameinfo 2406617cf57SGeorge V. Neville-Neilinto believing that 2416617cf57SGeorge V. Neville-Neil.Fa sa 2426617cf57SGeorge V. Neville-Neilis 2436617cf57SGeorge V. Neville-Neil.Li 10.1.1.1 2446617cf57SGeorge V. Neville-Neilwhen it is actually 2456617cf57SGeorge V. Neville-Neil.Li 127.0.0.1 . 2466617cf57SGeorge V. Neville-Neil.Pp 2476617cf57SGeorge V. Neville-NeilTo prevent such attacks, the use of 2486617cf57SGeorge V. Neville-Neil.Dv NI_NAMEREQD 2496617cf57SGeorge V. Neville-Neilis recommended when the result of 2506617cf57SGeorge V. Neville-Neil.Fn getnameinfo 2516617cf57SGeorge V. Neville-Neilis used 2526617cf57SGeorge V. Neville-Neilfor access control purposes: 2536617cf57SGeorge V. Neville-Neil.Bd -literal -offset indent 2546617cf57SGeorge V. Neville-Neilstruct sockaddr *sa; 2556617cf57SGeorge V. Neville-Neilsocklen_t salen; 2566617cf57SGeorge V. Neville-Neilchar addr[NI_MAXHOST]; 2576617cf57SGeorge V. Neville-Neilstruct addrinfo hints, *res; 2586617cf57SGeorge V. Neville-Neilint error; 2596617cf57SGeorge V. Neville-Neil 2606617cf57SGeorge V. Neville-Neilerror = getnameinfo(sa, salen, addr, sizeof(addr), 2616617cf57SGeorge V. Neville-Neil NULL, 0, NI_NAMEREQD); 2626617cf57SGeorge V. Neville-Neilif (error == 0) { 2636617cf57SGeorge V. Neville-Neil memset(&hints, 0, sizeof(hints)); 2646617cf57SGeorge V. Neville-Neil hints.ai_socktype = SOCK_DGRAM; /*dummy*/ 2656617cf57SGeorge V. Neville-Neil hints.ai_flags = AI_NUMERICHOST; 2666617cf57SGeorge V. Neville-Neil if (getaddrinfo(addr, "0", &hints, &res) == 0) { 2676617cf57SGeorge V. Neville-Neil /* malicious PTR record */ 2686617cf57SGeorge V. Neville-Neil freeaddrinfo(res); 2696617cf57SGeorge V. Neville-Neil printf("bogus PTR record\en"); 2706617cf57SGeorge V. Neville-Neil return -1; 2716617cf57SGeorge V. Neville-Neil } 2726617cf57SGeorge V. Neville-Neil /* addr is FQDN as a result of PTR lookup */ 2736617cf57SGeorge V. Neville-Neil} else { 2746617cf57SGeorge V. Neville-Neil /* addr is numeric string */ 2756617cf57SGeorge V. Neville-Neil error = getnameinfo(sa, salen, addr, sizeof(addr), 2766617cf57SGeorge V. Neville-Neil NULL, 0, NI_NUMERICHOST); 2776617cf57SGeorge V. Neville-Neil} 2786617cf57SGeorge V. Neville-Neil.Ed 2796617cf57SGeorge V. Neville-Neil.\".Pp 2806617cf57SGeorge V. Neville-Neil.\".Ox 2816617cf57SGeorge V. Neville-Neil.\"intentionally uses a different 2826617cf57SGeorge V. Neville-Neil.\".Dv NI_MAXHOST 2836617cf57SGeorge V. Neville-Neil.\"value from what 2846617cf57SGeorge V. Neville-Neil.\".Tn "RFC 2553" 2856617cf57SGeorge V. Neville-Neil.\"suggests, to avoid buffer length handling mistakes. 286