Sockets Library Functions                          rexec(3SOCKET)



NAME
     rexec, rexecaf - return stream to a remote command

SYNOPSIS
     cc [ flag ... ] file... -lsocket  -lnsl  [ library... ]
     #include 
     #include 

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


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


DESCRIPTION
     The rexec() and rexecaf() 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  speci-
     fied,  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  AFINET
     address  family.  The  rexecaf() function supports AFINET,
     AFINET6, or AFUNSPEC for the address family.  An  applica-
     tion  can choose which type of socket is returned by passing
     AFINET or AFINET6  as  the  address  family.  The  use  of
     AFUNSPEC means that the caller will accept any address fam-
     ily. Choosing AFUNSPEC 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(3XNET). The  pro-
     tocol   for   connection   is   described   in   detail   in
     in.rexecd(1M).


     If the call  succeeds,  a  socket  of  type  SOCKSTREAM  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  pro-
     cess 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



SunOS 5.11          Last change: 10 Feb 2004                    1






Sockets Library Functions                          rexec(3SOCKET)



     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 rexecaf()functions.

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


     If rexecaf() succeeds, the routine returns a file  descrip-
     tor  number  of  the  socket type SOCKSTREAM in the address
     family AFINET or AFINET6, as determined by  the  value  of
     the af parameter.


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

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE 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          Last change: 10 Feb 2004                    2