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