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: src/usr.bin/mt/mt.1,v 1.19.2.8 2002/11/08 11:35:57 joerg Exp $
  35 .\" $DragonFly: src/usr.bin/mt/mt.1,v 1.2 2003/06/17 04:29:29 dillon Exp $
  36 .\"
  37 .Dd June 6, 1993
  38 .Dt MT 1
  39 .Os
  40 .Sh NAME
  41 .Nm mt
  42 .Nd magnetic tape manipulating program
  43 .Sh SYNOPSIS
  44 .Nm
  45 .Op Fl f Ar tapename
  46 .Ar command
  47 .Op Ar count
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 utility is used to give commands to a magnetic tape drive.
  52 By default
  53 .Nm
  54 performs the requested operation once.  Operations
  55 may be performed multiple times by specifying
  56 .Ar count  .
  57 Note
  58 that
  59 .Ar tapename
  60 must reference a raw (not block) tape device.
  61 .Pp
  62 The available commands are listed below.  Only as many
  63 characters as are required to uniquely identify a command
  64 need be specified.
  65 .Bl -tag -width "eof, weof"
  66 .It Cm weof
  67 Write
  68 .Ar count
  69 end-of-file marks at the current position on the tape.
  70 .It Cm smk
  71 Write
  72 .Ar count
  73 setmarks at the current position on the tape.
  74 .It Cm fsf
  75 Forward space
  76 .Ar count
  77 files.
  78 .It Cm fsr
  79 Forward space
  80 .Ar count
  81 records.
  82 .It Cm fss
  83 Forward space
  84 .Ar count
  85 setmarks.
  86 .It Cm bsf
  87 Backward space
  88 .Ar count
  89 files.
  90 .It Cm bsr
  91 Backward space
  92 .Ar count
  93 records.
  94 .It Cm bss
  95 Backward space
  96 .Ar count
  97 setmarks.
  98 .It Cm rdhpos
  99 Read Hardware block position.
 100 Some drives do not support this.
 101 The block
 102 number reported is specific for that hardware only.
 103 The count argument is
 104 ignored.
 105 .It Cm rdspos
 106 Read SCSI logical block position.
 107 Some drives do not support this.
 108 The
 109 count argument is ignored.
 110 .It Cm sethpos
 111 Set Hardware block position.
 112 Some drives do not support this.
 113 The count
 114 argument is interpreted as a hardware block to which to position the tape.
 115 .It Cm setspos
 116 Set SCSI logical block position.
 117 Some drives do not support this.
 118 The count
 119 argument is interpreted as a SCSI logical block to which to position the tape.
 120 .It Cm rewind
 121 Rewind the tape
 122 (Count is ignored).
 123 .It Cm offline , rewoffl
 124 Rewind the tape and place the tape unit off-line
 125 (Count is ignored).
 126 .It Cm erase
 127 Erase the tape.
 128 A count of 0 disables long erase, which is on by default.
 129 .It Cm retension
 130 Re-tension the tape
 131 (one full wind forth and back, Count is ignored).
 132 .It Cm status
 133 Print status information about the tape unit.
 134 For SCSI magnetic tape devices,
 135 the current operating modes of density, blocksize, and whether compression
 136 is enabled is reported.
 137 The current state of the driver (what it thinks that
 138 it is doing with the device) is reported.
 139 If the driver knows the relative
 140 position from BOT (in terms of filemarks and records), it prints that.
 141 Note
 142 that this information is not definitive (only BOT, End of Recorded Media, and
 143 hardware or SCSI logical block position (if the drive supports such) are
 144 considered definitive tape positions).
 145 .It Cm errstat
 146 Print (and clear) error status information about this device.
 147 For every normal
 148 operation (e.g., a read or a write) and every control operation (e.g,, a
 149 rewind), the driver stores up the last command executed and it's associated
 150 status and any residual counts (if any). This command retrieves and prints this
 151 information.
 152 If possible, this also clears any latched error information.
 153 .It Cm blocksize
 154 Set the block size for the tape unit.  Zero means variable-length
 155 blocks.
 156 .It Cm density
 157 Set the density for the tape unit.  For the density codes, see below.
 158 The density value could be given either numerically, or as a string,
 159 corresponding to the
 160 .Dq Reference
 161 field.  If the string is abbreviated, it will be resolved in the order
 162 shown in the table, and the first matching entry will be used.  If the
 163 given string and the resulting canonical density name do not match
 164 exactly, an informational message is printed about what the given
 165 string has been taken for.
 166 .It Cm geteotmodel
 167 Fetch and print out the current EOT filemark model.
 168 The model states how
 169 many filemarks will be written at close if a tape was being written.
 170 .It Cm seteotmodel
 171 Set (from the
 172 .Ar count
 173 argument)
 174 and print out the current and EOT filemark model.
 175 Typically this will be
 176 .Ar 2
 177 filemarks, but some devices (typically QIC cartridge drives) can
 178 only write
 179 .Ar 1
 180 filemark.
 181 Currently you can only choose a value of
 182 .Ar 1
 183 or
 184 .Ar 2 .
 185 .It Cm eom
 186 Forward space to end of recorded medium
 187 (Count is ignored).
 188 .It Cm eod
 189 Forward space to end of data, identical to
 190 .Cm eom .
 191 .It Cm comp
 192 Set compression mode.
 193 There are currently several possible values for the compression mode:
 194 .Pp
 195 .Bl -tag -width 9n -compact
 196 .It off
 197 Turn compression off.
 198 .It on
 199 Turn compression on.
 200 .It none
 201 Same as
 202 .Ar off .
 203 .It enable
 204 Same as
 205 .Ar on .
 206 .It IDRC
 207 IBM Improved Data Recording Capability compression (0x10).
 208 .It DCLZ
 209 DCLZ compression algorithm (0x20).
 210 .El
 211 .Pp
 212 In addition to the above recognized compression keywords, the user can
 213 supply a numeric compression algorithm for the tape drive to use.  In most
 214 cases, simply turning the compression
 215 .Sq on
 216 will have the desired effect of enabling the default compression algorithm
 217 supported by the drive.  If this is not the case (see the
 218 .Cm status
 219 display to see which compression algorithm is currently in use), the user
 220 can manually specify one of the supported compression keywords (above), or
 221 supply a numeric compression value.
 222 .El
 223 .Pp
 224 If a tape name is not specified, and the environment variable
 225 .Ev TAPE
 226 does not exist;
 227 .Nm
 228 uses the device
 229 .Pa /dev/nsa0 .
 230 .Pp
 231 The
 232 .Nm
 233 utility returns a 0 exit status when the operation(s) were successful,
 234 1 if the command was unrecognized, and 2 if an operation failed.
 235 .Pp
 236 The following density table was taken from the
 237 .Sq Historical sequential access density codes
 238 table (A-1) in Revision 11 of the SCSI-3 Stream Device Commands (SSC)
 239 working draft, dated November 11, 1997.
 240 .Pp
 241 The different density codes are as follows:
 242 .Pp
 243 .Dl "0x0        default for device"
 244 .Dl "0xE        reserved for ECMA"
 245 .Bd -literal -offset 3n
 246 Value  Width        Tracks    Density         Code Type Reference   Note
 247         mm    in              bpmm       bpi
 248 0x01   12.7  (0.5)    9         32     (800)  NRZI  R   X3.22-1983   2
 249 0x02   12.7  (0.5)    9         63   (1,600)  PE    R   X3.39-1986   2
 250 0x03   12.7  (0.5)    9        246   (6,250)  GCR   R   X3.54-1986   2
 251 0x05    6.3  (0.25)  4/9       315   (8,000)  GCR   C   X3.136-1986  1
 252 0x06   12.7  (0.5)    9        126   (3,200)  PE    R   X3.157-1987  2
 253 0x07    6.3  (0.25)   4        252   (6,400)  IMFM  C   X3.116-1986  1
 254 0x08    3.81 (0.15)   4        315   (8,000)  GCR   CS  X3.158-1987  1
 255 0x09   12.7  (0.5)   18      1,491  (37,871)  GCR   C   X3.180       2
 256 0x0A   12.7  (0.5)   22        262   (6,667)  MFM   C   X3B5/86-199  1
 257 0x0B    6.3  (0.25)   4         63   (1,600)  PE    C   X3.56-1986   1
 258 0x0C   12.7  (0.5)   24        500  (12,690)  GCR   C   HI-TC1       1,6
 259 0x0D   12.7  (0.5)   24        999  (25,380)  GCR   C   HI-TC2       1,6
 260 0x0F    6.3  (0.25)  15        394  (10,000)  GCR   C   QIC-120      1,6
 261 0x10    6.3  (0.25)  18        394  (10,000)  GCR   C   QIC-150      1,6
 262 0x11    6.3  (0.25)  26        630  (16,000)  GCR   C   QIC-320      1,6
 263 0x12    6.3  (0.25)  30      2,034  (51,667)  RLL   C   QIC-1350     1,6
 264 0x13    3.81 (0.15)   1      2,400  (61,000)  DDS   CS  X3B5/88-185A 5
 265 0x14    8.0  (0.315)  1      1,703  (43,245)  RLL   CS  X3.202-1991  5
 266 0x15    8.0  (0.315)  1      1,789  (45,434)  RLL   CS  ECMA TC17    5
 267 0x16   12.7  (0.5)   48        394  (10,000)  MFM   C   X3.193-1990  1
 268 0x17   12.7  (0.5)   48      1,673  (42,500)  MFM   C   X3B5/91-174  1
 269 0x18   12.7  (0.5)  112      1,673  (42,500)  MFM   C   X3B5/92-50   1
 270 0x19   12.7  (0.5)  128      2,460  (62,500)  RLL   C   DLTapeIII    6,7
 271 0x1A   12.7  (0.5)  128      3,214  (81,633)  RLL   C   DLTapeIV(20) 6,7
 272 0x1B   12.7  (0.5)  208      3,383  (85,937)  RLL   C   DLTapeIV(35) 6,7
 273 0x1C    6.3  (0.25)  34      1,654  (42,000)  MFM   C   QIC-385M     1,6
 274 0x1D    6.3  (0.25)  32      1,512  (38,400)  GCR   C   QIC-410M     1,6
 275 0x1E    6.3  (0.25)  30      1,385  (36,000)  GCR   C   QIC-1000C    1,6
 276 0x1F    6.3  (0.25)  30      2,666  (67,733)  RLL   C   QIC-2100C    1,6
 277 0x20    6.3  (0.25) 144      2,666  (67,733)  RLL   C   QIC-6GB(M)   1,6
 278 0x21    6.3  (0.25) 144      2,666  (67,733)  RLL   C   QIC-20GB(C)  1,6
 279 0x22    6.3  (0.25)  42      1,600  (40,640)  GCR   C   QIC-2GB(C)   ?
 280 0x23    6.3  (0.25)  38      2,666  (67,733)  RLL   C   QIC-875M     ?
 281 0x24    3.81 (0.15)   1      2,400  (61,000)        CS  DDS-2        5
 282 0x25    3.81 (0.15)   1      3,816  (97,000)        CS  DDS-3        5
 283 0x26    3.81 (0.15)   1      3,816  (97,000)        CS  DDS-4        5
 284 0x27    8.0  (0.315)  1      3,056  (77,611)  RLL   CS  Mammoth      5
 285 0x28   12.7  (0.5)   36      1,491  (37,871)  GCR   C   X3.224       1
 286 0x29   12.7  (0.5)
 287 0x2A
 288 0x2B   12.7  (0.5)    3          ?        ?     ?   C   X3.267       5
 289 0x41   12.7  (0.5)  208      3,868  (98,250)  RLL   C   DLTapeIV(40) 6,7
 290 0x48   12.7  (0.5)  448      5,236  (133,000) PRML  C   SDLTapeI(110) 6,8
 291 0x49   12.7  (0.5)  448      7,598  (193,000) PRML  C   SDLTapeI(160) 6,8
 292 .Ed
 293 .Bd -literal -offset 3n
 294 Code Description                                   Type Description
 295 ----------------                                   ----------------
 296 NRZI    Non return to zero, change on ones         R Reel-to-reel
 297 GCR     Group code recording                       C Cartridge
 298 PE      Phase encoded                              CS Cassette
 299 IMFM    Inverted modified frequency modulation
 300 MFM     Modified frequency modulation
 301 DDS     DAT data storage
 302 RLL     Run length limited
 303 PRML    Partial Response Maximum Likelihood
 304 .Ed
 305 .Bd -literal -offset 3n
 306 NOTES
 307 1. Serial recorded.
 308 2. Parallel recorded.
 309 3. Old format known as QIC-11.
 310 5. Helical scan.
 311 6. This is not an American National Standard.  The reference is based on
 312    an industry standard definition of the media format.
 313 7. DLT recording: serially recorded track pairs (DLTapeIII and
 314    DLTapeIV(20)), or track quads (DLTapeIV(35) and DLTapeIV(40)).
 315 8. Super DLT (SDLT) recording: 56 serially recorded logical tracks with
 316    8 physical tracks each.
 317 .Ed
 318 .Sh ENVIRONMENT
 319 If the following environment variable exists, it is utilized by
 320 .Nm .
 321 .Bl -tag -width Fl
 322 .It Ev TAPE
 323 The
 324 .Nm
 325 utility checks the
 326 .Ev TAPE
 327 environment variable if the
 328 argument
 329 .Ar tapename
 330 is not given.
 331 .El
 332 .Sh FILES
 333 .Bl -tag -width /dev/*rst[0-9]*xx -compact
 334 .It Pa /dev/*rwt*
 335 QIC-02/QIC-36 magnetic tape interface
 336 .It Pa /dev/*rsa[0-9]*
 337 SCSI magnetic tape interface
 338 .El
 339 .Sh SEE ALSO
 340 .Xr dd 1 ,
 341 .Xr ioctl 2 ,
 342 .Xr mtio 4 ,
 343 .Xr sa 4 ,
 344 .Xr wt 4 ,
 345 .Xr environ 7
 346 .Sh HISTORY
 347 The
 348 .Nm
 349 command appeared in
 350 .Bx 4.3 .
 351 .Pp
 352 Extensions regarding the
 353 .Xr st 4
 354 driver appeared in
 355 .Bx 386 0.1
 356 as a separate
 357 .Xr st 1
 358 command, and have been merged into the
 359 .Nm
 360 command in
 361 .Fx 2.1 .
 362 .Pp
 363 The former
 364 .Cm eof
 365 command that used to be a synonym for
 366 .Cm weof
 367 has been abandoned in
 368 .Fx 2.1
 369 since it was often confused with
 370 .Cm eom ,
 371 which is fairly dangerous.