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