diff options
Diffstat (limited to 'man3/getnameinfo.3')
| -rw-r--r-- | man3/getnameinfo.3 | 345 |
1 files changed, 0 insertions, 345 deletions
diff --git a/man3/getnameinfo.3 b/man3/getnameinfo.3 deleted file mode 100644 index 16c202fc4..000000000 --- a/man3/getnameinfo.3 +++ /dev/null @@ -1,345 +0,0 @@ -'\" t -.\" %%%LICENSE_START(PUBLIC_DOMAIN) -.\" This page is in the public domain. -.\" %%%LICENSE_END -.\" -.\" Almost all details are from RFC 2553. -.\" -.\" 2004-12-14, mtk, Added EAI_OVERFLOW error -.\" 2004-12-14 Fixed description of error return -.\" -.TH getnameinfo 3 (date) "Linux man-pages (unreleased)" -.SH NAME -getnameinfo \- address-to-name translation in protocol-independent manner -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <sys/socket.h> -.B #include <netdb.h> -.P -.BI "int getnameinfo(const struct sockaddr *restrict " addr \ -", socklen_t " addrlen , -.BI " char " host "[_Nullable restrict ." hostlen ], -.BI " socklen_t " hostlen , -.BI " char " serv "[_Nullable restrict ." servlen ], -.BI " socklen_t " servlen , -.BI " int " flags ); -.fi -.P -.RS -4 -Feature Test Macro Requirements for glibc (see -.BR feature_test_macros (7)): -.RE -.P -.BR getnameinfo (): -.nf - Since glibc 2.22: - _POSIX_C_SOURCE >= 200112L - glibc 2.21 and earlier: - _POSIX_C_SOURCE -.fi -.SH DESCRIPTION -The -.BR getnameinfo () -function is the inverse of -.BR getaddrinfo (3): -it converts a socket address to a corresponding host and service, -in a protocol-independent manner. -It combines the functionality of -.BR gethostbyaddr (3) -and -.BR getservbyport (3), -but unlike those functions, -.BR getnameinfo () -is reentrant and allows programs to eliminate -IPv4-versus-IPv6 dependencies. -.P -The -.I addr -argument is a pointer to a generic socket address structure -(of type -.I sockaddr_in -or -.IR sockaddr_in6 ) -of size -.I addrlen -that holds the input IP address and port number. -The arguments -.I host -and -.I serv -are pointers to caller-allocated buffers (of size -.I hostlen -and -.I servlen -respectively) into which -.BR getnameinfo () -places null-terminated strings containing the host and -service names respectively. -.P -The caller can specify that no hostname (or no service name) -is required by providing a NULL -.I host -(or -.IR serv ) -argument or a zero -.I hostlen -(or -.IR servlen ) -argument. -However, at least one of hostname or service name -must be requested. -.P -The -.I flags -argument modifies the behavior of -.BR getnameinfo () -as follows: -.TP -.B NI_NAMEREQD -If set, then an error is returned if the hostname cannot be determined. -.TP -.B NI_DGRAM -If set, then the service is datagram (UDP) based rather than -stream (TCP) based. -This is required for the few ports (512\[en]514) -that have different services for UDP and TCP. -.TP -.B NI_NOFQDN -If set, return only the hostname part of the fully qualified domain name -for local hosts. -.TP -.B NI_NUMERICHOST -If set, then the numeric form of the hostname is returned. -.\" For example, by calling -.\" .BR inet_ntop () -.\" instead of -.\" .BR gethostbyaddr (). -(When not set, this will still happen in case the node's name -cannot be determined.) -.\" POSIX.1-2001 TC1 has NI_NUMERICSCOPE, but glibc doesn't have it. -.TP -.B NI_NUMERICSERV -If set, then the numeric form of the service address is returned. -(When not set, this will still happen in case the service's name -cannot be determined.) -.SS Extensions to getnameinfo() for Internationalized Domain Names -Starting with glibc 2.3.4, -.BR getnameinfo () -has been extended to selectively allow -hostnames to be transparently converted to and from the -Internationalized Domain Name (IDN) format (see RFC 3490, -.IR "Internationalizing Domain Names in Applications (IDNA)" ). -Three new flags are defined: -.TP -.B NI_IDN -If this flag is used, then the name found in the lookup process is -converted from IDN format to the locale's encoding if necessary. -ASCII-only names are not affected by the conversion, which -makes this flag usable in existing programs and environments. -.TP -.B NI_IDN_ALLOW_UNASSIGNED -.TQ -.B NI_IDN_USE_STD3_ASCII_RULES -Setting these flags will enable the -IDNA_ALLOW_UNASSIGNED (allow unassigned Unicode code points) and -IDNA_USE_STD3_ASCII_RULES (check output to make sure it is a STD3 -conforming hostname) -flags respectively to be used in the IDNA handling. -.SH RETURN VALUE -.\" FIXME glibc defines the following additional errors, some which -.\" can probably be returned by getnameinfo(); they need to -.\" be documented. -.\" -.\" #ifdef __USE_GNU -.\" #define EAI_INPROGRESS -100 /* Processing request in progress. */ -.\" #define EAI_CANCELED -101 /* Request canceled. */ -.\" #define EAI_NOTCANCELED -102 /* Request not canceled. */ -.\" #define EAI_ALLDONE -103 /* All requests done. */ -.\" #define EAI_INTR -104 /* Interrupted by a signal. */ -.\" #define EAI_IDN_ENCODE -105 /* IDN encoding failed. */ -.\" #endif -On success, 0 is returned, and node and service names, if requested, -are filled with null-terminated strings, possibly truncated to fit -the specified buffer lengths. -On error, one of the following nonzero error codes is returned: -.TP -.B EAI_AGAIN -The name could not be resolved at this time. -Try again later. -.TP -.B EAI_BADFLAGS -The -.I flags -argument has an invalid value. -.TP -.B EAI_FAIL -A nonrecoverable error occurred. -.TP -.B EAI_FAMILY -The address family was not recognized, -or the address length was invalid for the specified family. -.TP -.B EAI_MEMORY -Out of memory. -.TP -.B EAI_NONAME -The name does not resolve for the supplied arguments. -.B NI_NAMEREQD -is set and the host's name cannot be located, -or neither hostname nor service name were requested. -.TP -.B EAI_OVERFLOW -The buffer pointed to by -.I host -or -.I serv -was too small. -.TP -.B EAI_SYSTEM -A system error occurred. -The error code can be found in -.IR errno . -.P -The -.BR gai_strerror (3) -function translates these error codes to a human readable string, -suitable for error reporting. -.SH FILES -.I /etc/hosts -.br -.I /etc/nsswitch.conf -.br -.I /etc/resolv.conf -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.TS -allbox; -lbx lb lb -l l l. -Interface Attribute Value -T{ -.na -.nh -.BR getnameinfo () -T} Thread safety MT-Safe env locale -.TE -.SH STANDARDS -POSIX.1-2008. -RFC\ 2553. -.SH HISTORY -glibc 2.1. -POSIX.1-2001. -.P -Before glibc 2.2, the -.I hostlen -and -.I servlen -arguments were typed as -.IR size_t . -.SH NOTES -In order to assist the programmer in choosing reasonable sizes -for the supplied buffers, -.I <netdb.h> -defines the constants -.P -.in +4n -.EX -#define NI_MAXHOST 1025 -#define NI_MAXSERV 32 -.EE -.in -.P -Since glibc 2.8, -these definitions are exposed only if suitable -feature test macros are defined, namely: -.BR _GNU_SOURCE , -.B _DEFAULT_SOURCE -(since glibc 2.19), -or (in glibc versions up to and including 2.19) -.B _BSD_SOURCE -or -.BR _SVID_SOURCE . -.P -The former is the constant -.B MAXDNAME -in recent versions of BIND's -.I <arpa/nameser.h> -header file. -The latter is a guess based on the services listed -in the current Assigned Numbers RFC. -.SH EXAMPLES -The following code tries to get the numeric hostname and service name, -for a given socket address. -Note that there is no hardcoded reference to -a particular address family. -.P -.in +4n -.EX -struct sockaddr *addr; /* input */ -socklen_t addrlen; /* input */ -char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; -\& -if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), sbuf, - sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0) - printf("host=%s, serv=%s\en", hbuf, sbuf); -.EE -.in -.P -The following version checks if the socket address has a -reverse address mapping. -.P -.in +4n -.EX -struct sockaddr *addr; /* input */ -socklen_t addrlen; /* input */ -char hbuf[NI_MAXHOST]; -\& -if (getnameinfo(addr, addrlen, hbuf, sizeof(hbuf), - NULL, 0, NI_NAMEREQD)) - printf("could not resolve hostname"); -else - printf("host=%s\en", hbuf); -.EE -.in -.P -An example program using -.BR getnameinfo () -can be found in -.BR getaddrinfo (3). -.SH SEE ALSO -.BR accept (2), -.BR getpeername (2), -.BR getsockname (2), -.BR recvfrom (2), -.BR socket (2), -.BR getaddrinfo (3), -.BR gethostbyaddr (3), -.BR getservbyname (3), -.BR getservbyport (3), -.BR inet_ntop (3), -.BR hosts (5), -.BR services (5), -.BR hostname (7), -.BR named (8) -.P -R.\& Gilligan, S.\& Thomson, J.\& Bound and W.\& Stevens, -.IR "Basic Socket Interface Extensions for IPv6" , -RFC\ 2553, March 1999. -.P -Tatsuya Jinmei and Atsushi Onoe, -.IR "An Extension of Format for IPv6 Scoped Addresses" , -internet draft, work in progress -.UR ftp://ftp.ietf.org\:/internet\-drafts\:/draft\-ietf\-ipngwg\-scopedaddr\-format\-02.txt -.UE . -.P -Craig Metz, -.IR "Protocol Independence Using the Sockets API" , -Proceedings of the freenix track: -2000 USENIX annual technical conference, June 2000 -.ad l -.UR http://www.usenix.org\:/publications\:/library\:/proceedings\:/usenix2000\:/freenix\:/metzprotocol.html -.UE . |