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