Man pages rewrite.

[dump.git] / rmt / rmt.8.in

diff --git a/rmt/rmt.8.in b/rmt/rmt.8.in
index 6e93213178e2fcbce436b84b5d24eba618757e4b..228d2b24979c84c17f64e83b74a6d3ae7fe5f182 100644 (file)
--- a/rmt/rmt.8.in
+++ b/rmt/rmt.8.in
@@ -29,339 +29,341 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
 .\" 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 
 is a program used by the remote 

-.Nm dump,
-.Nm restore 
+.BR dump (8),
+.BR restore (8)

 or
 or

-.Nm tar
+.BR tar (1)

 programs in manipulating a magnetic tape drive through an interprocess
 communication connection.
 programs in manipulating a magnetic tape drive through an interprocess
 communication connection.

-.Nm rmt
+.B Rmt

 is normally started up with an
 is normally started up with an

-.Xr rexec 3
+.BR rexec (3)

 or
 or

-.Xr rcmd 3
+.BR rcmd (3)

 call.
 call.

-.Pp
+.PP

 The 
 The 

-.Nm
+.B rmt

 program accepts requests specific to the manipulation of magnetic tapes, 
 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.
 and in one of the following two forms.

-.Pp
+.PP

 Successful commands have responses of:
 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
 where

-.Ar number
+.I number

 is an
 is an

-.Tn ASCII
+.B ASCII

 representation of a decimal number.
 representation of a decimal number.

-.Pp
+.PP

 Unsuccessful commands are responded to with:
 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
 is one of the possible error numbers described in

-.Xr intro 2
+.BR intro (2)

 and
 and

-.Ar error-message
+.I error-message

 is the corresponding error string as printed from a call to
 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 
 Open the specified 

-.Ar device
+.I device

 using the indicated
 using the indicated

-.Ar mode .
-.Ar Device
+.IR mode .
+.I Device

 is a full pathname and
 is a full pathname and

-.Ar mode
+.I mode

 is an
 is an

-.Tn ASCII
+.B ASCII

 representation of a decimal number suitable for passing to
 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
 Close the currently open device.  The

-.Ar device
+.I device

 specified is ignored.
 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
 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.
 call.

-.Sm off
-.It Sy W Ar count No \en
-.Sm on
+.TP
+.B W\fIcount\fR\en

 Write data onto the open device.
 Write data onto the open device.

-.Nm rmt
+.B Rmt

 reads
 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
 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.
 call.

-.Sm off
-.It Sy R Ar count No \en
-.Sm on
+.TP
+.B R\fIcount\fR\en

 Read
 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 
 then performs the requested 

-.Xr read 2
+.BR read (2)

 and responds with 
 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
 Perform a

-.Dv MTIOCOP
-.Xr ioctl 2
+.B MTIOCOP
+.BR ioctl (2)

 command using the specified parameters.  The parameters are interpreted as the
 command using the specified parameters.  The parameters are interpreted as the

-.Tn ASCII
+.B ASCII

 representations of the decimal values to place in the 
 representations of the decimal values to place in the 

-.Ar mt_op
+.B mt_op

 and
 and

-.Ar mt_count
+.B mt_count

 fields of the structure used in the
 fields of the structure used in the

-.Xr ioctl
+.B ioctl

 call.  The return value is the
 call.  The return value is the

-.Ar count
+.I count

 parameter when the operation is successful.
 parameter when the operation is successful.

-.Pp
+.IP

 By issuing the
 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.
 command, a client will specify that he is using the VERSION 1 protocol.

-.Pp
+.IP

 For a VERSION 0 client, the
 For a VERSION 0 client, the

-.Ar operation
+.I operation

 parameter is the platform 
 parameter is the platform 

-.Ar mt_op
+.B mt_op

 value (could be different if the client and the
 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:
 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).
 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).
 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).
 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).
 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).
 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
 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 
 representations of the decimal values to place in the 

-.Ar mt_op
+.B mt_op

 and
 and

-.Ar mt_count
+.B mt_count

 fields of the structure used in the
 fields of the structure used in the

-.Xr ioctl
+.B ioctl

 call.  The return value is the
 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:
 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
 return the content of the structure member

-.Ar mt_type
+.B mt_type

 which contains the type of the magnetic tape device.
 which contains the type of the magnetic tape device.

-.It Ic D
+.TP
+.B D

 return the content of the structure member
 return the content of the structure member

-.Ar mt_dsreg
+.B mt_dsreg

 which contains the "drive status register".
 which contains the "drive status register".

-.It Ic E
+.TP
+.B E

 return the content of the structure member
 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
 which contains the "error register". This structure member must be retrieved
 first because it is cleared after each

-.Dv MTIOCGET
+.B MTIOCGET

 ioctl call.
 ioctl call.

-.It Ic R
+.TP
+.B R

 return the content of the structure member
 return the content of the structure member

-.Ar mt_resid
+.B mt_resid

 which contains the residual count of the last I/O.
 which contains the residual count of the last I/O.

-.It Ic F
+.TP
+.B F

 return the content of the structure member
 return the content of the structure member

-.Ar mt_fileno
+.B mt_fileno

 which contains the file number of the current tape position.
 which contains the file number of the current tape position.

-.It Ic B
+.TP
+.B B

 return the content of the structure member
 return the content of the structure member

-.Ar mt_blkno
+.B mt_blkno

 which contains the block number of the current tape position.
 which contains the block number of the current tape position.

-.It Ic f
+.TP
+.B f

 return the content of the structure member
 return the content of the structure member

-.Ar mt_flags
+.B mt_flags

 which contains MTF_ flags from the driver.
 which contains MTF_ flags from the driver.

-.It Ic b
+.TP
+.B b

 return the content of the structure member
 return the content of the structure member

-.Ar mt_bf
+.B mt_bf

 which contains the optimum blocking factor.
 which contains the optimum blocking factor.

-.El
-.El
-.Sm on
-.Pp
+.RE
+.PP

 Any other command causes 
 Any other command causes 

-.Nm
+.B rmt

 to exit.
 to exit.

-.Sh DIAGNOSTICS
+.SH DIAGNOSTICS

 All responses are of the form described above.
 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
 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
 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
 The

-.Nm
-command appeared in
-.Bx 4.2 .
+.B rmt
+command appeared in 4.2BSD.