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