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