man/man3/rcmd.3

   1 .\" Copyright (c) 1983 Regents of the University of California.
   2 .\" All rights reserved.  The Berkeley software License Agreement
   3 .\" specifies the terms and conditions for redistribution.
   4 .\"
   5 .\"     @(#)rcmd.3      6.7 (Berkeley) 5/14/86
   6 .\"
   7 .TH RCMD 3 "May 14, 1986"
   8 .UC 5
   9 .SH NAME
  10 rcmd, rresvport, ruserok \- routines for returning a stream to a remote command
  11 .SH SYNOPSIS
  12 .nf
  13 .B "#include <sys/types.h>"
  14 .B "#include <net/netlib.h>"
  15 .PP
  16 .B "rem = rcmd(ahost, inport, locuser, remuser, cmd, fd2p);"
  17 .B char **ahost;
  18 .B int inport;
  19 .B "char *locuser, *remuser, *cmd;"
  20 .B int *fd2p;
  21 .PP
  22 .B s = rresvport(port);
  23 .B int *port;
  24 .PP
  25 .B "ruserok(rhost, superuser, ruser, luser);"
  26 .B char *rhost;
  27 .B int superuser;
  28 .B char *ruser, *luser;
  29 .fi
  30 .SH DESCRIPTION
  31 .I Rcmd
  32 is a routine used by the super-user to execute a command on
  33 a remote machine using an authentication scheme based
  34 on reserved port numbers.
  35 .I Rresvport
  36 is a routine which returns a descriptor to a socket
  37 with an address in the privileged port space.
  38 .I Ruserok
  39 is a routine used by servers
  40 to authenticate clients requesting service with
  41 .IR rcmd .
  42 All three functions are present in the same file and are used
  43 by the
  44 .IR rshd (8)
  45 server (among others).
  46 .PP
  47 .I Rcmd
  48 looks up the host
  49 .I *ahost
  50 using
  51 .IR gethostbyname (3),
  52 returning \-1 if the host does not exist.
  53 Otherwise
  54 .I *ahost
  55 is set to the standard name of the host
  56 and a connection is established to a server
  57 residing at the well-known Internet port
  58 .IR inport .
  59 .PP
  60 If the connection succeeds,
  61 a socket in the Internet domain of type SOCK_STREAM
  62 is returned to the caller, and given to the remote
  63 command as
  64 .B stdin
  65 and
  66 .BR stdout .
  67 If
  68 .I fd2p
  69 is non-zero, then an auxiliary channel to a control
  70 process will be set up, and a descriptor for it will be placed
  71 in
  72 .IR *fd2p .
  73 The control process will return diagnostic
  74 output from the command (unit 2) on this channel, and will also
  75 accept bytes on this channel as being UNIX signal numbers, to be
  76 forwarded to the process group of the command.
  77 If
  78 .I fd2p
  79 is 0, then the
  80 .B stderr
  81 (unit 2 of the remote
  82 command) will be made the same as the
  83 .B stdout
  84 and no
  85 provision is made for sending arbitrary signals to the remote process,
  86 although you may be able to get its attention by using out-of-band data.
  87 .PP
  88 The protocol is described in detail in
  89 .IR rshd (8).
  90 .PP
  91 The
  92 .I rresvport
  93 routine is used to obtain a socket with a privileged
  94 address bound to it.  This socket is suitable for use
  95 by
  96 .I rcmd
  97 and several other routines.  Privileged Internet ports are those
  98 in the range 0 to 1023.  Only the super-user
  99 is allowed to bind an address of this sort to a socket.
 100 .PP
 101 .I Ruserok
 102 takes a remote host's name, as returned by a
 103 .IR gethostbyaddr (3)
 104 routine, two user names and a flag indicating whether
 105 the local user's name is that of the super-user.  It then
 106 checks the files
 107 .I /etc/hosts.equiv
 108 and, possibly,
 109 .I .rhosts
 110 in the current working directory (normally the local
 111 user's home directory) to see if the request for
 112 service is allowed.  A 0 is returned if the machine
 113 name is listed in the ``hosts.equiv'' file, or the
 114 host and remote user name are found in the ``.rhosts''
 115 file; otherwise
 116 .I ruserok
 117 returns \-1.  If the
 118 .I superuser
 119 flag is 1, the checking of the ``host.equiv'' file is
 120 bypassed.
 121 If the local domain (as obtained from \fIgethostname\fP\|(3))
 122 is the same as the remote domain, only the machine name need be specified.
 123 .SH SEE ALSO
 124 rlogin(1),
 125 rsh(1),
 126 intro(2),
 127 rexec(3),
 128 rexecd(8),
 129 rlogind(8),
 130 rshd(8)
 131 .SH DIAGNOSTICS
 132 .I Rcmd
 133 returns a valid socket descriptor on success.
 134 It returns -1 on error and prints a diagnostic message on the standard error.
 135 .PP
 136 .I Rresvport
 137 returns a valid, bound socket descriptor on success.
 138 It returns -1 on error with the global value
 139 .I errno
 140 set according to the reason for failure.
 141 The error code EAGAIN is overloaded to mean ``All network ports in use.''