Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 236 insertions, 0 deletions

diff --git a/upstream/archlinux/man3p/getnameinfo.3p b/upstream/archlinux/man3p/getnameinfo.3p
new file mode 100644
index 00000000..3415d4ae
--- /dev/null
+++ b/upstream/archlinux/man3p/getnameinfo.3p
@@ -0,0 +1,236 @@
+'\" et
+.TH GETNAMEINFO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+getnameinfo
+\(em get name information
+.SH SYNOPSIS
+.LP
+.nf
+#include <sys/socket.h>
+#include <netdb.h>
+.P
+int getnameinfo(const struct sockaddr *restrict \fIsa\fP, socklen_t \fIsalen\fP,
+    char *restrict \fInode\fP, socklen_t \fInodelen\fP, char *restrict \fIservice\fP,
+    socklen_t \fIservicelen\fP, int \fIflags\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIgetnameinfo\fR()
+function shall translate a socket address to a node name and service
+location, all of which are defined as in
+.IR "\fIfreeaddrinfo\fR\^(\|)".
+.P
+The
+.IR sa
+argument points to a socket address structure to be translated. The
+.IR salen
+argument contains the length of the address pointed to by
+.IR sa .
+.P
+If the socket address structure contains an IPv4-mapped IPv6 address or
+an IPv4-compatible IPv6 address, the implementation shall extract the
+embedded IPv4 address and lookup the node name for that IPv4 address.
+.P
+If the address is the IPv6 unspecified address (\c
+.BR \(dq::\(dq ),
+a lookup shall not be performed and the behavior shall be the same as
+when the node's name cannot be located.
+.P
+If the
+.IR node
+argument is non-NULL and the
+.IR nodelen
+argument is non-zero, then the
+.IR node
+argument points to a buffer able to contain up to
+.IR nodelen
+bytes that receives the node name as a null-terminated string. If the
+.IR node
+argument is NULL or the
+.IR nodelen
+argument is zero, the node name shall not be returned. If the node's
+name cannot be located, the numeric form of the address contained
+in the socket address structure pointed to by the
+.IR sa
+argument is returned instead of its name.
+.P
+If the
+.IR service
+argument is non-NULL and the
+.IR servicelen
+argument is non-zero, then the
+.IR service
+argument points to a buffer able to contain up to
+.IR servicelen
+bytes that receives the service name as a null-terminated string.
+If the
+.IR service
+argument is NULL or the
+.IR servicelen
+argument is zero, the service name shall not be returned. If the
+service's name cannot be located, the numeric form of the service
+address (for example, its port number) shall be returned instead of
+its name.
+.P
+The
+.IR flags
+argument is a flag that changes the default actions of the function. By
+default the fully-qualified domain name (FQDN) for the
+host shall be returned, but:
+.IP " *" 4
+If the flag bit NI_NOFQDN is set, only the node name portion of the
+FQDN shall be returned for local hosts.
+.IP " *" 4
+If the flag bit NI_NUMERICHOST is set, the numeric form of the address
+contained in the socket address structure pointed to by the
+.IR sa
+argument shall be returned instead of its name.
+.IP " *" 4
+If the flag bit NI_NAMEREQD is set, an error shall be returned if the
+host's name cannot be located.
+.IP " *" 4
+If the flag bit NI_NUMERICSERV is set, the numeric form of the service
+address shall be returned (for example, its port number) instead of its
+name.
+.IP " *" 4
+If the flag bit NI_NUMERICSCOPE is set, the numeric form of the scope
+identifier shall be returned (for example, interface index) instead of
+its name. This flag shall be ignored if the
+.IR sa
+argument is not an IPv6 address.
+.IP " *" 4
+If the flag bit NI_DGRAM is set, this indicates that the service is a
+datagram service (SOCK_DGRAM). The default behavior shall assume that
+the service is a stream service (SOCK_STREAM).
+.TP 10
+.BR Notes:
+.RS 10 
+.IP " 1." 4
+The two NI_NUMERICxxx flags are required to support the
+.BR \-n
+flag that many commands provide.
+.IP " 2." 4
+The NI_DGRAM flag is required for the few AF_INET and AF_INET6 port
+numbers (for example, [512,514]) that represent different services for
+UDP and TCP.
+.RE
+.P
+.P
+The
+\fIgetnameinfo\fR()
+function shall be thread-safe.
+.SH "RETURN VALUE"
+A zero return value for
+\fIgetnameinfo\fR()
+indicates successful completion; a non-zero return value indicates
+failure. The possible values for the failures are listed in the
+ERRORS section.
+.P
+Upon successful completion,
+\fIgetnameinfo\fR()
+shall return the
+.IR node
+and
+.IR service
+names, if requested, in the buffers provided. The returned names are
+always null-terminated strings.
+.SH ERRORS
+The
+\fIgetnameinfo\fR()
+function shall fail and return the corresponding value if:
+.IP [EAI_AGAIN] 12
+The name could not be resolved at this time. Future attempts may
+succeed.
+.IP [EAI_BADFLAGS] 12
+.br
+The
+.IR flags
+had an invalid value.
+.IP [EAI_FAIL] 12
+A non-recoverable error occurred.
+.IP [EAI_FAMILY] 12
+The address family was not recognized or the address length was invalid
+for the specified family.
+.IP [EAI_MEMORY] 12
+There was a memory allocation failure.
+.IP [EAI_NONAME] 12
+The name does not resolve for the supplied parameters.
+.RS 12 
+.P
+NI_NAMEREQD is set and the host's name cannot be located, or both
+.IR nodename
+and
+.IR servname
+were null.
+.RE
+.IP [EAI_OVERFLOW] 12
+.br
+An argument buffer overflowed. The buffer pointed to by the
+.IR node
+argument or the
+.IR service
+argument was too small.
+.IP [EAI_SYSTEM] 12
+A system error occurred. The error code can be found in
+.IR errno .
+.LP
+.IR "The following sections are informative."
+.SH "EXAMPLES"
+None.
+.SH "APPLICATION USAGE"
+If the returned values are to be used as part of any further name
+resolution (for example, passed to
+\fIgetaddrinfo\fR()),
+applications should provide buffers large enough to store any result
+possible on the system.
+.P
+Given the IPv4-mapped IPv6 address
+.BR \(dq::ffff:1.2.3.4\(dq ,
+the implementation performs a lookup as if the socket address structure
+contains the IPv4 address
+.BR \(dq1.2.3.4\(dq .
+.P
+The IPv6 unspecified address (\c
+.BR \(dq::\(dq )
+and the IPv6 loopback address (\c
+.BR \(dq::1\(dq )
+are not IPv4-compatible addresses.
+.SH "RATIONALE"
+None.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIendservent\fR\^(\|)",
+.IR "\fIfreeaddrinfo\fR\^(\|)",
+.IR "\fIgai_strerror\fR\^(\|)",
+.IR "\fIinet_ntop\fR\^(\|)",
+.IR "\fIsocket\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<netdb.h>\fP",
+.IR "\fB<sys_socket.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .