Regenerate configure.
[dump.git] / rmt / rmt.8.in
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. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\" $Id: rmt.8.in,v 1.10 2003/03/30 15:40:40 stelian Exp $
29 .\"
30 .TH RMT 8 "version __VERSION__ of __DATE__" BSD "System management commands"
31 .SH NAME
32 rmt \- remote magtape protocol module
33 .SH SYNOPSIS
34 .B rmt
35 .SH DESCRIPTION
36 .B Rmt
37 is a program used by the remote
38 .BR dump (8),
39 .BR restore (8)
40 or
41 .BR tar (1)
42 programs in manipulating a magnetic tape drive through an interprocess
43 communication connection.
44 .B Rmt
45 is normally started up with an
46 .BR rexec (3)
47 or
48 .BR rcmd (3)
49 call.
50 .PP
51 The
52 .B rmt
53 program accepts requests specific to the manipulation of magnetic tapes,
54 performs the commands, then responds with a status indication. All responses
55 are in
56 .B ASCII
57 and in one of the following two forms.
58 .PP
59 Successful commands have responses of:
60 .RS
61 .B A\fInumber\fR\en
62 .RE
63 .PP
64 where
65 .I number
66 is an
67 .B ASCII
68 representation of a decimal number.
69 .PP
70 Unsuccessful commands are responded to with:
71 .RS
72 .B E\fIerror-number\fR\en\fIerror-message\fR\en
73 .RE
74 .PP
75 where
76 .I error-number
77 is one of the possible error numbers described in
78 .BR intro (2)
79 and
80 .I error-message
81 is the corresponding error string as printed from a call to
82 .BR perror (3).
83 .PP
84 The protocol is comprised of the following commands, which are sent as
85 indicated - no spaces are supplied between the command and its arguments, or
86 between its arguments, and \en indicates that a newline should be supplied:
87 .TP
88 .B O\fIdevice\fR\en\fImode\fR\en
89 Open the specified
90 .I device
91 using the indicated
92 .IR mode .
93 .I Device
94 is a full pathname and
95 .I mode
96 is an
97 .B ASCII
98 representation of a decimal number suitable for passing to
99 .BR open (2).
100 If a device had already been opened, it is closed before a new open is
101 performed.
102 .TP
103 .B C\fIdevice\fR\en
104 Close the currently open device. The
105 .I device
106 specified is ignored.
107 .TP
108 .B L\fIwhence\fR\en\fIoffset\fR\en
109 Perform an
110 .BR lseek (2)
111 operation using the specified parameters. The response value is that returned
112 from the
113 .B lseek
114 call.
115 .TP
116 .B W\fIcount\fR\en
117 Write data onto the open device.
118 .B Rmt
119 reads
120 .I count
121 bytes from the connection, aborting if a premature end-of-file is encountered.
122 The response value is that returned from the
123 .BR write (2)
124 call.
125 .TP
126 .B R\fIcount\fR\en
127 Read
128 .I count
129 bytes of data from the open device. If
130 .I count
131 exceeds the size of the data buffer (10 kilobytes), it is truncated to the
132 data buffer size.
133 .B Rmt
134 then performs the requested
135 .BR read (2)
136 and responds with
137 .B A\fIcount-read\fR\en
138 if the read was successful; otherwise an error in the standard format is
139 returned. If the read was successful, the data read is then sent.
140 .TP
141 .B I\fIoperation\fR\en\fIcount\fR\en
142 Perform a
143 .B MTIOCOP
144 .BR ioctl (2)
145 command using the specified parameters. The parameters are interpreted as the
146 .B ASCII
147 representations of the decimal values to place in the
148 .B mt_op
149 and
150 .B mt_count
151 fields of the structure used in the
152 .B ioctl
153 call. The return value is the
154 .I count
155 parameter when the operation is successful.
156 .IP
157 By issuing the
158 .B I-1\en0\en
159 command, a client will specify that he is using the VERSION 1 protocol.
160 .IP
161 For a VERSION 0 client, the
162 .I operation
163 parameter is the platform
164 .B mt_op
165 value (could be different if the client and the
166 .B rmt
167 server are on two different platforms). For a VERSION 1 client, the
168 .I operation
169 parameter is standardized as below:
170 .RS
171 .TP
172 .B 0
173 Issue a
174 .B MTWEOF
175 command (write
176 .I count
177 end-of-file records).
178 .TP
179 .B 1
180 Issue a
181 .B MTFSF
182 command (forward space over
183 .I count
184 file marks).
185 .TP
186 .B 2
187 Issue a
188 .B MTBSF
189 command (backward space over
190 .I count
191 file marks).
192 .TP
193 .B 3
194 Issue a
195 .B MTFSR
196 command (forward space
197 .I count
198 inter-record gaps).
199 .TP
200 .B 4
201 Issue a
202 .B MTBSR
203 command (backward space
204 .I count
205 inter-record gaps).
206 .TP
207 .B 5
208 Issue a
209 .B MTREW
210 command (rewind).
211 .TP
212 .B 6
213 Issue a
214 .B MTOFFL
215 command (rewind and put the drive offline).
216 .TP
217 .B 7
218 Issue a
219 .B MTNOP
220 command (no operation, set status only).
221 .RE
222 .TP
223 .B i\fIoperation\fR\en\fIcount\fR\en
224 Perform an extended
225 .B MTIOCOP
226 .BR ioctl (2)
227 command using the specified parameters. The parameters are interpreted as the
228 .B ASCII
229 representations of the decimal values to place in the
230 .B mt_op
231 and
232 .B mt_count
233 fields of the structure used in the
234 .B ioctl
235 call. The return value is the
236 .I count
237 parameter when the operation is successful. The possible operations are:
238 .RS
239 .TP
240 .B 0
241 Issue a
242 .B MTCACHE
243 command (switch cache on).
244 .TP
245 .B 1
246 Issue a
247 .B MTNOCACHE
248 command (switch cache off).
249 .TP
250 .B 2
251 Issue a
252 .B MTRETEN
253 command (retension the tape).
254 .TP
255 .B 3
256 Issue a
257 .B MTERASE
258 command (erase the entire tape).
259 .TP
260 .B 4
261 Issue a
262 .B MTEOM
263 command (position to end of media).
264 .TP
265 .B 5
266 Issue a
267 .B MTNBSF
268 command (backward space count files to BOF).
269 .RE
270 .TP
271 .B S
272 Return the status of the open device, as obtained with a
273 .B MTIOCGET
274 .B ioctl
275 call. If the operation was successful, an \*(lqack\*(rq is sent with the size
276 of the status buffer, then the status buffer is sent (in binary, which is
277 non-portable between different platforms).
278 .TP
279 .BI s sub-command
280 This is a replacement for the previous
281 .B S
282 command, portable across different platforms. If the open device is a magnetic
283 tape, return members of the magnetic tape status structure, as obtained with a
284 .B MTIOCGET
285 ioctl call. If the open device is not a magnetic tape, an error is returned. If
286 the
287 .B MTIOCGET
288 operation was successful, the numerical value of the structure member is
289 returned in decimal. The following sub commands are supported:
290 .RS
291 .TP
292 .B T
293 return the content of the structure member
294 .B mt_type
295 which contains the type of the magnetic tape device.
296 .TP
297 .B D
298 return the content of the structure member
299 .B mt_dsreg
300 which contains the "drive status register".
301 .TP
302 .B E
303 return the content of the structure member
304 .B mt_erreg
305 which contains the "error register". This structure member must be retrieved
306 first because it is cleared after each
307 .B MTIOCGET
308 ioctl call.
309 .TP
310 .B R
311 return the content of the structure member
312 .B mt_resid
313 which contains the residual count of the last I/O.
314 .TP
315 .B F
316 return the content of the structure member
317 .B mt_fileno
318 which contains the file number of the current tape position.
319 .TP
320 .B B
321 return the content of the structure member
322 .B mt_blkno
323 which contains the block number of the current tape position.
324 .TP
325 .B f
326 return the content of the structure member
327 .B mt_flags
328 which contains MTF_ flags from the driver.
329 .TP
330 .B b
331 return the content of the structure member
332 .B mt_bf
333 which contains the optimum blocking factor.
334 .RE
335 .PP
336 Any other command causes
337 .B rmt
338 to exit.
339 .SH DIAGNOSTICS
340 All responses are of the form described above.
341 .SH SEE ALSO
342 .BR rcmd (3),
343 .BR rexec (3),
344 .I /usr/include/sys/mtio.h,
345 .BR rdump (8),
346 .BR rrestore (8)
347 .SH BUGS
348 People should be discouraged from using this for a remote file access protocol.
349 .SH AUTHOR
350 The
351 .B dump/restore
352 backup suit was ported to Linux's Second Extended File System by Remy Card
353 <card@Linux.EU.Org>. He maintained the initial versions of
354 .B dump
355 (up and including 0.4b4, released in january 1997).
356 .PP
357 Starting with 0.4b5, the new maintainer is Stelian Pop <stelian@popies.net>.
358 .SH AVAILABILITY
359 The
360 .B dump/restore
361 backup suit is available from <http://dump.sourceforge.net>
362 .SH HISTORY
363 The
364 .B rmt
365 command appeared in 4.2BSD.