Merging upstream version 6.8.

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

1 files changed, 304 insertions, 0 deletions

diff --git a/man/man3/rcmd.3 b/man/man3/rcmd.3
new file mode 100644
index 0000000..718a049
--- /dev/null
+++ b/man/man3/rcmd.3
@@ -0,0 +1,304 @@
+'\" t
+.\"	$NetBSD: rcmd.3,v 1.9 1996/05/28 02:07:39 mrg Exp $
+.\"
+.\" Copyright (c) 1983, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\"     @(#)rcmd.3	8.1 (Berkeley) 6/4/93
+.\"
+.\" Contributed as Linux man page by David A. Holland, 970908
+.\" I have not checked whether the Linux situation is exactly the same.
+.\"
+.\" 2007-12-08, mtk, Converted from mdoc to man macros
+.\"
+.TH rcmd 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+rcmd, rresvport, iruserok, ruserok, rcmd_af,
+rresvport_af, iruserok_af, ruserok_af \- routines for returning a
+stream to a remote command
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <netdb.h>    " "/* Or <unistd.h> on some systems */"
+.P
+.BI "int rcmd(char **restrict " ahost ", unsigned short " inport ,
+.BI "            const char *restrict " locuser ,
+.BI "            const char *restrict " remuser ,
+.BI "            const char *restrict " cmd ", int *restrict " fd2p );
+.P
+.BI "int rresvport(int *" port );
+.P
+.BI "int iruserok(uint32_t " raddr ", int " superuser ,
+.BI "            const char *" ruser ", const char *" luser );
+.BI "int ruserok(const char *" rhost ", int " superuser ,
+.BI "            const char *" ruser ", const char *" luser );
+.P
+.BI "int rcmd_af(char **restrict " ahost ", unsigned short " inport ,
+.BI "            const char *restrict " locuser ,
+.BI "            const char *restrict " remuser ,
+.BI "            const char *restrict " cmd ", int *restrict " fd2p ,
+.BI "            sa_family_t " af );
+.P
+.BI "int rresvport_af(int *" port ", sa_family_t " af );
+.P
+.BI "int iruserok_af(const void *restrict " raddr ", int " superuser ,
+.BI "            const char *restrict " ruser ", const char *restrict " luser ,
+.BI "            sa_family_t " af );
+.BI "int ruserok_af(const char *" rhost ", int " superuser ,
+.BI "            const char *" ruser ", const char *" luser ,
+.BI "            sa_family_t " af );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.ad l
+.P
+.BR rcmd (),
+.BR rcmd_af (),
+.BR rresvport (),
+.BR rresvport_af (),
+.BR iruserok (),
+.BR iruserok_af (),
+.BR ruserok (),
+.BR ruserok_af ():
+.nf
+    Since glibc 2.19:
+        _DEFAULT_SOURCE
+    glibc 2.19 and earlier:
+        _BSD_SOURCE
+.fi
+.ad
+.SH DESCRIPTION
+The
+.BR rcmd ()
+function is used by the superuser to execute a command on
+a remote machine using an authentication scheme based
+on privileged port numbers.
+The
+.BR rresvport ()
+function
+returns a file descriptor to a socket
+with an address in the privileged port space.
+The
+.BR iruserok ()
+and
+.BR ruserok ()
+functions are used by servers
+to authenticate clients requesting service with
+.BR rcmd ().
+All four functions are used by the
+.BR rshd (8)
+server (among others).
+.SS rcmd()
+The
+.BR rcmd ()
+function
+looks up the host
+.I *ahost
+using
+.BR gethostbyname (3),
+returning \-1 if the host does not exist.
+Otherwise,
+.I *ahost
+is set to the standard name of the host
+and a connection is established to a server
+residing at the well-known Internet port
+.IR inport .
+.P
+If the connection succeeds,
+a socket in the Internet domain of type
+.B SOCK_STREAM
+is returned to the caller, and given to the remote
+command as
+.I stdin
+and
+.IR stdout .
+If
+.I fd2p
+is nonzero, then an auxiliary channel to a control
+process will be set up, and a file descriptor for it will be placed
+in
+.IR *fd2p .
+The control process will return diagnostic
+output from the command (unit 2) on this channel, and will also
+accept bytes on this channel as being UNIX signal numbers, to be
+forwarded to the process group of the command.
+If
+.I fd2p
+is 0, then the
+.I stderr
+(unit 2 of the remote
+command) will be made the same as the
+.I stdout
+and no
+provision is made for sending arbitrary signals to the remote process,
+although you may be able to get its attention by using out-of-band data.
+.P
+The protocol is described in detail in
+.BR rshd (8).
+.SS rresvport()
+The
+.BR rresvport ()
+function is used to obtain a socket with a privileged
+port bound to it.
+This socket is suitable for use by
+.BR rcmd ()
+and several other functions.
+Privileged ports are those in the range 0 to 1023.
+Only a privileged process
+(on Linux, a process that has the
+.B CAP_NET_BIND_SERVICE
+capability in the user namespace governing its network namespace)
+is allowed to bind to a privileged port.
+In the glibc implementation,
+this function restricts its search to the ports from 512 to 1023.
+The
+.I port
+argument is value-result:
+the value it supplies to the call is used as the starting point
+for a circular search of the port range;
+on (successful) return, it contains the port number that was bound to.
+.\"
+.SS iruserok() and ruserok()
+The
+.BR iruserok ()
+and
+.BR ruserok ()
+functions take a remote host's IP address or name, respectively,
+two usernames and a flag indicating whether the local user's
+name is that of the superuser.
+Then, if the user is
+.I not
+the superuser, it checks the
+.I /etc/hosts.equiv
+file.
+If that lookup is not done, or is unsuccessful, the
+.I .rhosts
+in the local user's home directory is checked to see if the request for
+service is allowed.
+.P
+If this file does not exist, is not a regular file, is owned by anyone
+other than the user or the superuser, is writable by anyone other
+than the owner, or is hardlinked anywhere, the check automatically fails.
+Zero is returned if the machine name is listed in the
+.I hosts.equiv
+file, or the host and remote username are found in the
+.I .rhosts
+file; otherwise
+.BR iruserok ()
+and
+.BR ruserok ()
+return \-1.
+If the local domain (as obtained from
+.BR gethostname (2))
+is the same as the remote domain, only the machine name need be specified.
+.P
+If the IP address of the remote host is known,
+.BR iruserok ()
+should be used in preference to
+.BR ruserok (),
+as it does not require trusting the DNS server for the remote host's domain.
+.SS *_af() variants
+All of the functions described above work with IPv4
+.RB ( AF_INET )
+sockets.
+The "_af" variants take an extra argument that allows the
+socket address family to be specified.
+For these functions, the
+.I af
+argument can be specified as
+.B AF_INET
+or
+.BR AF_INET6 .
+In addition,
+.BR rcmd_af ()
+supports the use of
+.BR AF_UNSPEC .
+.SH RETURN VALUE
+The
+.BR rcmd ()
+function
+returns a valid socket descriptor on success.
+It returns \-1 on error and prints a diagnostic message on the standard error.
+.P
+The
+.BR rresvport ()
+function
+returns a valid, bound socket descriptor on success.
+On failure, it returns \-1 and sets
+.I errno
+to indicate the error.
+The error code
+.B EAGAIN
+is overloaded to mean: "All network ports in use".
+.P
+For information on the return from
+.BR ruserok ()
+and
+.BR iruserok (),
+see above.
+.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 rcmd (),
+.BR rcmd_af ()
+T}	Thread safety	MT-Unsafe
+T{
+.na
+.nh
+.BR rresvport (),
+.BR rresvport_af ()
+T}	Thread safety	MT-Safe
+T{
+.na
+.nh
+.BR iruserok (),
+.BR ruserok (),
+.BR iruserok_af (),
+.BR ruserok_af ()
+T}	Thread safety	MT-Safe locale
+.TE
+.SH STANDARDS
+BSD.
+.SH HISTORY
+.TP
+.BR iruserok_af ()
+.TQ
+.BR rcmd_af ()
+.TQ
+.BR rresvport_af ()
+.TQ
+.BR ruserok_af ()
+glibc 2.2.
+.P
+Solaris, 4.2BSD.
+The "_af" variants are more recent additions,
+and are not present on as wide a range of systems.
+.SH BUGS
+.BR iruserok ()
+and
+.BR iruserok_af ()
+are declared in glibc headers only since glibc 2.12.
+.\" Bug filed 25 Nov 2007:
+.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=5399
+.SH SEE ALSO
+.BR rlogin (1),
+.BR rsh (1),
+.BR rexec (3),
+.BR rexecd (8),
+.BR rlogind (8),
+.BR rshd (8)