diff options
Diffstat (limited to 'newlib/libc/sys/linux/net/getnameinfo.3')
| -rw-r--r-- | newlib/libc/sys/linux/net/getnameinfo.3 | 311 |
1 files changed, 0 insertions, 311 deletions
diff --git a/newlib/libc/sys/linux/net/getnameinfo.3 b/newlib/libc/sys/linux/net/getnameinfo.3 deleted file mode 100644 index d7afa2f40..000000000 --- a/newlib/libc/sys/linux/net/getnameinfo.3 +++ /dev/null @@ -1,311 +0,0 @@ -.\" $FreeBSD: src/lib/libc/net/getnameinfo.3,v 1.11 2001/10/01 16:08:55 ru Exp $ -.\" $KAME: getnameinfo.3,v 1.17 2000/08/09 21:16:17 itojun Exp $ -.\" -.\" Copyright (c) 1983, 1987, 1991, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 -.\" -.Dd May 25, 1995 -.Dt GETNAMEINFO 3 -.Os -.\" -.Sh NAME -.Nm getnameinfo -.Nd address-to-nodename translation in protocol-independent manner -.\" -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In sys/types.h -.In sys/socket.h -.In netdb.h -.Ft int -.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \ -"char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags" -.\" -.Sh DESCRIPTION -The -.Fn getnameinfo -function is defined for protocol-independent address-to-nodename translation. -Its functionality is a reverse conversion of -.Xr getaddrinfo 3 , -and implements similar functionality with -.Xr gethostbyaddr 3 -and -.Xr getservbyport 3 -in more sophisticated manner. -.Pp -This function looks up an IP address and port number provided by the -caller in the DNS and system-specific database, and returns text -strings for both in buffers provided by the caller. -The function indicates successful completion by a zero return value; -a non-zero return value indicates failure. -.Pp -The first argument, -.Fa sa , -points to either a -.Li sockaddr_in -structure (for IPv4) or a -.Li sockaddr_in6 -structure (for IPv6) that holds the IP address and port number. -The -.Fa salen -argument gives the length of the -.Li sockaddr_in -or -.Li sockaddr_in6 -structure. -.Pp -The function returns the nodename associated with the IP address in -the buffer pointed to by the -.Fa host -argument. -The caller provides the size of this buffer via the -.Fa hostlen -argument. -The service name associated with the port number is returned in the buffer -pointed to by -.Fa serv , -and the -.Fa servlen -argument gives the length of this buffer. -The caller specifies not to return either string by providing a zero -value for the -.Fa hostlen -or -.Fa servlen -arguments. -Otherwise, the caller must provide buffers large enough to hold the -nodename and the service name, including the terminating null characters. -.Pp -Unfortunately most systems do not provide constants that specify the -maximum size of either a fully-qualified domain name or a service name. -Therefore to aid the application in allocating buffers for these two -returned strings the following constants are defined in -.Aq Pa netdb.h : -.Bd -literal -offset -#define NI_MAXHOST 1025 -#define NI_MAXSERV 32 -.Ed -.Pp -The first value is actually defined as the constant -.Dv MAXDNAME -in recent versions of BIND's -.Aq Pa arpa/nameser.h -header -(older versions of BIND define this constant to be 256) -and the second is a guess based on the services listed in the current -Assigned Numbers RFC. -.Pp -The final argument is a -.Fa flag -that changes the default actions of this function. -By default the fully-qualified domain name (FQDN) for the host is -looked up in the DNS and returned. -If the flag bit -.Dv NI_NOFQDN -is set, only the nodename portion of the FQDN is returned for local hosts. -.Pp -If the -.Fa flag -bit -.Dv NI_NUMERICHOST -is set, or if the host's name cannot be located in the DNS, -the numeric form of the host's address is returned instead of its name -(e.g., by calling -.Fn inet_ntop -instead of -.Fn getnodebyaddr ) . -If the -.Fa flag -bit -.Dv NI_NAMEREQD -is set, an error is returned if the host's name cannot be located in the DNS. -.Pp -If the flag bit -.Dv NI_NUMERICSERV -is set, the numeric form of the service address is returned -(e.g., its port number) -instead of its name. -The two -.Dv NI_NUMERICxxx -flags are required to support the -.Fl n -flag that many commands provide. -.Pp -A fifth flag bit, -.Dv NI_DGRAM , -specifies that the service is a datagram service, and causes -.Fn getservbyport -to be called with a second argument of -.Dq udp -instead of its default of -.Dq tcp . -This is required for the few ports (512-514) -that have different services for UDP and TCP. -.Pp -These -.Dv NI_xxx -flags are defined in -.Aq Pa netdb.h . -.\" -.Sh EXTENSION -The implementation allows experimental numeric IPv6 address notation with -scope identifier. -IPv6 link-local address will appear as string like -.Dq Li fe80::1%ne0 , -if -.Dv NI_WITHSCOPEID -bit is enabled in -.Ar flags -argument. -Refer to -.Xr getaddrinfo 3 -for the notation. -.\" -.Sh EXAMPLES -The following code tries to get numeric hostname, and service name, -for given socket address. -Observe that there is no hardcoded reference to particular address family. -.Bd -literal -offset indent -struct sockaddr *sa; /* input */ -char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; - -if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, - sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { - errx(1, "could not get numeric hostname"); - /*NOTREACHED*/ -} -printf("host=%s, serv=%s\\n", hbuf, sbuf); -.Ed -.Pp -The following version checks if the socket address has reverse address mapping. -.Bd -literal -offset indent -struct sockaddr *sa; /* input */ -char hbuf[NI_MAXHOST]; - -if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, - NI_NAMEREQD)) { - errx(1, "could not resolve hostname"); - /*NOTREACHED*/ -} -printf("host=%s\\n", hbuf); -.Ed -.\" -.Sh FILES -.Bl -tag -width /etc/nsswitch.conf -compact -.It Pa /etc/hosts -.It Pa /etc/nsswitch.conf -.It Pa /etc/resolv.conf -.El -.\" -.Sh DIAGNOSTICS -The function indicates successful completion by a zero return value; -a non-zero return value indicates failure. -Error codes are as below: -.Bl -tag -width Er -.It Bq Er EAI_AGAIN -The name could not be resolved at this time. -Future attempts may succeed. -.It Bq Er EAI_BADFLAGS -The flags had an invalid value. -.It Bq Er EAI_FAIL -A non-recoverable error occurred. -.It Bq Er EAI_FAMILY -The address family was not recognized or the address length was invalid -for the specified family. -.It Bq Er EAI_MEMORY -There was a memory allocation failure. -.It Bq Er EAI_NONAME -The name does not resolve for the supplied parameters. -.Dv NI_NAMEREQD -is set and the host's name cannot be located, -or both nodename and servname were null. -.It Bq Er EAI_SYSTEM -A system error occurred. -The error code can be found in errno. -.El -.\" -.Sh SEE ALSO -.Xr getaddrinfo 3 , -.Xr gethostbyaddr 3 , -.Xr getservbyport 3 , -.Xr hosts 5 , -.Xr services 5 , -.Xr hostname 7 , -.Xr named 8 -.Pp -.Rs -.%A R. Gilligan -.%A S. Thomson -.%A J. Bound -.%A W. Stevens -.%T Basic Socket Interface Extensions for IPv6 -.%R RFC2553 -.%D March 1999 -.Re -.Rs -.%A Tatsuya Jinmei -.%A Atsushi Onoe -.%T "An Extension of Format for IPv6 Scoped Addresses" -.%R internet draft -.%N draft-ietf-ipngwg-scopedaddr-format-02.txt -.%O work in progress material -.Re -.Rs -.%A Craig Metz -.%T Protocol Independence Using the Sockets API -.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" -.%D June 2000 -.Re -.\" -.Sh HISTORY -The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit. -.\" -.Sh STANDARDS -The -.Fn getaddrinfo -function is defined in -.St -p1003.1g-2000 , -and documented in -.Dq Basic Socket Interface Extensions for IPv6 -(RFC2553). -.\" -.Sh BUGS -The current implementation is not thread-safe. -.Pp -The text was shamelessly copied from RFC2553. -.Pp -The type of the 2nd argument should be -.Li socklen_t -for RFC2553 conformance. -The current code is based on pre-RFC2553 specification. |