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 May 20, 2016 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. 287.Bl -tag -width 8n 288.It Fl l 289List parameters, values and descriptions. 290By default all parameters will be displayed. 291To display a specific parameter, specify the parameter with 292.Fl p . 293.It Fl p Ar name 294Specify the parameter name to list (with 295.Fl l ) 296or set (with 297.Fl s ) . 298.It Fl q 299Enable quiet mode for parameter listing. 300This will suppress printing of parameter descriptions. 301.It Fl s Ar value 302Specify the parameter value to set. 303The general type of this argument (integer, unsigned integer, string) is 304determined by the type of the variable indicated by the 305.Xr sa 4 306driver. 307More detailed argument checking is done by the 308.Xr sa 4 309driver. 310.It Fl x 311Print out all parameter information in XML format. 312.El 313.It Cm protect 314Display or set drive protection parameters. 315This is used to control checking and reporting a per-block checksum for 316tape drives that support it. 317Some drives may only support some parameters. 318.Bl -tag -width 8n 319.It Fl b Ar 0|1 320Set the Recover Buffered Data Protected bit. 321If set, this indicates that checksums are transferred with the logical 322blocks transferred by the RECOVERED BUFFERED DATA 323.Tn SCSI 324command. 325.It Fl d 326Disable all protection information settings. 327.It Fl e 328Enable all protection information settings. 329The default protection method used is Reed-Solomon CRC (protection method 3301), as specified in ECMA-319. 331The default protection information length used with Reed-Solomon CRC is 3324 bytes. 333To enable all settings except one more more settings, specify the 334.Fl e 335argument and then explicitly disable settings that you do not wish to 336enable. 337For example, specifying 338.Fl e 339.Fl w Ar 0 340will enable all settings except for LBP_W. 341.It Fl l 342List available protection parmeters and their current settings. 343.It Fl L Ar len 344Set the length of the protection information in bytes. 345For Reed-Solomon CRC, the protection information length should be 4 bytes. 346.It Fl m Ar num 347Specify the numeric value for the protection method. 348The numeric value for Reed-Solomon CRC is 1. 349.It Fl r Ar 0|1 350Set the LBP_R parameter. 351When set, this indicates that each block read from the tape drive will 352have a checksum at the end. 353.It Fl v 354Enable verbose mode for parameter listing. 355This will include descriptions of each parameter. 356.It Fl w Ar 0|1 357Set the LBP_W parameter. 358When set, this indicates that each block written to the tape drive will have 359a checksum at the end. 360The drive will verify the checksum before writing the block to tape. 361.El 362.It Cm locate 363Set the tape drive's logical position. 364One of 365.Fl b , 366.Fl e , 367.Fl f , 368or 369.Fl s 370must be specified to indicate the type of position. 371If the partition number is specified, the drive will first relocate to the 372given partition (if it exists) and then to the position indicated within 373that partition. 374If the partition number is not specified, the drive will relocate to the 375given position within the current partition. 376.Bl -tag -width 14n 377.It Fl b Ar block_addr 378Relocate to the given tape block or logical object identifier. 379Note that the block number is the Reported Record Number that is relative 380to the beginning of the partition (or beginning of tape). 381.It Fl e 382Relocate to the end of data. 383.It Fl f Ar fileno 384Relocate to the given file number. 385.It Fl p Ar partition 386Specify the partition to change to. 387.It Fl s Ar setmark 388Relocate to the given set mark. 389.El 390.It Cm comp 391Set the drive's compression mode. 392The non-numeric values of 393.Ar argument 394are: 395.Pp 396.Bl -tag -width 9n -compact 397.It off 398Turn compression off. 399.It on 400Turn compression on. 401.It none 402Same as 403.Ar off . 404.It enable 405Same as 406.Ar on . 407.It IDRC 408IBM Improved Data Recording Capability compression (0x10). 409.It DCLZ 410DCLZ compression algorithm (0x20). 411.El 412.Pp 413In addition to the above recognized compression keywords, the user can 414supply a numeric compression algorithm for the drive to use. 415In most 416cases, simply turning the compression 417.Sq on 418will have the desired effect of enabling the default compression algorithm 419supported by the drive. 420If this is not the case (see the 421.Cm status 422display to see which compression algorithm is currently in use), the user 423can manually specify one of the supported compression keywords (above), or 424supply a numeric compression value from the drive's specifications. 425.Pp 426Note that for some older tape drives (for example the Exabyte 8200 and 8500 427series drives) it is necessary to switch to a different density to tell the 428drive to record data in its compressed format. 429If the user attempts to turn compression on while the uncompressed density 430is selected, the drive will return an error. 431This is generally not an issue for modern tape drives. 432.It Cm density 433Set the density for the drive. 434For the density codes, see below. 435The density value could be given either numerically, or as a string, 436corresponding to the 437.Dq Reference 438field. 439If the string is abbreviated, it will be resolved in the order 440shown in the table, and the first matching entry will be used. 441If the 442given string and the resulting canonical density name do not match 443exactly, an informational message is output about what the given 444string has been taken for. 445.El 446.Pp 447The initial version of the density table below was taken from the 448.Sq Historical sequential access density codes 449table (A-1) in Revision 11 of the SCSI-3 Stream Device Commands (SSC) 450working draft, dated November 11, 1997. 451Subsequent additions have come from a number of sources. 452.Pp 453The density codes are: 454.Bd -literal -offset 2n 4550x0 default for device 4560xE reserved for ECMA 457 458Value Width Tracks Density Code Type Reference Note 459 mm in bpmm bpi 4600x01 12.7 (0.5) 9 32 (800) NRZI R X3.22-1983 2 4610x02 12.7 (0.5) 9 63 (1,600) PE R X3.39-1986 2 4620x03 12.7 (0.5) 9 246 (6,250) GCR R X3.54-1986 2 4630x05 6.3 (0.25) 4/9 315 (8,000) GCR C X3.136-1986 1 4640x06 12.7 (0.5) 9 126 (3,200) PE R X3.157-1987 2 4650x07 6.3 (0.25) 4 252 (6,400) IMFM C X3.116-1986 1 4660x08 3.81 (0.15) 4 315 (8,000) GCR CS X3.158-1987 1 4670x09 12.7 (0.5) 18 1,491 (37,871) GCR C X3.180 2 4680x0A 12.7 (0.5) 22 262 (6,667) MFM C X3B5/86-199 1 4690x0B 6.3 (0.25) 4 63 (1,600) PE C X3.56-1986 1 4700x0C 12.7 (0.5) 24 500 (12,690) GCR C HI-TC1 1,6 4710x0D 12.7 (0.5) 24 999 (25,380) GCR C HI-TC2 1,6 4720x0F 6.3 (0.25) 15 394 (10,000) GCR C QIC-120 1,6 4730x10 6.3 (0.25) 18 394 (10,000) GCR C QIC-150 1,6 4740x11 6.3 (0.25) 26 630 (16,000) GCR C QIC-320 1,6 4750x12 6.3 (0.25) 30 2,034 (51,667) RLL C QIC-1350 1,6 4760x13 3.81 (0.15) 1 2,400 (61,000) DDS CS X3B5/88-185A 5 4770x14 8.0 (0.315) 1 1,703 (43,245) RLL CS X3.202-1991 5,11 4780x15 8.0 (0.315) 1 1,789 (45,434) RLL CS ECMA TC17 5,12 4790x16 12.7 (0.5) 48 394 (10,000) MFM C X3.193-1990 1 4800x17 12.7 (0.5) 48 1,673 (42,500) MFM C X3B5/91-174 1 4810x18 12.7 (0.5) 112 1,673 (42,500) MFM C X3B5/92-50 1 4820x19 12.7 (0.5) 128 2,460 (62,500) RLL C DLTapeIII 6,7 4830x1A 12.7 (0.5) 128 3,214 (81,633) RLL C DLTapeIV(20) 6,7 4840x1B 12.7 (0.5) 208 3,383 (85,937) RLL C DLTapeIV(35) 6,7 4850x1C 6.3 (0.25) 34 1,654 (42,000) MFM C QIC-385M 1,6 4860x1D 6.3 (0.25) 32 1,512 (38,400) GCR C QIC-410M 1,6 4870x1E 6.3 (0.25) 30 1,385 (36,000) GCR C QIC-1000C 1,6 4880x1F 6.3 (0.25) 30 2,666 (67,733) RLL C QIC-2100C 1,6 4890x20 6.3 (0.25) 144 2,666 (67,733) RLL C QIC-6GB(M) 1,6 4900x21 6.3 (0.25) 144 2,666 (67,733) RLL C QIC-20GB(C) 1,6 4910x22 6.3 (0.25) 42 1,600 (40,640) GCR C QIC-2GB(C) ? 4920x23 6.3 (0.25) 38 2,666 (67,733) RLL C QIC-875M ? 4930x24 3.81 (0.15) 1 2,400 (61,000) CS DDS-2 5 4940x25 3.81 (0.15) 1 3,816 (97,000) CS DDS-3 5 4950x26 3.81 (0.15) 1 3,816 (97,000) CS DDS-4 5 4960x27 8.0 (0.315) 1 3,056 (77,611) RLL CS Mammoth 5 4970x28 12.7 (0.5) 36 1,491 (37,871) GCR C X3.224 1 4980x29 12.7 (0.5) 4990x2A 5000x2B 12.7 (0.5) 3 ? ? ? C X3.267 5 5010x40 12.7 (0.5) 384 4,800 (123,952) C LTO-1 5020x41 12.7 (0.5) 208 3,868 (98,250) RLL C DLTapeIV(40) 6,7 5030x42 12.7 (0.5) 512 7,398 (187,909) C LTO-2 5040x44 12.7 (0.5) 704 9,638 (244,805) C LTO-3 5050x46 12.7 (0.5) 896 12,725 (323,215) C LTO-4 5060x47 3.81 (0.25) ? 6,417 (163,000) CS DAT-72 5070x48 12.7 (0.5) 448 5,236 (133,000) PRML C SDLTapeI(110) 6,8,13 5080x49 12.7 (0.5) 448 7,598 (193,000) PRML C SDLTapeI(160) 6,8 5090x4A 12.7 (0.5) 768 ? C T10000A 10 5100x4B 12.7 (0.5) 1152 ? C T10000B 10 5110x4C 12.7 (0.5) 3584 ? C T10000C 10 5120x4D 12.7 (0.5) 4608 ? C T10000D 10 5130x51 12.7 (0.5) 512 11,800 (299,720) C 3592A1 (unencrypted) 5140x52 12.7 (0.5) 896 11,800 (299,720) C 3592A2 (unencrypted) 5150x53 12.7 (0.5) 1152 13,452 (341,681) C 3592A3 (unencrypted) 5160x54 12.7 (0.5) 2560 19,686 (500,024) C 3592A4 (unencrypted) 5170x55 12.7 (0.5) 5120 20,670 (525,018) C 3592A5 (unencrypted) 5180x58 12.7 (0.5) 1280 15,142 (384,607) C LTO-5 5190x5A 12.7 (0.5) 2176 15,142 (384,607) C LTO-6 5200x5C 12.7 (0.5) 3584 19,107 (485,318) C LTO-7 5210x71 12.7 (0.5) 512 11,800 (299,720) C 3592A1 (encrypted) 5220x72 12.7 (0.5) 896 11,800 (299,720) C 3592A2 (encrypted) 5230x73 12.7 (0.5) 1152 13,452 (341,681) C 3592A3 (encrypted) 5240x74 12.7 (0.5) 2560 19,686 (500,024) C 3592A4 (encrypted) 5250x75 12.7 (0.5) 5120 20,670 (525,018) C 3592A5 (encrypted) 5260x8c 8.0 (0.315) 1 1,789 (45,434) RLL CS EXB-8500c 5,9 5270x90 8.0 (0.315) 1 1,703 (43,245) RLL CS EXB-8200c 5,9 528.Ed 529.Bd -literal -offset 2n 530Code Description Type Description 531---- -------------------------------------- ---- ----------- 532NRZI Non return to zero, change on ones R Reel-to-reel 533GCR Group code recording C Cartridge 534PE Phase encoded CS Cassette 535IMFM Inverted modified frequency modulation 536MFM Modified frequency modulation 537DDS DAT data storage 538RLL Run length limited 539PRML Partial Response Maximum Likelihood 540.Ed 541.Bd -literal -offset 2n 542NOTES 5431. Serial recorded. 5442. Parallel recorded. 5453. Old format known as QIC-11. 5465. Helical scan. 5476. This is not an American National Standard. The reference is based 548 on an industry standard definition of the media format. 5497. DLT recording: serially recorded track pairs (DLTapeIII and 550 DLTapeIV(20)), or track quads (DLTapeIV(35) and DLTapeIV(40)). 5518. Super DLT (SDLT) recording: 56 serially recorded logical tracks 552 with 8 physical tracks each. 5539. Vendor-specific Exabyte density code for compressed format. 55410. bpi/bpmm values for the Oracle/StorageTek T10000 tape drives are 555 not listed in the manual. Someone with access to a drive can 556 supply the necessary values by running 'mt getdensity'. 55711. This is Exabyte 8200 uncompressed format. The compressed format 558 density code is 0x90. 55912. This is Exabyte 8500 uncompressed format. The compressed format 560 density code is 0x8c. 56113. This density code (0x48) was also used for DAT-160. 562.Ed 563.Sh ENVIRONMENT 564.Bl -tag -width ".Ev TAPE" 565.It Ev TAPE 566This is the pathname of the tape drive. 567The default (if the variable is unset, but not if it is null) is 568.Pa /dev/nsa0 . 569It may be overridden with the 570.Fl f 571option. 572.El 573.Sh FILES 574.Bl -tag -width ".Pa /dev/*sa[0-9]*" -compact 575.It Pa /dev/*sa[0-9]* 576SCSI magnetic tape interface 577.El 578.Sh DIAGNOSTICS 579The exit status will be 0 when the drive operations were successful, 5802 when the drive operations were unsuccessful, and 1 for other 581problems like an unrecognized command or a missing drive device. 582.Sh COMPATIBILITY 583Some undocumented commands support old software. 584.Sh SEE ALSO 585.Xr dd 1 , 586.Xr ioctl 2 , 587.Xr mtio 4 , 588.Xr sa 4 , 589.Xr environ 7 590.Sh HISTORY 591The 592.Nm 593command appeared in 594.Bx 4.3 . 595.Pp 596Extensions regarding the 597.Xr st 4 598driver appeared in 599.Bx 386 0.1 600as a separate 601.Nm st 602command, and have been merged into the 603.Nm 604command in 605.Fx 2.1 . 606.Pp 607The former 608.Cm eof 609command that used to be a synonym for 610.Cm weof 611has been abandoned in 612.Fx 2.1 613since it was often confused with 614.Cm eom , 615which is fairly dangerous. 616.Sh BUGS 617The utility cannot be interrupted or killed during a long erase 618(which can be longer than an hour), and it is easy to forget 619that the default erase is long. 620.Pp 621Hardware block numbers do not always correspond to blocks on the tape 622when the drive uses internal compression. 623.Pp 624Erasure is not guaranteed if the tape is not at its beginning. 625.Pp 626Tape-related documentation is poor, here and elsewhere. 627