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