1 files changed, 178 insertions, 0 deletions
diff --git a/usr/src/man/man3socket/rcmd.3socket b/usr/src/man/man3socket/rcmd.3socket
new file mode 100644
index 0000000000..266dc6e2b5
--- /dev/null
+++ b/usr/src/man/man3socket/rcmd.3socket
@@ -0,0 +1,178 @@
+'\" te
+.\"  Copyright (c) 1983 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement  specifies the terms and conditions for redistribution.
+.\" Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved
+.TH rcmd 3SOCKET "10 Feb 2004" "SunOS 5.11" "Sockets Library Functions"
+.SH NAME
+rcmd, rcmd_af, rresvport, rresvport_af, ruserok \- routines for returning a
+stream to a remote command
+.SH SYNOPSIS
+.LP
+.nf
+\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR... ]
+#include <netdb.h>
+#include <unistd.h>
+
+\fBint\fR \fBrcmd\fR(\fBchar **\fR\fIahost\fR, \fBunsigned short\fR \fIinport\fR, \fBconst char *\fR\fIluser\fR,
+     \fBconst char *\fR\fIruser\fR, \fBconst char *\fR\fIcmd\fR, \fBint *\fR\fIfd2p\fR);
+.fi
+
+.LP
+.nf
+\fBint\fR \fBrcmd_af\fR(\fBchar **\fR\fIahost\fR, \fBunsigned short\fR \fIinport\fR, \fBconst char *\fR\fIluser\fR,
+     \fBconst char *\fR\fIruser\fR, \fBconst char *\fR\fIcmd\fR, \fBint *\fR\fIfd2p\fR, \fBint\fR \fIaf\fR);
+.fi
+
+.LP
+.nf
+\fBint\fR \fBrresvport\fR(\fBint *\fR\fIport\fR);
+.fi
+
+.LP
+.nf
+\fBint\fR \fBrresvport_af\fR(\fBint *\fR\fIport\fR, \fBint\fR \fIaf\fR);
+.fi
+
+.LP
+.nf
+\fBint\fR \fBruserok\fR(\fBconst char *\fR\fIrhost\fR, \fBint\fR \fIsuser\fR, \fBconst char *\fR\fIruser\fR,
+     \fBconst char *\fR\fIluser\fR);
+.fi
+
+.SH DESCRIPTION
+.sp
+.LP
+The \fBrcmd()\fR function is used by the superuser to execute a command on a
+remote machine with an authentication scheme based on reserved port numbers. An
+\fBAF_INET\fR socket is returned with \fBrcmd()\fR. The \fBrcmd_af()\fR
+function supports \fBAF_INET\fR, \fBAF_INET6\fR or \fBAF_UNSPEC\fR for the
+address family. An application can choose which type of socket is returned by
+passing \fBAF_INET\fR or \fBAF_INET6\fR as the address family. The use of
+\fBAF_UNSPEC\fR means that the caller will accept any address family. Choosing
+\fBAF_UNSPEC\fR provides a socket that best suits the connectivity to the
+remote host.
+.sp
+.LP
+The \fBrresvport()\fR function returns a descriptor to a socket with an address
+in the privileged port space. The \fBrresvport_af()\fR function is the
+equivalent to \fBrresvport()\fR, except that you can choose \fBAF_INET\fR or
+\fBAF_INET6\fR as the socket address family to be returned by
+\fBrresvport_af()\fR. \fBAF_UNSPEC\fR does not apply to the \fBrresvport()\fR
+function.
+.sp
+.LP
+The \fBruserok()\fR function is a routine used by servers to authenticate
+clients that request as service with \fBrcmd\fR.
+.sp
+.LP
+All of these functions are present in the same file and are used by the
+\fBin.rshd\fR(1M) server among others.
+.sp
+.LP
+The \fBrcmd()\fR and \fBrcmd_af()\fR functions look up the host \fI*ahost\fR
+using \fBgetaddrinfo\fR(3SOCKET) and return \fB\(mi1\fR if the host does not
+exist. Otherwise, *\fIahost\fR is set to the standard name of the host and a
+connection is established to a server residing at the Internet port
+\fIinport\fR.
+.sp
+.LP
+If the connection succeeds, a socket in the Internet domain of type
+\fBSOCK_STREAM\fR is returned to the caller. The socket is given to the remote
+command as standard input (file descriptor 0) and standard output (file
+descriptor 1). If \fIfd2p\fR is non-zero, an auxiliary channel to a control
+process is set up and a descriptor for it is placed in \fI*fd2p\fR. The control
+process returns diagnostic output file (descriptor 2) from the command on the
+auxiliary channel. The control process also accepts bytes on this channel as
+signal numbers to be forwarded to the process group of the command. If
+\fIfd2p\fR is 0, the standard error (file descriptor 2) of the remote command
+is made the same as its standard output. No provision is made for sending
+arbitrary signals to the remote process, other than possibly sending
+out-of-band data.
+.sp
+.LP
+The protocol is described in detail in \fBin.rshd\fR(1M).
+.sp
+.LP
+The \fBrresvport()\fR and \fBrresvport_af()\fR functions are used to obtain a
+socket bound to a privileged port number. The socket is suitable for use by
+\fBrcmd()\fR and \fBrresvport_af()\fR and several other routines. Privileged
+Internet ports are those in the range 1 to 1023. Only the superuser is allowed
+to bind a socket to a privileged port number. The application must pass in
+\fIport\fR, which must be in the range 512 to 1023. The system first tries to
+bind to that port number.  If it fails, the system then tries to bind to
+another unused privileged port, if one is available.
+.sp
+.LP
+The \fBruserok()\fR function takes a remote host name returned by the
+\fBgethostbyaddr()\fR function with two user names and a flag to indicate
+whether the local user's name is that of the superuser. See
+\fBgethostbyname\fR(3NSL). The \fBruserok()\fR function then checks the files
+\fB/etc/hosts.equiv\fR and possibly \fB\&.rhosts\fR in the local user's home
+directory to see if the request for service is allowed. A \fB0\fR value is
+returned if the machine name is listed in the \fB/etc/hosts.equiv\fR file, or
+if the host and remote user name are found in the \fB\&.rhosts\fR file.
+Otherwise, the \fBruserok()\fR function returns \fB\(mi1\fR\&. If the superuser
+flag is \fB1\fR, the \fB/etc/hosts.equiv\fR is not checked.
+.sp
+.LP
+The error code \fBEAGAIN\fR is overloaded to mean "All network ports in use."
+.SH RETURN VALUES
+.sp
+.LP
+The \fBrcmd()\fR and \fBrcmd_af()\fR functions return a valid socket descriptor
+upon success. The functions returns \fB\(mi1\fR upon error and print a
+diagnostic message to standard error.
+.sp
+.LP
+The \fBrresvport()\fR and \fBrresvport_af()\fR functions return a valid, bound
+socket descriptor upon success. The functions return \fB\(mi1\fR upon error
+with the global value \fIerrno\fR set according to the reason for failure.
+.SH FILES
+.sp
+.ne 2
+.mk
+.na
+\fB\fB/etc/hosts.equiv\fR\fR
+.ad
+.RS 20n
+.rt  
+system trusted hosts and users
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fB~/.rhosts\fR\fR
+.ad
+.RS 20n
+.rt  
+user's trusted hosts and users
+.RE
+
+.SH ATTRIBUTES
+.sp
+.LP
+See \fBattributes\fR(5) for descriptions of the following attributes:
+.sp
+
+.sp
+.TS
+tab() box;
+cw(2.75i) |cw(2.75i) 
+lw(2.75i) |lw(2.75i) 
+.
+ATTRIBUTE TYPEATTRIBUTE VALUE
+_
+MT-LevelUnsafe
+.TE
+
+.sp
+.LP
+This interface is Unsafe in multithreaded applications. Unsafe interfaces
+should be called only from the main thread.
+.SH SEE ALSO
+.sp
+.LP
+\fBrlogin\fR(1), \fBrsh\fR(1), \fBin.rexecd\fR(1M), \fBin.rshd\fR(1M),
+\fBIntro\fR(2), \fBgetaddrinfo\fR(3SOCKET), \fBgethostbyname\fR(3NSL),
+\fBrexec\fR(3SOCKET), \fBattributes\fR(5)