X-Git-Url: https://git.wh0rd.org/?p=dump.git;a=blobdiff_plain;f=rmt%2Frmt.8.in;h=228d2b24979c84c17f64e83b74a6d3ae7fe5f182;hp=f986a3e05659b999b8ed10de0cb863e3eb1510bf;hb=1c736b782dfb4cf419bc53bcc795537585a283bc;hpb=ebcbe7f6c10482913b60fc792e72e494b439b242 diff --git a/rmt/rmt.8.in b/rmt/rmt.8.in index f986a3e..228d2b2 100644 --- a/rmt/rmt.8.in +++ b/rmt/rmt.8.in @@ -29,204 +29,341 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: rmt.8.in,v 1.4 2000/01/21 10:17:41 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 . 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 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.