Sockets Library Functions                           rcmd(3SOCKET)

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

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

     int rcmd(char **ahost, unsigned  short  inport,  const  char
     *luser, const char *ruser, const char *cmd, int *fd2p);

     int rcmd_af(char **ahost, unsigned short inport, const  char
     *luser,  const  char *ruser, const char *cmd, int *fd2p, int
     af);

     int rresvport(int *port);

     int rresvport_af(int *port, int af);

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

DESCRIPTION
     rcmd() is a routine used by the superuser to execute a  com-
     mand  on  a  remote  machine  using an authentication scheme
     based on reserved  port  numbers.  It  is  assumed  that  an
     AF_INET socket is returned with rcmd(). rcmd_af() allows the
     application to choose which type of socket  is  returned  by
     passing in the address family, either AF_INET or AF_INET6.

     rresvport() is a routine that  returns  a  descriptor  to  a
     socket  with  an  address  in  the  privileged  port  space.
     rresvport_af() is equivalent to rresvport(), except that you
     can  choose  the  type of socket address family that will be
     returned by rresvport_af(), either AF_INET or AF_INET6.

     ruserok() is a  routine  used  by  servers  to  authenticate
     clients requesting service with rcmd.

     All of these functions are present in the same file and  are
     used by the in.rshd(1M) server (among others).

     rcmd()  and  rcmd_af()  look  up  the  host   *ahost   using
     getipnodebyname(3SOCKET),  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 its standard input (file descriptor 0)
     and  standard  output  (file  descriptor 1). If fd2p is non-
     zero, then an auxiliary channel to a control process will be

SunOS 5.8           Last change: 10 Nov 1999                    1

Sockets Library Functions                           rcmd(3SOCKET)

     set  up,  and  a  descriptor for it will be placed in *fd2p.
     The control process will return diagnostic output  from  the
     command  (file  descriptor 2) on this channel, and will also
     accept bytes on this channel as signal numbers, to  be  for-
     warded  to  the process group of the command.  If fd2p is 0,
     then the standard error (file descriptor 2)  of  the  remote
     command  will be made the same as its standard output and no
     provision is made  for  sending  arbitrary  signals  to  the
     remote  process,  although you may be able to get its atten-
     tion by using out-of-band data.

     The protocol is described in detail in in.rshd(1M).

     The rresvport() and  rresvport_af()  routines  are  used  to
     obtain  a  socket  bound  to a privileged port number.  This
     socket is suitable for use by rcmd() and rresvport_af()  and
     several  other routines. Privileged Internet ports are those
     in the range 1 to 1023.  Only the superuser  is  allowed  to
     bind  a  socket to a privileged port number. The application
     must pass in port, which must be in the range 512  to  1023.
     The  system  first tries to bind to that port number.  If it
     fails, the system then  tries  to  bind  to  another  unused
     privileged port, if one is available.

     ruserok() takes a remote  host's  name,  as  returned  by  a
     gethostbyaddr()  routine, two user names and a flag indicat-
     ing whether the local user's name is that of the  superuser.
     See   gethostbyname(3NSL).   It   then   checks   the  files
     /etc/hosts.equiv and possibly .rhosts in  the  local  user's
     home directory to see if the request for service is allowed.
     0  is  returned  if  the  machine  name  is  listed  in  the
     /etc/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
     /etc/hosts.equiv file is bypassed.

RETURN VALUES
     rcmd() and rcmd_af() return a valid socket  descriptor  upon
     success.  They  returns -1 upon error and print a diagnostic
     message to standard error.

     rresvport() and rresvport_af() return a valid, bound  socket
     descriptor  upon success. They return -1 upon error with the
     global value errno set according to the reason for failure.

FILES
     /etc/hosts.equiv
           system trusted hosts and users

     ~/.rhosts
           user's trusted hosts and users

SunOS 5.8           Last change: 10 Nov 1999                    2

Sockets Library Functions                           rcmd(3SOCKET)

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Unsafe                      |
    |_____________________________|_____________________________|

SEE ALSO
     rlogin(1),  rsh(1),  in.rexecd(1M),  in.rshd(1M),  intro(2),
     gethostbyname(3NSL),               getipnodebyname(3SOCKET),
     rexec(3SOCKET), attributes(5)

NOTES
     The error code EAGAIN is overloaded  to  mean  "All  network
     ports in use."

     These interfaces are unsafe in  multithreaded  applications.
     Unsafe  interfaces  should  be  called  only  from  the main
     thread.

SunOS 5.8           Last change: 10 Nov 1999                    3