1mtio(7I) Ioctl Requests mtio(7I)
2
6 mtio - general magnetic tape interface
7
9 #include <sys/types.h>
10 #include <sys/ioctl.h>
11 #include <sys/mtio.h>
12
15 1/2", 1/4", 4mm, and 8mm magnetic tape drives all share the same gen‐
16 eral character device interface.
17 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 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 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 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 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 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 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 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 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 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 Persistent Error Handling
83 Persistent error handling is a modification of the current error han‐
84 dling behaviors, BSD and SVR4. With persistent error handling enabled,
85 all tape operations after an error or exception will return immediately
86 with an error. Persistent error handling can be most useful with asyn‐
87 chronous tape operations that use the aioread(3C) and aiowrite(3C)
88 functions.
89 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 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 Disabling persistent error handling returns the error behavior to nor‐
107 mal SVR4 error handling, and will not occur until all outstanding oper‐
108 ations 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 The Read Operation and Write Operation subsections contain more perti‐
115 nent information reguarding persistent error handling.
116 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 Two successful successive reads that both return zero byte counts indi‐
135 cate EOM on the tape. No further reading should be performed past the
136 EOM.
137 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 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 multi‐
149 ple records are limited to 65,534 bytes. Newer variable-length tape
150 drivers may relax the above limitation and allow applications to read
151 record sizes larger than 65,534. Refer to the specific tape driver man
152 page for details.
153 Reading past logical EOT is transparent to the user. A read operation
156 should never hit physical EOT.
157 Read requests that are lesser than a physical tape record are not
160 allowed. Appropriate error is returned.
161 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 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 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 overwrit‐
179 ing records; the erase head is just forward of the write head and any
180 following records will also be erased.
181 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 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 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 applica‐
202 tions to write record sizes larger than 65,534. Refer to the specific
203 tape driver man page for details.
204 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 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 MTIO‐
222 CLRERR, the next write will succeed (possibly short), followed by
223 another zero byte write count, and then another ENOSPC error.
224 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 Seeks are ignored in tape I/O.
232 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 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 posi‐
244 tioned to read the first record of the next file. However, if the tape
245 is at the first record of a file it doesn't advance again to the first
246 record of the next file. These semantics are different from the older
247 BSD behavior. If BSD behavior is required where no implicit space oper‐
248 ation is executed on close, the non-rewind device name containing the
249 letter b (for BSD behavior) in the final component should be specified.
250 If data was written, a file mark is automatically written by the driver
253 upon close. If the rewinding device was specified, the tape will be
254 rewound after the file mark is written. If the user wrote a file mark
255 prior to closing, then no file mark is written upon close. If a file
256 positioning ioctl, like rewind, is issued after writing, a file mark is
257 written before repositioning the tape.
258 All buffers are flushed on closing a tape device. Hence, it is strongly
261 recommended that the application wait for all buffers to be flushed
262 before closing the device. This can be done by writing a filemark via
263 MTWEOF, even with a zero count.
264 Note that for 1/2" reel tape devices, two file marks are written to
267 mark the EOM before rewinding or performing a file positioning ioctl.
268 If the user wrote a file mark before closing a 1/2" reel tape device,
269 the driver will always write a file mark before closing to insure that
270 the end of recorded media is marked properly. If the non-rewinding
271 device was specified, two file marks are written and the tape is left
272 positioned between the two so that the second one is overwritten on a
273 subsequent open(2) and write(2).
274 If no data was written and the driver was opened for WRITE-ONLY access,
277 one or two file marks are written, thus creating a null file.
278 After closing the device, persistent error handling will be disabled
281 and any error or exception will be cleared.
282
284 Not all devices support all ioctls. The driver returns an ENOTTY error
285 on unsupported ioctls.
286 The following structure definitions for magnetic tape ioctl commands
289 are from <sys/mtio.h>.
290 The minor device byte structure is::
293 15 7 6 5 4 3 2 1 0
295 ________________________________________________________________________
296 Unit # BSD Reserved Density Density No rewind Unit #
297 Bits 7-15 behavior Select Select on Close Bits 0-1
298 /*
301 * Layout of minor device byte:
302 */
303 #define MTUNIT(dev) (((minor(dev) & 0xff80) >> 5) +
304 (minor(dev) & 0x3))
305 #define MT_NOREWIND (1 <<2)
306 #define MT_DENSITY_MASK (3 <<3)
307 #define MT_DENSITY1 (0 <<3) /* Lowest density/format */
308 #define MT_DENSITY2 (1 <<3)
309 #define MT_DENSITY3 (2 <<3)
310 #define MT_DENSITY4 (3 <<3) /* Highest density/format */
311 #define MTMINOR(unit) (((unit & 0x7fc) << 5) + (unit & 0x3))
312 #define MT_BSD (1 <<6) /* BSD behavior on close */
313 /* Structure for MTIOCTOP − magnetic tape operation command */
316 struct mtop {
318 short mt_op; /* operation */
319 daddr_t mt_count; /* number of operations */
320 };
321 /* Structure for MTIOCLTOP - magnetic tape operation command */
324 Works exactly like MTIOCTOP except passes 64 bit mt_count values.
325 struct mtlop {
326 short mt_op;
327 short pad[3];
328 int64_t mt_count;
329 };
330 The following operations of MTIOCTOP and MTIOCLTOP ioctls are sup‐
334 ported:
335 MTWEOF write an end-of-file record
337 MTFSF forward space over file mark
340 MTBSF backward space over file mark (1/2", 8mm only)
343 MTFSR forward space to inter-record gap
346 MTBSR backward space to inter-record gap
349 MTREW rewind
352 MTOFFL rewind and take the drive off-line
355 MTNOP no operation, sets status only
358 MTRETEN retension the tape (cartridge tape only)
361 MTERASE erase the entire tape and rewind
364 MTEOM position to EOM
367 MTNBSF backward space file to beginning of file
370 MTSRSZ set record size
373 MTGRSZ get record size
376 MTTELL get current position
379 MTSEEK go to requested position
382 MTFSSF forward to requested number of sequential file marks
385 MTBSSF backward to requested number of sequential file marks
388 MTLOCK prevent media removal
391 MTUNLOCK allow media removal
394 MTLOAD load the next tape cartridge into the tape drive
397 MTIOCGETERROR retrieve error records from the st driver
400 /* structure for MTIOCGET − magnetic tape get status command */
403 struct mtget {
405 short mt_type; /* type of magtape device */
406 /* the following two registers are device dependent */
407 short mt_dsreg; /* "drive status" register */
408 short mt_erreg; /* "error" register */
409 /* optional error info. */
410 daddr_t mt_resid; /* residual count */
411 daddr_t mt_fileno; /* file number of current position */
412 daddr_t mt_blkno; /* block number of current position */
413 ushort_t mt_flags;
414 short mt_bf; /* optimum blocking factor */
415 };
416 /* structure for MTIOCGETDRIVETYPE − get tape config data command */
417 struct mtdrivetype_request {
418 int size;
419 struct mtdrivetype *mtdtp;
420 };
421 struct mtdrivetype {
422 char name[64]; /* Name, for debug */
423 char vid[25]; /* Vendor id and product id */
424 char type; /* Drive type for driver */
425 int bsize; /* Block size */
426 int options; /* Drive options */
427 int max_rretries; /* Max read retries */
428 int max_wretries; /* Max write retries */
429 uchar_t densities[MT_NDENSITIES]; /* density codes,low->hi */
430 uchar_t default_density; /* Default density chosen */
431 uchar_t speeds[MT_NSPEEDS]; /* speed codes, low->hi */
432 ushort_t non_motion_timeout; /* Seconds for non-motion */
433 ushort_t io_timeout; /* Seconds for data to from tape */
434 ushort_t rewind_timeout; /* Seconds to rewind */
435 ushort_t space_timeout; /* Seconds to space anywhere */
436 ushort_t load_timeout; /* Seconds to load tape and ready */
437 ushort_t unload_timeout; /* Seconds to unload */
438 ushort_t erase_timeout; /* Seconds to do long erase */
439 };
440 /* structure for MTIOCGETPOS and MTIOCRESTPOS - get/set tape position */
443 /*
444 * eof/eot/eom codes.
445 */
446 typedef enum {
447 ST_NO_EOF,
448 ST_EOF_PENDING, /* filemrk pending */
449 ST_EOF, /* at filemark */
450 ST_EOT_PENDING, /* logical eot pend. */
451 ST_EOT, /* at logical eot */
452 ST_EOM, /* at physical eot */
453 ST_WRITE_AFTER_EOM /* flag allowing writes after EOM */
454 }pstatus;
455 typedef enum { invalid, legacy, logical } posmode;
457 typedef struct tapepos {
459 uint64_t lgclblkno; /* Blks from start of partition */
460 int32_t fileno; /* Num. of current file */
461 int32_t blkno; /* Blk number in current file */
462 int32_t partition; /* Current partition */
463 pstatus eof; /* eof states */
464 posmode pmode; /* which pos. data is valid */
465 char pad[4];
466 }tapepos_t;
467 If the pmode is legacy,fileno and blkno fields are valid.
469 If the pmode is logical, lgclblkno field is valid.
470 The MTWEOF ioctl is used for writing file marks to tape. Not only does
474 this signify the end of a file, but also usually has the side effect of
475 flushing all buffers in the tape drive to the tape medium. A zero count
476 MTWEOF will just flush all the buffers and will not write any file
477 marks. Because a successful completion of this tape operation will
478 guarantee that all tape data has been written to the tape medium, it is
479 recommended that this tape operation be issued before closing a tape
480 device.
481 When spacing forward over a record (either data or EOF), the tape head
484 is positioned in the tape gap between the record just skipped and the
485 next record. When spacing forward over file marks (EOF records), the
486 tape head is positioned in the tape gap between the next EOF record and
487 the record that follows it.
488 When spacing backward over a record (either data or EOF), the tape head
491 is positioned in the tape gap immediately preceding the tape record
492 where the tape head is currently positioned. When spacing backward over
493 file marks (EOF records), the tape head is positioned in the tape gap
494 preceding the EOF. Thus the next read would fetch the EOF.
495 Record skipping does not go past a file mark; file skipping does not go
498 past the EOM. After an MTFSR <huge number> command, the driver leaves
499 the tape logically positioned before the EOF. A related feature is that
500 EOFs remain pending until the tape is closed. For example, a program
501 which first reads all the records of a file up to and including the EOF
502 and then performs an MTFSF command will leave the tape positioned just
503 after that same EOF, rather than skipping the next file.
504 The MTNBSF and MTFSF operations are inverses. Thus, an " MTFSF −1" is
507 equivalent to an " MTNBSF 1". An " MTNBSF 0" is the same as " MTFSF 0";
508 both position the tape device at the beginning of the current file.
509 MTBSF moves the tape backwards by file marks. The tape position will
512 end on the beginning of the tape side of the desired file mark. An "
513 MTBSF 0" will position the tape at the end of the current file, before
514 the filemark.
515 MTBSR and MTFSR operations perform much like space file operations,
518 except that they move by records instead of files. Variable-length I/O
519 devices (1/2" reel, for example) space actual records; fixed-length I/O
520 devices space physical records (blocks). 1/4" cartridge tape, for exam‐
521 ple, spaces 512 byte physical records. The status ioctl residual count
522 contains the number of files or records not skipped.
523 MTFSSF and MTBSSF space forward or backward, respectively, to the next
526 occurrence of the requested number of file marks, one following
527 another. If there are more sequential file marks on tape than were
528 requested, it spaces over the requested number and positions after the
529 requested file mark. Note that not all drives support this command and
530 if a request is sent to a drive that does not, ENOTTY is returned.
531 MTOFFL rewinds and, if appropriate, takes the device off-line by
534 unloading the tape. It is recommended that the device be closed after
535 offlining and then re-opened after a tape has been inserted to facili‐
536 tate portability to other platforms and other operating systems.
537 Attempting to re-open the device with no tape will result in an error
538 unless the O_NDELAY flag is used. (See open(2).)
539 The MTRETEN retension ioctl applies only to 1/4" cartridge tape
542 devices. It is used to restore tape tension, improving the tape's soft
543 error rate after extensive start-stop operations or long-term storage.
544 MTERASE rewinds the tape, erases it completely, and returns to the
547 beginning of tape. Erasing may take a long time depending on the device
548 and/or tapes. For time details, refer to the the drive specific man‐
549 ual.
550 MTEOM positions the tape at a location just after the last file written
553 on the tape. For 1/4" cartridge and 8mm tape, this is after the last
554 file mark on the tape. For 1/2" reel tape, this is just after the first
555 file mark but before the second (and last) file mark on the tape. Addi‐
556 tional files can then be appended onto the tape from that point.
557 Note the difference between MTBSF (backspace over file mark) and MTNBSF
560 (backspace file to beginning of file). The former moves the tape back‐
561 ward until it crosses an EOF mark, leaving the tape positioned before
562 the file mark. The latter leaves the tape positioned after the file
563 mark. Hence, "MTNBSF n" is equivalent to "MTBSF (n+1)" followed by
564 "MTFSF 1". The 1/4" cartridge tape devices do not support MTBSF.
565 MTSRSZ and MTGRSZ are used to set and get fixed record lengths. The
568 MTSRSZ ioctl allows variable length and fixed length tape drives that
569 support multiple record sizes to set the record length. The mt_count
570 field of the mtop struct is used to pass the record size to/from the
571 st driver. A value of 0 indicates variable record size. The MTSRSZ
572 ioctl makes a variable-length tape device behave like a fixed-length
573 tape device. Refer to the specific tape driver man page for details.
574 MTLOAD loads the next tape cartridge into the tape drive. This is gen‐
577 erally only used with stacker and tower type tape drives which handle
578 multiple tapes per tape drive. A tape device without a tape inserted
579 can be opened with the O_NDELAY flag, in order to execute this opera‐
580 tion.
581 MTIOCGETERROR allows user-level applications to retrieve error records
584 from the st driver. An error record consists of the SCSI command cdb
585 which causes the error and a scsi_arq_status(9S) structure if avail‐
586 able. The user-level application is responsible for allocating and
587 releasing the memory for mtee_cdb_buf and scsi_arq_status of each mter‐
588 ror_entry. Before issuing the ioctl, the mtee_arq_status_len value
589 should be at least equal to "sizeof(struct scsi_arq_status)." If more
590 sense data than the size of scsi_arq_status(9S) is desired, the
591 mtee_arq_status_len may be larger than "sizeof(struct scsi_arq_status)"
592 by the amount of additional extended sense data desired. The
593 es_add_len field of scsi_extended_sense(9S) can be used to determine
594 the amount of valid sense data returned by the device.
595 The MTIOCGET get status ioctl call returns the drive ID (mt_type),
598 sense key error (mt_erreg), file number (mt_fileno), optimum blocking
599 factor (mt_bf) and record number (mt_blkno) of the last error. The
600 residual count (mt_resid) is set to the number of bytes not transferred
601 or files/records not spaced. The flags word (mt_flags) contains infor‐
602 mation indicating if the device is SCSI, if the device is a reel device
603 and whether the device supports absolute file positioning. The mt_flags
604 also indicates if the device is requesting cleaning media be used,
605 whether the device is capable of reporting the requirement of cleaning
606 media and if the currently loaded media is WORM (Write Once Read Many)
607 media.
608 Note -
610 When tape alert cleaning is managed by the st driver, the tape target
612 driver may continue to return a "drive needs cleaning" status unless
613 an MTIOCGET ioctl() call is made while the cleaning media is in the
614 drive.
615 The MTIOCGETDRIVETYPE get drivetype ioctl call returns the name of the
618 tape drive as defined in st.conf (name), Vendor ID and model (prod‐
619 uct), ID (vid), type of tape device (type), block size (bsize), drive
620 options (options), maximum read retry count (max_rretries), maximum
621 write retry count (max_wretries), densities supported by the drive
622 (densities), and default density of the tape drive (default_density).
623 The MTIOCGETPOS ioctl returns the current tape position of the drive.
626 It is returned in struct tapepos as defined in
627 /usr/include/sys/scsi/targets/stdef.h.
628 The MTIOCRESTPOS ioctl restores a saved position from the MTIOCGETPOS.
631 Persistent Error Handling IOCTLs and Asynchronous Tape Operations
633 MTIOCPERSISTENT enables/disables persistent error handling
634 MTIOCPERSISTENTSTATUS queries for persistent error handling
637 MTIOCLRERR clears persistent error handling
640 MTIOCGUARANTEEDORDER checks whether driver guarantees order of
643 I/O's
644 The MTIOCPERSISTENT ioctl enables or disables persistent error han‐
648 dling. It takes as an argument a pointer to an integer that turns it
649 either on or off. If the ioctl succeeds, the desired operation was suc‐
650 cessful. It will wait for all outstanding I/O's to complete before
651 changing the persistent error handling status. For example,
652 int on = 1;
654 ioctl(fd, MTIOCPERSISTENT, &on);
655 int off = 0;
656 ioctl(fd, MTIOCPERSISTENT, &off);
657 The MTIOCPERSISTENTSTATUS ioctl enables or disables persistent error
661 handling. It takes as an argument a pointer to an integer inserted by
662 the driver. The integer can be either 1 if persistent error handling is
663 'on', or 0 if persistent error handling is 'off'. It will not wait for
664 outstanding I/O's. For example,
665 int query;
667 ioctl(fd, MTIOCPERSISTENTSTATUS, &query);
668 The MTIOCLRERR ioctl clears persistent error handling and allows tape
672 operations to continual normally. This ioctl requires no argument and
673 will always succeed, even if persistent error handling has not been
674 enabled. It will wait for any outstanding I/O's before it clears the
675 error.
676 The MTIOCGUARANTEEDORDER ioctl is used to determine whether the driver
679 guarantees the order of I/O's. It takes no argument. If the ioctl suc‐
680 ceeds, the driver will support guaranteed order. If the driver does not
681 support guaranteed order, then it should not be used for asynchronous
682 I/O with libaio. It will wait for any outstanding I/O's before it
683 returns. For example,
684 ioctl(fd, MTIOCGUARANTEEDORDER)
686 See the Persistent Error Handling subsection above for more information
690 on persistent error handling.
691 Asynchronous and State Change IOCTLS
693 MTIOCSTATE This ioctl blocks until the state of the drive, inserted
694 or ejected, is changed. The argument is a pointer to a
695 mtio_state, enum, whose possible enumerations are listed
696 below. The initial value should be either the last
697 reported state of the drive, or MTIO_NONE. Upon return,
698 the enum pointed to by the argument is updated with the
699 current state of the drive.
700 enum mtio_state {
703 MTIO_NONE /* Return tape's current state */
704 MTIO_EJECTED /* Tape state is "ejected" */
705 MTIO_INSERTED /* Tape state is "inserted" */
706 ;
707 When using asynchronous operations, most ioctls will wait for all out‐
711 standing commands to complete before they are executed.
712 IOCTLS for Multi-initiator Configurations
714 MTIOCRESERVE reserve the tape drive
715 MTIOCRELEASE revert back to the default behavior of reserve on
718 open/release on close
719 MTIOCFORCERESERVE reserve the tape unit by breaking reservation held
722 by another host
723 The MTIOCRESERVE ioctl reserves the tape drive such that it does not
727 release the tape drive at close. This changes the default behavior of
728 releasing the device upon close. Reserving the tape drive that is
729 already reserved has no effect. For example,
730 ioctl(fd, MTIOCRESERVE);
733 The MTIOCRELEASE ioctl reverts back to the default behavior of reserve
736 on open/release on close operation, and a release will occur during the
737 next close. Releasing the tape drive that is already released has no
738 effect. For example,
739 ioctl(fd, MTIOCRELEASE);
742 The MTIOCFORCERESERVE ioctl breaks a reservation held by another host,
745 interrupting any I/O in progress by that other host, and then reserves
746 the tape unit. This ioctl can be executed only with super-user privi‐
747 leges. It is recommended to open the tape device in O_NDELAY mode when
748 this ioctl needs to be executed, otherwise the open will fail if
749 another host indeed has it reserved. For example,
750 ioctl(fd, MTIOCFORCERESERVE);
752 IOCTLS for Handling Tape Configuration Options
755 MTIOCSHORTFMK enables/disable support for writing short file‐
756 marks. This is specific to Exabyte drives.
757 MTIOCREADIGNOREILI enables/disable supress incorrect length indica‐
760 tor support during reads
761 MTIOCREADIGNOREEOFS enables/disable support for reading past two EOF
764 marks which otherwise indicate End-Of-recording-
765 Media (EOM) in the case of 1/2" reel tape drives
766 The MTIOCSHORTFMK ioctl enables or disables support for short file‐
770 marks. This ioctl is only applicable to Exabyte drives which support
771 short filemarks. As an argument, it takes a pointer to an integer. If
772 0 (zero) is the specified integer, then long filemarks will be writ‐
773 ten. If 1 is the specified integer, then short filemarks will be writ‐
774 ten. The specified tape bahavior will be in effect until the device is
775 closed.
776 For example:
779 int on = 1;
781 int off = 0;
782 /* enable short filemarks */
783 ioctl(fd, MTIOSHORTFMK, &on);
784 /* disable short filemarks */
785 ioctl(fd, MTIOCSHORTFMK, &off);
786 Tape drives which do not support short filemarks will return an errno
790 of ENOTTY.
791 The MTIOCREADIGNOREILI ioctl enables or disables the suppress incorrect
794 length indicator (SILI) support during reads. As an argument, it takes
795 a pointer to an integer. If 0 (zero) is the specified integer, SILI
796 will not be used during reads and incorrect length indicator will not
797 be supressed. If 1 is the specified integer, SILI will be used during
798 reads and incorrect length indicator will be supressed. The specified
799 tape bahavior will be in effect until the device is closed.
800 For example:
803 int on = 1;
805 int off = 0;
806 ioctl(fd, MTIOREADIGNOREILI, &on);
807 ioctl(fd, MTIOREADIGNOREILI, &off);
808 The MTIOCREADIGNOREEOFS ioctl enables or disables support for reading
812 past double EOF marks which otherwise indicate End-Of-recorded-media
813 (EOM) in the case of 1/2" reel tape drives. As an argument, it takes a
814 pointer to an integer. If 0 (zero) is the specified integer, then
815 double EOF marks indicate End-Of-recodred-media (EOD). If 1 is the
816 specified integer, the double EOF marks no longer indicate EOM, thus
817 allowing applications to read past two EOF marks. In this case it is
818 the responsibility of the application to detect end-of-recorded-media
819 (EOM). The specified tape bahavior will be in effect until the device
820 is closed.
821 For example:
824 int on = 1;
826 int off = 0;
827 ioctl(fd, MTIOREADIGNOREEOFS, &on);
828 ioctl(fd, MTIOREADIGNOREEOFS, &off);
829 Tape drives other than 1/2" reel tapes will return an errno of ENOTTY.
833
835 Example 1 Tape Positioning and Tape Drives
836 Suppose you have written three files to the non-rewinding 1/2" tape
839 device, /dev/rmt/0ln, and that you want to go back and dd(1M) the sec‐
840 ond file off the tape. The commands to do this are:
841 mt -F /dev/rmt/0lbn bsf 3
844 mt -F /dev/rmt/0lbn fsf 1
845 dd if=/dev/rmt/0ln
846 To accomplish the same tape positioning in a C program, followed by a
850 get status ioctl:
851 struct mtop mt_command;
854 struct mtget mt_status;
855 mt_command.mt_op = MTBSF;
856 mt_command.mt_count = 3;
857 ioctl(fd, MTIOCTOP, &mt_command);
858 mt_command.mt_op = MTFSF;
859 mt_command.mt_count = 1;
860 ioctl(fd, MTIOCTOP, &mt_command);
861 ioctl(fd, MTIOCGET, (char *)&mt_status);
862 or
866 mt_command.mt_op = MTNBSF;
869 mt_command.mt_count = 2;
870 ioctl(fd, MTIOCTOP, &mt_command);
871 ioctl(fd, MTIOCGET, (char *)&mt_status);
872 To get information about the tape drive:
876 struct mtdrivetype mtdt;
879 struct mtdrivetype_request mtreq;
880 mtreq.size = sizeof(struct mtdrivetype);
881 mtreq.mtdtp = &mtdt;
882 ioctl(fd, MTIOCGETDRIVETYPE, &mtreq);
883
886 /dev/rmt/<unit number><density>[<BSD behavior>][<no rewind>]
887 Where density can be l, m, h, u/c (low, medium, high, ultra/compressed,
890 respectively), the BSD behavior option is b, and the no rewind option
891 is n.
892 For example, /dev/rmt/0hbn specifies unit 0, high density, BSD behavior
895 and no rewind.
896
898 mt(1), tar(1), dd(1M), open(2), read(2), write(2), aioread(3C),
899 aiowrite(3C), ar.h(3HEAD), st(7D)
900 1/4 Inch Tape Drive Tutorial
903SunOS 5.11 15 Sep 2007 mtio(7I)