Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
MT(1)                   FreeBSD General Commands Manual                  MT(1)

NAME
     mt - magnetic tape manipulating program

SYNOPSIS
     mt [-f tapename] command [count]
     mt [-f tapename] command argument

DESCRIPTION
     The mt utility is used to command a magnetic tape drive for operations
     other than reading or writing data.

     The -f option's tapename overrides the TAPE environment variable
     described below.

     The available commands are listed below.  Only as many characters as are
     required to uniquely identify a command need be specified.

     The following commands optionally take a count, which defaults to 1.

     weof       Write count end-of-file (EOF) marks at the current position.
                This returns when the file mark has been written to the media.

     weofi      Write count end-of-file (EOF) marks at the current position.
                This returns as soon as the command has been validated by the
                tape drive.

     smk        Write count setmarks at the current position (DDS drives
                only).

     fsf        Forward space count files.

     fsr        Forward space count records.

     fss        Forward space count setmarks (DDS drives only).

     bsf        Backward space count files.

     bsr        Backward space count records.

     bss        Backward space count setmarks (DDS drives only).

     erase      Erase the tape using a long (often very long) method.  With a
                count of 0, it will erase the tape using a quick method.
                Operation is not guaranteed if the tape is not at its
                beginning.  The tape will be at its beginning upon completion.

     The following commands ignore count.

     rdhpos           Read the hardware block position.  The block number
                      reported is specific for that hardware only.  With drive
                      data compression especially, this position may have more
                      to do with the amount of data sent to the drive than the
                      amount of data written to tape.  Some drives do not
                      support this.

     rdspos           Read the SCSI logical block position.  This typically is
                      greater than the hardware position by the number of end-
                      of-file marks.  Some drives do not support this.

     rewind           Rewind the tape.

     offline, rewoffl
                      Rewind the tape and place the drive off line.  Some
                      drives are never off line.

     load             Load the tape into the drive.

     retension        Re-tension the tape.  This winds the tape from the
                      current position to the end and then to the beginning.
                      This sometimes improves subsequent reading and writing,
                      particularly for streaming drives.  Some drives do not
                      support this.

     ostatus          Output status information about the drive.  For SCSI
                      magnetic tape devices, the current operating modes of
                      density, blocksize, and whether compression is enabled
                      is reported.  The current state of the driver (what it
                      thinks that it is doing with the device) is reported.
                      If the driver knows the relative position from BOT (in
                      terms of filemarks and records), it outputs that.  Note
                      that this information is not definitive (only BOT, End
                      of Recorded Media, and hardware or SCSI logical block
                      position (if the drive supports such) are considered
                      definitive tape positions).

                      Also note that this is the old status command, and will
                      be eliminated in favor of the new status command (see
                      below) in a future release.

     errstat          Output (and clear) error status information about this
                      device.  For every normal operation (e.g., a read or a
                      write) and every control operation (e.g,, a rewind), the
                      driver stores up the last command executed and it is
                      associated status and any residual counts (if any).
                      This command retrieves and outputs this information.  If
                      possible, this also clears any latched error
                      information.

     geteotmodel      Output the current EOT filemark model.  The model states
                      how many filemarks will be written at close if a tape
                      was being written.

     eod, eom         Wind the tape to the end of the recorded data, typically
                      after an EOF mark where another file may be written.

     rblim            Report the block limits of the tape drive, including the
                      minimum and maximum block size, and the block
                      granularity if any.

     The following commands may require an argument.

     sethpos          Set the hardware block position.  The argument is a
                      hardware block number to which to position the tape.
                      Some drives do not support this.

     setspos          Set the SCSI logical block position.  The argument is a
                      SCSI logical block number to which to position the tape.
                      Some drives do not support this.

     blocksize        Set the block size for the drive.  The argument is the
                      number of bytes per block, except 0 commands the drive
                      to use variable-length blocks.

     seteotmodel      Set the EOT filemark model to argument and output the
                      old and new models.  Typically this will be 2 filemarks,
                      but some devices (typically QIC cartridge drives) can
                      only write 1 filemark.  You may only choose a value of 1
                      or 2.

     status           Output status information about the drive.  For SCSI
                      magnetic tape devices, the current operating modes of
                      density, blocksize, and whether compression is enabled
                      is reported.  The current state of the driver (what it
                      thinks that it is doing with the device) is reported.

                      If the driver knows the relative position from BOT (in
                      terms of filemarks and records), it outputs that.  If
                      the tape drive supports the long form report of the SCSI
                      READ POSITION command, the Reported File Number and
                      Reported Record Number will be numbers other than -1,
                      and there may be Flags reported as well.

                      The BOP flag means that the logical position of the
                      drive is at the beginning of the partition.

                      The EOP flag means that the logical position of the
                      drive is between Early Warning and End of Partition.

                      The BPEW flag means that the logical position of the
                      drive is in a Programmable Early Warning Zone or on the
                      EOP side of Early Warning.

                      Note that the Reported Record Number is the tape block
                      or object number relative to the beginning of the
                      partition.  The Calculated Record Number is the tape
                      block or object number relative to the previous file
                      mark.

                      Note that the Calculated File and Record Numbers are not
                      definitive.  The Reported File and Record Numbers are
                      definitive, if they are numbers other than -1.

                      -v      Print additional status information, such as the
                              maximum supported I/O size.

                      -x      Print all available status data to stdout in XML
                              format.

     getdensity       Report density support information for the tape drive
                      and any media that is loaded.  Most drives will report
                      at least basic density information similar to that
                      reported by status command.  Newer tape drives that
                      conform to the T-10 SSC and newer tape specifications
                      may report more detailed information about the types of
                      tapes they support and the tape currently in the drive.

                      -x      Print all available density data to stdout in
                              XML format.  Because density information is
                              currently included in the general status XML
                              report used for mt status command, this will be
                              the same XML output via ``mt status -x''

     param            Display or set parameters.  One of -l, -s, or -x must be
                      specified to indicate which operation to perform.

                      -l        List parameters, values and descriptions.  By
                                default all parameters will be displayed.  To
                                display a specific parameter, specify the
                                parameter with -p.

                      -p name   Specify the parameter name to list (with -l)
                                or set (with -s).

                      -q        Enable quiet mode for parameter listing.  This
                                will suppress printing of parameter
                                descriptions.

                      -s value  Specify the parameter value to set.  The
                                general type of this argument (integer,
                                unsigned integer, string) is determined by the
                                type of the variable indicated by the sa(4)
                                driver.  More detailed argument checking is
                                done by the sa(4) driver.

                      -x        Print out all parameter information in XML
                                format.

     protect          Display or set drive protection parameters.  This is
                      used to control checking and reporting a per-block
                      checksum for tape drives that support it.  Some drives
                      may only support some parameters.

                      -b 0|1    Set the Recover Buffered Data Protected bit.
                                If set, this indicates that checksums are
                                transferred with the logical blocks
                                transferred by the RECOVERED BUFFERED DATA
                                SCSI command.

                      -d        Disable all protection information settings.

                      -e        Enable all protection information settings.
                                The default protection method used is Reed-
                                Solomon CRC (protection method 1), as
                                specified in ECMA-319.  The default protection
                                information length used with Reed-Solomon CRC
                                is 4 bytes.  To enable all settings except one
                                more more settings, specify the -e argument
                                and then explicitly disable settings that you
                                do not wish to enable.  For example,
                                specifying -e -w 0 will enable all settings
                                except for LBP_W.

                      -l        List available protection parmeters and their
                                current settings.

                      -L len    Set the length of the protection information
                                in bytes.  For Reed-Solomon CRC, the
                                protection information length should be 4
                                bytes.

                      -m num    Specify the numeric value for the protection
                                method.  The numeric value for Reed-Solomon
                                CRC is 1.

                      -r 0|1    Set the LBP_R parameter.  When set, this
                                indicates that each block read from the tape
                                drive will have a checksum at the end.

                      -v        Enable verbose mode for parameter listing.
                                This will include descriptions of each
                                parameter.

                      -w 0|1    Set the LBP_W parameter.  When set, this
                                indicates that each block written to the tape
                                drive will have a checksum at the end.  The
                                drive will verify the checksum before writing
                                the block to tape.

     locate           Set the tape drive's logical position.  One of -b, -e,
                      -f, or -s must be specified to indicate the type of
                      position.  If the partition number is specified, the
                      drive will first relocate to the given partition (if it
                      exists) and then to the position indicated within that
                      partition.  If the partition number is not specified,
                      the drive will relocate to the given position within the
                      current partition.

                      -b block_addr   Relocate to the given tape block or
                                      logical object identifier.  Note that
                                      the block number is the Reported Record
                                      Number that is relative to the beginning
                                      of the partition (or beginning of tape).

                      -e              Relocate to the end of data.

                      -f fileno       Relocate to the given file number.

                      -p partition    Specify the partition to change to.

                      -s setmark      Relocate to the given set mark.

     comp             Set the drive's compression mode.  The non-numeric
                      values of argument are:

                      off        Turn compression off.
                      on         Turn compression on.
                      none       Same as off.
                      enable     Same as on.
                      IDRC       IBM Improved Data Recording Capability
                                 compression (0x10).
                      DCLZ       DCLZ compression algorithm (0x20).

                      In addition to the above recognized compression
                      keywords, the user can supply a numeric compression
                      algorithm for the drive to use.  In most cases, simply
                      turning the compression `on' will have the desired
                      effect of enabling the default compression algorithm
                      supported by the drive.  If this is not the case (see
                      the status display to see which compression algorithm is
                      currently in use), the user can manually specify one of
                      the supported compression keywords (above), or supply a
                      numeric compression value from the drive's
                      specifications.

                      Note that for some older tape drives (for example the
                      Exabyte 8200 and 8500 series drives) it is necessary to
                      switch to a different density to tell the drive to
                      record data in its compressed format.  If the user
                      attempts to turn compression on while the uncompressed
                      density is selected, the drive will return an error.
                      This is generally not an issue for modern tape drives.

     density          Set the density for the drive.  For the density codes,
                      see below.  The density value could be given either
                      numerically, or as a string, corresponding to the
                      ``Reference'' field.  If the string is abbreviated, it
                      will be resolved in the order shown in the table, and
                      the first matching entry will be used.  If the given
                      string and the resulting canonical density name do not
                      match exactly, an informational message is output about
                      what the given string has been taken for.

     The initial version of the density table below was taken from the
     `Historical sequential access density codes' table (A-1) in Revision 11
     of the SCSI-3 Stream Device Commands (SSC) working draft, dated November
     11, 1997.  Subsequent additions have come from a number of sources.

     The density codes are:

       0x0    default for device
       0xE    reserved for ECMA

       Value  Width        Tracks    Density         Code Type Reference   Note
               mm    in              bpmm       bpi
       0x01   12.7  (0.5)    9         32     (800)  NRZI  R   X3.22-1983   2
       0x02   12.7  (0.5)    9         63   (1,600)  PE    R   X3.39-1986   2
       0x03   12.7  (0.5)    9        246   (6,250)  GCR   R   X3.54-1986   2
       0x05    6.3  (0.25)  4/9       315   (8,000)  GCR   C   X3.136-1986  1
       0x06   12.7  (0.5)    9        126   (3,200)  PE    R   X3.157-1987  2
       0x07    6.3  (0.25)   4        252   (6,400)  IMFM  C   X3.116-1986  1
       0x08    3.81 (0.15)   4        315   (8,000)  GCR   CS  X3.158-1987  1
       0x09   12.7  (0.5)   18      1,491  (37,871)  GCR   C   X3.180       2
       0x0A   12.7  (0.5)   22        262   (6,667)  MFM   C   X3B5/86-199  1
       0x0B    6.3  (0.25)   4         63   (1,600)  PE    C   X3.56-1986   1
       0x0C   12.7  (0.5)   24        500  (12,690)  GCR   C   HI-TC1       1,6
       0x0D   12.7  (0.5)   24        999  (25,380)  GCR   C   HI-TC2       1,6
       0x0F    6.3  (0.25)  15        394  (10,000)  GCR   C   QIC-120      1,6
       0x10    6.3  (0.25)  18        394  (10,000)  GCR   C   QIC-150      1,6
       0x11    6.3  (0.25)  26        630  (16,000)  GCR   C   QIC-320      1,6
       0x12    6.3  (0.25)  30      2,034  (51,667)  RLL   C   QIC-1350     1,6
       0x13    3.81 (0.15)   1      2,400  (61,000)  DDS   CS  X3B5/88-185A 5
       0x14    8.0  (0.315)  1      1,703  (43,245)  RLL   CS  X3.202-1991  5,11
       0x15    8.0  (0.315)  1      1,789  (45,434)  RLL   CS  ECMA TC17    5,12
       0x16   12.7  (0.5)   48        394  (10,000)  MFM   C   X3.193-1990  1
       0x17   12.7  (0.5)   48      1,673  (42,500)  MFM   C   X3B5/91-174  1
       0x18   12.7  (0.5)  112      1,673  (42,500)  MFM   C   X3B5/92-50   1
       0x19   12.7  (0.5)  128      2,460  (62,500)  RLL   C   DLTapeIII    6,7
       0x1A   12.7  (0.5)  128      3,214  (81,633)  RLL   C   DLTapeIV(20) 6,7
       0x1B   12.7  (0.5)  208      3,383  (85,937)  RLL   C   DLTapeIV(35) 6,7
       0x1C    6.3  (0.25)  34      1,654  (42,000)  MFM   C   QIC-385M     1,6
       0x1D    6.3  (0.25)  32      1,512  (38,400)  GCR   C   QIC-410M     1,6
       0x1E    6.3  (0.25)  30      1,385  (36,000)  GCR   C   QIC-1000C    1,6
       0x1F    6.3  (0.25)  30      2,666  (67,733)  RLL   C   QIC-2100C    1,6
       0x20    6.3  (0.25) 144      2,666  (67,733)  RLL   C   QIC-6GB(M)   1,6
       0x21    6.3  (0.25) 144      2,666  (67,733)  RLL   C   QIC-20GB(C)  1,6
       0x22    6.3  (0.25)  42      1,600  (40,640)  GCR   C   QIC-2GB(C)   ?
       0x23    6.3  (0.25)  38      2,666  (67,733)  RLL   C   QIC-875M     ?
       0x24    3.81 (0.15)   1      2,400  (61,000)        CS  DDS-2        5
       0x25    3.81 (0.15)   1      3,816  (97,000)        CS  DDS-3        5
       0x26    3.81 (0.15)   1      3,816  (97,000)        CS  DDS-4        5
       0x27    8.0  (0.315)  1      3,056  (77,611)  RLL   CS  Mammoth      5
       0x28   12.7  (0.5)   36      1,491  (37,871)  GCR   C   X3.224       1
       0x29   12.7  (0.5)
       0x2A
       0x2B   12.7  (0.5)    3          ?        ?     ?   C   X3.267       5
       0x40   12.7  (0.5)  384      4,800  (123,952)       C   LTO-1
       0x41   12.7  (0.5)  208      3,868  (98,250)  RLL   C   DLTapeIV(40) 6,7
       0x42   12.7  (0.5)  512      7,398  (187,909)       C   LTO-2
       0x44   12.7  (0.5)  704      9,638  (244,805)       C   LTO-3
       0x46   12.7  (0.5)  896      12,725 (323,215)       C   LTO-4
       0x47    3.81 (0.25)   ?      6,417  (163,000)       CS  DAT-72
       0x48   12.7  (0.5)  448      5,236  (133,000) PRML  C   SDLTapeI(110) 6,8,13
       0x49   12.7  (0.5)  448      7,598  (193,000) PRML  C   SDLTapeI(160) 6,8
       0x4A   12.7  (0.5)  768          ?                  C   T10000A      10
       0x4B   12.7  (0.5) 1152          ?                  C   T10000B      10
       0x4C   12.7  (0.5) 3584          ?                  C   T10000C      10
       0x4D   12.7  (0.5) 4608          ?                  C   T10000D      10
       0x51   12.7  (0.5)  512      11,800 (299,720)       C   3592A1 (unencrypted)
       0x52   12.7  (0.5)  896      11,800 (299,720)       C   3592A2 (unencrypted)
       0x53   12.7  (0.5) 1152      13,452 (341,681)       C   3592A3 (unencrypted)
       0x54   12.7  (0.5) 2560      19,686 (500,024)       C   3592A4 (unencrypted)
       0x55   12.7  (0.5) 5120      20,670 (525,018)       C   3592A5 (unencrypted)
       0x58   12.7  (0.5) 1280      15,142 (384,607)       C   LTO-5
       0x5A   12.7  (0.5) 2176      15,142 (384,607)       C   LTO-6
       0x71   12.7  (0.5)  512      11,800 (299,720)       C   3592A1 (encrypted)
       0x72   12.7  (0.5)  896      11,800 (299,720)       C   3592A2 (encrypted)
       0x73   12.7  (0.5) 1152      13,452 (341,681)       C   3592A3 (encrypted)
       0x74   12.7  (0.5) 2560      19,686 (500,024)       C   3592A4 (encrypted)
       0x75   12.7  (0.5) 5120      20,670 (525,018)       C   3592A5 (encrypted)
       0x8c    8.0  (0.315)  1      1,789  (45,434)  RLL   CS  EXB-8500c    5,9
       0x90    8.0  (0.315)  1      1,703  (43,245)  RLL   CS  EXB-8200c    5,9

       Code    Description                                Type Description
       ----    --------------------------------------     ---- -----------
       NRZI    Non return to zero, change on ones         R    Reel-to-reel
       GCR     Group code recording                       C    Cartridge
       PE      Phase encoded                              CS   Cassette
       IMFM    Inverted modified frequency modulation
       MFM     Modified frequency modulation
       DDS     DAT data storage
       RLL     Run length limited
       PRML    Partial Response Maximum Likelihood

       NOTES
       1.  Serial recorded.
       2.  Parallel recorded.
       3.  Old format known as QIC-11.
       5.  Helical scan.
       6.  This is not an American National Standard.  The reference is based
           on an industry standard definition of the media format.
       7.  DLT recording: serially recorded track pairs (DLTapeIII and
           DLTapeIV(20)), or track quads (DLTapeIV(35) and DLTapeIV(40)).
       8.  Super DLT (SDLT) recording: 56 serially recorded logical tracks
           with 8 physical tracks each.
       9.  Vendor-specific Exabyte density code for compressed format.
       10. bpi/bpmm values for the Oracle/StorageTek T10000 tape drives are
           not listed in the manual.  Someone with access to a drive can
           supply the necessary values by running 'mt getdensity'.
       11. This is Exabyte 8200 uncompressed format.  The compressed format
           density code is 0x90.
       12. This is Exabyte 8500 uncompressed format.  The compressed format
           density code is 0x8c.
       13. This density code (0x48) was also used for DAT-160.

ENVIRONMENT
     TAPE      This is the pathname of the tape drive.  The default (if the
               variable is unset, but not if it is null) is /dev/nsa0.  It may
               be overridden with the -f option.

FILES
     /dev/*sa[0-9]*      SCSI magnetic tape interface

DIAGNOSTICS
     The exit status will be 0 when the drive operations were successful, 2
     when the drive operations were unsuccessful, and 1 for other problems
     like an unrecognized command or a missing drive device.

COMPATIBILITY
     Some undocumented commands support old software.

SEE ALSO
     dd(1), ioctl(2), mtio(4), sa(4), environ(7)

HISTORY
     The mt command appeared in 4.3BSD.

     Extensions regarding the st(4) driver appeared in 386BSD-0.1 as a
     separate st command, and have been merged into the mt command in
     FreeBSD 2.1.

     The former eof command that used to be a synonym for weof has been
     abandoned in FreeBSD 2.1 since it was often confused with eom, which is
     fairly dangerous.

BUGS
     The utility cannot be interrupted or killed during a long erase (which
     can be longer than an hour), and it is easy to forget that the default
     erase is long.

     Hardware block numbers do not always correspond to blocks on the tape
     when the drive uses internal compression.

     Erasure is not guaranteed if the tape is not at its beginning.

     Tape-related documentation is poor, here and elsewhere.

FreeBSD 11.0-PRERELEASE          March 3, 2014         FreeBSD 11.0-PRERELEASE

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | FILES | DIAGNOSTICS | COMPATIBILITY | SEE ALSO | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mt&manpath=FreeBSD+10.3-RELEASE+and+Ports>

home | help