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
|