.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" $Id: rmt.8.in,v 1.8 2002/04/15 11:57:29 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
+.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
-.Nm dump,
-.Nm restore
+.BR dump (8),
+.BR restore (8)
or
-.Nm tar
+.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
+.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
-.Tn ASCII
+performs the commands, then responds with a status indication. All responses
+are in
+.B ASCII
and in one of the following two forms.
-.Pp
+.PP
Successful commands have responses of:
-.Bd -filled -offset indent
-.Sm off
-.Sy A Ar number No \en
-.Sm on
-.Ed
-.Pp
+.RS
+.B A\fInumber\fR\en
+.RE
+.PP
where
-.Ar number
+.I number
is an
-.Tn ASCII
+.B ASCII
representation of a decimal number.
-.Pp
+.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
-where
-.Ar error-number
+.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
-.Xr intro 2
+.BR intro (2)
and
-.Ar error-message
+.I error-message
is the corresponding error string as printed from a call to
-.Xr 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
-.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
-.Sm on
+.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
+.B 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.
-.Sm off
-.It Xo Sy C Ar device No \en
-.Xc
-.Sm on
+.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.
-.Sm off
-.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
+.I 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
+.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
+.B MTIOCOP
+.BR ioctl (2)
command using the specified parameters. The parameters are interpreted as the
-.Tn ASCII
+.B ASCII
representations of the decimal values to place in the
-.Ar mt_op
+.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.
-.Pp
+.IP
By issuing the
-.Ql I-1\en0\en
+.B I-1\en0\en
command, a client will specify that he is using the VERSION 1 protocol.
-.Pp
+.IP
For a VERSION 0 client, the
-.Ar operation
+.I operation
parameter is the platform
-.Ar mt_op
+.B mt_op
value (could be different if the client and the
-.Nm
-server are on two different platforms). For a VERSION 1 client,
-the
-.Ar operation
+.B rmt
+server are on two different platforms). For a VERSION 1 client, the
+.I operation
parameter is standardized as below:
-.Bl -tag -width Fl
-.It Ic 0
-Issue a MTWEOF command (write
-.Ar count
+.RS
+.TP
+.B 0
+Issue a
+.B MTWEOF
+command (write
+.I count
end-of-file records).
-.It Ic 1
-Issue a MTFSF command (forward space over
-.Ar count
+.TP
+.B 1
+Issue a
+.B MTFSF
+command (forward space over
+.I count
file marks).
-.It Ic 2
-Issue a MTBSF command (backward space over
-.Ar count
+.TP
+.B 2
+Issue a
+.B MTBSF
+command (backward space over
+.I count
file marks).
-.It Ic 3
-Issue a MTFSR command (forward space
-.Ar count
+.TP
+.B 3
+Issue a
+.B MTFSR
+command (forward space
+.I count
inter-record gaps).
-.It Ic 4
-Issue a MTBSR command (backward space
-.Ar count
+.TP
+.B 4
+Issue a
+.B MTBSR
+command (backward space
+.I count
inter-record gaps).
-.It Ic 5
-Issue a MTREW command (rewind).
-.It Ic 6
-Issue a MTOFFL command (rewind and put the drive offline).
-.It Ic 7
-Issue a MTNOP command (no operation, set status only).
-.El
-.Sm off
-.It Xo Sy i Ar operation
-.No \en Ar count No \en
-.Xc
-.Sm on
+.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
-.Dv MTIOCOP
-.Xr ioctl 2
-command using the specified parameters.
-The parameters are interpreted as the
-.Tn ASCII
+.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
-.Ar mt_op
+.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
-parameter when the operation is successful.
-The possible operations are:
-.Bl -tag -width Fl
-.It Ic 0
-Issue a MTCACHE command (switch cache on).
-.It Ic 1
-Issue a MTNOCACHE command (switch cache off).
-.It Ic 2
-Issue a MTRETEN command (retension the tape).
-.It Ic 3
-Issue a MTERASE command (erase the entire tape).
-.It Ic 4
-Issue a MTEOM command (position to end of media).
-.It Ic 5
-Issue a MTNBSF command (backward space count files to BOF).
-.El
-.ne 1i
-.Sm off
-.It Sy S
-.Sm on
-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, which is non-portable between different platforms).
-.Sm off
-.It Xo Sy s Ar sub-command
-.Xc
-.Sm on
-This is a replacement for the previous 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
-.Dv MTIOCGET
-ioctl call. If the open device is not a magnetic tape, an error is returned.
-If the
-.Dv MTIOCGET
+.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:
-.Bl -tag -width Fl
-.It Ic T
+.RS
+.TP
+.B T
return the content of the structure member
-.Ar mt_type
+.B mt_type
which contains the type of the magnetic tape device.
-.It Ic D
+.TP
+.B D
return the content of the structure member
-.Ar mt_dsreg
+.B mt_dsreg
which contains the "drive status register".
-.It Ic E
+.TP
+.B E
return the content of the structure member
-.Ar mt_erreg
+.B mt_erreg
which contains the "error register". This structure member must be retrieved
first because it is cleared after each
-.Dv MTIOCGET
+.B MTIOCGET
ioctl call.
-.It Ic R
+.TP
+.B R
return the content of the structure member
-.Ar mt_resid
+.B mt_resid
which contains the residual count of the last I/O.
-.It Ic F
+.TP
+.B F
return the content of the structure member
-.Ar mt_fileno
+.B mt_fileno
which contains the file number of the current tape position.
-.It Ic B
+.TP
+.B B
return the content of the structure member
-.Ar mt_blkno
+.B mt_blkno
which contains the block number of the current tape position.
-.It Ic f
+.TP
+.B f
return the content of the structure member
-.Ar mt_flags
+.B mt_flags
which contains MTF_ flags from the driver.
-.It Ic b
+.TP
+.B b
return the content of the structure member
-.Ar mt_bf
+.B mt_bf
which contains the optimum blocking factor.
-.El
-.El
-.Sm on
-.Pp
+.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 /usr/include/sys/mtio.h ,
-.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
-<stelian@popies.net>.
-.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