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  pass-
       word  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 sup-
       plied by a call to htons(3XNET). The protocol for connection is described in detail in 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  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(5) 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

       in.rexecd(1M), getaddrinfo(3SOCKET), gethostbyname(3NSL), getservbyname(3SOCKET), htonl(3XNET), socket(3SOCKET), attributes(5)

SunOS 5.11							    10 Feb 2004 						    rexec(3SOCKET)