X-Git-Url: https://git.wh0rd.org/?p=dump.git;a=blobdiff_plain;f=rmt%2Frmt.8.in;fp=rmt%2Frmt.8.in;h=228d2b24979c84c17f64e83b74a6d3ae7fe5f182;hp=6e93213178e2fcbce436b84b5d24eba618757e4b;hb=153f9a83677b05d887ecec5dde9b4c4be8e3c8ca;hpb=2a2e321dfe4fd80e0c961355b950bf4e6a1cfd68 diff --git a/rmt/rmt.8.in b/rmt/rmt.8.in index 6e93213..228d2b2 100644 --- 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. .\" -.\" $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 . 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 -. -.Sh AVAILABILITY +.B dump/restore +backup suit was ported to Linux's Second Extended File System by Remy Card +. 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 . +.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 +.SH HISTORY The -.Nm -command appeared in -.Bx 4.2 . +.B rmt +command appeared in 4.2BSD.