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