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