usr.bin/mt/mt.1

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