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