CRUX-ARM : Home

Home :: Documentation :: Download :: Development :: Community :: Ports :: Packages :: Bugs :: Links :: About :: Donors
procps: updated to 3.3.3 and aligned with upstream. Cleaned cross patches.
[crossrootfs.git] / tar / rmt.8
1 .\" Copyright (c) 1983, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" @(#)rmt.8 8.2 (Berkeley) 12/11/93
33 .\"
34 .Dd December 11, 1993
35 .Dt RMT 8
36 .Os BSD 4.2
37 .Sh NAME
38 .Nm rmt
39 .Nd remote magtape protocol module
40 .Sh SYNOPSIS
41 .Nm rmt
42 .Sh DESCRIPTION
43 .Nm Rmt
44 is a program used by tar, cpio, mt, and the remote dump and restore
45 programs in manipulating a magnetic tape drive through an interprocess
46 communication connection.
47 .Nm Rmt
48 is normally started up with an
49 .Xr rexec 3
50 or
51 .Xr rcmd 3
52 call or the
53 .Xr rsh 1
54 command.
55 .Pp
56 The
57 .Nm rmt
58 program accepts requests specific to the manipulation of
59 magnetic tapes, performs the commands, then responds with
60 a status indication. All responses are in
61 .Tn ASCII
62 and in
63 one of two forms.
64 Successful commands have responses of:
65 .Bd -filled -offset indent
66 .Sm off
67 .Sy A Ar number No \en
68 .Sm on
69 .Ed
70 .Pp
71 .Ar Number
72 is an
73 .Tn ASCII
74 representation of a decimal number.
75 Unsuccessful commands are responded to with:
76 .Bd -filled -offset indent
77 .Sm off
78 .Xo Sy E Ar error-number
79 .No \en Ar error-message
80 .No \en
81 .Xc
82 .Sm on
83 .Ed
84 .Pp
85 .Ar Error-number
86 is one of the possible error
87 numbers described in
88 .Xr intro 2
89 and
90 .Ar error-message
91 is the corresponding error string as printed
92 from a call to
93 .Xr perror 3 .
94 The protocol is comprised of the
95 following commands, which are sent as indicated - no spaces are supplied
96 between the command and its arguments, or between its arguments, and
97 .Ql \en
98 indicates that a newline should be supplied:
99 .Bl -tag -width Ds
100 .Sm off
101 .It Xo Sy \&O Ar device
102 .No \en Ar mode No \en
103 .Xc
104 Open the specified
105 .Ar device
106 using the indicated
107 .Ar mode .
108 .Ar Device
109 is a full pathname and
110 .Ar mode
111 is an
112 .Tn ASCII
113 representation of a decimal
114 number suitable for passing to
115 .Xr open 2 .
116 If a device had already been opened, it is
117 closed before a new open is performed.
118 .It Xo Sy C Ar device No \en
119 .Xc
120 Close the currently open device. The
121 .Ar device
122 specified is ignored.
123 .It Xo Sy L
124 .Ar offset No \en
125 .Ar whence No \en
126 .Xc
127 .Sm on
128 Perform an
129 .Xr lseek 2
130 operation using the specified parameters.
131 The response value is that returned from the
132 .Xr lseek
133 call.
134 .Sm off
135 .It Sy W Ar count No \en
136 .Sm on
137 Write data onto the open device.
138 .Nm Rmt
139 reads
140 .Ar count
141 bytes from the connection, aborting if
142 a premature end-of-file is encountered.
143 The response value is that returned from
144 the
145 .Xr write 2
146 call.
147 .Sm off
148 .It Sy R Ar count No \en
149 .Sm on
150 Read
151 .Ar count
152 bytes of data from the open device.
153 If
154 .Ar count
155 exceeds the size of the data buffer (10 kilobytes), it is
156 truncated to the data buffer size.
157 .Nm rmt
158 then performs the requested
159 .Xr read 2
160 and responds with
161 .Sm off
162 .Sy A Ar count-read No \en
163 .Sm on
164 if the read was
165 successful; otherwise an error in the
166 standard format is returned. If the read
167 was successful, the data read is then sent.
168 .Sm off
169 .It Xo Sy I Ar operation
170 .No \en Ar count No \en
171 .Xc
172 .Sm on
173 Perform a
174 .Dv MTIOCOP
175 .Xr ioctl 2
176 command using the specified parameters.
177 The parameters are interpreted as the
178 .Tn ASCII
179 representations of the decimal values
180 to place in the
181 .Ar mt_op
182 and
183 .Ar mt_count
184 fields of the structure used in the
185 .Xr ioctl
186 call. The return value is the
187 .Ar count
188 parameter when the operation is successful.
189 .It Sy S
190 Return the status of the open device, as
191 obtained with a
192 .Dv MTIOCGET
193 .Xr ioctl
194 call. If the operation was successful,
195 an ``ack'' is sent with the size of the
196 status buffer, then the status buffer is
197 sent (in binary).
198 .El
199 .Sm on
200 .Pp
201 Any other command causes
202 .Nm rmt
203 to exit.
204 .Sh DIAGNOSTICS
205 All responses are of the form described above.
206 .Sh SEE ALSO
207 .Xr tar 1 ,
208 .Xr cpio 1 ,
209 .Xr mt 1 ,
210 .Xr rsh 1 ,
211 .Xr rcmd 3 ,
212 .Xr rexec 3 ,
213 .Xr mtio 4 ,
214 .Xr rdump 8 ,
215 .Xr rrestore 8
216 .Sh BUGS
217 People should be discouraged from using this for a remote
218 file access protocol.
219 .Sh HISTORY
220 The
221 .Nm
222 command appeared in
223 .Bx 4.2 .