RCMD(3X) Series 300 Only RCMD(3X)
NAME
rcmd, rresvport, ruserok - routines for returning a stream
to a remote command
SYNOPSIS
int rem
rem = rcmd(ahost, inport, locuser, remuser, cmd, fd2p);
char **ahost;
u_short inport;
char *locuser, *remuser, *cmd;
int *fd2p;
s = rresvport(port);
int *port;
ruserok(rhost, superuser, ruser, luser);
char *rhost;
int superuser;
char *ruser, *luser;
HP-UX COMPATIBILITY
Level: HP-UX/NON-STANDARD
Origin: UCB
Remarks: Implemented on the Series 300 only.
DESCRIPTION
These libraries can be accessed by giving the -lbsdipc
option to ld(1).
Rcmd is a routine used by the super-user to execute a
command on a remote host using an authentication scheme
based on reserved port numbers. The name of the remote host
can be either its official name or an alias as listed in
/etc/hosts; see hosts(5). Rresvport is a routine which
returns a descriptor to a socket with an address in the
privileged port space. Ruserok is a routine used by servers
to authenticate clients requesting service with rcmd.
Any program using rcmd or rresvport needs to have super-user
privileges. Rcmd looks up the host *ahost using
gethostbyname(3N), returning -1 if the host does not exist.
Otherwise *ahost is set to the standard name of the host and
a connection is established to a server residing at the
internet port inport. If the connection is refused after
five tries or if it was refused for a reason other than the
port being in use, then rcmd returns a -1.
If the call succeeds, a socket of type SOCK_STREAM is
returned to the caller, and given to the remote command as
stdin and stdout. If fd2p is non-zero, then an auxiliary
Hewlett-Packard - 1 - (printed 7/16/86)
RCMD(3X) Series 300 Only RCMD(3X)
connection to a control process is set up, and a descriptor
for it is placed in *fd2p. The control process returns
diagnostic output from the command on this connection, and
also accepts bytes on this connection as being UNIX signal
numbers, to be forwarded to the process group of the
command. If the auxiliary port cannot be set up, then rcmd
returns a -1. If fd2p is 0, then stderr of the remote
command is made the same as stdout and no provision is made
for sending arbitrary signals to the remote process.
The protocol is described in detail in remshd(1M).
The rresvport routine is used to obtain a socket with a
privileged address bound to it. This socket is suitable for
use by rcmd and several other routines. Privileged
addresses consist of a port in the range 0 to 1023. Only
the super-user is allowed to bind an address of this sort to
a socket.
Ruserok takes a remote host's name, as returned by a
gethostent(3N) routine, two user names and a flag indicating
if the local user's name is the super-user. It then checks
the files /etc/hosts.equiv and, possibly, .rhosts in the
current working directory (normally the local user's home
directory) to see if the request for service is allowed; see
hosts.equiv(5). Ruserok returns a 0 if the name is listed
in /etc/hosts.equiv, or the host and remote user name are
found in $HOME/.rhosts; otherwise ruserok returns -1. If
the superuser flag is set, /etc/host.equiv is bypassed.
EXAMPLES
To execute the command date on the remote host ``hpxzgy''
using the remote account ``chm'' you can use rcmd as shown
below. This program needs to have super-user privileges and
the remote account needs to be equivalent (see
hosts.equiv(5)) to the local account that runs the program.
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <errno.h>
#include <netdb.h>
#include <stdio.h>
#include <pwd.h>
struct passwd *getpwuid();
main(argv,argc)
char **argv;
int argc;
{
char *host = "hpxzgy";
Hewlett-Packard - 2 - (printed 7/16/86)
RCMD(3X) Series 300 Only RCMD(3X)
struct servent *sp;
struct passwd *pwd;
char *cmd = "date";
char *ruser = "chm";
int rem, readfrom, cc;
int one = 1;
char buf[BUFSIZ];
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 */
ioctl(rem, FIONBIO, &one);
do {
readfrom = (1<<rem);
if (select(16, &readfrom, 0,0,0) < 0)
{
if (errno != EINTR)
{
perror("select");
exit(1);
}
continue;
}
/* Write any information transmitted through the socket */
/* to stdout. */
if (readfrom & (1<<rem))
{
cc = read(rem, buf, sizeof(buf));
if (cc <= 0)
{
if (errno != EWOULDBLOCK)
readfrom &= ~(1<<rem);
}
else
write(1, buf, cc);
}
} while (readfrom);
exit(0);
}
DIAGNOSTICS
Rcmd Diagnostic Messages
The diagnostic messages rcmd returns are:
<hostname>: Unknown host
Rcmd was unable to find an entry in the host database
file /etc/hosts matching the address of the server; see
Hewlett-Packard - 3 - (printed 7/16/86)
RCMD(3X) Series 300 Only RCMD(3X)
hosts(5).
Next step: Have the system administrator of your host
check if the remote host's entry is in /etc/hosts.
connect: <hostname>: ...
Unable to establish a connection to the reserved port.
A message which specifies the reason for the failure is
appended to this diagnostic message.
write: Setting up stderr
Error writing to the socket connection set up for error
transmission.
<system call>: ...
Error executing the system call. Appended to this
error is a message specifying the reason for the
failure.
socket: Protocol failure in circuit setup
Socket connection not established on a reserved port or
socket address not of the internet family type.
read: <hostname>: ....
Error reading the information from the standard socket
connection. Appended to this error is a message
explaining the reason for the error.
Connection timeout
The remote host did not connect within 30 seconds to
the secondary socket set up as an error connection.
Lost connection
The program attempts to read from the socket and fails.
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 stderr.
Rcmd and Rresvport Diagnostic Messages
The diagnostic messages associated with rresvport can also
appear in rcmd since rcmd calls rresvport; they are the
following:
<system call>:...
Error in executing the system call. The error message
returned by the system call is appended to the message.
socket: All ports in use
Hewlett-Packard - 4 - (printed 7/16/86)
RCMD(3X) Series 300 Only RCMD(3X)
All reserved ports in use.
SEE ALSO
rlogin(1), remsh(1), rlogind(1M), remshd(1M).
WARNINGS
There is no way to specify options to the socket call which
rcmd makes.
Hewlett-Packard - 5 - (printed 7/16/86)