1.\" $FreeBSD$ 2.\" $KAME: getnameinfo.3,v 1.16 2000/07/05 08:22:04 itojun Exp $ 3.\" 4.\" Copyright (c) 1983, 1987, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 36.\" 37.Dd May 25, 1995 38.Dt GETNAMEINFO 3 39.Os KAME 40.\" 41.Sh NAME 42.Nm getnameinfo 43.Nd address-to-nodename translation in protocol-independent manner 44.\" 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.Fd #include <sys/types.h> 49.Fd #include <sys/socket.h> 50.Fd #include <netdb.h> 51.Ft int 52.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \ 53"char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags" 54.\" 55.Sh DESCRIPTION 56The 57.Fn getnameinfo 58function is defined for protocol-independent address-to-nodename translation. 59Its functionality is a reverse conversion of 60.Xr getaddrinfo 3 61and is similar to that of 62.Xr gethostbyaddr 3 63and 64.Xr getservbyport 3 . 65.Pp 66This function looks up an IP address and port number provided by the 67caller in the DNS and system-specific database and then returns text 68strings for both in buffers provided by the caller. 69The function indicates successful completion by a zero return value; 70a non-zero return value indicates failure. 71.Pp 72The first argument, 73.Fa sa , 74points to either a 75.Li sockaddr_in 76structure (for IPv4) or a 77.Li sockaddr_in6 78structure (for IPv6) that holds the IP address and port number. 79The 80.Fa salen 81argument gives the length of the 82.Li sockaddr_in 83or 84.Li sockaddr_in6 85structure. 86.Pp 87The function returns the nodename associated with the IP address in 88the buffer pointed to by the 89.Fa host 90argument. 91The caller provides the size of this buffer via the 92.Fa hostlen 93argument. 94The service name associated with the port number is returned in the buffer 95pointed to by 96.Fa serv , 97and the 98.Fa servlen 99argument gives the length of this buffer. 100The caller specifies not to return either string by providing a zero 101value for the 102.Fa hostlen 103or 104.Fa servlen 105arguments. 106Otherwise, the caller must provide buffers large enough to hold the 107nodename and the service name, including the terminating null characters. 108.Pp 109Unfortunately most systems do not provide constants that specify the 110maximum size of either a fully-qualified domain name or a service name. 111Therefore to aid the application in allocating buffers for these two 112returned strings the following constants are defined in 113.Aq Pa netdb.h : 114.Bd -literal -offset 115#define NI_MAXHOST 1025 116#define NI_MAXSERV 32 117.Ed 118.Pp 119The first value is actually defined as the constant 120.Dv MAXDNAME 121in recent versions of BIND's 122.Aq Pa arpa/nameser.h 123header 124.Po 125older versions of BIND define this constant to be 256 126.Pc 127and the second is a guess based on the services listed in the current 128Assigned Numbers RFC. 129.Pp 130The final argument is a 131.Fa flag 132that changes the default actions of this function. 133By default the fully-qualified domain name (FQDN) for the host is 134looked up in the DNS and returned. 135If the flag bit 136.Dv NI_NOFQDN 137is set, only the nodename portion of the FQDN is returned for local hosts. 138.Pp 139If the 140.Fa flag 141bit 142.Dv NI_NUMERICHOST 143is set, or if the host's name cannot be located in the DNS, 144the numeric form of the host's address is returned instead of its name 145.Po 146e.g., by calling 147.Fn inet_ntop 148instead of 149.Fn getnodebyaddr 150.Pc . 151If the 152.Fa flag 153bit 154.Dv NI_NAMEREQD 155is set, an error is returned if the host's name cannot be located in the DNS. 156.Pp 157If the flag bit 158.Dv NI_NUMERICSERV 159is set, the numeric form of the service address is returned 160.Pq e.g., its port number 161instead of its name. 162The two 163.Dv NI_NUMERICxxx 164flags are required to support the 165.Fl n 166flag that many commands provide. 167.Pp 168A fifth flag bit, 169.Dv NI_DGRAM , 170specifies that the service is a datagram service, and causes 171.Fn getservbyport 172to be called with a second argument of 173.Dq udp 174instead of its default of 175.Dq tcp . 176This is required for the few ports (512-514) 177that have different services for UDP and TCP. 178.Pp 179These 180.Dv NI_xxx 181flags are defined in 182.Aq Pa netdb.h . 183.\" 184.Sh EXTENSION 185The implementation allows experimental numeric IPv6 address notation with 186scope identifier. 187IPv6 link-local address will appear as string like 188.Dq Li fe80::1%ne0 , 189if 190.Dv NI_WITHSCOPEID 191bit is enabled in 192.Ar flags 193argument. 194Refer to 195.Xr getaddrinfo 3 196for the notation. 197.\" 198.Sh EXAMPLES 199The following code tries to get numeric hostname, and service name, 200for given socket address. 201Observe that there is no hardcoded reference to particular address family. 202.Bd -literal -offset indent 203struct sockaddr *sa; /* input */ 204char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; 205 206if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, 207 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { 208 errx(1, "could not get numeric hostname"); 209 /*NOTREACHED*/ 210} 211printf("host=%s, serv=%s\\n", hbuf, sbuf); 212.Ed 213.Pp 214The following version checks if the socket address has reverse address mapping. 215.Bd -literal -offset indent 216struct sockaddr *sa; /* input */ 217char hbuf[NI_MAXHOST]; 218 219if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, 220 NI_NAMEREQD)) { 221 errx(1, "could not resolve hostname"); 222 /*NOTREACHED*/ 223} 224printf("host=%s\\n", hbuf); 225.Ed 226.\" 227.Sh FILES 228.Bl -tag -width /etc/resolv.conf -compact 229.It Pa /etc/hosts 230.It Pa /etc/host.conf 231.It Pa /etc/resolv.conf 232.El 233.\" 234.Sh DIAGNOSTICS 235The function indicates successful completion by a zero return value; 236a non-zero return value indicates failure. 237Error codes are as below: 238.Bl -tag -width Er 239.It Bq Er EAI_AGAIN 240The name could not be resolved at this time. 241Future attempts may succeed. 242.It Bq Er EAI_BADFLAGS 243The flags had an invalid value. 244.It Bq Er EAI_FAIL 245A non-recoverable error occurred. 246.It Bq Er EAI_FAMILY 247The address family was not recognized or the address length was invalid 248for the specified family. 249.It Bq Er EAI_MEMORY 250There was a memory allocation failure. 251.It Bq Er EAI_NONAME 252The name does not resolve for the supplied parameters. 253.Dv NI_NAMEREQD 254is set and the host's name cannot be located, 255or both nodename and servname were null. 256.It Bq Er EAI_SYSTEM 257A system error occurred. 258The error code can be found in errno. 259.El 260.\" 261.Sh SEE ALSO 262.Xr getaddrinfo 3 , 263.Xr gethostbyaddr 3 , 264.Xr getservbyport 3 , 265.Xr hosts 5 , 266.Xr services 5 , 267.Xr hostname 7 , 268.Xr named 8 269.Pp 270.Rs 271.%A R. Gilligan 272.%A S. Thomson 273.%A J. Bound 274.%A W. Stevens 275.%T Basic Socket Interface Extensions for IPv6 276.%R RFC2553 277.%D March 1999 278.Re 279.Rs 280.%A Tatsuya Jinmei 281.%A Atsushi Onoe 282.%T "An Extension of Format for IPv6 Scoped Addresses" 283.%R internet draft 284.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 285.%O work in progress material 286.Re 287.Rs 288.%A Craig Metz 289.%T Protocol Independence Using the Sockets API 290.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 291.%D June 2000 292.Re 293.\" 294.Sh HISTORY 295The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. 296.\" 297.Sh STANDARDS 298The 299.Fn getaddrinfo 300function is defined IEEE POSIX 1003.1g draft specification, 301and documented in 302.Dq Basic Socket Interface Extensions for IPv6 303.Pq RFC2553 . 304.\" 305.Sh BUGS 306The text was shamelessly copied from RFC2553. 307.Pp 308The type of the 2nd argument should be 309.Li socklen_t 310for RFC2553 conformance. 311The current code is based on pre-RFC2553 specification. 312