HP-UX Reference (11i v1 00/12) - 3 Library Functions N-Z (vol 7)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man3/nan.3m
________________________________________________________________
___ ___
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 com-
mand 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 con-
trol 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 signalsto 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 connec-
tion.
Section 3−−772 − 1 − HP-UX Release 11i: December 2000
___
___