NAME

     rcmd, rresvport, ruserok - routines for returning  a  stream
     to a remote command


SYNOPSIS

     #include <sys/types.h>
     #include <net/netlib.h>

     rem = rcmd(ahost, inport, locuser, remuser, cmd, fd2p);
     char **ahost;
     int inport;
     char *locuser, *remuser, *cmd;
     int *fd2p;

     s = rresvport(port);
     int *port;

     ruserok(rhost, superuser, ruser, luser);
     char *rhost;
     int superuser;
     char *ruser, *luser;


DESCRIPTION

     Rcmd is a routine used by the super-user to execute  a  com-
     mand  on  a  remote  machine  using an authentication scheme
     based on reserved port  numbers.   Rresvport  is  a  routine
     which  returns  a  descriptor to a socket with an address in
     the privileged port space.  Ruserok is  a  routine  used  by
     servers  to  authenticate  clients  requesting  service with
     rcmd.  All three functions are present in the same file  and
     are used by the rshd(8) server (among others).

     Rcmd  looks  up  the  host  *ahost  using  gethostbyname(3),
     returning  -1  if the host does not exist.  Otherwise *ahost
     is set to the standard name of the host and a connection  is
     established  to a server residing at the well-known Internet
     port inport.

     If the connection succeeds, a socket in the Internet  domain
     of  type SOCK_STREAM is returned to the caller, and given to
     the remote command as stdin and stdout.   If  fd2p  is  non-
     zero, then an auxiliary channel to a control process will be
     set up, and a descriptor for it will  be  placed  in  *fd2p.
     The  control  process will return diagnostic output from the
     command (unit 2) on this channel, and will also accept bytes
     on  this  channel  as  being UNIX signal numbers, to be for-
     warded to the process group of the command.  If fd2p  is  0,
     then  the stderr (unit 2 of the remote command) will be made
     the same as the stdout and no provision is made for  sending
     arbitrary signals to the remote process, although you may be
     able to get its attention by using out-of-band data.

     The protocol is described in detail in rshd(8).

     The rresvport routine is used to  obtain  a  socket  with  a
     privileged address bound to it.  This socket is suitable for
     use by rcmd and several other routines.  Privileged Internet
     ports are those in the range 0 to 1023.  Only the super-user
     is allowed to bind an address of this sort to a socket.

     Ruserok takes  a  remote  host's  name,  as  returned  by  a
     gethostbyaddr(3) routine, two user names and a flag indicat-
     ing whether the local user's name is that of the super-user.
     It  then  checks  the  files /etc/hosts.equiv and, possibly,
     .rhosts in the current working directory (normally the local
     user's  home directory) to see if the request for service is
     allowed.  A 0 is returned if the machine name is  listed  in
     the  ``hosts.equiv''  file, or the host and remote user name
     are found in the ``.rhosts'' file; otherwise ruserok returns
     -1.   If  the  superuser  flag  is  1,  the  checking of the
     ``host.equiv'' file is bypassed.  If the  local  domain  (as
     obtained  from  gethostname(3))  is  the  same as the remote
     domain, only the machine name need be specified.


SEE ALSO

     rlogin(1),  rsh(1),  intro(2),  rexec(3),  rexecd(8),   rlo-
     gind(8), rshd(8)


DIAGNOSTICS

     Rcmd returns a  valid  socket  descriptor  on  success.   It
     returns  -1  on error and prints a diagnostic message on the
     standard error.

     Rresvport returns a valid, bound socket descriptor  on  suc-
     cess.   It  returns  -1 on error with the global value errno
     set according to the reason for  failure.   The  error  code
     EAGAIN is overloaded to mean ``All network ports in use.''