RCMD(3)                                             Linux Programmer's Manual                                            RCMD(3)



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

SYNOPSIS
       #include <netdb.h>   /* Or <unistd.h> on some systems */

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

       int rresvport(int *port);

       int iruserok(uint32_t raddr, int superuser,
                    const char *ruser, const char *luser);

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

   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

       rcmd(), rresvport(), ruserok(): _BSD_SOURCE

DESCRIPTION
       The  rcmd()  function  is  used  by the superuser to execute a command on a remote machine using an authentication scheme
       based on privileged port numbers.  The rresvport() function returns a descriptor to a socket with an address in the priv-
       ileged port space.  The iruserok() and ruserok() functions are used by servers to authenticate clients requesting service
       with rcmd().  All four functions are present in the same file and are used by the rshd(8) server (among others).

       The rcmd() function 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 nonzero, 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 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(8).

       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 those in the range 0 to 1023.  Only the supe-
       ruser is allowed to bind an address of this sort to a socket.

       The iruserok() and ruserok() functions take a remote host's IP address or name, respectively, two usernames  and  a  flag
       indicating whether the local user's name is that of the superuser.  Then, if the user is not the superuser, it checks the
       /etc/hosts.equiv file.  If that lookup is not done, or is unsuccessful, the .rhosts in the local user's home directory is
       checked 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
       writable by anyone other than the owner, the check automatically fails.  Zero is returned if the machine name  is  listed
       in  the  hosts.equiv  file,  or  the  host  and  remote  username are found in the .rhosts file; otherwise iruserok() and
       ruserok() return -1.  If the local domain (as obtained from gethostname(2)) is the same as the remote  domain,  only  the
       machine name need be specified.

       If  the  IP  address  of  the  remote host is known, iruserok() should be used in preference to ruserok(), as it does not
       require trusting the DNS server for the remote host's domain.

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

       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."

CONFORMING TO
       Not in POSIX.1-2001.  Present on the BSDs, Solaris, and many other systems.  These functions appeared in 4.2BSD.

BUGS
       iruserok() is not declared in glibc headers.

SEE ALSO
       rlogin(1), rsh(1), intro(2), rexec(3), rexecd(8), rlogind(8), rshd(8)

COLOPHON
       This  page  is  part of release 3.25 of the Linux man-pages project.  A description of the project, and information about
       reporting bugs, can be found at http://www.kernel.org/doc/man-pages/.



Linux                                                      2007-12-28                                                    RCMD(3)