1 MTIO(7I)                        Ioctl Requests                        MTIO(7I)
   2 
   3 NAME
   4      mtio - general magnetic tape interface
   5 
   6 SYNOPSIS
   7      #include <sys/types.h>
   8      #include <sys/ioctl.h>
   9      #include <sys/mtio.h>
  10 
  11 DESCRIPTION
  12      1/2", 1/4", 4mm, and 8mm magnetic tape drives all share the same general
  13      character device interface.
  14 
  15      There are two types of tape records: data records and end-of-file (EOF)
  16      records.  EOF records are also known as tape marks and file marks.  A
  17      record is separated by interrecord (or tape) gaps on a tape.
  18 
  19      End-of-recorded-media (EOM) is indicated by two EOF marks on 1/2" tape;
  20      by one EOF mark on 1/4", 4mm, and 8mm cartridge tapes.
  21 
  22    1/2" Reel Tape
  23      Data bytes are recorded in parallel onto the 9-track tape.  Since it is a
  24      variable-length tape device, the number of bytes in a physical record may
  25      vary.
  26 
  27      The recording formats available (check specific tape drive) are 800 BPI,
  28      1600 BPI, 6250 BPI, and data compression.  Actual storage capacity is a
  29      function of the recording format and the length of the tape reel.  For
  30      example, using a 2400 foot tape, 20 Mbyte can be stored using 800 BPI, 40
  31      Mbyte using 1600 BPI, 140 Mbyte using 6250 BPI, or up to 700 Mbyte using
  32      data compression.
  33 
  34    1/4" Cartridge Tape
  35      Data is recorded serially onto 1/4" cartridge tape.  The number of bytes
  36      per record is determined by the physical record size of the device.  The
  37      I/O request size must be a multiple of the physical record size of the
  38      device.  For QIC-11, QIC-24, and QIC-150 tape drives, the block size is
  39      512 bytes.
  40 
  41      The records are recorded on tracks in a serpentine motion.  As one track
  42      is completed, the drive switches to the next and begins writing in the
  43      opposite direction, eliminating the wasted motion of rewinding.  Each
  44      file, including the last, ends with one file mark.
  45 
  46      Storage capacity is based on the number of tracks the drive is capable of
  47      recording.  For example, 4-track drives can only record 20 Mbyte of data
  48      on a 450 foot tape; 9-track drives can record up to 45 Mbyte of data on a
  49      tape of the same length.  QIC-11 is the only tape format available for
  50      4-track tape drives.  In contrast, 9-track tape drives can use either
  51      QIC-24 or QIC-11.  Storage capacity is not appreciably affected by using
  52      either format.  QIC-24 is preferable to QIC-11 because it records a
  53      reference signal to mark the position of the first track on the tape, and
  54      each block has a unique block number.
  55 
  56      The QIC-150 tape drives require DC-6150 (or equivalent) tape cartridges
  57      for writing.  However, they can read other tape cartridges in QIC-11,
  58      QIC-24, or QIC-120 tape formats.
  59 
  60    8mm Cartridge Tape
  61      Data is recorded serially onto 8mm helical scan cartridge tape.  Since it
  62      is a variable-length tape device, the number of bytes in a physical
  63      record may vary.  The recording formats available (check specific tape
  64      drive) are standard 2Gbyte, 5Gbyte, and compressed format.
  65 
  66    4mm DAT Tape
  67      Data is recorded either in Digital Data Storage (DDS) tape format or in
  68      Digital Data Storage, Data Compressed (DDS-DC) tape format.  Since it is
  69      a variable-length tape device, the number of bytes in a physical record
  70      may vary.  The recording formats available are standard 2Gbyte and
  71      compressed format.
  72 
  73    Persistent Error Handling
  74      Persistent error handling is a modification of the current error handling
  75      behaviors, BSD and SVR4.  With persistent error handling enabled, all
  76      tape operations after an error or exception will return immediately with
  77      an error.  Persistent error handling can be most useful with asynchronous
  78      tape operations that use the aioread(3C) and aiowrite(3C) functions.
  79 
  80      To enable persistent error handling, the ioctl MTIOCPERSISTENT must be
  81      issued.  If this ioctl succeeds, then persistent error handling is
  82      enabled and changes the current error behavior.  This ioctl will fail if
  83      the device driver does not support persistent error handling.
  84 
  85      With persistent error handling enabled, all tape operations after an
  86      exception or error will return with the same error as the first command
  87      that failed; the operations will not be executed.  An exception is some
  88      event that might stop normal tape operations, such as an End Of File
  89      (EOF) mark or an End Of Tape (EOT) mark.  An example of an error is a
  90      media error.  The MTIOCLRERR ioctl must be issued to allow normal tape
  91      operations to continue and to clear the error.
  92 
  93      Disabling persistent error handling returns the error behavior to normal
  94      SVR4 error handling, and will not occur until all outstanding operations
  95      are completed.  Applications should wait for all outstanding operations
  96      to complete before disabling persistent error handling.  Closing the
  97      device will also disable persistent error handling and clear any errors
  98      or exceptions.
  99 
 100      The Read Operation and Write Operation subsections contain more pertinent
 101      information regarding persistent error handling.
 102 
 103    Read Operation
 104      The read(2) function reads the next record on the tape.  The record size
 105      is passed back as the number of bytes read, provided it is not greater
 106      than the number requested.  When a tape mark or end of data is read, a
 107      zero byte count is returned; all successive reads after the zero read
 108      will return an error and errno will be set to EIO.  To move to the next
 109      file, an MTFSF ioctl can be issued before or after the read causing the
 110      error.  This error handling behavior is different from the older BSD
 111      behavior, where another read will fetch the first record of the next tape
 112      file.  If the BSD behavior is required, device names containing the
 113      letter `b' (for BSD behavior) in the final component should be used.  If
 114      persistent error handling was enabled with either the BSD or SVR4 tape
 115      device behavior, all operations after this read error will return EIO
 116      errors until the MTIOCLRERR ioctl is issued.  An MTFSF ioctl can then be
 117      issued.
 118 
 119      Two successful successive reads that both return zero byte counts
 120      indicate EOM on the tape.  No further reading should be performed past
 121      the EOM.
 122 
 123      Fixed-length I/O tape devices require the number of bytes read to be a
 124      multiple of the physical record size.  For example, 1/4" cartridge tape
 125      devices only read multiples of 512 bytes.  If the blocking factor is
 126      greater than 64,512 bytes (minphys limit), fixed-length I/O tape devices
 127      read multiple records.
 128 
 129      Most tape devices which support variable-length I/O operations may read a
 130      range of 1 to 65,535 bytes.  If the record size exceeds 65,535 bytes, the
 131      driver reads multiple records to satisfy the request.  These multiple
 132      records are limited to 65,534 bytes.  Newer variable-length tape drivers
 133      may relax the above limitation and allow applications to read record
 134      sizes larger than 65,534.  Refer to the specific tape driver man page for
 135      details.
 136 
 137      Reading past logical EOT is transparent to the user.  A read operation
 138      should never hit physical EOT.
 139 
 140      Read requests that are lesser than a physical tape record are not
 141      allowed.  Appropriate error is returned.
 142 
 143    Write Operation
 144      The write(2) function writes the next record on the tape.  The record has
 145      the same length as the given buffer.
 146 
 147      Writing is allowed on 1/4" tape at either the beginning of tape or after
 148      the last written file on the tape.  With the Exabyte 8200, data may be
 149      appended only at the beginning of tape, before a filemark, or after the
 150      last written file on the tape.
 151 
 152      Writing is not so restricted on 1/2", 4mm, and the other 8mm cartridge
 153      tape drives.  Care should be used when appending files onto 1/2" reel
 154      tape devices, since an extra file mark is appended after the last file to
 155      mark the EOM.  This extra file mark must be overwritten to prevent the
 156      creation of a null file.  To facilitate write append operations, a space
 157      to the EOM ioctl is provided.  Care should be taken when overwriting
 158      records; the erase head is just forward of the write head and any
 159      following records will also be erased.
 160 
 161      Fixed-length I/O tape devices require the number of bytes written to be a
 162      multiple of the physical record size.  For example, 1/4" cartridge tape
 163      devices only write multiples of 512 bytes.
 164 
 165      Fixed-length I/O tape devices write multiple records if the blocking
 166      factor is greater than 64,512 bytes (minphys limit).  These multiple
 167      writes are limited to 64,512 bytes.  For example, if a write request is
 168      issued for 65,536 bytes using a 1/4" cartridge tape, two writes are
 169      issued; the first for 64,512 bytes and the second for 1024 bytes.
 170 
 171      Most tape devices which support variable-length I/O operations may write
 172      a range of 1 to 65,535 bytes.  If the record size exceeds 65,535 bytes,
 173      the driver writes multiple records to satisfy the request.  These
 174      multiple records are limited to 65,534 bytes.  As an example, if a write
 175      request for 65,540 bytes is issued, two records are written; one for
 176      65,534 bytes followed by another record for 6 bytes.  Newer variable-
 177      length tape drivers may relax the above limitation and allow applications
 178      to write record sizes larger than 65,534.  effer to the specific tape
 179      driver man page for details.
 180 
 181      When logical EOT is encountered during a write, that write operation
 182      completes and the number of bytes successfully transferred is returned
 183      (note that a 'short write' may have occurred and not all the requested
 184      bytes would have been transferred.  The actual amount of data written
 185      will depend on the type of device being used).  The next write will
 186      return a zero byte count.  A third write will successfully transfer some
 187      bytes (as indicated by the returned byte count, which again could be a
 188      short write); the fourth will transfer zero bytes, and so on, until the
 189      physical EOT is reached and all writes will fail with EIO.
 190 
 191      When logical EOT is encountered with persistent error handling enabled,
 192      the current write may complete or be a short write.  The next write will
 193      return a zero byte count.  At this point an application should act
 194      appropriately for end of tape cleanup or issue yet another write, which
 195      will return the error ENOSPC.  After clearing the exception with
 196      MTIOCLRERR, the next write will succeed (possibly short), followed by
 197      another zero byte write count, and then another ENOSPC error.
 198 
 199      Allowing writes after EOT has been encountered enables the flushing of
 200      buffers.  However, it is strongly recommended to terminate the writing
 201      and close the file as soon as possible.
 202 
 203      Seeks are ignored in tape I/O.
 204 
 205    Close Operation
 206      Magnetic tapes are rewound when closed, except when the "no-rewind"
 207      devices have been specified.  The names of no-rewind device files use the
 208      letter `n' as the end of the final component.  The no-rewind version of
 209      /dev/rmt/0l is /dev/rmt/0ln.  In case of error for a no-rewind device,
 210      the next open rewinds the device.
 211 
 212      If the driver was opened for reading and a no-rewind device has been
 213      specified, the close advances the tape past the next filemark (unless the
 214      current file position is at EOM), leaving the tape correctly positioned
 215      to read the first record of the next file.  However, if the tape is at
 216      the first record of a file it doesn't advance again to the first record
 217      of the next file.  These semantics are different from the older BSD
 218      behavior.  If BSD behavior is required where no implicit space operation
 219      is executed on close, the non-rewind device name containing the letter
 220      `b' (for BSD behavior) in the final component should be specified.
 221 
 222      If data was written, a file mark is automatically written by the driver
 223      upon close.  If the rewinding device was specified, the tape will be
 224      rewound after the file mark is written.  If the user wrote a file mark
 225      prior to closing, then no file mark is written upon close.  If a file
 226      positioning ioctl, like rewind, is issued after writing, a file mark is
 227      written before repositioning the tape.
 228 
 229      All buffers are flushed on closing a tape device.  Hence, it is strongly
 230      recommended that the application wait for all buffers to be flushed
 231      before closing the device.  This can be done by writing a filemark via
 232      MTWEOF, even with a zero count.
 233 
 234      Note that for 1/2" reel tape devices, two file marks are written to mark
 235      the EOM before rewinding or performing a file positioning ioctl.  If the
 236      user wrote a file mark before closing a 1/2" reel tape device, the driver
 237      will always write a file mark before closing to insure that the end of
 238      recorded media is marked properly.  If the non-rewinding device was
 239      specified, two file marks are written and the tape is left positioned
 240      between the two so that the second one is overwritten on a subsequent
 241      open(2) and write(2).
 242 
 243      If no data was written and the driver was opened for WRITE-ONLY access,
 244      one or two file marks are written, thus creating a null file.
 245 
 246      After closing the device, persistent error handling will be disabled and
 247      any error or exception will be cleared.
 248 
 249 IOCTLS
 250      Not all devices support all ioctls.  The driver returns an ENOTTY error
 251      on unsupported ioctls.
 252 
 253      The following structure definitions for magnetic tape ioctl(2) commands
 254      are from <sys/mtio.h>.
 255 
 256      The minor device byte structure is:
 257 
 258      15      7      6          5          4         3          2       1   0
 259      ________________________________________________________________________
 260      Unit #       BSD      Reserved   Density   Density   No rewind    Unit #
 261      Bits 7-15   behavior              Select    Select    on Close    Bits 0-1
 262 
 263      /*
 264       * Layout of minor device byte:
 265       */
 266      #define MTUNIT(dev)   (((minor(dev) & 0xff80) >> 5) + (minor(dev) & 0x3))
 267      #define MT_NOREWIND     (1 <<2)
 268      #define MT_DENSITY_MASK (3 <<3)
 269      #define MT_DENSITY1     (0 <<3) /*   Lowest density/format */
 270      #define MT_DENSITY2     (1 <<3)
 271      #define MT_DENSITY3     (2 <<3)
 272      #define MT_DENSITY4     (3 <<3) /*   Highest density/format */
 273      #define MTMINOR(unit)   (((unit & 0x7fc) << 5) + (unit & 0x3))
 274      #define MT_BSD  (1 <<6)           /* BSD behavior on close */
 275 
 276      /* Structure for MTIOCTOP - magnetic tape operation command */
 277 
 278      struct mtop {
 279        short   mt_op;       /* operation */
 280        daddr_t mt_count;    /* number of operations */
 281      };
 282 
 283      /* Structure for MTIOCLTOP - magnetic tape operation command */
 284      Works exactly like MTIOCTOP except passes 64 bit mt_count values.
 285      struct mtlop {
 286              short           mt_op;
 287              short           pad[3];
 288              int64_t         mt_count;
 289      };
 290 
 291      The following operations of MTIOCTOP and MTIOCLTOP ioctls are supported:
 292 
 293        MTWEOF         Write an end-of-file record
 294        MTFSF          Forward space over file mark
 295        MTBSF          Backward space over file mark (1/2", 8mm only)
 296        MTFSR          Forward space to inter-record gap
 297        MTBSR          Backward space to inter-record gap
 298        MTREW          Rewind
 299        MTOFFL         Rewind and take the drive off-line
 300        MTNOP          No operation, sets status only
 301        MTRETEN        Retension the tape (cartridge tape only)
 302        MTERASE        Erase the entire tape and rewind
 303        MTEOM          Position to EOM
 304        MTNBSF         Backward space file to beginning of file
 305        MTSRSZ         Set record size
 306        MTGRSZ         Get record size
 307        MTTELL         Get current position
 308        MTSEEK         Go to requested position
 309        MTFSSF         Forward to requested number of sequential file marks
 310        MTBSSF         Backward to requested number of sequential file marks
 311        MTLOCK         Prevent media removal
 312        MTUNLOCK       Allow media removal
 313        MTLOAD         Load the next tape cartridge into the tape drive
 314        MTIOCGETERROR  Retrieve error records from the st driver
 315 
 316        /* structure for MTIOCGET - magnetic tape get status command */
 317 
 318        struct  mtget {
 319          short mt_type;        /* type of magtape device */
 320 
 321          /* the following two registers are device dependent */
 322          short  mt_dsreg;      /* "drive status" register */
 323          short  mt_erreg;      /* "error" register */
 324 
 325          /* optional error info.  */
 326          daddr_t   mt_resid;   /* residual count */
 327          daddr_t   mt_fileno;  /* file number of current position */
 328          daddr_t   mt_blkno;   /* block number of current position */
 329          ushort_t  mt_flags;
 330          short     mt_bf;      /* optimum blocking factor */
 331        };
 332 
 333        /* structure for MTIOCGETDRIVETYPE - get tape config data command */
 334        struct mtdrivetype_request {
 335          int  size;
 336          struct  mtdrivetype   *mtdtp;
 337        };
 338        struct mtdrivetype {
 339          char    name[64];                  /* Name, for debug */
 340          char    vid[25];                   /* Vendor id and product id */
 341          char    type;                      /* Drive type for driver */
 342          int     bsize;                     /* Block size */
 343          int     options;                   /* Drive options */
 344          int     max_rretries;              /* Max read retries */
 345          int     max_wretries;              /* Max write retries */
 346          uchar_t densities[MT_NDENSITIES];  /* density codes,low->hi */
 347          uchar_t default_density;           /* Default density chosen */
 348          uchar_t speeds[MT_NSPEEDS];        /* speed codes, low->hi */
 349          ushort_t non_motion_timeout;       /* Seconds for non-motion */
 350          ushort_t io_timeout;               /* Seconds for data to from tape */
 351          ushort_t rewind_timeout;           /* Seconds to rewind */
 352          ushort_t space_timeout;            /* Seconds to space anywhere */
 353          ushort_t load_timeout;             /* Seconds to load tape and ready */
 354          ushort_t unload_timeout;           /* Seconds to unload */
 355          ushort_t erase_timeout;            /* Seconds to do long erase */
 356        };
 357 
 358        /* structure for MTIOCGETPOS and MTIOCRESTPOS - get/set tape position */
 359        /*
 360         * eof/eot/eom codes.
 361         */
 362         typedef enum {
 363               ST_NO_EOF,
 364               ST_EOF_PENDING,         /* filemrk pending */
 365               ST_EOF,                 /* at filemark */
 366               ST_EOT_PENDING,         /* logical eot pend.  */
 367               ST_EOT,                 /* at logical eot */
 368               ST_EOM,                 /* at physical eot */
 369               ST_WRITE_AFTER_EOM      /* flag allowing writes after EOM */
 370        } pstatus;
 371 
 372        typedef enum { invalid, legacy, logical } posmode;
 373 
 374        typedef struct tapepos {
 375           uint64_t lgclblkno;  /* Blks from start of partition */
 376           int32_t fileno;      /* Num. of current file */
 377           int32_t blkno;       /* Blk  number in current file */
 378           int32_t partition;   /* Current partition */
 379           pstatus eof;         /* eof states */
 380           posmode pmode;       /* which pos. data is valid */
 381           char    pad[4];
 382        } tapepos_t;
 383 
 384      If the pmode is legacy, fileno and blkno fields are valid.
 385 
 386      If the pmode is logical, lgclblkno field is valid.
 387 
 388      The MTWEOF ioctl is used for writing file marks to tape.  Not only does
 389      this signify the end of a file, but also usually has the side effect of
 390      flushing all buffers in the tape drive to the tape medium.  A zero count
 391      MTWEOF will just flush all the buffers and will not write any file marks.
 392      Because a successful completion of this tape operation will guarantee
 393      that all tape data has been written to the tape medium, it is recommended
 394      that this tape operation be issued before closing a tape device.
 395 
 396      When spacing forward over a record (either data or EOF), the tape head is
 397      positioned in the tape gap between the record just skipped and the next
 398      record.  When spacing forward over file marks (EOF records), the tape
 399      head is positioned in the tape gap between the next EOF record and the
 400      record that follows it.
 401 
 402      When spacing backward over a record (either data or EOF), the tape head
 403      is positioned in the tape gap immediately preceding the tape record where
 404      the tape head is currently positioned.  When spacing backward over file
 405      marks (EOF records), the tape head is positioned in the tape gap
 406      preceding the EOF.  Thus the next read would fetch the EOF.
 407 
 408      Record skipping does not go past a file mark; file skipping does not go
 409      past the EOM.  After an MTFSR <huge number> command, the driver leaves
 410      the tape logically positioned before the EOF.  A related feature is that
 411      EOFs remain pending until the tape is closed.  For example, a program
 412      which first reads all the records of a file up to and including the EOF
 413      and then performs an MTFSF command will leave the tape positioned just
 414      after that same EOF, rather than skipping the next file.
 415 
 416      The MTNBSF and MTFSF operations are inverses.  Thus, an "MTFSF -1" is
 417      equivalent to an "MTNBSF 1".  An "MTNBSF 0" is the same as "MTFSF 0";
 418      both position the tape device at the beginning of the current file.
 419 
 420      MTBSF moves the tape backwards by file marks.  The tape position will end
 421      on the beginning of the tape side of the desired file mark.  An "MTBSF 0"
 422      will position the tape at the end of the current file, before the
 423      filemark.
 424 
 425      MTBSR and MTFSR operations perform much like space file operations,
 426      except that they move by records instead of files.  Variable-length I/O
 427      devices (1/2" reel, for example) space actual records; fixed-length I/O
 428      devices space physical records (blocks).  1/4" cartridge tape, for
 429      example, spaces 512 byte physical records.  The status ioctl residual
 430      count contains the number of files or records not skipped.
 431 
 432      MTFSSF and MTBSSF space forward or backward, respectively, to the next
 433      occurrence of the requested number of file marks, one following another.
 434      If there are more sequential file marks on tape than were requested, it
 435      spaces over the requested number and positions after the requested file
 436      mark.  Note that not all drives support this command and if a request is
 437      sent to a drive that does not, ENOTTY is returned.
 438 
 439      MTOFFL rewinds and, if appropriate, takes the device off-line by
 440      unloading the tape.  It is recommended that the device be closed after
 441      offlining and then re-opened after a tape has been inserted to facilitate
 442      portability to other platforms and other operating systems.  Attempting
 443      to re-open the device with no tape will result in an error unless the
 444      O_NDELAY flag is used.  (See open(2).)
 445 
 446      The MTRETEN retension ioctl applies only to 1/4" cartridge tape devices.
 447      It is used to restore tape tension, improving the tape's soft error rate
 448      after extensive start-stop operations or long-term storage.
 449 
 450      MTERASE rewinds the tape, erases it completely, and returns to the
 451      beginning of tape.  Erasing may take a long time depending on the device
 452      and/or tapes.  For time details, refer to the drive specific manual.
 453 
 454      MTEOM positions the tape at a location just after the last file written
 455      on the tape.  For 1/4" cartridge and 8mm tape, this is after the last
 456      file mark on the tape.  For 1/2" reel tape, this is just after the first
 457      file mark but before the second (and last) file mark on the tape.
 458      Additional files can then be appended onto the tape from that point.
 459 
 460      Note the difference between MTBSF (backspace over file mark) and MTNBSF
 461      (backspace file to beginning of file).  The former moves the tape
 462      backward until it crosses an EOF mark, leaving the tape positioned before
 463      the file mark.  The latter leaves the tape positioned after the file
 464      mark.  Hence, "MTNBSF n" is equivalent to "MTBSF (n+1)" followed by
 465      "MTFSF 1".  The 1/4" cartridge tape devices do not support MTBSF.
 466 
 467      MTSRSZ and MTGRSZ are used to set and get fixed record lengths.  The
 468      MTSRSZ ioctl allows variable length and fixed length tape drives that
 469      support multiple record sizes to set the record length.  The mt_count
 470      field of the mtop struct is used to pass the record size to/from the
 471      st(7D) driver.  A value of `0' indicates variable record size.  The
 472      MTSRSZ ioctl makes a variable-length tape device behave like a fixed-
 473      length tape device.  Refer to the specific tape driver man page for
 474      details.
 475 
 476      MTLOAD loads the next tape cartridge into the tape drive.  This is
 477      generally only used with stacker and tower type tape drives which handle
 478      multiple tapes per tape drive.  A tape device without a tape inserted can
 479      be opened with the O_NDELAY flag, in order to execute this operation.
 480 
 481      MTIOCGETERROR allows user-level applications to retrieve error records
 482      from the st(7D) driver.  An error record consists of the SCSI command cdb
 483      which causes the error and a scsi_arq_status(9S) structure if available.
 484      The user-level application is responsible for allocating and releasing
 485      the memory for mtee_cdb_buf and scsi_arq_status of each mterror_entry.
 486      Before issuing the ioctl, the mtee_arq_status_len value should be at
 487      least equal to `sizeof (struct scsi_arq_status)'.  If more sense data
 488      than the size of scsi_arq_status(9S) is desired, the mtee_arq_status_len
 489      may be larger than `sizeof (struct scsi_arq_status)' by the amount of
 490      additional extended sense data desired.  The es_add_len field of
 491      scsi_extended_sense(9S) can be used to determine the amount of valid
 492      sense data returned by the device.
 493 
 494      The MTIOCGET get status ioctl(2) call returns the drive ID (mt_type),
 495      sense key error (mt_erreg), file number (mt_fileno), optimum blocking
 496      factor (mt_bf) and record number (mt_blkno) of the last error.  The
 497      residual count (mt_resid) is set to the number of bytes not transferred
 498      or files/records not spaced.  The flags word (mt_flags) contains
 499      information indicating if the device is SCSI, if the device is a reel
 500      device and whether the device supports absolute file positioning.  The
 501      mt_flags also indicates if the device is requesting cleaning media be
 502      used, whether the device is capable of reporting the requirement of
 503      cleaning media and if the currently loaded media is WORM (Write Once Read
 504      Many) media.
 505 
 506      Note -- When tape alert cleaning is managed by the st driver, the tape
 507      target driver may continue to return a "drive needs cleaning" status
 508      unless an MTIOCGE ioct(2) call is made while the cleaning media is in the
 509      drive.
 510 
 511      The MTIOCGETDRIVETYPE get drivetype ioctl call returns the name of the
 512      tape drive as defined in st.conf (name), Vendor ID and model (product),
 513      ID (vid), type of tape device (type), block size (size), drive options
 514      (options), maximum read retry count (max_rretries), maximum write retry
 515      count (max_wretries), densities supported by the drive (densities), and
 516      default density of the tape drive (default_density).
 517 
 518      The MTIOCGETPOS ioctl returns the current tape position of the drive.  It
 519      is returned in struct tapepos as defined in
 520      /usr/include/sys/scsi/targets/stdef.h.
 521 
 522      The MTIOCRESTPOS ioctl restores a saved position from the MTIOCGETPOS.
 523 
 524    Persistent Error Handling IOCTLs and Asynchronous Tape Operations
 525      MTIOCPERSISTENT        enables/disables persistent error handling
 526      MTIOCPERSISTENTSTATUS  queries for persistent error handling
 527      MTIOCLRERR             clears persistent error handling
 528      MTIOCGUARANTEEDORDER   checks whether driver guarantees order of I/O's
 529 
 530      The MTIOCPERSISTENT ioctl enables or disables persistent error handling.
 531      It takes as an argument a pointer to an integer that turns it either on
 532      or off.  If the ioctl succeeds, the desired operation was successful.  It
 533      will wait for all outstanding I/O's to complete before changing the
 534      persistent error handling status.  For example,
 535 
 536        int on = 1;
 537        ioctl(fd, MTIOCPERSISTENT, &on);
 538        int off = 0;
 539        ioctl(fd, MTIOCPERSISTENT, &off);
 540 
 541      The MTIOCPERSISTENTSTATUS ioctl enables or disables persistent error
 542      handling.  It takes as an argument a pointer to an integer inserted by
 543      the driver.  The integer can be either 1 if persistent error handling is
 544      `on', or 0 if persistent error handling is `off'.  It will not wait for
 545      outstanding I/O's.  For example,
 546 
 547        int query;
 548        ioctl(fd, MTIOCPERSISTENTSTATUS, &query);
 549 
 550      The MTIOCLRERR ioctl clears persistent error handling and allows tape
 551      operations to continual normally.  This ioctl requires no argument and
 552      will always succeed, even if persistent error handling has not been
 553      enabled.  It will wait for any outstanding I/O's before it clears the
 554      error.
 555 
 556      The MTIOCGUARANTEEDORDER ioctl is used to determine whether the driver
 557      guarantees the order of I/O's.  It takes no argument.  If the ioctl
 558      succeeds, the driver will support guaranteed order.  If the driver does
 559      not support guaranteed order, then it should not be used for asynchronous
 560      I/O with libaio(3lib).  It will wait for any outstanding I/O's before it
 561      returns.  For example,
 562 
 563        ioctl(fd, MTIOCGUARANTEEDORDER)
 564 
 565      See the Persistent Error Handling subsection above for more information
 566      on persistent error handling.
 567 
 568    Asynchronous and State Change IOCTLS
 569      MTIOCSTATE
 570         This ioctl blocks until the state of the drive, inserted or ejected,
 571         is changed.  The argument is a pointer to a enum mtio_state, whose
 572         possible enumerations are listed below.  The initial value should be
 573         either the last reported state of the drive, or MTIO_NONE.  Upon
 574         return, the enum pointed to by the argument is updated with the
 575         current state of the drive.
 576 
 577           enum mtio_state {
 578               MTIO_NONE      /* Return tape's current state */
 579               MTIO_EJECTED   /* Tape state is "ejected" */
 580               MTIO_INSERTED  /* Tape state is "inserted" */
 581           };
 582 
 583      When using asynchronous operations, most ioctls will wait for all
 584      outstanding commands to complete before they are executed.
 585 
 586    IOCTLS for Multi-initiator Configurations
 587      MTIOCRESERVE       reserve the tape drive
 588      MTIOCRELEASE       revert back to the default behavior of reserve on
 589                         open/release on close
 590      MTIOCFORCERESERVE  reserve the tape unit by breaking reservation held by
 591                         another host
 592 
 593      The MTIOCRESERVE ioctl reserves the tape drive such that it does not
 594      release the tape drive at close.  This changes the default behavior of
 595      releasing the device upon close.  Reserving the tape drive that is
 596      already reserved has no effect.  For example,
 597 
 598        ioctl(fd, MTIOCRESERVE);
 599 
 600      The MTIOCRELEASE ioctl reverts back to the default behavior of reserve on
 601      open/release on close operation, and a release will occur during the next
 602      close.  Releasing the tape drive that is already released has no effect.
 603      For example,
 604 
 605        ioctl(fd, MTIOCRELEASE);
 606 
 607      The MTIOCFORCERESERVE ioctl breaks a reservation held by another host,
 608      interrupting any I/O in progress by that other host, and then reserves
 609      the tape unit.  This ioctl can be executed only with super-user
 610      privileges.  It is recommended to open the tape device in O_NDELAY mode
 611      when this ioctl needs to be executed, otherwise the open will fail if
 612      another host indeed has it reserved.  For example,
 613 
 614        ioctl(fd, MTIOCFORCERESERVE);
 615 
 616    IOCTLS for Handling Tape Configuration Options
 617      MTIOCSHORTFMK        enables/disables support for writing short
 618                           filemarks.  This is specific to Exabyte drives.
 619 
 620      MTIOCREADIGNOREILI   enables/disables suppress incorrect length indicator
 621                           (SILI) support during reads
 622 
 623      MTIOCREADIGNOREEOFS  enables/disables support for reading past two EOF
 624                           marks which otherwise indicate End-Of-recording-
 625                           Media (EOM) in the case of 1/2" reel tape drives
 626 
 627      The MTIOCSHORTFMK ioctl enables or disables support for short filemarks.
 628      This ioctl is only applicable to Exabyte drives which support short
 629      filemarks.  As an argument, it takes a pointer to an integer.  If 0
 630      (zero) is the specified integer, then long filemarks will be written.  If
 631      1 is the specified integer, then short filemarks will be written.  The
 632      specified tape behavior will be in effect until the device is closed.
 633 
 634      For example:
 635 
 636        int on = 1;
 637        int off = 0;
 638        /* enable short filemarks */
 639        ioctl(fd, MTIOSHORTFMK, &on);
 640        /* disable short filemarks */
 641        ioctl(fd, MTIOCSHORTFMK, &off);
 642 
 643      Tape drives which do not support short filemarks will return an errno of
 644      ENOTTY.
 645 
 646      The MTIOCREADIGNOREILI ioctl enables or disables the suppress incorrect
 647      length indicator (SILI) support during reads.  As an argument, it takes a
 648      pointer to an integer.  If 0 (zero) is the specified integer, SILI will
 649      not be used during reads and incorrect length indicator will not be
 650      suppressed.  If 1 is the specified integer, SILI will be used during
 651      reads and incorrect length indicator will be suppressed.  The specified
 652      tape behavior will be in effect until the device is closed.
 653 
 654      For example:
 655 
 656        int on = 1;
 657        int off = 0;
 658        ioctl(fd, MTIOREADIGNOREILI, &on);
 659        ioctl(fd, MTIOREADIGNOREILI, &off);
 660 
 661      The MTIOCREADIGNOREEOFS ioctl enables or disables support for reading
 662      past double EOF marks which otherwise indicate End-Of-recorded-media
 663      (EOM) in the case of 1/2" reel tape drives.  As an argument, it takes a
 664      pointer to an integer.  If 0 (zero) is the specified integer, then double
 665      EOF marks indicate End-Of-recorded-media (EOD).  If 1 is the specified
 666      integer, the double EOF marks no longer indicate EOM, thus allowing
 667      applications to read past two EOF marks.  In this case it is the
 668      responsibility of the application to detect end-of-recorded-media (EOM).
 669      The specified tape behavior will be in effect until the device is closed.
 670 
 671      For example:
 672 
 673        int on = 1;
 674        int off = 0;
 675        ioctl(fd, MTIOREADIGNOREEOFS, &on);
 676        ioctl(fd, MTIOREADIGNOREEOFS, &off);
 677 
 678      Tape drives other than 1/2" reel tapes will return an errno of ENOTTY.
 679 
 680 FILES
 681      /dev/rmt/<unit number><density>[<BSD behavior>][<no rewind>]
 682 
 683      Where <density> can be `l', `m', `h', `u/c' (low, medium, high,
 684      ultra/compressed, respectively), the <BSD behavior> option   is `b, and
 685      the' <no rewind> option is   `n'.
 686 
 687      For example, /dev/rmt/0hbn specifies unit 0, high density, BSD behavior
 688      and no rewind.
 689 
 690 EXAMPLES
 691      Example 1 Tape Positioning and Tape Drives
 692 
 693      Suppose you have written three files to the non-rewinding 1/2" tape
 694      device, /dev/rmt/0ln, and that you want to go back and dd(1M) the second
 695      file off the tape.  The commands to do this are:
 696 
 697        mt -F /dev/rmt/0lbn bsf 3
 698        mt -F /dev/rmt/0lbn fsf 1
 699        dd if=/dev/rmt/0ln
 700 
 701      To accomplish the same tape positioning in a C program, followed by a get
 702      status ioctl:
 703 
 704        struct mtop mt_command;
 705        struct mtget mt_status;
 706        mt_command.mt_op = MTBSF;
 707        mt_command.mt_count = 3;
 708        ioctl(fd, MTIOCTOP, &mt_command);
 709        mt_command.mt_op = MTFSF;
 710        mt_command.mt_count = 1;
 711        ioctl(fd, MTIOCTOP, &mt_command);
 712        ioctl(fd, MTIOCGET, (char *)&mt_status);
 713 
 714      or
 715 
 716        mt_command.mt_op = MTNBSF;
 717        mt_command.mt_count = 2;
 718        ioctl(fd, MTIOCTOP, &mt_command);
 719        ioctl(fd, MTIOCGET, (char *)&mt_status);
 720 
 721      To get information about the tape drive:
 722 
 723        struct mtdrivetype mtdt;
 724        struct mtdrivetype_request mtreq;
 725        mtreq.size = sizeof(struct mtdrivetype);
 726        mtreq.mtdtp = &mtdt;
 727        ioctl(fd, MTIOCGETDRIVETYPE, &mtreq);
 728 
 729 SEE ALSO
 730      mt(1), tar(1), dd(1M), open(2), read(2), write(2), aioread(3C),
 731      aiowrite(3C), ar.h(3HEAD), st(7D)
 732 
 733      1/4 Inch Tape Drive Tutorial
 734 
 735 illumos                        February 17, 2020                       illumos