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. 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 May 11, 2017 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. 74This returns when the file mark has been written to the media. 75.It Cm weofi 76Write 77.Ar count 78end-of-file (EOF) marks at the current position. 79This returns as soon as the command has been validated by the tape drive. 80.It Cm smk 81Write 82.Ar count 83setmarks at the current position (DDS drives only). 84.It Cm fsf 85Forward space 86.Ar count 87files. 88.It Cm fsr 89Forward space 90.Ar count 91records. 92.It Cm fss 93Forward space 94.Ar count 95setmarks (DDS drives only). 96.It Cm bsf 97Backward space 98.Ar count 99files. 100.It Cm bsr 101Backward space 102.Ar count 103records. 104.It Cm bss 105Backward space 106.Ar count 107setmarks (DDS drives only). 108.It Cm erase 109Erase the tape using a long (often very long) method. 110With a 111.Ar count 112of 0, it will erase the tape using a quick method. 113Operation is not guaranteed if the tape is not at its beginning. 114The tape will be at its beginning upon completion. 115.El 116.Pp 117The following commands ignore 118.Ar count . 119.Bl -tag -width ".Cm geteotmodel" 120.It Cm rdhpos 121Read the hardware block position. 122The block 123number reported is specific for that hardware only. 124With drive data compression especially, 125this position may have more to do with the amount of data 126sent to the drive than the amount of data written to tape. 127Some drives do not support this. 128.It Cm rdspos 129Read the SCSI logical block position. 130This typically is greater than the hardware position 131by the number of end-of-file marks. 132Some drives do not support this. 133.It Cm rewind 134Rewind the tape. 135.It Cm offline , rewoffl 136Rewind the tape and place the drive off line. 137Some drives are never off line. 138.It Cm load 139Load the tape into the drive. 140.It Cm retension 141Re-tension the tape. 142This winds the tape from the current position to the end 143and then to the beginning. 144This sometimes improves subsequent reading and writing, 145particularly for streaming drives. 146Some drives do not support this. 147.It Cm ostatus 148Output status information about the drive. 149For SCSI magnetic tape devices, 150the current operating modes of density, blocksize, and whether compression 151is enabled is reported. 152The current state of the driver (what it thinks that 153it is doing with the device) is reported. 154If the driver knows the relative 155position from BOT (in terms of filemarks and records), it outputs that. 156Note 157that this information is not definitive (only BOT, End of Recorded Media, and 158hardware or SCSI logical block position (if the drive supports such) are 159considered definitive tape positions). 160.Pp 161Also note that this is the old status command, and will be eliminated in 162favor of the new status command (see below) in a future release. 163.It Cm errstat 164Output (and clear) error status information about this device. 165For every normal 166operation (e.g., a read or a write) and every control operation (e.g,, a 167rewind), the driver stores up the last command executed and it is associated 168status and any residual counts (if any). 169This command retrieves and outputs this 170information. 171If possible, this also clears any latched error information. 172.It Cm geteotmodel 173Output the current EOT filemark model. 174The model states how 175many filemarks will be written at close if a tape was being written. 176.It Cm eod , eom 177Wind the tape to the end of the recorded data, 178typically after an EOF mark where another file may be written. 179.It Cm rblim 180Report the block limits of the tape drive, including the minimum and 181maximum block size, and the block granularity if any. 182.El 183.Pp 184The following commands may require an 185.Ar argument . 186.Bl -tag -width ".Cm seteotmodel" 187.It Cm sethpos 188Set the hardware block position. 189The 190.Ar argument 191is a hardware block number to which to position the tape. 192Some drives do not support this. 193.It Cm setspos 194Set the SCSI logical block position. 195The 196.Ar argument 197is a SCSI logical block number to which to position the tape. 198Some drives do not support this. 199.It Cm blocksize 200Set the block size for the drive. 201The 202.Ar argument 203is the number of bytes per block, 204except 0 commands the drive to use variable-length blocks. 205.It Cm seteotmodel 206Set the EOT filemark model to 207.Ar argument 208and output the old and new models. 209Typically this will be 2 210filemarks, but some devices (typically QIC cartridge drives) can 211only write 1 filemark. 212You may only choose a value of 213.Ar 1 214or 215.Ar 2 . 216.It Cm status 217Output status information about the drive. 218For SCSI magnetic tape devices, 219the current operating modes of density, blocksize, and whether compression 220is enabled is reported. 221The current state of the driver (what it thinks that 222it is doing with the device) is reported. 223.Pp 224If the driver knows the relative 225position from BOT (in terms of filemarks and records), it outputs that. 226If the tape drive supports the long form report of the 227.Tn SCSI 228READ POSITION command, the Reported File Number and Reported Record Number 229will be numbers other than -1, and there may be Flags reported as well. 230.Pp 231The BOP flag means that the logical position of the drive is at the 232beginning of the partition. 233.Pp 234The EOP flag means that the logical position of the drive is between Early 235Warning and End of Partition. 236.Pp 237The BPEW flag means that the logical position of the drive is in a 238Programmable Early Warning Zone or on the EOP side of Early Warning. 239.Pp 240Note that the Reported Record Number is the tape block or object number 241relative to the beginning of the partition. 242The Calculated Record Number is the tape block or object number relative 243to the previous file mark. 244.Pp 245Note 246that the Calculated File and Record Numbers are not definitive. 247The Reported File and Record Numbers are definitive, if they are numbers 248other than -1. 249.Bl -tag -width 6n 250.It Fl v 251Print additional status information, such as the maximum supported I/O 252size. 253.It Fl x 254Print all available status data to stdout in XML format. 255.El 256.It Cm getdensity 257Report density support information for the tape drive and any media that is 258loaded. 259Most drives will report at least basic density information similar to that 260reported by 261.Nm status 262command. 263Newer tape drives that conform to the T-10 SSC and newer tape 264specifications may report more detailed information about the types of 265tapes they support and the tape currently in the drive. 266.Bl -tag -width 6n 267.It Fl x 268Print all available density data to stdout in XML format. 269Because density information is currently included in the general status XML 270report used for 271.Nm 272status command, this will be the same XML output via 273.Do 274.Nm 275status 276.Fl x 277.Dc 278.El 279.It Cm param 280Display or set parameters. 281One of 282.Fl l , 283.Fl s , 284or 285.Fl x 286must be specified to indicate which operation to perform. 287See 288.Xr sa 4 289for more detailed information on the parameters. 290.Bl -tag -width 8n 291.It Fl l 292List parameters, values and descriptions. 293By default all parameters will be displayed. 294To display a specific parameter, specify the parameter with 295.Fl p . 296.It Fl p Ar name 297Specify the parameter name to list (with 298.Fl l ) 299or set (with 300.Fl s ) . 301.It Fl q 302Enable quiet mode for parameter listing. 303This will suppress printing of parameter descriptions. 304.It Fl s Ar value 305Specify the parameter value to set. 306The general type of this argument (integer, unsigned integer, string) is 307determined by the type of the variable indicated by the 308.Xr sa 4 309driver. 310More detailed argument checking is done by the 311.Xr sa 4 312driver. 313.It Fl x 314Print out all parameter information in XML format. 315.El 316.It Cm protect 317Display or set drive protection parameters. 318This is used to control checking and reporting a per-block checksum for 319tape drives that support it. 320Some drives may only support some parameters. 321.Bl -tag -width 8n 322.It Fl b Ar 0|1 323Set the Recover Buffered Data Protected bit. 324If set, this indicates that checksums are transferred with the logical 325blocks transferred by the RECOVERED BUFFERED DATA 326.Tn SCSI 327command. 328.It Fl d 329Disable all protection information settings. 330.It Fl e 331Enable all protection information settings. 332The default protection method used is Reed-Solomon CRC (protection method 3331), as specified in ECMA-319. 334The default protection information length used with Reed-Solomon CRC is 3354 bytes. 336To enable all settings except one more more settings, specify the 337.Fl e 338argument and then explicitly disable settings that you do not wish to 339enable. 340For example, specifying 341.Fl e 342.Fl w Ar 0 343will enable all settings except for LBP_W. 344.It Fl l 345List available protection parmeters and their current settings. 346.It Fl L Ar len 347Set the length of the protection information in bytes. 348For Reed-Solomon CRC, the protection information length should be 4 bytes. 349.It Fl m Ar num 350Specify the numeric value for the protection method. 351The numeric value for Reed-Solomon CRC is 1. 352.It Fl r Ar 0|1 353Set the LBP_R parameter. 354When set, this indicates that each block read from the tape drive will 355have a checksum at the end. 356.It Fl v 357Enable verbose mode for parameter listing. 358This will include descriptions of each parameter. 359.It Fl w Ar 0|1 360Set the LBP_W parameter. 361When set, this indicates that each block written to the tape drive will have 362a checksum at the end. 363The drive will verify the checksum before writing the block to tape. 364.El 365.It Cm locate 366Set the tape drive's logical position. 367One of 368.Fl b , 369.Fl e , 370.Fl f , 371or 372.Fl s 373must be specified to indicate the type of position. 374If the partition number is specified, the drive will first relocate to the 375given partition (if it exists) and then to the position indicated within 376that partition. 377If the partition number is not specified, the drive will relocate to the 378given position within the current partition. 379.Bl -tag -width 14n 380.It Fl b Ar block_addr 381Relocate to the given tape block or logical object identifier. 382Note that the block number is the Reported Record Number that is relative 383to the beginning of the partition (or beginning of tape). 384.It Fl e 385Relocate to the end of data. 386.It Fl f Ar fileno 387Relocate to the given file number. 388.It Fl p Ar partition 389Specify the partition to change to. 390.It Fl s Ar setmark 391Relocate to the given set mark. 392.El 393.It Cm comp 394Set the drive's compression mode. 395The non-numeric values of 396.Ar argument 397are: 398.Pp 399.Bl -tag -width 9n -compact 400.It off 401Turn compression off. 402.It on 403Turn compression on. 404.It none 405Same as 406.Ar off . 407.It enable 408Same as 409.Ar on . 410.It IDRC 411IBM Improved Data Recording Capability compression (0x10). 412.It DCLZ 413DCLZ compression algorithm (0x20). 414.El 415.Pp 416In addition to the above recognized compression keywords, the user can 417supply a numeric compression algorithm for the drive to use. 418In most 419cases, simply turning the compression 420.Sq on 421will have the desired effect of enabling the default compression algorithm 422supported by the drive. 423If this is not the case (see the 424.Cm status 425display to see which compression algorithm is currently in use), the user 426can manually specify one of the supported compression keywords (above), or 427supply a numeric compression value from the drive's specifications. 428.Pp 429Note that for some older tape drives (for example the Exabyte 8200 and 8500 430series drives) it is necessary to switch to a different density to tell the 431drive to record data in its compressed format. 432If the user attempts to turn compression on while the uncompressed density 433is selected, the drive will return an error. 434This is generally not an issue for modern tape drives. 435.It Cm density 436Set the density for the drive. 437For the density codes, see below. 438The density value could be given either numerically, or as a string, 439corresponding to the 440.Dq Reference 441field. 442If the string is abbreviated, it will be resolved in the order 443shown in the table, and the first matching entry will be used. 444If the 445given string and the resulting canonical density name do not match 446exactly, an informational message is output about what the given 447string has been taken for. 448.El 449.Pp 450The initial version of the density table below was taken from the 451.Sq Historical sequential access density codes 452table (A-1) in Revision 11 of the SCSI-3 Stream Device Commands (SSC) 453working draft, dated November 11, 1997. 454Subsequent additions have come from a number of sources. 455.Pp 456The density codes are: 457.Bd -literal -offset 2n 4580x0 default for device 4590xE reserved for ECMA 460 461Value Width Tracks Density Code Type Reference Note 462 mm in bpmm bpi 4630x01 12.7 (0.5) 9 32 (800) NRZI R X3.22-1983 2 4640x02 12.7 (0.5) 9 63 (1,600) PE R X3.39-1986 2 4650x03 12.7 (0.5) 9 246 (6,250) GCR R X3.54-1986 2 4660x05 6.3 (0.25) 4/9 315 (8,000) GCR C X3.136-1986 1 4670x06 12.7 (0.5) 9 126 (3,200) PE R X3.157-1987 2 4680x07 6.3 (0.25) 4 252 (6,400) IMFM C X3.116-1986 1 4690x08 3.81 (0.15) 4 315 (8,000) GCR CS X3.158-1987 1 4700x09 12.7 (0.5) 18 1,491 (37,871) GCR C X3.180 2 4710x0A 12.7 (0.5) 22 262 (6,667) MFM C X3B5/86-199 1 4720x0B 6.3 (0.25) 4 63 (1,600) PE C X3.56-1986 1 4730x0C 12.7 (0.5) 24 500 (12,690) GCR C HI-TC1 1,6 4740x0D 12.7 (0.5) 24 999 (25,380) GCR C HI-TC2 1,6 4750x0F 6.3 (0.25) 15 394 (10,000) GCR C QIC-120 1,6 4760x10 6.3 (0.25) 18 394 (10,000) GCR C QIC-150 1,6 4770x11 6.3 (0.25) 26 630 (16,000) GCR C QIC-320 1,6 4780x12 6.3 (0.25) 30 2,034 (51,667) RLL C QIC-1350 1,6 4790x13 3.81 (0.15) 1 2,400 (61,000) DDS CS X3B5/88-185A 5 4800x14 8.0 (0.315) 1 1,703 (43,245) RLL CS X3.202-1991 5,11 4810x15 8.0 (0.315) 1 1,789 (45,434) RLL CS ECMA TC17 5,12 4820x16 12.7 (0.5) 48 394 (10,000) MFM C X3.193-1990 1 4830x17 12.7 (0.5) 48 1,673 (42,500) MFM C X3B5/91-174 1 4840x18 12.7 (0.5) 112 1,673 (42,500) MFM C X3B5/92-50 1 4850x19 12.7 (0.5) 128 2,460 (62,500) RLL C DLTapeIII 6,7 4860x1A 12.7 (0.5) 128 3,214 (81,633) RLL C DLTapeIV(20) 6,7 4870x1B 12.7 (0.5) 208 3,383 (85,937) RLL C DLTapeIV(35) 6,7 4880x1C 6.3 (0.25) 34 1,654 (42,000) MFM C QIC-385M 1,6 4890x1D 6.3 (0.25) 32 1,512 (38,400) GCR C QIC-410M 1,6 4900x1E 6.3 (0.25) 30 1,385 (36,000) GCR C QIC-1000C 1,6 4910x1F 6.3 (0.25) 30 2,666 (67,733) RLL C QIC-2100C 1,6 4920x20 6.3 (0.25) 144 2,666 (67,733) RLL C QIC-6GB(M) 1,6 4930x21 6.3 (0.25) 144 2,666 (67,733) RLL C QIC-20GB(C) 1,6 4940x22 6.3 (0.25) 42 1,600 (40,640) GCR C QIC-2GB(C) ? 4950x23 6.3 (0.25) 38 2,666 (67,733) RLL C QIC-875M ? 4960x24 3.81 (0.15) 1 2,400 (61,000) CS DDS-2 5 4970x25 3.81 (0.15) 1 3,816 (97,000) CS DDS-3 5 4980x26 3.81 (0.15) 1 3,816 (97,000) CS DDS-4 5 4990x27 8.0 (0.315) 1 3,056 (77,611) RLL CS Mammoth 5 5000x28 12.7 (0.5) 36 1,491 (37,871) GCR C X3.224 1 5010x29 12.7 (0.5) 5020x2A 5030x2B 12.7 (0.5) 3 ? ? ? C X3.267 5 5040x40 12.7 (0.5) 384 4,800 (123,952) C LTO-1 5050x41 12.7 (0.5) 208 3,868 (98,250) RLL C DLTapeIV(40) 6,7 5060x42 12.7 (0.5) 512 7,398 (187,909) C LTO-2 5070x44 12.7 (0.5) 704 9,638 (244,805) C LTO-3 5080x46 12.7 (0.5) 896 12,725 (323,215) C LTO-4 5090x47 3.81 (0.25) ? 6,417 (163,000) CS DAT-72 5100x48 12.7 (0.5) 448 5,236 (133,000) PRML C SDLTapeI(110) 6,8,13 5110x49 12.7 (0.5) 448 7,598 (193,000) PRML C SDLTapeI(160) 6,8 5120x4A 12.7 (0.5) 768 ? C T10000A 10 5130x4B 12.7 (0.5) 1152 ? C T10000B 10 5140x4C 12.7 (0.5) 3584 ? C T10000C 10 5150x4D 12.7 (0.5) 4608 ? C T10000D 10 5160x51 12.7 (0.5) 512 11,800 (299,720) C 3592A1 (unencrypted) 5170x52 12.7 (0.5) 896 11,800 (299,720) C 3592A2 (unencrypted) 5180x53 12.7 (0.5) 1152 13,452 (341,681) C 3592A3 (unencrypted) 5190x54 12.7 (0.5) 2560 19,686 (500,024) C 3592A4 (unencrypted) 5200x55 12.7 (0.5) 5120 20,670 (525,018) C 3592A5 (unencrypted) 5210x58 12.7 (0.5) 1280 15,142 (384,607) C LTO-5 5220x5A 12.7 (0.5) 2176 15,142 (384,607) C LTO-6 5230x5C 12.7 (0.5) 3584 19,107 (485,318) C LTO-7 5240x5E 12.7 (0.5) 6656 20,669 (524,993) C LTO-8 5250x71 12.7 (0.5) 512 11,800 (299,720) C 3592A1 (encrypted) 5260x72 12.7 (0.5) 896 11,800 (299,720) C 3592A2 (encrypted) 5270x73 12.7 (0.5) 1152 13,452 (341,681) C 3592A3 (encrypted) 5280x74 12.7 (0.5) 2560 19,686 (500,024) C 3592A4 (encrypted) 5290x75 12.7 (0.5) 5120 20,670 (525,018) C 3592A5 (encrypted) 5300x8c 8.0 (0.315) 1 1,789 (45,434) RLL CS EXB-8500c 5,9 5310x90 8.0 (0.315) 1 1,703 (43,245) RLL CS EXB-8200c 5,9 532.Ed 533.Bd -literal -offset 2n 534Code Description Type Description 535---- -------------------------------------- ---- ----------- 536NRZI Non return to zero, change on ones R Reel-to-reel 537GCR Group code recording C Cartridge 538PE Phase encoded CS Cassette 539IMFM Inverted modified frequency modulation 540MFM Modified frequency modulation 541DDS DAT data storage 542RLL Run length limited 543PRML Partial Response Maximum Likelihood 544.Ed 545.Bd -literal -offset 2n 546NOTES 5471. Serial recorded. 5482. Parallel recorded. 5493. Old format known as QIC-11. 5505. Helical scan. 5516. This is not an American National Standard. The reference is based 552 on an industry standard definition of the media format. 5537. DLT recording: serially recorded track pairs (DLTapeIII and 554 DLTapeIV(20)), or track quads (DLTapeIV(35) and DLTapeIV(40)). 5558. Super DLT (SDLT) recording: 56 serially recorded logical tracks 556 with 8 physical tracks each. 5579. Vendor-specific Exabyte density code for compressed format. 55810. bpi/bpmm values for the Oracle/StorageTek T10000 tape drives are 559 not listed in the manual. Someone with access to a drive can 560 supply the necessary values by running 'mt getdensity'. 56111. This is Exabyte 8200 uncompressed format. The compressed format 562 density code is 0x90. 56312. This is Exabyte 8500 uncompressed format. The compressed format 564 density code is 0x8c. 56513. This density code (0x48) was also used for DAT-160. 566.Ed 567.Sh ENVIRONMENT 568.Bl -tag -width ".Ev TAPE" 569.It Ev TAPE 570This is the pathname of the tape drive. 571The default (if the variable is unset, but not if it is null) is 572.Pa /dev/nsa0 . 573It may be overridden with the 574.Fl f 575option. 576.El 577.Sh FILES 578.Bl -tag -width ".Pa /dev/*sa[0-9]*" -compact 579.It Pa /dev/*sa[0-9]* 580SCSI magnetic tape interface 581.El 582.Sh DIAGNOSTICS 583The exit status will be 0 when the drive operations were successful, 5842 when the drive operations were unsuccessful, and 1 for other 585problems like an unrecognized command or a missing drive device. 586.Sh COMPATIBILITY 587Some undocumented commands support old software. 588.Sh SEE ALSO 589.Xr dd 1 , 590.Xr ioctl 2 , 591.Xr mtio 4 , 592.Xr sa 4 , 593.Xr environ 7 594.Sh HISTORY 595The 596.Nm 597command appeared in 598.Bx 4.3 . 599.Pp 600Extensions regarding the 601.Xr st 4 602driver appeared in 603.Bx 386 0.1 604as a separate 605.Nm st 606command, and have been merged into the 607.Nm 608command in 609.Fx 2.1 . 610.Pp 611The former 612.Cm eof 613command that used to be a synonym for 614.Cm weof 615has been abandoned in 616.Fx 2.1 617since it was often confused with 618.Cm eom , 619which is fairly dangerous. 620.Sh BUGS 621The utility cannot be interrupted or killed during a long erase 622(which can be longer than an hour), and it is easy to forget 623that the default erase is long. 624.Pp 625Hardware block numbers do not always correspond to blocks on the tape 626when the drive uses internal compression. 627.Pp 628Erasure is not guaranteed if the tape is not at its beginning. 629.Pp 630Tape-related documentation is poor, here and elsewhere. 631