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