.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" $Id: rmt.8.in,v 1.5 2000/01/21 10:23:30 stelian Exp $
+.\" $Id: rmt.8.in,v 1.9 2002/07/24 14:12:01 stelian Exp $
.\"
-.Dd __DATE__
-.Dt RMT 8
-.Os "rmt __VERSION__"
-.Sh NAME
-.Nm rmt
-.Nd remote magtape protocol module
-.Sh SYNOPSIS
-.Nm rmt
-.Sh DESCRIPTION
-.Nm Rmt
-is a program used by the remote dump and restore programs
-in manipulating a magnetic tape drive through an interprocess
+.TH RMT 8 "version __VERSION__ of __DATE__" BSD "System management commands"
+.SH NAME
+rmt \- remote magtape protocol module
+.SH SYNOPSIS
+.B rmt
+.SH DESCRIPTION
+.B Rmt
+is a program used by the remote
+.BR dump (8),
+.BR restore (8)
+or
+.BR tar (1)
+programs in manipulating a magnetic tape drive through an interprocess
communication connection.
-.Nm Rmt
+.B Rmt
is normally started up with an
-.Xr rexec 3
+.BR rexec (3)
or
-.Xr rcmd 3
+.BR rcmd (3)
call.
-.Pp
+.PP
The
-.Nm
-program accepts requests specific to the manipulation of
-magnetic tapes, performs the commands, then responds with
-a status indication. All responses are in
-.Tn ASCII
-and in
-one of two forms.
+.B rmt
+program accepts requests specific to the manipulation of magnetic tapes,
+performs the commands, then responds with a status indication. All responses
+are in
+.B ASCII
+and in one of the following two forms.
+.PP
Successful commands have responses of:
-.Bd -filled -offset indent
-.Sm off
-.Sy A Ar number No \en
-.Sm on
-.Ed
-.Pp
-.Ar Number
+.RS
+.B A\fInumber\fR\en
+.RE
+.PP
+where
+.I number
is an
-.Tn ASCII
+.B ASCII
representation of a decimal number.
+.PP
Unsuccessful commands are responded to with:
-.Bd -filled -offset indent
-.Sm off
-.Xo Sy E Ar error-number
-.No \en Ar error-message
-.No \en
-.Xc
-.Sm on
-.Ed
-.Pp
-.Ar Error-number
-is one of the possible error
-numbers described in
-.Xr intro 2
+.RS
+.B E\fIerror-number\fR\en\fIerror-message\fR\en
+.RE
+.PP
+where
+.I error-number
+is one of the possible error numbers described in
+.BR intro (2)
and
-.Ar error-message
-is the corresponding error string as printed
-from a call to
-.Xr perror 3 .
-The protocol is comprised of the
-following commands, which are sent as indicated - no spaces are supplied
-between the command and its arguments, or between its arguments, and
-.Ql \en
-indicates that a newline should be supplied:
-.Bl -tag -width Ds
-.Sm off
-.It Xo Sy \&O Ar device
-.No \en Ar mode No \en
-.Xc
+.I error-message
+is the corresponding error string as printed from a call to
+.BR perror (3).
+.PP
+The protocol is comprised of the following commands, which are sent as
+indicated - no spaces are supplied between the command and its arguments, or
+between its arguments, and \en indicates that a newline should be supplied:
+.TP
+.B O\fIdevice\fR\en\fImode\fR\en
Open the specified
-.Ar device
+.I device
using the indicated
-.Ar mode .
-.Ar Device
+.IR mode .
+.I Device
is a full pathname and
-.Ar mode
+.I mode
is an
-.Tn ASCII
-representation of a decimal
-number suitable for passing to
-.Xr open 2 .
-If a device had already been opened, it is
-closed before a new open is performed.
-.It Xo Sy C Ar device No \en
-.Xc
+.B ASCII
+representation of a decimal number suitable for passing to
+.BR open (2).
+If a device had already been opened, it is closed before a new open is
+performed.
+.TP
+.B C\fIdevice\fR\en
Close the currently open device. The
-.Ar device
+.I device
specified is ignored.
-.It Xo Sy L
-.Ar whence No \en
-.Ar offset No \en
-.Xc
-.Sm on
+.TP
+.B L\fIwhence\fR\en\fIoffset\fR\en
Perform an
-.Xr lseek 2
-operation using the specified parameters.
-The response value is that returned from the
-.Xr lseek
+.BR lseek (2)
+operation using the specified parameters. The response value is that returned
+from the
+.B lseek
call.
-.Sm off
-.It Sy W Ar count No \en
-.Sm on
+.TP
+.B W\fIcount\fR\en
Write data onto the open device.
-.Nm Rmt
+.B Rmt
reads
-.Ar count
-bytes from the connection, aborting if
-a premature end-of-file is encountered.
-The response value is that returned from
-the
-.Xr write 2
+.I count
+bytes from the connection, aborting if a premature end-of-file is encountered.
+The response value is that returned from the
+.BR write (2)
call.
-.Sm off
-.It Sy R Ar count No \en
-.Sm on
+.TP
+.B R\fIcount\fR\en
Read
-.Ar count
-bytes of data from the open device.
-If
-.Ar count
-exceeds the size of the data buffer (10 kilobytes), it is
-truncated to the data buffer size.
-.Nm Rmt
+.I count
+bytes of data from the open device. If
+.I count
+exceeds the size of the data buffer (10 kilobytes), it is truncated to the
+data buffer size.
+.B Rmt
then performs the requested
-.Xr read 2
+.BR read (2)
and responds with
-.Sm off
-.Sy A Ar count-read No \en
-.Sm on
-if the read was
-successful; otherwise an error in the
-standard format is returned. If the read
-was successful, the data read is then sent.
-.Sm off
-.It Xo Sy I Ar operation
-.No \en Ar count No \en
-.Xc
-.Sm on
+.B A\fIcount-read\fR\en
+if the read was successful; otherwise an error in the standard format is
+returned. If the read was successful, the data read is then sent.
+.TP
+.B I\fIoperation\fR\en\fIcount\fR\en
Perform a
-.Dv MTIOCOP
-.Xr ioctl 2
-command using the specified parameters.
-The parameters are interpreted as the
-.Tn ASCII
-representations of the decimal values
-to place in the
-.Ar mt_op
+.B MTIOCOP
+.BR ioctl (2)
+command using the specified parameters. The parameters are interpreted as the
+.B ASCII
+representations of the decimal values to place in the
+.B mt_op
and
-.Ar mt_count
+.B mt_count
fields of the structure used in the
-.Xr ioctl
+.B ioctl
call. The return value is the
-.Ar count
+.I count
parameter when the operation is successful.
-.ne 1i
-.It Sy S
-Return the status of the open device, as
-obtained with a
-.Dv MTIOCGET
-.Xr ioctl
-call. If the operation was successful,
-an ``ack'' is sent with the size of the
-status buffer, then the status buffer is
-sent (in binary).
-.El
-.Sm on
-.Pp
+.IP
+By issuing the
+.B I-1\en0\en
+command, a client will specify that he is using the VERSION 1 protocol.
+.IP
+For a VERSION 0 client, the
+.I operation
+parameter is the platform
+.B mt_op
+value (could be different if the client and the
+.B rmt
+server are on two different platforms). For a VERSION 1 client, the
+.I operation
+parameter is standardized as below:
+.RS
+.TP
+.B 0
+Issue a
+.B MTWEOF
+command (write
+.I count
+end-of-file records).
+.TP
+.B 1
+Issue a
+.B MTFSF
+command (forward space over
+.I count
+file marks).
+.TP
+.B 2
+Issue a
+.B MTBSF
+command (backward space over
+.I count
+file marks).
+.TP
+.B 3
+Issue a
+.B MTFSR
+command (forward space
+.I count
+inter-record gaps).
+.TP
+.B 4
+Issue a
+.B MTBSR
+command (backward space
+.I count
+inter-record gaps).
+.TP
+.B 5
+Issue a
+.B MTREW
+command (rewind).
+.TP
+.B 6
+Issue a
+.B MTOFFL
+command (rewind and put the drive offline).
+.TP
+.B 7
+Issue a
+.B MTNOP
+command (no operation, set status only).
+.RE
+.TP
+.B i\fIoperation\fR\en\fIcount\fR\en
+Perform an extended
+.B MTIOCOP
+.BR ioctl (2)
+command using the specified parameters. The parameters are interpreted as the
+.B ASCII
+representations of the decimal values to place in the
+.B mt_op
+and
+.B mt_count
+fields of the structure used in the
+.B ioctl
+call. The return value is the
+.I count
+parameter when the operation is successful. The possible operations are:
+.RS
+.TP
+.B 0
+Issue a
+.B MTCACHE
+command (switch cache on).
+.TP
+.B 1
+Issue a
+.B MTNOCACHE
+command (switch cache off).
+.TP
+.B 2
+Issue a
+.B MTRETEN
+command (retension the tape).
+.TP
+.B 3
+Issue a
+.B MTERASE
+command (erase the entire tape).
+.TP
+.B 4
+Issue a
+.B MTEOM
+command (position to end of media).
+.TP
+.B 5
+Issue a
+.B MTNBSF
+command (backward space count files to BOF).
+.RE
+.TP
+.B S
+Return the status of the open device, as obtained with a
+.B MTIOCGET
+.B ioctl
+call. If the operation was successful, an \*(lqack\*(rq is sent with the size
+of the status buffer, then the status buffer is sent (in binary, which is
+non-portable between different platforms).
+.TP
+.BI s sub-command
+This is a replacement for the previous
+.B S
+command, portable across different platforms. If the open device is a magnetic
+tape, return members of the magnetic tape status structure, as obtained with a
+.B MTIOCGET
+ioctl call. If the open device is not a magnetic tape, an error is returned. If
+the
+.B MTIOCGET
+operation was successful, the numerical value of the structure member is
+returned in decimal. The following sub commands are supported:
+.RS
+.TP
+.B T
+return the content of the structure member
+.B mt_type
+which contains the type of the magnetic tape device.
+.TP
+.B D
+return the content of the structure member
+.B mt_dsreg
+which contains the "drive status register".
+.TP
+.B E
+return the content of the structure member
+.B mt_erreg
+which contains the "error register". This structure member must be retrieved
+first because it is cleared after each
+.B MTIOCGET
+ioctl call.
+.TP
+.B R
+return the content of the structure member
+.B mt_resid
+which contains the residual count of the last I/O.
+.TP
+.B F
+return the content of the structure member
+.B mt_fileno
+which contains the file number of the current tape position.
+.TP
+.B B
+return the content of the structure member
+.B mt_blkno
+which contains the block number of the current tape position.
+.TP
+.B f
+return the content of the structure member
+.B mt_flags
+which contains MTF_ flags from the driver.
+.TP
+.B b
+return the content of the structure member
+.B mt_bf
+which contains the optimum blocking factor.
+.RE
+.PP
Any other command causes
-.Nm
+.B rmt
to exit.
-.Sh DIAGNOSTICS
+.SH DIAGNOSTICS
All responses are of the form described above.
-.Sh SEE ALSO
-.Xr rcmd 3 ,
-.Xr rexec 3 ,
-.Xr mtio 4 ,
-.Xr rdump 8 ,
-.Xr rrestore 8
-.Sh BUGS
-People should be discouraged from using this for a remote
-file access protocol.
-.Sh AUTHOR
+.SH SEE ALSO
+.BR rcmd (3),
+.BR rexec (3),
+.I /usr/include/sys/mtio.h,
+.BR rdump (8),
+.BR rrestore (8)
+.SH BUGS
+People should be discouraged from using this for a remote file access protocol.
+.SH AUTHOR
The
-.Nm dump/restore
-backup suit was ported to Linux's Second Extended File System
-by Remy Card <card@Linux.EU.Org>. He maintained the initial versions
-of dump (up and including 0.4b4, released in january 1997).
-.Pp
-Starting with 0.4b5, the new maintainer is Stelian Pop
-.br
-<pop@cybercable.fr>.
-.Sh AVAILABILITY
+.B dump/restore
+backup suit was ported to Linux's Second Extended File System by Remy Card
+<card@Linux.EU.Org>. He maintained the initial versions of
+.B dump
+(up and including 0.4b4, released in january 1997).
+.PP
+Starting with 0.4b5, the new maintainer is Stelian Pop <stelian@popies.net>.
+.SH AVAILABILITY
The
-.Nm dump/restore
-backup suit is available from
-.br
-http://dump.sourceforge.net
-.Sh HISTORY
+.B dump/restore
+backup suit is available from <http://dump.sourceforge.net>
+.SH HISTORY
The
-.Nm
-command appeared in
-.Bx 4.2 .
+.B rmt
+command appeared in 4.2BSD.
git.wh0rd.org / dump.git / blobdiff