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