1.\" Copyright (c) 1981, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. All advertising materials mentioning features or use of this software 14.\" must display the following acknowledgement: 15.\" This product includes software developed by the University of 16.\" California, Berkeley and its contributors. 17.\" 4. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" @(#)mt.1 8.1 (Berkeley) 6/6/93 34.\" $FreeBSD$ 35.\" 36.Dd June 6, 1993 37.Dt MT 1 38.Os 39.Sh NAME 40.Nm mt 41.Nd magnetic tape manipulating program 42.Sh SYNOPSIS 43.Nm 44.Op Fl f Ar tapename 45.Ar command 46.Op Ar count 47.Nm 48.Op Fl f Ar tapename 49.Ar command 50.Ar argument 51.Sh DESCRIPTION 52The 53.Nm 54utility is used to command a magnetic tape drive for operations 55other than reading or writing data. 56.Pp 57The 58.Fl f 59option's 60.Ar tapename 61overrides the TAPE environment variable described below. 62.Pp 63The available commands are listed below. 64Only as many 65characters as are required to uniquely identify a command 66need be specified. 67.Pp 68The following commands optionally take a 69.Ar count , 70which defaults to 1. 71.Bl -tag -width "erase" 72.It Cm weof 73Write 74.Ar count 75end-of-file (EOF) marks at the current position. 76.It Cm smk 77Write 78.Ar count 79setmarks at the current position. 80.It Cm fsf 81Forward space 82.Ar count 83files. 84.It Cm fsr 85Forward space 86.Ar count 87records. 88.It Cm fss 89Forward space 90.Ar count 91setmarks. 92.It Cm bsf 93Backward space 94.Ar count 95files. 96.It Cm bsr 97Backward space 98.Ar count 99records. 100.It Cm bss 101Backward space 102.Ar count 103setmarks. 104.It Cm erase 105Erase the tape using a long (often very long) method. 106With a 107.Ar count 108of 0, it will erase the tape using a quick method. 109Operation is not guaranteed if the tape is not at its beginning. 110The tape will be at its beginning upon completion. 111.El 112.Pp 113The following commands ignore 114.Ar count . 115.Bl -tag -width "geteotmodel" 116.It Cm rdhpos 117Read the hardware block position. 118The block 119number reported is specific for that hardware only. 120With drive data compression especially, 121this position may have more to do with the amount of data 122sent to the drive than the amount of data written to tape. 123Some drives do not support this. 124.It Cm rdspos 125Read the SCSI logical block position. 126This typically is greater than the hardware position 127by the number of end-of-file marks. 128Some drives do not support this. 129.It Cm rewind 130Rewind the tape. 131.It Cm offline , rewoffl 132Rewind the tape and place the drive off line. 133Some drives are never off line. 134.It Cm retension 135Re-tension the tape. 136This winds the tape from the current position to the end 137and then to the beginning. 138This sometimes improves subsequent reading and writing, 139particularly for streaming drives. 140Some drives do not support this. 141.It Cm status 142Output status information about the drive. 143For SCSI magnetic tape devices, 144the current operating modes of density, blocksize, and whether compression 145is enabled is reported. 146The current state of the driver (what it thinks that 147it is doing with the device) is reported. 148If the driver knows the relative 149position from BOT (in terms of filemarks and records), it outputs that. 150Note 151that this information is not definitive (only BOT, End of Recorded Media, and 152hardware or SCSI logical block position (if the drive supports such) are 153considered definitive tape positions). 154.It Cm errstat 155Output (and clear) error status information about this device. 156For every normal 157operation (e.g., a read or a write) and every control operation (e.g,, a 158rewind), the driver stores up the last command executed and it is associated 159status and any residual counts (if any). 160This command retrieves and outputs this 161information. 162If possible, this also clears any latched error information. 163.It Cm geteotmodel 164Output the current EOT filemark model. 165The model states how 166many filemarks will be written at close if a tape was being written. 167.It Cm eod , eom 168Wind the tape to the end of the recorded data, 169typically after an EOF mark where another file may be written. 170.El 171.Pp 172The following commands require an 173.Ar argument . 174.Bl -tag -width "seteotmodel" 175.It Cm sethpos 176Set the hardware block position. 177The 178.Ar argument 179is a hardware block number to which to position the tape. 180Some drives do not support this. 181.It Cm setspos 182Set the SCSI logical block position. 183The 184.Ar argument 185is a SCSI logical block number to which to position the tape. 186Some drives do not support this. 187.It Cm blocksize 188Set the block size for the drive. 189The 190.Ar argument 191is the number of bytes per block, 192except 0 commands the drive to use variable-length blocks. 193.It Cm seteotmodel 194Set the EOT filemark model to 195.Ar argument 196and output the old and new models. 197Typically this will be 2 198filemarks, but some devices (typically QIC cartridge drives) can 199only write 1 filemark. 200You may only choose a value of 201.Ar 1 202or 203.Ar 2 . 204.It Cm comp 205Set the drive's compression mode. 206The non-numeric values of 207.Ar argument 208are: 209.Pp 210.Bl -tag -width 9n -compact 211.It off 212Turn compression off. 213.It on 214Turn compression on. 215.It none 216Same as 217.Ar off . 218.It enable 219Same as 220.Ar on . 221.It IDRC 222IBM Improved Data Recording Capability compression (0x10). 223.It DCLZ 224DCLZ compression algorithm (0x20). 225.El 226.Pp 227In addition to the above recognized compression keywords, the user can 228supply a numeric compression algorithm for the drive to use. 229In most 230cases, simply turning the compression 231.Sq on 232will have the desired effect of enabling the default compression algorithm 233supported by the drive. 234If this is not the case (see the 235.Cm status 236display to see which compression algorithm is currently in use), the user 237can manually specify one of the supported compression keywords (above), or 238supply a numeric compression value from the drive's specifications. 239.It Cm density 240Set the density for the drive. 241For the density codes, see below. 242The density value could be given either numerically, or as a string, 243corresponding to the 244.Dq Reference 245field. 246If the string is abbreviated, it will be resolved in the order 247shown in the table, and the first matching entry will be used. 248If the 249given string and the resulting canonical density name do not match 250exactly, an informational message is output about what the given 251string has been taken for. 252.El 253.Pp 254The following density table was taken from the 255.Sq Historical sequential access density codes 256table (A-1) in Revision 11 of the SCSI-3 Stream Device Commands (SSC) 257working draft, dated November 11, 1997. 258.Pp 259The density codes are: 260.Bd -literal -offset 3n 2610x0 default for device 2620xE reserved for ECMA 263.Dl "" 264Value Width Tracks Density Code Type Reference Note 265 mm in bpmm bpi 2660x01 12.7 (0.5) 9 32 (800) NRZI R X3.22-1983 2 2670x02 12.7 (0.5) 9 63 (1,600) PE R X3.39-1986 2 2680x03 12.7 (0.5) 9 246 (6,250) GCR R X3.54-1986 2 2690x05 6.3 (0.25) 4/9 315 (8,000) GCR C X3.136-1986 1 2700x06 12.7 (0.5) 9 126 (3,200) PE R X3.157-1987 2 2710x07 6.3 (0.25) 4 252 (6,400) IMFM C X3.116-1986 1 2720x08 3.81 (0.15) 4 315 (8,000) GCR CS X3.158-1987 1 2730x09 12.7 (0.5) 18 1,491 (37,871) GCR C X3.180 2 2740x0A 12.7 (0.5) 22 262 (6,667) MFM C X3B5/86-199 1 2750x0B 6.3 (0.25) 4 63 (1,600) PE C X3.56-1986 1 2760x0C 12.7 (0.5) 24 500 (12,690) GCR C HI-TC1 1,6 2770x0D 12.7 (0.5) 24 999 (25,380) GCR C HI-TC2 1,6 2780x0F 6.3 (0.25) 15 394 (10,000) GCR C QIC-120 1,6 2790x10 6.3 (0.25) 18 394 (10,000) GCR C QIC-150 1,6 2800x11 6.3 (0.25) 26 630 (16,000) GCR C QIC-320 1,6 2810x12 6.3 (0.25) 30 2,034 (51,667) RLL C QIC-1350 1,6 2820x13 3.81 (0.15) 1 2,400 (61,000) DDS CS X3B5/88-185A 5 2830x14 8.0 (0.315) 1 1,703 (43,245) RLL CS X3.202-1991 5 2840x15 8.0 (0.315) 1 1,789 (45,434) RLL CS ECMA TC17 5 2850x16 12.7 (0.5) 48 394 (10,000) MFM C X3.193-1990 1 2860x17 12.7 (0.5) 48 1,673 (42,500) MFM C X3B5/91-174 1 2870x18 12.7 (0.5) 112 1,673 (42,500) MFM C X3B5/92-50 1 2880x19 12.7 (0.5) 128 2,460 (62,500) RLL C DLTapeIII 6,7 2890x1A 12.7 (0.5) 128 3,214 (81,633) RLL C DLTapeIV(20) 6,7 2900x1B 12.7 (0.5) 208 3,383 (85,937) RLL C DLTapeIV(35) 6,7 2910x1C 6.3 (0.25) 34 1,654 (42,000) MFM C QIC-385M 1,6 2920x1D 6.3 (0.25) 32 1,512 (38,400) GCR C QIC-410M 1,6 2930x1E 6.3 (0.25) 30 1,385 (36,000) GCR C QIC-1000C 1,6 2940x1F 6.3 (0.25) 30 2,666 (67,733) RLL C QIC-2100C 1,6 2950x20 6.3 (0.25) 144 2,666 (67,733) RLL C QIC-6GB(M) 1,6 2960x21 6.3 (0.25) 144 2,666 (67,733) RLL C QIC-20GB(C) 1,6 2970x22 6.3 (0.25) 42 1,600 (40,640) GCR C QIC-2GB(C) ? 2980x23 6.3 (0.25) 38 2,666 (67,733) RLL C QIC-875M ? 2990x24 3.81 (0.15) 1 2,400 (61,000) CS DDS-2 5 3000x25 3.81 (0.15) 1 3,816 (97,000) CS DDS-3 5 3010x26 3.81 (0.15) 1 3,816 (97,000) CS DDS-4 5 3020x27 8.0 (0.315) 1 3,056 (77,611) RLL CS Mammoth 5 3030x28 12.7 (0.5) 36 1,491 (37,871) GCR C X3.224 1 3040x29 12.7 (0.5) 3050x2A 3060x2B 12.7 (0.5) 3 ? ? ? C X3.267 5 3070x41 12.7 (0.5) 208 3,868 (98,250) RLL C DLTapeIV(40) 6,7 3080x48 12.7 (0.5) 448 5,236 (133,000) PRML C SDLTapeI(110) 6,8 3090x49 12.7 (0.5) 448 7,598 (193,000) PRML C SDLTapeI(160) 6,8 310.Ed 311.Bd -literal -offset 3n 312Code Description Type Description 313---------------- ---------------- 314NRZI Non return to zero, change on ones R Reel-to-reel 315GCR Group code recording C Cartridge 316PE Phase encoded CS Cassette 317IMFM Inverted modified frequency modulation 318MFM Modified frequency modulation 319DDS DAT data storage 320RLL Run length limited 321PRML Partial Response Maximum Likelihood 322.Ed 323.Bd -literal -offset 3n 324NOTES 3251. Serial recorded. 3262. Parallel recorded. 3273. Old format known as QIC-11. 3285. Helical scan. 3296. This is not an American National Standard. The reference is based on 330 an industry standard definition of the media format. 3317. DLT recording: serially recorded track pairs (DLTapeIII and 332 DLTapeIV(20)), or track quads (DLTapeIV(35) and DLTapeIV(40)). 3338. Super DLT (SDLT) recording: 56 serially recorded logical tracks with 334 8 physical tracks each. 335.Ed 336.Sh ENVIRONMENT 337.Bl -tag -width TAPE 338.It Ev TAPE 339This is the pathname of the tape drive. 340The default (if the variable is unset, but not if it is null) is 341.Pa /dev/nsa0 . 342It may be overridden with the 343.Fl f 344option. 345.El 346.Sh FILES 347.Bl -tag -width /dev/*sa[0-9]*xx -compact 348.It Pa /dev/*wt* 349QIC-02/QIC-36 magnetic tape interface 350.It Pa /dev/*sa[0-9]* 351SCSI magnetic tape interface 352.El 353.Sh DIAGNOSTICS 354.Pp 355The exit status will be 0 when the drive operations were successful, 3562 when the drive operations were unsuccessful, and 1 for other 357problems like an unrecognized command or a missing drive device. 358.Sh COMPATIBILITY 359Some undocumented commands support old software. 360.Sh SEE ALSO 361.Xr dd 1 , 362.Xr ioctl 2 , 363.Xr ast 4 , 364.Xr mtio 4 , 365.Xr sa 4 , 366.Xr environ 7 367.Sh HISTORY 368The 369.Nm 370command appeared in 371.Bx 4.3 . 372.Pp 373Extensions regarding the 374.Xr st 4 375driver appeared in 376.Bx 386 0.1 377as a separate 378.Nm st 379command, and have been merged into the 380.Nm 381command in 382.Fx 2.1 . 383.Pp 384The former 385.Cm eof 386command that used to be a synonym for 387.Cm weof 388has been abandoned in 389.Fx 2.1 390since it was often confused with 391.Cm eom , 392which is fairly dangerous. 393.Sh BUGS 394The utility cannot be interrupted or killed during a long erase 395(which can be longer than an hour), and it is easy to forget 396that the default erase is long. 397.Pp 398Hardware block numbers do not always correspond to blocks on the tape 399when the drive uses internal compression. 400.Pp 401Erasure is not guaranteed if the tape is not at its beginning. 402.Pp 403Tape-related documentation is poor, here and elsewhere. 404