rcmd(3N)rcmd(3N)NAMErcmd(), rcmd_af(), rresvport(), rresvport_af(), ruserok() - return a
stream to a remote command
SYNOPSISDESCRIPTIONrcmd()
The function is used by privileged programs to execute a command on a
remote host. returns a file descriptor for the socket to which the
standard input and standard output of the command are attached. A com‐
mand level interface to is provided by (see remsh(1)), which is the
same as the BSD command.
ahost is a pointer to the address of the remote host name. The name of
the remote host can be either an official host name or an alias as
understood by (see gethostent(3N), named(1M), and hosts(4)).
remport is the Internet port on the remote system, which will try to
connect to.
locuser and remuser point to the user login name on the local host and
on the remote host, respectively. The names are used by the server on
the remote host to authenticate the user (see below).
cmd points to a string that specifies the command to be executed on the
remote host.
fd2p is a pointer to an integer (it can be a NULL pointer).
looks up the host using returning −1 if the host does not exist. Oth‐
erwise, is set to the standard name of the host and a connection is
established to a server accepting requests at the port remport. If the
connection is refused after five tries, or if it was refused for a rea‐
son other than the port being in use, returns −1.
If the call succeeds, a socket of type SOCK_STREAM is returned to the
caller and given to the remote command as and If fd2p is non-NULL,
opens a second socket between the calling process (local) and the con‐
trol process (remote), and places its descriptor in On this connection,
the control process sends the diagnostic output from cmd to the calling
process, and receives UNIX signals from the calling process, to be for‐
warded to cmd. If the auxiliary port cannot be set up, returns −1. If
fd2p is NULL, of the remote command is made the same as and no provi‐
sion is made for sending arbitrary signals to the remote process.
The protocol is described in detail in remshd(1M).
Any program using must be run as superuser.
rcmd_af()
function behaves the same as but it can also create an TCP socket. The
type of socket to be created is specified through the argument. fails
with if the address family is not supported.
rresvport()
The function creates a socket and binds it to a reserved port. This
socket is suitable for use by and several other routines.
The caller is expected to set the initial value of to a number between
512 and (The value of is defined in and is 1024.) Typically, the ini‐
tial value of is set to If the value is outside the valid range, resets
it silently to The function uses the inital value of as the first port
number that it tries to bind to the created socket. If the operation
fails, decrements and attempts to bind the new port number to the
socket. The process is repeated until either the operation succeeds,
or the port numbers between 512 and are exhausted.
If the call succeeds, the socket descriptor is returned to the caller
and the port number is returned in the location pointed to by port. If
the call fails, −1 is returned to the caller.
The socket returned by has the option on.
Only the superuser is permitted to bind a privileged address to a
socket. Therefore, any program using must be run as superuser.
rresvport_af()
function behaves the same as but it can also create an TCP socket. The
type of socket to be created is specified through the argument. fails
with if the address family is not supported.
ruserok()
The function is used by servers to authenticate clients requesting ser‐
vice with verifies that ruser on rhost is authorized to act as luser on
the local host.
superuser is an integer flag that should be nonzero if the local user
name corresponds to a superuser. If the superuser flag is not set,
first checks the file to authenticate the request for service. If this
check succeeds, returns 0. If the superuser flag is set, or if there
is no file or if the check fails, then checks the file (if there is
one) in the local user's home directory. returns 0 if this check suc‐
ceeds. Otherwise, it returns −1.
Typically, the file contains a list of host names, and users' files
contain host-name/user-name pairs. A remote user is authenticated by
if the remote host name appears in and the remote user name and local
user name are the same, or if the remote host name and the remote user
name appear together in in the home directory of the local user.
For a complete explanation of the syntax understood by see
hosts.equiv(4).
DIAGNOSTICSrcmd() Diagnostic Messages
generates the following diagnostic messages.
gethostbyname
was unable to find an entry in the hosts database match‐
ing the name of the server (see gethostent(3N) and
hosts(4)).
Next step: Have the system administrator of your host
check whether the remote host's entry is in the database
(see hosts(4)).
Unable to establish a connection to the
reserved port.
A message that specifies the reason for the failure is
appended to this diagnostic message.
Error writing to the socket connection set
up for error message transmission.
Error executing the system call.
Appended to this error is a message specifying the reason
for the failure.
Socket connection not established on a
reserved port
or socket address not of the Internet family type.
Error in reading information from the stan‐
dard socket connection.
Appended to this error is a message explaining the reason
for the error.
The remote host did not connect within 30
seconds to the secondary socket
set up as an error connection.
The program attempted to read from the
socket and failed.
This means the socket connection with the remote host was
lost.
message...
An error message can be transmitted through the socket
connection from the daemon. That message will be sent to
While waiting for the secondary socket to
be set up,
had its primary connection shut down. This may have been
caused by an inetd security failure.
While trying to set up the secondary
socket, had an error condition on its primary connection.
While trying to set up its secondary
socket,
ran out of some resource that caused the accept to be
timed out.
Next step: Repeat the command.
rresvport() Diagnostic Messages
generates the following diagnostic messages. These messages can also
appear in since calls
Error in executing the system call.
The error message returned by the system call is appended
to the message.
All reserved ports in use.
If a timeout occurs, check whether the Internet Services
are installed and is running.
EXAMPLES
To execute the command on remote host using the remote account call as
shown below. This program requires superuser privileges and the remote
account must be equivalent (see hosts.equiv(4)) to the local account
that runs the program.
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>
#include <stdio.h>
#include <pwd.h>
struct passwd *getpwuid();
char *host[] = { "hpxzgy" };
char *cmd = "date";
char *ruser = "chm";
main(argc,argv)
int argc;
char **argv;
{
struct servent *sp;
struct passwd *pwd;
FILE *fp;
char ch;
int rem;
sp = getservbyname("shell","tcp");
pwd = getpwuid(getuid());
rem = rcmd(host, sp->s_port, pwd->pw_name, ruser, cmd, 0);
if (rem < 0)
exit(1); /* rcmd outputs its own error messages */
fp = fdopen(rem, "r");
while ((ch = getc(fp)) != EOF)
putchar(ch);
}
WARNINGS
There is no way to specify options to the call that makes. Since
replaces the pointer to the host name with a pointer to the standard
name of the host in a static data area, this value must be copied into
the user's data area if it is to be used later. Otherwise, unpre‐
dictable results will occur.
AUTHOR
was developed by the University of California, Berkeley.
SEE ALSOlogin(1), rlogin(1), remsh(1), named(1M), remshd(1M), rexecd(1M), geth‐
ostent(3N), rexec(3N), hosts.equiv(4), thread_safety(5).
rcmd(3N)