ruserok(3)                                                   ruserok(3)

  rcmd

  NAME

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

  SYNOPSIS

    #include 

    int rcmd (char **ahost, unsigned short inport, const char *locuser,
             const char *remuser, const char *cmd, int *fd2p)
    int rresvport (int *port)
    int iruserok (unsigned long raddr, int superuser, const char *ruser,
                  const char *luser)
    int ruserok (const char *rhost, int superuser, const char *ruser,
                 const char *luser)

  DESCRIPTION

    The rcmd(3) function is used to execute a command on a remote computer
    using an authentication scheme based on reserved port numbers. The
    rresvport(3) function returns a descriptor to a socket with an address in
    the privileged port space. The ruserok(3) function is used by servers to
    authenticate clients requesting service with rcmd(3). All three functions
    are present in the same file and are used by the rshd(1) server (among
    others).

    The rcmd(3) function looks up the host *ahost using gethostbyname(2),
    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. The host name can be
    specified in either name or numeric dot-notation format.

    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, 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
    POSIX signal numbers, to be forwarded 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(1).

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

    The iruserok(3) and ruserok(3) functions take a remote host's internet
    protocol (IP) address or name, as returned by the gethostbyname(2)
    routines, two user names and a flag indicating whether the local user is
    privileged (equivalent to superuser on UNIX computers). If the user is not
    privileged user, it checks the $INTERIX_ROOT/etc/hosts.equiv file. If that
    lookup is not done, or is unsuccessful, it checks the .rhosts in the local
    user's home directory to see if the request for service is allowed.

    If this file does not exist, is not a regular file, is owned by anyone
    other than the user or the superuser, or is writeable by anyone other than
    the owner, the check automatically fails. Zero is returned if the computer
    name is listed in the hosts.equiv file, or the host and remote user name
    are found in the .rhosts file; otherwise iruserok(3) and ruserok(3) return
    -1. If the local domain (as obtained from gethostname(3)) is the same as
    the remote domain, only the computer name need be specified.

    The iruserok(3) function is strongly preferred for security reasons. It
    requires trusting the local Domain Name System (DNS) networking protocol
    at most, while the ruserok(3) function requires trusting the entire DNS,
    which can be spoofed.

  RETURN VALUES

    The rcmd(3) function returns a valid socket descriptor on success. It
    returns -1 on error and prints a diagnostic message on the standard error.

    The rresvport(3) 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."

  SEE ALSO

    rlogin(1)

    rsh(1)

    rexecd(1)

    rlogind(1)

    rshd(1)

    rexec(3)

  USAGE NOTES

    None of these functions are thread safe.

    None of these functions are async-signal safe.