RCMD(3,L) AIX Technical Reference RCMD(3,L)
-------------------------------------------------------------------------------
rcmd, rresvport, ruserok
PURPOSE
Allows execution of commands on a remote host that is running the rshd.
LIBRARY
Internet Library (libc.a)
SYNTAX
int rcmd (host, port, locuser, remuser, command, errfd)
char **host;
unsigned short port;
char *locuser, *remuser, *command;
int *errfd;
int rresvport (port)
int *port;
int ruserok (host, superuser, remuser, locuser)
char *host;
int superuser;
char *remuser, *locuser;
DESCRIPTION
The rcmd subroutine is used to execute a command on a remote machine. The
rresvport subroutine is used to obtain a socket with a privileged address bound
to the socket. A privileged Internet port is one that falls in the range 0 to
1023. The ruserok subroutine is used by servers to authenticate clients
requesting services with the rcmd subroutine.
The rcmd and rresvport subroutines can only be used by processes with an
effective user ID of superuser. An authentication scheme based on remote port
numbers is used to verify permissions.
The rcmd subroutine uses the gethostbyname subroutine to find the host
specified by host. The host parameter is updated to point to the standard name
of the host found by gethostbyname. If the host does not exist, the rcmd
subroutine fails and returns -1.
The port parameter specifies the well-known DARPA Internet port to use for the
connection, which is part of the services data base. (See the description of
the /etc/services file in AIX TCP/IP User's Guide for more information.)
The locuser and remuser parameters point to user names that are valid at the
local and remote host, respectively. Any valid user name can be given.
Processed November 7, 1990 RCMD(3,L) 1
RCMD(3,L) AIX Technical Reference RCMD(3,L)
The command parameter points to the name of the command to be executed at the
remote host.
If the connection succeeds, a socket in the Internet domain of type SOCK_STREAM
is returned to the calling process and given to the remote command as standard
input and standard output.
If errfd is not 0, an auxiliary channel to a control process is set up, and the
errfd parameter points to the file descriptor for the channel. The control
process provides diagnostic output from the remote command on this channel and
also accepts bytes as signal numbers to be forwarded to the process group of
the command.
If errfd is NULL, then the standard error of the remote command is the same as
standard output, and no provision is made for sending arbitrary signals to the
remote process. In this case, however, it may be possible to send out-of-band
data to the remote command.
The host parameter of the ruserok subroutine contains the name of a remote
host. The ruserok subroutine checks for this host in the /etc/host.equiv file.
Then, if necessary, this subroutine checks a file in the user's home directory
at the server called .rhosts for a host and remote user ID.
The superuser parameter indicates whether the effective user ID of the calling
process is that of the superuser. A value of 0 indicates the caller is not
superuser. A value of 1 indicates that this process has local superuser
privileges, and the checking of the /etc/host.equiv file is not performed.
The remuser and locuser parameters point to user names that are valid at the
local and remote host, respectively. Any valid user name can be given.
If the local domain (obtained with the gethostname subroutine) is the same as
the remote domain, only the host name (without the domain parts) must be
specified.
RETURN VALUE
The rcmd subroutine returns a valid socket descriptor on success. If the
effective user ID of the calling process is not superuser, rcmd returns a value
of -1.
The rresvport subroutine returns a valid, bound socket descriptor on success.
If the rresvport subroutine fails, a value of -1 is returned and errno is set
to indicate the error.
The ruserok subroutine returns a value of 0 if the host name is found in the
/etc/hosts.equiv file, or if the host and remuser IDs are found in the .rhosts
file. If the host is not found, ruserok returns a value of -1.
ERROR CONDITIONS
Processed November 7, 1990 RCMD(3,L) 2
RCMD(3,L) AIX Technical Reference RCMD(3,L)
The rresvport subroutine fails if one or more of the following are true:
EAGAIN All network ports are in use.
EAFNOSUPPORT The addresses in the specified address family cannot be used
with this socket.
EMFILE Two hundred (200) file descriptors are currently open.
ENFILE The system file table is full.
ENOBUFS Insufficient buffers were available in the system to complete
the call.
RELATED INFORMATION
In this book: "gethostname, sethostname" and "rexec."
The discussions of /etc/services, rlogind, and rshd in AIX TCP/IP User's Guide.
Processed November 7, 1990 RCMD(3,L) 3