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