HP-UX Reference (11i v2 03/08) - 3 Library Functions N-Z (vol 7)

r
rexec(3N) rexec(3N)
NAME
rexec() - return stream to a remote command
SYNOPSIS
int rexec(char **ahost,
int inport,
const char *user,
const char *passwd,
const char *cmd,
int *fd2p);
DESCRIPTION
The rexec() routine performs the necessary tasks to arrange for the remote execution of cmd on the
remote host
*ahost as user, who is authenticated with passwd. Upon completion of authentication, a file
descriptor is returned for the socket to which standard input and standard output of cmd are attached. A
command-level interface to
rexec() is provided by the rexec command (see remsh(1)).
When invoked,
rexec() looks up host *ahost using
gethostbyname() (see gethostent (3N)) and
returns −1 if the host does not exist. The host name can be either the official name or an alias. If the
gethostbyname()
call succeeds, *ahost is set to the standard name of the host. Next,
rexec()
passes a user name and password to the remote host for authentication, as specified in the user and
passwd parameters to
rexec(). If either user or passwd are NULL, rexec() searches for the
appropriate information in the .netrc file (see netrc(4)) in the user’s home directory. If no user or
passwd are found,
rexec() prompts the user for the remote user name and password, defaulting to the
local user name and a NULL password.
The inport variable specifies which TCP port to use for the connection; it is normally the value returned
by the following call to
getservbyname :
getservbyname("exec", "tcp")
(see getservent (3N)). The protocol used by rexec() is described in detail in rexecd(1M).
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 connection to a socket is denied after five tries, or for some other
reason (other than the port is in use), rexec() returns −1. If fd2p is non-zero, an auxiliary connection
to a control process is set up and a file descriptor for it is placed in
*fd2p. The control process returns
diagnostic output from the command on this connection and accepts bytes on this connection, interpreting
them as UNIX signal numbers to be forwarded to the process group of the command. If the auxiliary port
cannot be set up,
rexec() returns −1. If fd2p is 0, stderr of the remote command is made the same as
stdout and no provision is made for sending arbitrary signals to the remote process.
DIAGNOSTICS
When invoked,
rexec() produces the following diagnostic messages:
hostname
: Unknown host
The remote host name was not found by gethostbyname().
system call
: message
Error in executing the system call. The message specifies the cause of the failure.
connect: hostname : message
Error in connecting to the socket obtained for
rexec(). The message specifies the cause of the
failure.
Secondary socket: message
Error in creating a secondary socket for error transmission to be used by
rexec().
read: hostname : message
Error in reading information transmitted over the socket. The message specifies the cause of the
failure.
Connection timeout
The remote host did not connect within 30 seconds to the secondary socket set up as an error con-
nection.
Section 3−−864 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: August 2003