rcmd(3)                             CLIX                             rcmd(3)



  NAME

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

  LIBRARY

    Berkeley Software Distribution Library (libbsd.a)

  SYNOPSIS

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

    int rresvport(
      int *port );

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

  DESCRIPTION

    The rcmd() function is used by the superuser to execute a command on a
    remote machine using an authentication scheme based on reserved port
    numbers.  The rresvport() function returns a descriptor to a socket with
    an address in the privileged port space.  The ruserok() function is used
    by servers to authenticate clients requesting service with rcmd().  All
    three functions are in the same file and are used by the rshd server
    (among others).  The rcmd() looks up the host ahost using gethostbyname(),
    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 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
    nonzero, an auxiliary channel to a control process will be set up, and a
    descriptor for it will be placed in the integer pointed to by fd2p.  The
    control process will return diagnostic output from the command (unit 2) on
    this channel and will also accept bytes on this channel representing CLIX
    signal numbers to be forwarded to the process group of the command.  If
    fd2p is 0, the stderr (unit 2 of the remote command) will be the same as
    the stdout with no provision for sending arbitrary signals to the remote
    process, although out-of-band data could be used to attract its attention.




  2/94 - Intergraph Corporation                                              1

  rcmd(3)                             CLIX                             rcmd(3)



    The protocol is described in detail in rshd.

    The rresvport() function is used to obtain a socket with a privileged
    address bound to it.  This socket is suitable for use by rcmd and several
    other functions.  Privileged Internet ports are in the 0 to 1023 range.
    Only the superuser is allowed to bind this type of address to a socket.

    The ruserok() function assumes a remote host's name returned by a
    gethostbyaddr() function, with two usernames and a flag indicating whether
    the local user's name is also the superuser's.  It then checks the files
    /etc/hosts.equiv and possibly .rhosts in the 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 /etc/hosts.equiv file or the host and remote
    username are in the .rhosts file; otherwise ruserok() returns -1.  If the
    superuser flag is 1, the checking of the /etc/host.equiv file is bypassed.
    If the local domain (as obtained from gethostname() is the same as the
    remote domain, only the machine name should be specified.

  RETURN VALUES

    The rcmd() function returns a valid socket descriptor on success.  It
    returns -1 on error and displays a diagnostic message on stderr.

    The rresvport() function returns a valid, bound socket descriptor on
    success.  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.''

  RELATED INFORMATION

    Commands:  rcmd(1), rexecd(1), rshd(1)

    Functions:  rexec(3)





















  2                                              Intergraph Corporation - 2/94