1.\" Copyright (c) 1983, 1987, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 33.\" KAME Id: getnameinfo.3,v 1.4 1999/12/10 04:04:31 itojun Exp 34.\" 35.Dd May 25, 1995 36.Dt GETNAMEINFO 3 37.Os KAME 38.\" 39.Sh NAME 40.Nm getnameinfo 41.Nd address-to-nodename translation in protocol-independent manner 42.\" 43.Sh LIBRARY 44.Lb libc 45.\" 46.Sh SYNOPSIS 47.Fd #include <sys/socket.h> 48.Fd #include <netdb.h> 49.Ft int 50.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \ 51"char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags" 52.\" 53.Sh DESCRIPTION 54The 55.Fn getnameinfo 56function is defined for protocol-independent address-to-nodename translation. 57Its functionality is a reverse conversion of 58.Xr getaddrinfo 3 , 59and implements similar functionality with 60.Xr gethostbyaddr 3 and 61.Xr getservbyport 3 62in more sophisticated manner. 63.Pp 64This function looks up an IP address and port number provided by the 65caller in the DNS and system-specific database, and returns text 66strings for both in buffers provided by the caller. 67The function indicates successful completion by a zero return value; 68a non-zero return value indicates failure. 69.Pp 70The first argument, 71.Fa sa , 72points to either a 73.Li sockaddr_in 74structure (for IPv4) or a 75.Li sockaddr_in6 76structure (for IPv6) that holds the IP address and port number. 77The 78.Fa salen 79argument gives the length of the 80.Li sockaddr_in 81or 82.Li sockaddr_in6 83structure. 84.Pp 85The function returns the nodename associated with the IP address in 86the buffer pointed to by the 87.Fa host 88argument. 89The caller provides the size of this buffer via the 90.Fa hostlen 91argument. 92The service name associated with the port number is returned in the buffer 93pointed to by 94.Fa serv , 95and the 96.Fa servlen 97argument gives the length of this buffer. 98The caller specifies not to return either string by providing a zero 99value for the 100.Fa hostlen 101or 102.Fa servlen 103arguments. 104Otherwise, the caller must provide buffers large enough to hold the 105nodename and the service name, including the terminating null characters. 106.Pp 107Unfortunately most systems do not provide constants that specify the 108maximum size of either a fully-qualified domain name or a service name. 109Therefore to aid the application in allocating buffers for these two 110returned strings the following constants are defined in 111.Aq Pa netdb.h : 112.Bd -literal -offset 113#define NI_MAXHOST 1025 114#define NI_MAXSERV 32 115.Ed 116.Pp 117The first value is actually defined as the constant 118.Dv MAXDNAME 119in recent versions of BIND's 120.Aq Pa arpa/nameser.h 121header 122.Po 123older versions of BIND define this constant to be 256 124.Pc 125and the second is a guess based on the services listed in the current 126Assigned Numbers RFC. 127.Pp 128The final argument is a 129.Fa flag 130that changes the default actions of this function. 131By default the fully-qualified domain name (FQDN) for the host is 132looked up in the DNS and returned. 133If the flag bit 134.Dv NI_NOFQDN 135is set, only the nodename portion of the FQDN is returned for local hosts. 136.Pp 137If the 138.Fa flag 139bit 140.Dv NI_NUMERICHOST 141is set, or if the host's name cannot be located in the DNS, 142the numeric form of the host's address is returned instead of its name 143.Po 144e.g., by calling 145.Fn inet_ntop 146instead of 147.Fn getnodebyaddr 148.Pc . 149If the 150.Fa flag 151bit 152.Dv NI_NAMEREQD 153is set, an error is returned if the host's name cannot be located in the DNS. 154.Pp 155If the flag bit 156.Dv NI_NUMERICSERV 157is set, the numeric form of the service address is returned 158.Pq e.g., its port number 159instead of its name. 160The two 161.Dv NI_NUMERICxxx 162flags are required to support the 163.Fl n 164flag that many commands provide. 165.Pp 166A fifth flag bit, 167.Dv NI_DGRAM , 168specifies that the service is a datagram service, and causes 169.Fn getservbyport 170to be called with a second argument of 171.Dq udp 172instead of its default of 173.Dq tcp . 174This is required for the few ports (512-514) 175that have different services for UDP and TCP. 176.Pp 177These 178.Dv NI_xxx 179flags are defined in 180.Aq Pa netdb.h . 181.\" 182.Sh EXTENSION 183The implementation allows experimental numeric IPv6 address notation with 184scope identifier. 185IPv6 link-local address will appear as string like 186.Dq Li fe80::1@ne0 , 187if 188.Dv NI_WITHSCOPEID 189bit is enabled in 190.Ar flags 191argument. 192Refer to 193.Xr getaddrinfo 3 194for the notation. 195.\" 196.Sh FILES 197.Bl -tag -width /etc/resolv.conf -compact 198.It Pa /etc/hosts 199.It Pa /etc/host.conf 200.It Pa /etc/resolv.conf 201.El 202.\" 203.Sh DIAGNOSTICS 204The function indicates successful completion by a zero return value; 205a non-zero return value indicates failure. 206.\" 207.Sh SEE ALSO 208.Xr getaddrinfo 3 , 209.Xr gethostbyaddr 3 , 210.Xr getservbyport 3 , 211.Xr hosts 5 , 212.Xr services 5 , 213.Xr hostname 7 , 214.Xr named 8 215.Pp 216.Rs 217.%A R. Gilligan 218.%A S. Thomson 219.%A J. Bound 220.%A W. Stevens 221.%T Basic Socket Interface Extensions for IPv6 222.%R RFC2553 223.%D March 1999 224.Re 225.\" 226.Sh HISTORY 227The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. 228.\" 229.Sh STANDARDS 230The 231.Fn getaddrinfo 232function is defined IEEE POSIX 1003.1g draft specification, 233and documented in 234.Dq Basic Socket Interface Extensions for IPv6 235.Pq RFC2533 . 236.\" 237.Sh BUGS 238The text was shamelessly copied from RFC2553. 239