HP-UX Reference (11i v3 07/02) - 3 Library Functions N-Z (vol 7)

r
rexec(3N) rexec(3N)
NAME
rexec(), rexec_af() - return stream to a remote command
SYNOPSIS
int rexec(char **ahost,
int inport,
const char *user,
const char *passwd,
const char *cmd,
int *fd2p);
int rexec_af(char **ahost,
int inport,
const char *user,
const char *passwd,
const char *cmd,
int *fd2p,
int af);
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 signals to the remote process.
The rexec_af() routine is similar to the rexec() routine except for the additional parameter af. The
af parameter in the rexec_af() routine can be used to specify an AF_INET6 TCP socket or an
AF_INET TCP socket. If the address family specified in the af argument is not supported, rexec_af()
fails with the following error code: [EAFNOSUPPORT].
DIAGNOTISCS
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
292 Hewlett-Packard Company − 1 − HP-UX 11i Version 3: February 2007