Print this page
10529 Convert mtio(7I) to mandoc
   1 MTIO(7I)                        Ioctl Requests                        MTIO(7I)
   2 
   3 
   4 
   5 NAME
   6        mtio - general magnetic tape interface
   7 
   8 SYNOPSIS
   9        #include <sys/types.h>
  10        #include <sys/ioctl.h>
  11        #include <sys/mtio.h>
  12 
  13 
  14 DESCRIPTION
  15        1/2", 1/4", 4mm, and 8mm magnetic tape drives all share the same
  16        general character device interface.
  17 
  18 
  19        There are two types of tape records: data records and end-of-file (EOF)
  20        records. SEOF records are also known as tape marks and file marks. A
  21        record is separated by interrecord (or tape) gaps on a tape.
  22 
  23 
  24        End-of-recorded-media (EOM) is indicated by two EOF marks on 1/2" tape;
  25        by one EOF mark on 1/4", 4mm, and 8mm cartridge tapes.
  26 
  27    1/2 Reel Tape"
  28        Data bytes are recorded in parallel onto the 9-track tape. Since it is
  29        a variable-length tape device, the number of bytes in a  physical
  30        record may vary.
  31 






  32 
  33        The recording formats available (check specific tape drive) are 800
  34        BPI, 1600 BPI, 6250 BPI, and data compression. Actual storage capacity
  35        is a function of the recording format and the length of the tape reel.
  36        For example, using a 2400 foot tape, 20 Mbyte can be stored using 800
  37        BPI, 40 Mbyte using 1600 BPI, 140 Mbyte using 6250 BPI, or up to 700
  38        Mbyte using data compression.
  39 
  40    1/4 Cartridge Tape"
  41        Data is recorded serially onto 1/4" cartridge tape. The number of bytes
  42        per record is determined by the physical record size of the device. The
  43        I/O request size must be a multiple of the physical record size of the
  44        device. For QIC-11, QIC-24, and QIC-150 tape drives, the block size is
  45        512 bytes.
  46 
  47 
  48        The records are recorded on tracks in a serpentine motion. As one track
  49        is completed, the drive switches to the next and begins writing in the
  50        opposite direction, eliminating the wasted motion of rewinding. Each
  51        file, including the last, ends with one file mark.
  52 









  53 
  54        Storage capacity is based on the number of tracks the drive is capable
  55        of recording. For example, 4-track drives can only record 20 Mbyte of
  56        data on a 450 foot tape; 9-track drives can record up to 45 Mbyte of
  57        data on a tape of the same length. QIC-11 is the only tape format
  58        available for 4-track tape drives. In contrast, 9-track tape drives can
  59        use either QIC-24 or QIC-11. Storage capacity is not appreciably
  60        affected by using either format. QIC-24 is preferable to QIC-11 because
  61        it records a reference signal to mark the position of the first track
  62        on the tape, and each block has a unique block number.
  63 
  64 
  65        The QIC-150 tape drives require DC-6150 (or equivalent) tape cartridges
  66        for writing. However, they can read other tape cartridges in QIC-11,
  67        QIC-24, or QIC-120 tape formats.
  68 
  69    8mm Cartridge Tape
  70        Data is recorded serially onto 8mm helical scan cartridge tape. Since
  71        it is a variable-length tape device, the number of bytes in a  physical
  72        record may vary. The recording formats available (check specific tape
  73        drive) are standard 2Gbyte, 5Gbyte, and compressed format.
  74 
  75    4mm DAT Tape
  76        Data is recorded either in Digital Data Storage (DDS) tape format or in
  77        Digital Data Storage, Data Compressed (DDS-DC) tape format. Since it is
  78        a variable-length tape device, the number of bytes in a  physical
  79        record may vary. The recording formats available are standard 2Gbyte
  80        and compressed format.
  81 
  82    Persistent Error Handling
  83        Persistent error handling is a modification of the current error
  84        handling behaviors, BSD and SVR4. With persistent error handling
  85        enabled, all tape operations after an error or exception will return
  86        immediately with an error.  Persistent error handling can be most
  87        useful with asynchronous tape operations that use the aioread(3C) and
  88        aiowrite(3C) functions.
  89 
  90 
  91        To enable persistent error handling, the ioctl MTIOCPERSISTENT must be
  92        issued. If this ioctl succeeds, then persistent error handling is
  93        enabled and changes the current error behavior. This ioctl will fail if
  94        the device driver does not support persistent error handling.
  95 
  96 
  97        With persistent error handling enabled, all tape operations after an
  98        exception or error will return with the same error as the first command
  99        that failed; the operations will not be executed. An exception is some
 100        event that might stop normal tape operations, such as an End Of File
 101        (EOF) mark or  an End Of Tape (EOT) mark. An example of an error is a
 102        media error. The MTIOCLRERR ioctl must be issued to allow normal tape
 103        operations to continue and to clear the error.
 104 






 105 
 106        Disabling persistent error handling returns the error behavior to
 107        normal SVR4 error handling, and will not occur until all outstanding
 108        operations are completed. Applications should wait for all outstanding
 109        operations to complete before disabling persistent error handling.
 110        Closing the device will also disable persistent error handling and
 111        clear any errors or exceptions.
 112 
 113 
 114        The Read Operation and Write Operation subsections contain more
 115        pertinent information reguarding persistent error handling.
 116 
 117    Read Operation
 118        The read(2) function reads the next record on the tape. The record size
 119        is passed back as the number of bytes read, provided it is not greater
 120        than the number requested. When a tape mark or end of data is read, a
 121        zero byte count is returned; all successive reads after the zero read
 122        will return an error and errno will be set to EIO. To move to the next
 123        file, an MTFSF ioctl can be issued before or after the read causing the
 124        error. This error handling behavior is different from the older BSD
 125        behavior, where another read will fetch the first record of the next
 126        tape file. If the BSD behavior is required, device names containing the
 127        letter b (for BSD behavior) in the final component should be used. If
 128        persistent error handling was enabled with either the BSD or SVR4 tape
 129        device behavior, all operations after this read error will return EIO
 130        errors until the MTIOCLRERR ioctl is issued. An MTFSF ioctl can then he
 131        issued.
 132 
 133 
 134        Two successful successive reads that both return zero byte counts
 135        indicate EOM on the tape. No further reading should be performed past
 136        the EOM.
 137 
 138 
 139        Fixed-length I/O tape devices require the number of bytes read to be a
 140        multiple of the physical record size. For example, 1/4" cartridge tape
 141        devices only read multiples of 512 bytes. If the blocking factor is
 142        greater than 64,512 bytes (minphys limit), fixed-length I/O tape
 143        devices read multiple records.
 144 







 145 
 146        Most tape devices which support variable-length I/O operations may read
 147        a range of 1 to 65,535 bytes. If the record size exceeds 65,535 bytes,
 148        the driver reads multiple records to satisfy the request. These
 149        multiple records are limited to 65,534 bytes. Newer variable-length
 150        tape drivers may relax the above limitation and allow applications to
 151        read record sizes larger than 65,534. Refer to the specific tape driver
 152        man page for details.
 153 
 154 
 155        Reading past logical EOT is transparent to the user. A read operation
 156        should never hit physical EOT.
 157 
 158 
 159        Read requests that are lesser than a physical tape record are not
 160        allowed.  Appropriate error is returned.
 161 
 162    Write Operation
 163        The write(2) function writes the next record on the tape. The record
 164        has the same length as the given buffer.
 165 




 166 
 167        Writing is allowed on 1/4" tape at either the beginning of tape or
 168        after the last written file on the tape. With the Exabyte 8200, data
 169        may be appended only at the beginning of tape, before a filemark, or
 170        after the last written file on the tape.
 171 
 172 
 173        Writing is not so restricted on 1/2", 4mm, and the other 8mm cartridge
 174        tape drives. Care should be used when appending files onto 1/2" reel
 175        tape devices, since an extra file mark is appended after the last file
 176        to mark the EOM. This extra file mark must be overwritten to prevent
 177        the creation of a null file. To facilitate write append operations, a
 178        space to the EOM ioctl is provided. Care should be taken when
 179        overwriting records; the erase head is just forward of the write head
 180        and any following records will also be erased.
 181 



 182 
 183        Fixed-length I/O tape devices require the number of bytes written to be
 184        a multiple of the physical record size. For example, 1/4" cartridge
 185        tape devices only write multiples of 512 bytes.
 186 
 187 
 188        Fixed-length I/O tape devices write multiple records if the blocking
 189        factor is greater than 64,512 bytes (minphys limit). These multiple
 190        writes are limited to 64,512 bytes. For example, if a write request is
 191        issued for 65,536 bytes using a 1/4" cartridge tape, two writes are
 192        issued; the first for 64,512 bytes and the second for 1024 bytes.
 193 
 194 
 195        Most tape devices which support variable-length I/O operations may
 196        write a range of 1 to 65,535 bytes. If the record size exceeds 65,535
 197        bytes, the driver writes multiple records to satisfy the request. These
 198        multiple records are limited to 65,534 bytes. As an example, if a write
 199        request for 65,540 bytes is issued, two records are written; one for
 200        65,534 bytes followed by another record for 6 bytes. Newer variable-
 201        length tape drivers may relax the above limitation and allow
 202        applications to write record sizes larger  than 65,534.  Refer to the
 203        specific tape driver man page for details.
 204 
 205 
 206        When logical EOT is encountered during a write, that write operation
 207        completes and the number of bytes successfully transferred is returned
 208        (note that a 'short write' may have occurred and not all the requested
 209        bytes would have been transferred. The actual amount of data written
 210        will depend on the type of device being used). The next write will
 211        return a zero byte count. A third write will successfully transfer some
 212        bytes (as indicated by the returned byte count, which again could be a
 213        short write); the fourth will transfer zero bytes, and so on, until the
 214        physical EOT is reached and all writes will fail with EIO.
 215 
 216 
 217        When logical EOT is encountered with persistent error handling enabled,
 218        the current write may complete or be a short write. The next write will
 219        return a zero byte count. At this point an application should act
 220        appropriately for end of tape cleanup or issue yet another write, which
 221        will return the error ENOSPC. After clearing the exception with
 222        MTIOCLRERR, the next write will succeed (possibly short), followed by
 223        another zero byte write count, and then another ENOSPC error.
 224 
 225 
 226        Allowing writes after LEOT has been encountered enables the flushing of
 227        buffers. However, it is strongly recommended to terminate the writing
 228        and close the file as soon as possible.
 229 
 230 
 231        Seeks are ignored in tape I/O.
 232 
 233    Close Operation
 234        Magnetic tapes are rewound when closed, except when the "no-rewind"
 235        devices have been specified. The names of no-rewind device files use
 236        the letter n as the end of the final component. The no-rewind version
 237        of /dev/rmt/0l is /dev/rmt/0ln. In case of error for a no-rewind
 238        device, the next open rewinds the device.
 239 
 240 
 241        If the driver was opened for reading and a no-rewind device has been
 242        specified, the close advances the tape past the next filemark (unless
 243        the current file position is at EOM), leaving the tape correctly
 244        positioned to read the first record of the next file. However, if the
 245        tape is at the first record of a file it doesn't advance again to the
 246        first record of the next file. These semantics are different from the
 247        older BSD behavior. If BSD behavior is required where no implicit space
 248        operation is executed on close, the non-rewind device name containing
 249        the letter b (for BSD behavior) in the final component should be
 250        specified.
 251 
 252 
 253        If data was written, a file mark is automatically written by the driver
 254        upon close. If the rewinding device was specified, the tape will be
 255        rewound after the file mark is written. If the user wrote a file mark
 256        prior to closing, then no file mark is written upon close. If a file
 257        positioning ioctl, like rewind, is issued after writing, a file mark is
 258        written before repositioning the tape.
 259 
 260 
 261        All buffers are flushed on closing a tape device. Hence, it is strongly
 262        recommended that the application wait for all buffers to be flushed
 263        before closing the device. This can be done by writing a filemark via
 264        MTWEOF, even with a zero count.
 265 








 266 
 267        Note that for 1/2" reel tape devices, two file marks are written to
 268        mark the EOM before rewinding or performing a file positioning ioctl.
 269        If the user wrote a file mark before closing a 1/2" reel tape device,
 270        the driver will always write a file mark before closing to insure that
 271        the end of recorded media is marked properly. If the non-rewinding
 272        device was specified, two file marks are written and the tape is left
 273        positioned between the two so that the second one is overwritten on a
 274        subsequent open(2) and write(2).
 275 
 276 
 277        If no data was written and the driver was opened for WRITE-ONLY access,
 278        one or two file marks are written, thus creating a null file.
 279 


 280 
 281        After closing the device, persistent error handling will be disabled
 282        and any error or exception will be cleared.
 283 
 284 IOCTLS
 285        Not all devices support all ioctls. The driver returns an ENOTTY error
 286        on unsupported ioctls.
 287 
 288 
 289        The following structure definitions for magnetic tape ioctl commands
 290        are from <sys/mtio.h>.
 291 

 292 
 293        The minor device byte structure is::
 294 
 295          15      7      6          5          4         3          2       1   0
 296          ________________________________________________________________________
 297          Unit #       BSD      Reserved   Density   Density   No rewind    Unit #
 298          Bits 7-15   behavior              Select    Select    on Close    Bits 0-1
 299 
 300 
 301          /*
 302           * Layout of minor device byte:
 303           */
 304          #define MTUNIT(dev) (((minor(dev) & 0xff80) >>       5) +
 305          (minor(dev) & 0x3))
 306          #define MT_NOREWIND (1 <<2)
 307          #define MT_DENSITY_MASK  (3 <<3)
 308          #define MT_DENSITY1 (0 <<3)   /* Lowest density/format   */
 309          #define MT_DENSITY2 (1 <<3)
 310          #define MT_DENSITY3 (2 <<3)
 311          #define MT_DENSITY4 (3 <<3)   /* Highest density/format */
 312          #define MTMINOR(unit)    (((unit & 0x7fc) << 5) + (unit & 0x3))
 313          #define MT_BSD (1 <<6)         /* BSD behavior on close */
 314 
 315 
 316          /* Structure for MTIOCTOP - magnetic tape operation command */
 317 
 318          struct  mtop {
 319            short   mt_op;       /* operation */
 320            daddr_t mt_count;    /* number of operations */
 321          };
 322 
 323 
 324          /* Structure for MTIOCLTOP - magnetic tape operation command */
 325          Works exactly like MTIOCTOP except passes 64 bit mt_count values.
 326          struct  mtlop    {
 327                  short           mt_op;
 328                  short           pad[3];
 329                  int64_t         mt_count;
 330          };
 331 

 332 






















 333 
 334        The following operations of MTIOCTOP and MTIOCLTOP ioctls are
 335        supported:
 336 
 337        MTWEOF
 338                         write an end-of-file record
 339 
 340 
 341        MTFSF
 342                         forward space over file mark
 343 
 344 
 345        MTBSF
 346                         backward space over file mark (1/2", 8mm only)
 347 
 348 
 349        MTFSR
 350                         forward space to inter-record gap
 351 
 352 
 353        MTBSR
 354                         backward space to inter-record gap
 355 
 356 
 357        MTREW
 358                         rewind
 359 
 360 
 361        MTOFFL
 362                         rewind and take the drive off-line
 363 
 364 
 365        MTNOP
 366                         no operation, sets status only
 367 
 368 
 369        MTRETEN
 370                         retension the tape (cartridge tape only)
 371 
 372 
 373        MTERASE
 374                         erase the entire tape and rewind
 375 
 376 
 377        MTEOM
 378                         position to EOM
 379 
 380 
 381        MTNBSF
 382                         backward space file to beginning of file
 383 
 384 
 385        MTSRSZ
 386                         set record size
 387 
 388 
 389        MTGRSZ
 390                         get record size
 391 
 392 
 393        MTTELL
 394                         get current position
 395 
 396 
 397        MTSEEK
 398                         go to  requested  position
 399 
 400 
 401        MTFSSF
 402                         forward to requested number of sequential file marks
 403 
 404 
 405        MTBSSF
 406                         backward to requested number of sequential file marks
 407 
 408 
 409        MTLOCK
 410                         prevent media removal
 411 
 412 
 413        MTUNLOCK
 414                         allow media removal
 415 
 416 
 417        MTLOAD
 418                         load the next tape cartridge into the tape drive
 419 
 420 
 421        MTIOCGETERROR
 422                         retrieve error records from the st driver
 423 
 424 
 425          /* structure for MTIOCGET - magnetic tape get status command */
 426 
 427          struct  mtget {
 428            short   mt_type;  /* type of magtape device */

 429          /* the following two registers are device dependent */
 430            short  mt_dsreg;      /* "drive status" register */
 431            short  mt_erreg;      /* "error" register */

 432          /* optional error info. */
 433            daddr_t   mt_resid;   /* residual count */
 434            daddr_t   mt_fileno;  /* file number of current position */
 435            daddr_t   mt_blkno;   /* block number of current position */
 436            ushort_t  mt_flags;
 437            short     mt_bf;      /* optimum blocking factor */
 438          };

 439          /* structure for MTIOCGETDRIVETYPE - get tape config data command */
 440          struct mtdrivetype_request {
 441            int  size;
 442            struct  mtdrivetype    *mtdtp;
 443          };
 444          struct mtdrivetype {
 445            char    name[64];                  /* Name, for debug */
 446            char    vid[25];                   /* Vendor id and product id */
 447            char    type;                      /* Drive type for driver */
 448            int     bsize;                     /* Block size */
 449            int     options;                   /* Drive options */
 450            int     max_rretries;              /* Max read retries */
 451            int     max_wretries;              /* Max write retries */
 452            uchar_t densities[MT_NDENSITIES];  /* density codes,low->hi */
 453            uchar_t default_density;           /* Default density chosen */
 454            uchar_t speeds[MT_NSPEEDS];        /* speed codes, low->hi */
 455            ushort_t non_motion_timeout;       /* Seconds for non-motion */
 456            ushort_t io_timeout;               /* Seconds for data to from tape */
 457            ushort_t rewind_timeout;           /* Seconds to rewind */
 458            ushort_t space_timeout;            /* Seconds to space anywhere */
 459            ushort_t load_timeout;             /* Seconds to load tape and ready */
 460            ushort_t unload_timeout;           /* Seconds to unload */
 461            ushort_t erase_timeout;            /* Seconds to do long erase */
 462          };
 463 
 464 
 465          /* structure for MTIOCGETPOS and MTIOCRESTPOS - get/set tape position */
 466               /*
 467            * eof/eot/eom codes.
 468                */
 469           typedef enum {
 470                 ST_NO_EOF,
 471                 ST_EOF_PENDING,         /* filemrk pending */
 472                 ST_EOF,                 /* at filemark */
 473                 ST_EOT_PENDING,         /* logical eot pend. */
 474                 ST_EOT,                 /* at logical eot */
 475                 ST_EOM,                 /* at physical eot */
 476                 ST_WRITE_AFTER_EOM      /* flag allowing writes after EOM */
 477               }pstatus;
 478 
 479               typedef enum { invalid, legacy, logical } posmode;
 480 
 481               typedef struct tapepos {
 482                       uint64_t lgclblkno;   /* Blks from start of partition */
 483                       int32_t fileno;       /* Num. of current file */
 484                       int32_t blkno;        /* Blk  number in current file */
 485                       int32_t partition;    /* Current partition */
 486                       pstatus eof;         /* eof states */
 487                       posmode pmode;         /* which pos. data is valid */
 488                       char    pad[4];
 489               }tapepos_t;
 490 
 491               If the pmode is legacy,fileno and blkno fields are valid.

 492               If the pmode is logical, lgclblkno field is valid.
 493 
 494 
 495 
 496        The MTWEOF ioctl is used for writing file marks to tape. Not only does
 497        this signify the end of a file, but also usually has the side effect of
 498        flushing all buffers in the tape drive to the tape medium. A zero count
 499        MTWEOF will just flush all the buffers and will not write any file
 500        marks.  Because a successful completion of this tape operation will
 501        guarantee that all tape data has been written to the tape medium, it is
 502        recommended that this tape operation be issued before closing a tape
 503        device.
 504 





 505 
 506        When spacing forward over a record (either data or EOF), the tape head
 507        is positioned in the tape gap between the record just skipped and the
 508        next record.  When spacing forward over file marks (EOF records), the
 509        tape head is positioned in the tape gap between the next EOF record and
 510        the record that follows it.
 511 
 512 
 513        When spacing backward over a record (either data or EOF), the tape head
 514        is positioned in the tape gap immediately preceding the tape record
 515        where the tape head is currently positioned. When spacing backward over
 516        file marks (EOF records), the tape head is positioned in the tape gap
 517        preceding the EOF. Thus the next read would fetch the EOF.
 518 
 519 
 520        Record skipping does not go past a file mark; file skipping does not go
 521        past the EOM. After an MTFSR <huge number> command, the driver leaves
 522        the tape logically positioned before the EOF. A related feature is that
 523        EOFs remain pending until the tape is closed. For example, a program
 524        which first reads all the records of a file up to and including the EOF
 525        and then performs an MTFSF command will leave the tape positioned just
 526        after that same EOF, rather than skipping the next file.
 527 
 528 
 529        The MTNBSF and MTFSF operations are inverses. Thus, an " MTFSF -1" is
 530        equivalent to an " MTNBSF 1". An " MTNBSF 0" is the same as " MTFSF 0";
 531        both position the tape device at the beginning of the current file.
 532 




 533 
 534        MTBSF moves the tape backwards by file marks. The tape position will
 535        end on the beginning of the tape side of the desired file mark. An "
 536        MTBSF 0" will position the tape at the end of the current file, before
 537        the filemark.
 538 
 539 
 540        MTBSR and MTFSR operations perform much like space file operations,
 541        except that they move by records instead of files. Variable-length I/O
 542        devices (1/2" reel, for example) space actual records; fixed-length I/O
 543        devices space physical records (blocks). 1/4" cartridge tape, for
 544        example, spaces 512 byte physical records. The status ioctl residual
 545        count contains the number of files or records not skipped.
 546 
 547 
 548        MTFSSF and MTBSSF space forward or backward, respectively, to the next
 549        occurrence of the requested number of file marks, one following
 550        another. If there are more sequential file marks on tape than were
 551        requested, it spaces over the requested number and positions after the
 552        requested file mark. Note that not all drives support this command and
 553        if a request is sent to a drive that does not, ENOTTY is returned.
 554 
 555 
 556        MTOFFL rewinds and, if appropriate, takes the device off-line by
 557        unloading the tape. It is recommended that the device be closed after
 558        offlining and then re-opened after a tape has been inserted to
 559        facilitate portability to other platforms and other operating systems.
 560        Attempting to re-open the device with no tape will result in an error
 561        unless the O_NDELAY flag is used.  (See open(2).)
 562 



 563 
 564        The MTRETEN retension ioctl applies only to 1/4" cartridge tape
 565        devices.  It is used to restore tape tension, improving the tape's soft
 566        error rate after extensive start-stop operations or long-term storage.
 567 
 568 
 569        MTERASE rewinds the tape, erases it completely, and returns to the
 570        beginning of tape. Erasing may take a long time depending on the device
 571        and/or tapes. For time details, refer to the drive specific manual.
 572 
 573 
 574        MTEOM positions the tape at a location just after the last file written
 575        on the tape. For 1/4" cartridge and 8mm tape, this is after the last
 576        file mark on the tape. For 1/2" reel tape, this is just after the first
 577        file mark but before the second (and last) file mark on the tape.
 578        Additional files can then be appended onto the tape from that point.
 579 
 580 
 581        Note the difference between MTBSF (backspace over file mark) and MTNBSF
 582        (backspace file to beginning of file). The former moves the tape
 583        backward until it crosses an EOF mark, leaving the tape positioned
 584        before the file mark. The latter leaves the tape positioned after the
 585        file mark. Hence, "MTNBSF n" is equivalent to "MTBSF (n+1)" followed by
 586        "MTFSF 1". The 1/4" cartridge tape devices do not support MTBSF.
 587 
 588 
 589        MTSRSZ and MTGRSZ are used to set and get fixed record lengths. The
 590        MTSRSZ ioctl allows variable length and fixed length tape drives that
 591        support multiple record sizes to set the record length. The mt_count
 592        field of the  mtop struct is used to pass the record size to/from the
 593        st driver. A value of 0 indicates variable record size. The MTSRSZ
 594        ioctl makes a variable-length tape device behave like a fixed-length
 595        tape device. Refer to the specific tape driver man page for details.

 596 
 597 
 598        MTLOAD loads the next tape cartridge into the tape drive. This is
 599        generally only used with stacker and tower type tape drives which
 600        handle multiple tapes per tape drive. A tape device without a tape
 601        inserted can be opened with the O_NDELAY flag, in order to execute this
 602        operation.
 603 
 604 
 605        MTIOCGETERROR allows user-level applications to retrieve error records
 606        from the st driver. An error record consists of the SCSI command cdb
 607        which causes the error and a scsi_arq_status(9S) structure if
 608        available.  The user-level application is responsible for allocating
 609        and releasing the memory for mtee_cdb_buf and scsi_arq_status of each
 610        mterror_entry. Before issuing the ioctl, the mtee_arq_status_len value
 611        should be at least equal to "sizeof(struct scsi_arq_status)." If more
 612        sense data than the size of scsi_arq_status(9S) is desired, the
 613        mtee_arq_status_len may be larger than "sizeof(struct scsi_arq_status)"
 614        by the amount of additional extended sense data desired.  The
 615        es_add_len field of scsi_extended_sense(9S) can be used to determine
 616        the amount of valid sense data returned by the device.
 617 
 618 
 619        The MTIOCGET get status ioctl call returns the drive ID (mt_type),
 620        sense key error (mt_erreg), file  number (mt_fileno), optimum blocking
 621        factor (mt_bf) and record number (mt_blkno) of the last error. The
 622        residual count (mt_resid) is set to the number of bytes not transferred
 623        or files/records not spaced. The flags word (mt_flags) contains
 624        information indicating if the device is SCSI, if the device is a reel
 625        device and whether the device supports absolute file positioning. The
 626        mt_flags also indicates if the device is requesting cleaning media be
 627        used, whether the device is capable of reporting the requirement of
 628        cleaning media and if the currently loaded media is WORM (Write Once
 629        Read Many) media.
 630 
 631        Note -
 632 
 633          When tape alert cleaning is managed by the st driver, the tape target
 634          driver may continue to return a "drive needs cleaning" status unless
 635          an MTIOCGET ioctl() call is made while the cleaning media is in the
 636          drive.
 637 
 638 
 639        The  MTIOCGETDRIVETYPE get drivetype ioctl call returns the name of the
 640        tape drive as defined in  st.conf (name), Vendor ID and model
 641        (product), ID (vid), type of tape device (type), block size  (bsize),
 642        drive options  (options), maximum read retry count (max_rretries),
 643        maximum write retry count (max_wretries), densities supported by the
 644        drive (densities), and default density of the tape drive
 645        (default_density).
 646 
 647 
 648        The MTIOCGETPOS ioctl returns the current tape position of the drive.
 649        It is returned in struct tapepos as defined in
 650        /usr/include/sys/scsi/targets/stdef.h.
 651 
 652 
 653        The  MTIOCRESTPOS ioctl restores a saved position from the MTIOCGETPOS.
 654 
 655    Persistent Error Handling IOCTLs and Asynchronous Tape Operations
 656        MTIOCPERSISTENT
 657                                 enables/disables persistent error handling


 658 





 659 
 660        MTIOCPERSISTENTSTATUS
 661                                 queries for persistent error handling
 662 
 663 
 664        MTIOCLRERR
 665                                 clears persistent error handling
 666 
 667 
 668        MTIOCGUARANTEEDORDER
 669                                 checks whether driver guarantees order of
 670                                 I/O's
 671 
 672 
 673 
 674        The MTIOCPERSISTENT ioctl enables or disables persistent error
 675        handling.  It takes as an argument a pointer to an integer that turns
 676        it either on or off.  If the ioctl succeeds, the desired operation was
 677        successful. It will wait for all outstanding I/O's to complete before
 678        changing the persistent error handling status. For example,
 679 
 680          int on = 1;
 681          ioctl(fd, MTIOCPERSISTENT, &on);
 682          int off = 0;
 683          ioctl(fd, MTIOCPERSISTENT, &off);
 684 
 685 
 686 
 687        The MTIOCPERSISTENTSTATUS ioctl enables or disables persistent error
 688        handling. It takes as an argument a pointer to an integer inserted by
 689        the driver. The integer can be either 1 if persistent error handling is
 690        'on', or 0 if persistent error handling is 'off'. It will not wait for
 691        outstanding I/O's.  For example,
 692 
 693          int query;
 694          ioctl(fd, MTIOCPERSISTENTSTATUS, &query);
 695 
 696 
 697 
 698        The MTIOCLRERR ioctl clears persistent error handling and allows tape
 699        operations to continual normally. This ioctl requires no argument and
 700        will always succeed, even if persistent error handling has not been
 701        enabled. It will wait for any outstanding I/O's before it clears the
 702        error.
 703 
 704 
 705        The MTIOCGUARANTEEDORDER ioctl is used to determine whether the driver
 706        guarantees the order of I/O's. It takes no argument. If the ioctl
 707        succeeds, the driver will support guaranteed order. If the driver does
 708        not support guaranteed order, then it should not be used for
 709        asynchronous I/O with libaio. It will wait for any outstanding I/O's
 710        before it returns. For example,
 711 
 712          ioctl(fd, MTIOCGUARANTEEDORDER)
 713 
 714 
 715 
 716        See the Persistent Error Handling subsection above for more information
 717        on persistent error handling.
 718 
 719    Asynchronous and State Change IOCTLS
 720        MTIOCSTATE
 721                      This ioctl blocks until the state of the drive, inserted
 722                      or ejected, is changed. The argument is a pointer to a
 723                      mtio_state, enum, whose possible enumerations are listed
 724                      below. The initial value should be either the last
 725                      reported state of the drive, or MTIO_NONE. Upon return,
 726                      the enum pointed to by the argument is updated with the
 727                      current state of the drive.
 728 
 729 
 730          enum mtio_state {
 731          MTIO_NONE      /* Return tape's current state */
 732          MTIO_EJECTED   /* Tape state is "ejected" */
 733          MTIO_INSERTED  /* Tape state is "inserted" */
 734          ;
 735 
 736 
 737 
 738        When using asynchronous operations, most ioctls will wait for all
 739        outstanding commands to complete before they are executed.
 740 
 741    IOCTLS for Multi-initiator Configurations
 742        MTIOCRESERVE
 743                             reserve the tape drive
 744 
 745 
 746        MTIOCRELEASE
 747                             revert back to the default behavior of reserve on
 748                             open/release on close


 749 
 750 
 751        MTIOCFORCERESERVE
 752                             reserve the tape unit by breaking reservation held
 753                             by another host
 754 
 755 
 756 
 757        The MTIOCRESERVE ioctl reserves the tape drive such that it does not
 758        release the tape drive at close. This changes the default behavior of
 759        releasing the device upon close. Reserving the tape drive that is
 760        already reserved has no effect. For example,
 761 
 762 
 763        ioctl(fd, MTIOCRESERVE);
 764 




 765 
 766        The MTIOCRELEASE ioctl reverts back to the default behavior of reserve
 767        on open/release on close operation, and a release will occur during the
 768        next close. Releasing the tape drive that is already released has no
 769        effect. For example,
 770 
 771 
 772        ioctl(fd, MTIOCRELEASE);
 773 
 774 
 775        The MTIOCFORCERESERVE ioctl breaks a reservation held by another host,
 776        interrupting any I/O in progress by that other host, and then reserves
 777        the tape unit. This ioctl can be executed only with super-user
 778        privileges. It is recommended to open the tape device in O_NDELAY mode
 779        when this ioctl needs to be executed, otherwise the open will fail if
 780        another host indeed has it reserved. For example,
 781 
 782          ioctl(fd, MTIOCFORCERESERVE);
 783 
 784 
 785    IOCTLS for Handling Tape Configuration Options
 786        MTIOCSHORTFMK
 787                               enables/disables support for writing short
 788                               filemarks. This is specific to Exabyte drives.
 789 


 790 
 791        MTIOCREADIGNOREILI
 792                               enables/disables suppress incorrect length
 793                               indicator (SILI) support during reads
 794 






 795 
 796        MTIOCREADIGNOREEOFS
 797                               enables/disables support for reading past two
 798                               EOF marks which otherwise indicate End-Of-
 799                               recording-Media (EOM) in the case of 1/2" reel
 800                               tape drives
 801 
 802 
 803 
 804        The MTIOCSHORTFMK ioctl enables or disables support for short
 805        filemarks.  This ioctl is only applicable to Exabyte drives which
 806        support short filemarks.  As an argument, it takes a pointer to an
 807        integer.  If 0 (zero) is the specified integer, then long filemarks
 808        will be written. If 1 is the  specified integer, then short filemarks
 809        will be written. The specified tape behavior will be in effect until
 810        the device is closed.
 811 
 812 
 813        For example:
 814 
 815          int on = 1;
 816          int off = 0;
 817          /* enable short filemarks */
 818          ioctl(fd, MTIOSHORTFMK, &on);
 819          /* disable short filemarks */
 820          ioctl(fd, MTIOCSHORTFMK, &off);
 821 


 822 
 823 
 824        Tape drives which do not support short filemarks will return an errno
 825        of ENOTTY.
 826 
 827 
 828        The MTIOCREADIGNOREILI ioctl enables or disables the suppress incorrect
 829        length indicator (SILI) support during reads.  As an argument, it takes
 830        a pointer to an integer.   If 0 (zero) is the specified integer, SILI
 831        will not be used during reads and incorrect length indicator will not
 832        be suppressed.  If 1 is  the specified integer, SILI will be used
 833        during reads and incorrect length indicator will be suppressed.  The
 834        specified  tape behavior will be in effect until the device is closed.
 835 
 836 
 837        For example:
 838 
 839          int on = 1;
 840          int off = 0;
 841          ioctl(fd, MTIOREADIGNOREILI, &on);
 842          ioctl(fd, MTIOREADIGNOREILI, &off);
 843 
 844 
 845 
 846        The MTIOCREADIGNOREEOFS ioctl enables or disables support for reading
 847        past double EOF marks which otherwise indicate End-Of-recorded-media
 848        (EOM) in the case of 1/2" reel tape drives.  As an argument, it takes a
 849        pointer to an integer.   If 0 (zero) is the specified integer, then
 850        double EOF marks indicate End-Of-recodred-media (EOD). If 1 is the
 851        specified integer, the double EOF marks no longer indicate EOM, thus
 852        allowing applications to read past two EOF marks.  In this case it is
 853        the responsibility of the application to detect end-of-recorded-media
 854        (EOM).  The specified  tape behavior will be in effect until the device
 855        is closed.
 856 
 857 
 858        For example:
 859 
 860          int on = 1;
 861          int off = 0;
 862          ioctl(fd, MTIOREADIGNOREEOFS, &on);
 863          ioctl(fd, MTIOREADIGNOREEOFS, &off);
 864 

 865 


 866 
 867        Tape drives other than 1/2" reel tapes will return an errno of ENOTTY.


 868 



 869 EXAMPLES
 870        Example 1 Tape Positioning and Tape Drives
 871 
 872 
 873        Suppose you have written three files to the non-rewinding 1/2" tape
 874        device, /dev/rmt/0ln, and that you want to go back and dd(1M) the
 875        second file off the tape. The commands to do this are:
 876 
 877 
 878          mt -F /dev/rmt/0lbn bsf 3
 879          mt -F /dev/rmt/0lbn fsf 1
 880          dd if=/dev/rmt/0ln
 881 


 882 
 883 
 884        To accomplish the same tape positioning in a C program, followed by a
 885        get status ioctl:
 886 
 887 
 888          struct mtop mt_command;
 889          struct mtget mt_status;
 890          mt_command.mt_op = MTBSF;
 891          mt_command.mt_count = 3;
 892          ioctl(fd, MTIOCTOP, &mt_command);
 893          mt_command.mt_op = MTFSF;
 894          mt_command.mt_count = 1;
 895          ioctl(fd, MTIOCTOP, &mt_command);
 896          ioctl(fd, MTIOCGET, (char *)&mt_status);
 897 
 898 
 899 
 900        or
 901 
 902 
 903          mt_command.mt_op = MTNBSF;
 904          mt_command.mt_count = 2;
 905          ioctl(fd, MTIOCTOP, &mt_command);
 906          ioctl(fd, MTIOCGET, (char *)&mt_status);
 907 
 908 
 909 
 910        To get information about the tape drive:
 911 
 912 
 913          struct mtdrivetype mtdt;
 914          struct mtdrivetype_request mtreq;
 915          mtreq.size = sizeof(struct mtdrivetype);
 916          mtreq.mtdtp = &mtdt;
 917          ioctl(fd, MTIOCGETDRIVETYPE, &mtreq);
 918 
 919 
 920 FILES
 921        /dev/rmt/<unit number><density>[<BSD behavior>][<no rewind>]
 922 
 923 
 924        Where density can be l, m, h, u/c (low, medium, high, ultra/compressed,
 925        respectively), the BSD behavior  option is b, and the no rewind  option
 926        is n.
 927 
 928 
 929        For example, /dev/rmt/0hbn specifies unit 0, high density, BSD behavior
 930        and no rewind.
 931 
 932 SEE ALSO
 933        mt(1), tar(1), dd(1M), open(2), read(2), write(2), aioread(3C),
 934        aiowrite(3C), ar.h(3HEAD), st(7D)
 935 
 936 
 937        1/4 Inch Tape Drive Tutorial
 938 
 939 
 940 
 941                                  April 9, 2016                        MTIO(7I)
   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 reguarding 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 he
 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-recodred-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                         August 31, 2018                        illumos