Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 344 insertions, 0 deletions

diff --git a/man3/getnameinfo.3 b/man3/getnameinfo.3
new file mode 100644
index 0000000..580a265
--- /dev/null
+++ b/man3/getnameinfo.3
@@ -0,0 +1,344 @@
+'\" 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 2023-07-20 "Linux man-pages 6.05.01"
+.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>
+.PP
+.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
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.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.
+.PP
+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.
+.PP
+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.
+.PP
+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
+.BR NI_IDN_ALLOW_UNASSIGNED ", " 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 .
+.PP
+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
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+RFC\ 2553.
+.SH HISTORY
+glibc 2.1.
+POSIX.1-2001.
+.PP
+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
+.PP
+.in +4n
+.EX
+#define NI_MAXHOST      1025
+#define NI_MAXSERV      32
+.EE
+.in
+.PP
+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 .
+.PP
+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.
+.PP
+.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
+.PP
+The following version checks if the socket address has a
+reverse address mapping.
+.PP
+.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
+.PP
+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)
+.PP
+R.\& Gilligan, S.\& Thomson, J.\& Bound and W.\& Stevens,
+.IR "Basic Socket Interface Extensions for IPv6" ,
+RFC\ 2553, March 1999.
+.PP
+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 .
+.PP
+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 .