rcmd(), rcmd

Execute a command on a remote host

Synopsis:

#include <unistd.h>

int rcmd( char ** ahost, 
          unsigned short inport,
          const char * locuser,
          const char * remuser,
          const char * cmd, 
          int * fd2p );

int rcmd_af( char ** ahost, 
             unsigned short inport,
             const char * locuser,
             const char * remuser,
             const char * cmd, 
             int * fd2p,
             int af );

Arguments:

ahost: The name of the host that you want to execute the command on. If the function can find the host, it sets *ahost to the standard name of the host.
inport: The well-known Internet port on the host, where the server resides.
locuser: The user ID on the local machine.
remuser: The user ID on the remote machine.
cmd: The command that you want to execute.
fd2p: See below.
af: (rcmd_af() only) The address family; see <sys/socket.h>. If af is AF_UNSPEC or PF_UNSPEC, interpretation of *ahost obeys the underlying address resolution like DNS.

Library:

libsocket

Use the -l socket option to qcc to link against this library.

Description:

The rcmd() function is used by the superuser to execute a command, cmd, on a remote machine using an authentication scheme based on reserved port numbers. The rcmd() function can handle only IPv4 addresses as the first argument; rcmd_af() can handle other types of addresses as well. The rshd server (among others) uses the rcmd(), rresvport(), and ruserok() functions.

The rcmd() and rcmd_af() functions look up the host *ahost by means of gethostbyname(), and return -1 if the host doesn't exist. Otherwise, *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 inport.

If the connection succeeds, a SOCK_STREAM socket in the Internet domain is returned to the caller and given to the remote command as standard input and standard output.

If `fd2p` is:	Then:
Nonzero	An auxiliary channel to a control process is set up, and a descriptor for it is placed in *`fd2p`. The control process will return diagnostic output from the command (unit 2) on this channel and will accept bytes as signal numbers to be forwarded to the command's process group.
Zero	The standard error (unit 2 of the remote command) is made the same as the standard output 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).

The protocol is described in detail in rshd in the Utilities Reference.

Returns:

A valid socket descriptor; or -1 if an error occurs and a message is printed to standard error.

Errors:

The error code EAGAIN is overloaded to mean “All network ports in use.”

Classification:

Unix

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	No
Thread	No

rcmd(), rcmd_af()