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