1.\" $FreeBSD: src/lib/libc/net/getnameinfo.3,v 1.2.2.8 2001/12/14 18:33:55 ru Exp $ 2.\" $KAME: getnameinfo.3,v 1.17 2000/08/09 21:16:17 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 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.In sys/types.h 49.In sys/socket.h 50.In 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 implements similar functionality with 62.Xr gethostbyaddr 3 63and 64.Xr getservbyport 3 65in more sophisticated manner. 66.Pp 67This function looks up an IP address and port number provided by the 68caller in the DNS and system-specific database, and returns text 69strings for both in buffers provided by the caller. 70The function indicates successful completion by a zero return value; 71a non-zero return value indicates failure. 72.Pp 73The first argument, 74.Fa sa , 75points to either a 76.Li sockaddr_in 77structure (for IPv4) or a 78.Li sockaddr_in6 79structure (for IPv6) that holds the IP address and port number. 80The 81.Fa salen 82argument gives the length of the 83.Li sockaddr_in 84or 85.Li sockaddr_in6 86structure. 87.Pp 88The function returns the nodename associated with the IP address in 89the buffer pointed to by the 90.Fa host 91argument. 92The caller provides the size of this buffer via the 93.Fa hostlen 94argument. 95The service name associated with the port number is returned in the buffer 96pointed to by 97.Fa serv , 98and the 99.Fa servlen 100argument gives the length of this buffer. 101The caller specifies not to return either string by providing a zero 102value for the 103.Fa hostlen 104or 105.Fa servlen 106arguments. 107Otherwise, the caller must provide buffers large enough to hold the 108nodename and the service name, including the terminating null characters. 109.Pp 110Unfortunately most systems do not provide constants that specify the 111maximum size of either a fully-qualified domain name or a service name. 112Therefore to aid the application in allocating buffers for these two 113returned strings the following constants are defined in 114.Aq Pa netdb.h : 115.Bd -literal -offset 116#define NI_MAXHOST 1025 117#define NI_MAXSERV 32 118.Ed 119.Pp 120The first value is actually defined as the constant 121.Dv MAXDNAME 122in recent versions of BIND's 123.Aq Pa arpa/nameser.h 124header 125(older versions of BIND define this constant to be 256) 126and the second is a guess based on the services listed in the current 127Assigned Numbers RFC. 128.Pp 129The final argument is a 130.Fa flag 131that changes the default actions of this function. 132By default the fully-qualified domain name (FQDN) for the host is 133looked up in the DNS and returned. 134If the flag bit 135.Dv NI_NOFQDN 136is set, only the nodename portion of the FQDN is returned for local hosts. 137.Pp 138If the 139.Fa flag 140bit 141.Dv NI_NUMERICHOST 142is set, or if the host's name cannot be located in the DNS, 143the numeric form of the host's address is returned instead of its name 144(e.g., by calling 145.Fn inet_ntop 146instead of 147.Fn getnodebyaddr ) . 148If the 149.Fa flag 150bit 151.Dv NI_NAMEREQD 152is set, an error is returned if the host's name cannot be located in the DNS. 153.Pp 154If the flag bit 155.Dv NI_NUMERICSERV 156is set, the numeric form of the service address is returned 157(e.g., its port number) 158instead of its name. 159The two 160.Dv NI_NUMERICxxx 161flags are required to support the 162.Fl n 163flag that many commands provide. 164.Pp 165A fifth flag bit, 166.Dv NI_DGRAM , 167specifies that the service is a datagram service, and causes 168.Fn getservbyport 169to be called with a second argument of 170.Dq udp 171instead of its default of 172.Dq tcp . 173This is required for the few ports (512-514) 174that have different services for UDP and TCP. 175.Pp 176These 177.Dv NI_xxx 178flags are defined in 179.Aq Pa netdb.h . 180.\" 181.Sh EXTENSION 182The implementation allows experimental numeric IPv6 address notation with 183scope identifier. 184IPv6 link-local address will appear as string like 185.Dq Li fe80::1%ne0 , 186if 187.Dv NI_WITHSCOPEID 188bit is enabled in 189.Ar flags 190argument. 191Refer to 192.Xr getaddrinfo 3 193for the notation. 194.\" 195.Sh EXAMPLES 196The following code tries to get numeric hostname, and service name, 197for given socket address. 198Observe that there is no hardcoded reference to particular address family. 199.Bd -literal -offset indent 200struct sockaddr *sa; /* input */ 201char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; 202 203if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, 204 sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { 205 errx(1, "could not get numeric hostname"); 206 /*NOTREACHED*/ 207} 208printf("host=%s, serv=%s\\n", hbuf, sbuf); 209.Ed 210.Pp 211The following version checks if the socket address has reverse address mapping. 212.Bd -literal -offset indent 213struct sockaddr *sa; /* input */ 214char hbuf[NI_MAXHOST]; 215 216if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, 217 NI_NAMEREQD)) { 218 errx(1, "could not resolve hostname"); 219 /*NOTREACHED*/ 220} 221printf("host=%s\\n", hbuf); 222.Ed 223.\" 224.Sh FILES 225.Bl -tag -width /etc/resolv.conf -compact 226.It Pa /etc/hosts 227.It Pa /etc/host.conf 228.It Pa /etc/resolv.conf 229.El 230.\" 231.Sh DIAGNOSTICS 232The function indicates successful completion by a zero return value; 233a non-zero return value indicates failure. 234Error codes are as below: 235.Bl -tag -width Er 236.It Bq Er EAI_AGAIN 237The name could not be resolved at this time. 238Future attempts may succeed. 239.It Bq Er EAI_BADFLAGS 240The flags had an invalid value. 241.It Bq Er EAI_FAIL 242A non-recoverable error occurred. 243.It Bq Er EAI_FAMILY 244The address family was not recognized or the address length was invalid 245for the specified family. 246.It Bq Er EAI_MEMORY 247There was a memory allocation failure. 248.It Bq Er EAI_NONAME 249The name does not resolve for the supplied parameters. 250.Dv NI_NAMEREQD 251is set and the host's name cannot be located, 252or both nodename and servname were null. 253.It Bq Er EAI_SYSTEM 254A system error occurred. 255The error code can be found in errno. 256.El 257.\" 258.Sh SEE ALSO 259.Xr getaddrinfo 3 , 260.Xr gethostbyaddr 3 , 261.Xr getservbyport 3 , 262.Xr hosts 5 , 263.Xr services 5 , 264.Xr hostname 7 , 265.Xr named 8 266.Pp 267.Rs 268.%A R. Gilligan 269.%A S. Thomson 270.%A J. Bound 271.%A W. Stevens 272.%T Basic Socket Interface Extensions for IPv6 273.%R RFC2553 274.%D March 1999 275.Re 276.Rs 277.%A Tatsuya Jinmei 278.%A Atsushi Onoe 279.%T "An Extension of Format for IPv6 Scoped Addresses" 280.%R internet draft 281.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 282.%O work in progress material 283.Re 284.Rs 285.%A Craig Metz 286.%T Protocol Independence Using the Sockets API 287.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" 288.%D June 2000 289.Re 290.\" 291.Sh HISTORY 292The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. 293.\" 294.Sh STANDARDS 295The 296.Fn getaddrinfo 297function is defined in 298.St -p1003.1g-2000 , 299and documented in 300.Dq Basic Socket Interface Extensions for IPv6 301(RFC2553). 302.\" 303.Sh BUGS 304The current implementation is not thread-safe. 305.Pp 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