|This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.|
Execute a command on a remote host
#include <unistd.h> int rcmd( char ** ahost, unsigned short inport, const char * locuser, const char * remuser, const char * cmd, int * fd2p );
- 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.
- The well-known Internet port on the host, where the server resides.
- The user ID on the local machine.
- The user ID on the remote machine.
- The command that you want to execute.
- See below.
Use the -l socket option to qcc to link against this library.
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 rshd server (among others) uses the rcmd(), rresvport(), and ruserok() functions.
The rcmd() function looks up the host *ahost by means of gethostbyname(), and returns -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.
A valid socket descriptor; or -1 if an error occurs and a message is printed to standard error.
The error code EAGAIN is overloaded to mean "All network ports in use."