REXEC(3SOCKET) Sockets Library Functions REXEC(3SOCKET)

NAME

rexec, rexec_af - return stream to a remote command

SYNOPSIS

cc [ flag ... ] file... -lsocket -lnsl [ library... ]
#include <netdb.h>
#include <unistd.h>

int rexec(char **ahost, unsigned short inport, const char *user,
const char *passwd, const char *cmd, int *fd2p);


int rexec_af(char **ahost, unsigned short inport, const char *user,
const char *passwd, const char *cmd, int *fd2p, int af);

DESCRIPTION

The rexec() and rexec_af() functions look up the host ahost using
getaddrinfo(3SOCKET) and return -1 if the host does not exist. Otherwise
ahost is set to the standard name of the host. The username and password
are used in remote host authentication. When a username and password are
not specified, the .netrc file in the user's home directory is searched
for the appropriate information. If the search fails, the user is
prompted for the information.


The rexec() function always returns a socket of the AF_INET address
family. The rexec_af() function supports AF_INET, AF_INET6, or AF_UNSPEC
for the address family. An application can choose which type of socket is
returned by passing AF_INET or AF_INET6 as the address family. The use of
AF_UNSPEC means that the caller will accept any address family. Choosing
AF_UNSPEC provides a socket that best suits the connectivity to the
remote host.


The port inport specifies which DARPA Internet port to use for the
connection. The port number used must be in network byte order, as
supplied by a call to htons(3C). The protocol for connection is described
in detail in in.rexecd(8).


If the call succeeds, a socket of type SOCK_STREAM is returned to the
caller, and given to the remote command as its standard input and
standard output. If fd2p is non-zero, an auxiliary channel to a control
process is set up and a file descriptor for it is placed in *fd2p. The
control process returns diagnostic output (file descriptor 2), from the
command on the auxiliary channel. The control process also accepts bytes
on this channel as signal numbers to be forwarded to the process group of
the command. If fd2p is 0, the standard error (file descriptor 2) of the
remote command is made the same as its standard output. No provision is
made for sending arbitrary signals to the remote process, other than
possibly sending out-of-band data.


There is no way to specify options to the socket() call made by the
rexec() or rexec_af()functions.

RETURN VALUES

If rexec() succeeds, a file descriptor number is returned of the socket
type SOCK_STREAM and the address family AF_INET. The parameter *ahost is
set to the standard name of the host. If the value of fd2p is other than
NULL, a file descriptor number is placed in *fd2p which represents the
standard error stream of the command.


If rexec_af() succeeds, the routine returns a file descriptor number of
the socket type SOCK_STREAM in the address family AF_INET or AF_INET6, as
determined by the value of the af parameter.


If either rexec() or rexec_af() fails, -1 is returned.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT-Level | Unsafe |
+---------------+-----------------+


This interface is Unsafe in multithreaded applications. Unsafe interfaces
should be called only from the main thread.

SEE ALSO

htonl(3C), gethostbyname(3NSL), getaddrinfo(3SOCKET),
getservbyname(3SOCKET), socket(3SOCKET), attributes(7), in.rexecd(8)

February 10, 2004 REXEC(3SOCKET)