1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH MTIO 7I "April 9, 2016"
7 .SH NAME
8 mtio \- general magnetic tape interface
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/types.h>
13 #include <sys/ioctl.h>
14 #include <sys/mtio.h>
15 .fi
16
17 .SH DESCRIPTION
18 .LP
19 1/2", 1/4", 4mm, and 8mm magnetic tape drives all share the same general
20 character device interface.
21 .sp
22 .LP
23 There are two types of tape records: data records and end-of-file (EOF)
24 records. S\fBEOF\fR records are also known as tape marks and file marks. A
25 record is separated by interrecord (or tape) gaps on a tape.
26 .sp
27 .LP
28 End-of-recorded-media (EOM) is indicated by two \fBEOF\fR marks on 1/2" tape;
29 by one \fBEOF\fR mark on 1/4", 4mm, and 8mm cartridge tapes.
30 .SS "1/2" Reel Tape"
31 .LP
32 Data bytes are recorded in parallel onto the 9-track tape. Since it is a
33 variable-length tape device, the number of bytes in a physical record may
34 vary.
35 .sp
36 .LP
37 The recording formats available (check specific tape drive) are 800 \fBBPI,\fR
38 1600 \fBBPI,\fR 6250 \fBBPI,\fR and data compression. Actual storage capacity
39 is a function of the recording format and the length of the tape reel. For
40 example, using a 2400 foot tape, 20 Mbyte can be stored using 800 \fBBPI,\fR 40
41 Mbyte using 1600 \fBBPI,\fR 140 Mbyte using 6250 \fBBPI,\fR or up to 700 Mbyte
42 using data compression.
43 .SS "1/4" Cartridge Tape"
44 .LP
45 Data is recorded serially onto 1/4" cartridge tape. The number of bytes per
46 record is determined by the physical record size of the device. The I/O request
47 size must be a multiple of the physical record size of the device. For
48 \fBQIC-11,\fR \fBQIC-24,\fR and \fBQIC-150\fR tape drives, the block size is
49 512 bytes.
50 .sp
51 .LP
52 The records are recorded on tracks in a serpentine motion. As one track is
53 completed, the drive switches to the next and begins writing in the opposite
54 direction, eliminating the wasted motion of rewinding. Each file, including the
55 last, ends with one file mark.
56 .sp
57 .LP
58 Storage capacity is based on the number of tracks the drive is capable of
59 recording. For example, 4-track drives can only record 20 Mbyte of data on a
60 450 foot tape; 9-track drives can record up to 45 Mbyte of data on a tape of
61 the same length. \fBQIC-11\fR is the only tape format available for 4-track
62 tape drives. In contrast, 9-track tape drives can use either \fBQIC-24\fR or
63 \fBQIC-11.\fR Storage capacity is not appreciably affected by using either
64 format. \fBQIC-24\fR is preferable to \fBQIC-11\fR because it records a
65 reference signal to mark the position of the first track on the tape, and each
66 block has a unique block number.
67 .sp
68 .LP
69 The \fBQIC-150\fR tape drives require \fBDC-6150\fR (or equivalent) tape
70 cartridges for writing. However, they can read other tape cartridges in
71 \fBQIC-11,\fR \fBQIC-24,\fR or \fBQIC-120\fR tape formats.
72 .SS "8mm Cartridge Tape"
73 .LP
74 Data is recorded serially onto 8mm helical scan cartridge tape. Since it is a
75 variable-length tape device, the number of bytes in a physical record may
76 vary. The recording formats available (check specific tape drive) are standard
77 2Gbyte, 5Gbyte, and compressed format.
78 .SS "4mm DAT Tape"
79 .LP
80 Data is recorded either in Digital Data Storage (DDS) tape format or in Digital
81 Data Storage, Data Compressed (DDS-DC) tape format. Since it is a
82 variable-length tape device, the number of bytes in a physical record may
83 vary. The recording formats available are standard 2Gbyte and compressed
84 format.
85 .SS "Persistent Error Handling"
86 .LP
87 Persistent error handling is a modification of the current error handling
88 behaviors, BSD and SVR4. With persistent error handling enabled, all tape
89 operations after an error or exception will return immediately with an error.
90 Persistent error handling can be most useful with asynchronous tape operations
91 that use the \fBaioread\fR(3C) and \fBaiowrite\fR(3C) functions.
92 .sp
93 .LP
94 To enable persistent error handling, the ioctl \fBMTIOCPERSISTENT\fR must be
95 issued. If this ioctl succeeds, then persistent error handling is enabled and
96 changes the current error behavior. This ioctl will fail if the device driver
97 does not support persistent error handling.
98 .sp
99 .LP
100 With persistent error handling enabled, all tape operations after an exception
101 or error will return with the same error as the first command that failed; the
102 operations will not be executed. An exception is some event that might stop
103 normal tape operations, such as an End Of File (EOF) mark or an End Of Tape
104 (EOT) mark. An example of an error is a media error. The \fBMTIOCLRERR\fR ioctl
105 must be issued to allow normal tape operations to continue and to clear the
106 error.
107 .sp
108 .LP
109 Disabling persistent error handling returns the error behavior to normal SVR4
110 error handling, and will not occur until all outstanding operations are
111 completed. Applications should wait for all outstanding operations to complete
112 before disabling persistent error handling. Closing the device will also
113 disable persistent error handling and clear any errors or exceptions.
114 .sp
115 .LP
116 The \fBRead Operation\fR and \fBWrite Operation\fR subsections contain more
117 pertinent information reguarding persistent error handling.
118 .SS "Read Operation"
119 .LP
120 The \fBread\fR(2) function reads the next record on the tape. The record size
121 is passed back as the number of bytes read, provided it is not greater than the
122 number requested. When a tape mark or end of data is read, a zero byte count is
123 returned; all successive reads after the zero read will return an error and
124 \fBerrno\fR will be set to \fBEIO\fR. To move to the next file, an \fBMTFSF\fR
125 ioctl can be issued before or after the read causing the error. This error
126 handling behavior is different from the older \fBBSD\fR behavior, where another
127 read will fetch the first record of the next tape file. If the \fBBSD\fR
128 behavior is required, device names containing the letter \fBb\fR (for \fBBSD\fR
129 behavior) in the final component should be used. If persistent error handling
130 was enabled with either the BSD or SVR4 tape device behavior, all operations
131 after this read error will return \fBEIO\fR errors until the \fBMTIOCLRERR\fR
132 ioctl is issued. An \fBMTFSF\fR ioctl can then he issued.
133 .sp
134 .LP
135 Two successful successive reads that both return zero byte counts indicate
136 \fBEOM\fR on the tape. No further reading should be performed past the
137 \fBEOM.\fR
138 .sp
139 .LP
140 Fixed-length I/O tape devices require the number of bytes read to be a multiple
141 of the physical record size. For example, 1/4" cartridge tape devices only read
142 multiples of 512 bytes. If the blocking factor is greater than 64,512 bytes
143 (minphys limit), fixed-length I/O tape devices read multiple records.
144 .sp
145 .LP
146 Most tape devices which support variable-length I/O operations may read a range
147 of 1 to 65,535 bytes. If the record size exceeds 65,535 bytes, the driver reads
148 multiple records to satisfy the request. These multiple records are limited to
149 65,534 bytes. Newer variable-length tape drivers may relax the above limitation
150 and allow applications to read record sizes larger than 65,534. Refer to the
151 specific tape driver man page for details.
152 .sp
153 .LP
154 Reading past logical \fBEOT\fR is transparent to the user. A read operation
155 should never hit physical EOT.
156 .sp
157 .LP
158 Read requests that are lesser than a physical tape record are not allowed.
159 Appropriate error is returned.
160 .SS "Write Operation"
161 .LP
162 The \fBwrite\fR(2) function writes the next record on the tape. The record has
163 the same length as the given buffer.
164 .sp
165 .LP
166 Writing is allowed on 1/4" tape at either the beginning of tape or after the
167 last written file on the tape. With the Exabyte 8200, data may be appended only
168 at the beginning of tape, before a filemark, or after the last written file on
169 the tape.
170 .sp
171 .LP
172 Writing is not so restricted on 1/2", 4mm, and the other 8mm cartridge tape
173 drives. Care should be used when appending files onto 1/2" reel tape devices,
174 since an extra file mark is appended after the last file to mark the \fBEOM.\fR
175 This extra file mark must be overwritten to prevent the creation of a null
176 file. To facilitate write append operations, a space to the \fBEOM\fR ioctl is
177 provided. Care should be taken when overwriting records; the erase head is just
178 forward of the write head and any following records will also be erased.
179 .sp
180 .LP
181 Fixed-length I/O tape devices require the number of bytes written to be a
182 multiple of the physical record size. For example, 1/4" cartridge tape devices
183 only write multiples of 512 bytes.
184 .sp
185 .LP
186 Fixed-length I/O tape devices write multiple records if the blocking factor is
187 greater than 64,512 bytes (minphys limit). These multiple writes are limited to
188 64,512 bytes. For example, if a write request is issued for 65,536 bytes using
189 a 1/4" cartridge tape, two writes are issued; the first for 64,512 bytes and
190 the second for 1024 bytes.
191 .sp
192 .LP
193 Most tape devices which support variable-length I/O operations may write a
194 range of 1 to 65,535 bytes. If the record size exceeds 65,535 bytes, the driver
195 writes multiple records to satisfy the request. These multiple records are
196 limited to 65,534 bytes. As an example, if a write request for 65,540 bytes is
197 issued, two records are written; one for 65,534 bytes followed by another
198 record for 6 bytes. Newer variable-length tape drivers may relax the above
199 limitation and allow applications to write record sizes larger than 65,534.
200 Refer to the specific tape driver man page for details.
201 .sp
202 .LP
203 When logical \fBEOT\fR is encountered during a write, that write operation
204 completes and the number of bytes successfully transferred is returned (note
205 that a 'short write' may have occurred and not all the requested bytes would
206 have been transferred. The actual amount of data written will depend on the
207 type of device being used). The next write will return a zero byte count. A
208 third write will successfully transfer some bytes (as indicated by the returned
209 byte count, which again could be a short write); the fourth will transfer zero
210 bytes, and so on, until the physical \fBEOT\fR is reached and all writes will
211 fail with \fBEIO\fR.
212 .sp
213 .LP
214 When logical \fBEOT\fR is encountered with persistent error handling enabled,
215 the current write may complete or be a short write. The next write will return
216 a zero byte count. At this point an application should act appropriately for
217 end of tape cleanup or issue yet another write, which will return the error
218 \fBENOSPC\fR. After clearing the exception with \fBMTIOCLRERR\fR, the next
219 write will succeed (possibly short), followed by another zero byte write count,
220 and then another \fBENOSPC\fR error.
221 .sp
222 .LP
223 Allowing writes after \fBLEOT\fR has been encountered enables the flushing of
224 buffers. However, it is strongly recommended to terminate the writing and close
225 the file as soon as possible.
226 .sp
227 .LP
228 Seeks are ignored in tape I/O.
229 .SS "Close Operation"
230 .LP
231 Magnetic tapes are rewound when closed, except when the "no-rewind" devices
232 have been specified. The names of no-rewind device files use the letter \fBn\fR
233 as the end of the final component. The no-rewind version of \fB/dev/rmt/0l\fR
234 is \fB/dev/rmt/0ln\fR. In case of error for a no-rewind device, the next open
235 rewinds the device.
236 .sp
237 .LP
238 If the driver was opened for reading and a no-rewind device has been specified,
239 the close advances the tape past the next filemark (unless the current file
240 position is at \fBEOM),\fR leaving the tape correctly positioned to read the
241 first record of the next file. However, if the tape is at the first record of a
242 file it doesn't advance again to the first record of the next file. These
243 semantics are different from the older \fBBSD\fR behavior. If \fBBSD\fR
244 behavior is required where no implicit space operation is executed on close,
245 the non-rewind device name containing the letter \fBb\fR (for \fBBSD\fR
246 behavior) in the final component should be specified.
247 .sp
248 .LP
249 If data was written, a file mark is automatically written by the driver upon
250 close. If the rewinding device was specified, the tape will be rewound after
251 the file mark is written. If the user wrote a file mark prior to closing, then
252 no file mark is written upon close. If a file positioning ioctl, like rewind,
253 is issued after writing, a file mark is written before repositioning the tape.
254 .sp
255 .LP
256 All buffers are flushed on closing a tape device. Hence, it is strongly
257 recommended that the application wait for all buffers to be flushed before
258 closing the device. This can be done by writing a filemark via \fBMTWEOF,\fR
259 even with a zero count.
260 .sp
261 .LP
262 Note that for 1/2" reel tape devices, two file marks are written to mark the
263 \fBEOM\fR before rewinding or performing a file positioning ioctl. If the user
264 wrote a file mark before closing a 1/2" reel tape device, the driver will
265 always write a file mark before closing to insure that the end of recorded
266 media is marked properly. If the non-rewinding device was specified, two file
267 marks are written and the tape is left positioned between the two so that the
268 second one is overwritten on a subsequent \fBopen\fR(2) and \fBwrite\fR(2).
269 .sp
270 .LP
271 If no data was written and the driver was opened for \fBWRITE-ONLY\fR access,
272 one or two file marks are written, thus creating a null file.
273 .sp
274 .LP
275 After closing the device, persistent error handling will be disabled and any
276 error or exception will be cleared.
277 .SH IOCTLS
278 .LP
279 Not all devices support all \fBioctls\fR. The driver returns an \fBENOTTY\fR
280 error on unsupported ioctls.
281 .sp
282 .LP
283 The following structure definitions for magnetic tape \fBioctl \fRcommands are
284 from \fB<sys/mtio.h>\fR\&.
285 .sp
286 .LP
287 The minor device byte structure is::
288 .sp
289 .in +2
290 .nf
291 15 7 6 5 4 3 2 1 0
292 ________________________________________________________________________
293 Unit # BSD Reserved Density Density No rewind Unit #
294 Bits 7-15 behavior Select Select on Close Bits 0-1
295 .fi
296 .in -2
297
298 .sp
299 .in +2
300 .nf
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 \(mi magnetic tape operation command */
317
318 struct mtop {
319 short mt_op; /* operation */
320 daddr_t mt_count; /* number of operations */
321 };
322 .fi
323 .in -2
324
325 .sp
326 .in +2
327 .nf
328 /* Structure for MTIOCLTOP - magnetic tape operation command */
329 Works exactly like MTIOCTOP except passes 64 bit mt_count values.
330 struct mtlop {
331 short mt_op;
332 short pad[3];
333 int64_t mt_count;
334 };
335 .fi
336 .in -2
337
338 .sp
339 .LP
340 The following operations of \fBMTIOCTOP\fR and \fBMTIOCLTOP\fR ioctls are
341 supported:
342 .sp
343 .ne 2
344 .na
345 \fBMTWEOF\fR
346 .ad
347 .RS 17n
348 write an end-of-file record
349 .RE
350
351 .sp
352 .ne 2
353 .na
354 \fBMTFSF\fR
355 .ad
356 .RS 17n
357 forward space over file mark
358 .RE
359
360 .sp
361 .ne 2
362 .na
363 \fBMTBSF\fR
364 .ad
365 .RS 17n
366 backward space over file mark (1/2", 8mm only)
367 .RE
368
369 .sp
370 .ne 2
371 .na
372 \fBMTFSR\fR
373 .ad
374 .RS 17n
375 forward space to inter-record gap
376 .RE
377
378 .sp
379 .ne 2
380 .na
381 \fBMTBSR\fR
382 .ad
383 .RS 17n
384 backward space to inter-record gap
385 .RE
386
387 .sp
388 .ne 2
389 .na
390 \fBMTREW\fR
391 .ad
392 .RS 17n
393 rewind
394 .RE
395
396 .sp
397 .ne 2
398 .na
399 \fBMTOFFL\fR
400 .ad
401 .RS 17n
402 rewind and take the drive off-line
403 .RE
404
405 .sp
406 .ne 2
407 .na
408 \fBMTNOP\fR
409 .ad
410 .RS 17n
411 no operation, sets status only
412 .RE
413
414 .sp
415 .ne 2
416 .na
417 \fBMTRETEN\fR
418 .ad
419 .RS 17n
420 retension the tape (cartridge tape only)
421 .RE
422
423 .sp
424 .ne 2
425 .na
426 \fBMTERASE\fR
427 .ad
428 .RS 17n
429 erase the entire tape and rewind
430 .RE
431
432 .sp
433 .ne 2
434 .na
435 \fBMTEOM\fR
436 .ad
437 .RS 17n
438 position to EOM
439 .RE
440
441 .sp
442 .ne 2
443 .na
444 \fBMTNBSF\fR
445 .ad
446 .RS 17n
447 backward space file to beginning of file
448 .RE
449
450 .sp
451 .ne 2
452 .na
453 \fBMTSRSZ\fR
454 .ad
455 .RS 17n
456 set record size
457 .RE
458
459 .sp
460 .ne 2
461 .na
462 \fBMTGRSZ\fR
463 .ad
464 .RS 17n
465 get record size
466 .RE
467
468 .sp
469 .ne 2
470 .na
471 \fBMTTELL\fR
472 .ad
473 .RS 17n
474 get current position
475 .RE
476
477 .sp
478 .ne 2
479 .na
480 \fBMTSEEK\fR
481 .ad
482 .RS 17n
483 go to requested position
484 .RE
485
486 .sp
487 .ne 2
488 .na
489 \fBMTFSSF\fR
490 .ad
491 .RS 17n
492 forward to requested number of sequential file marks
493 .RE
494
495 .sp
496 .ne 2
497 .na
498 \fBMTBSSF\fR
499 .ad
500 .RS 17n
501 backward to requested number of sequential file marks
502 .RE
503
504 .sp
505 .ne 2
506 .na
507 \fBMTLOCK\fR
508 .ad
509 .RS 17n
510 prevent media removal
511 .RE
512
513 .sp
514 .ne 2
515 .na
516 \fBMTUNLOCK\fR
517 .ad
518 .RS 17n
519 allow media removal
520 .RE
521
522 .sp
523 .ne 2
524 .na
525 \fBMTLOAD\fR
526 .ad
527 .RS 17n
528 load the next tape cartridge into the tape drive
529 .RE
530
531 .sp
532 .ne 2
533 .na
534 \fBMTIOCGETERROR\fR
535 .ad
536 .RS 17n
537 retrieve error records from the st driver
538 .RE
539
540 .sp
541 .in +2
542 .nf
543 /* structure for MTIOCGET \(mi magnetic tape get status command */
544
545 struct mtget {
546 short mt_type; /* type of magtape device */
547 /* the following two registers are device dependent */
548 short mt_dsreg; /* "drive status" register */
549 short mt_erreg; /* "error" register */
550 /* optional error info. */
551 daddr_t mt_resid; /* residual count */
552 daddr_t mt_fileno; /* file number of current position */
553 daddr_t mt_blkno; /* block number of current position */
554 ushort_t mt_flags;
555 short mt_bf; /* optimum blocking factor */
556 };
557 /* structure for MTIOCGETDRIVETYPE \(mi get tape config data command */
558 struct mtdrivetype_request {
559 int size;
560 struct mtdrivetype *mtdtp;
561 };
562 struct mtdrivetype {
563 char name[64]; /* Name, for debug */
564 char vid[25]; /* Vendor id and product id */
565 char type; /* Drive type for driver */
566 int bsize; /* Block size */
567 int options; /* Drive options */
568 int max_rretries; /* Max read retries */
569 int max_wretries; /* Max write retries */
570 uchar_t densities[MT_NDENSITIES]; /* density codes,low->hi */
571 uchar_t default_density; /* Default density chosen */
572 uchar_t speeds[MT_NSPEEDS]; /* speed codes, low->hi */
573 ushort_t non_motion_timeout; /* Seconds for non-motion */
574 ushort_t io_timeout; /* Seconds for data to from tape */
575 ushort_t rewind_timeout; /* Seconds to rewind */
576 ushort_t space_timeout; /* Seconds to space anywhere */
577 ushort_t load_timeout; /* Seconds to load tape and ready */
578 ushort_t unload_timeout; /* Seconds to unload */
579 ushort_t erase_timeout; /* Seconds to do long erase */
580 };
581 .fi
582 .in -2
583
584 .sp
585 .in +2
586 .nf
587 /* structure for MTIOCGETPOS and MTIOCRESTPOS - get/set tape position */
588 /*
589 * eof/eot/eom codes.
590 */
591 typedef enum {
592 ST_NO_EOF,
593 ST_EOF_PENDING, /* filemrk pending */
594 ST_EOF, /* at filemark */
595 ST_EOT_PENDING, /* logical eot pend. */
596 ST_EOT, /* at logical eot */
597 ST_EOM, /* at physical eot */
598 ST_WRITE_AFTER_EOM /* flag allowing writes after EOM */
599 }pstatus;
600
601 typedef enum { invalid, legacy, logical } posmode;
602
603 typedef struct tapepos {
604 uint64_t lgclblkno; /* Blks from start of partition */
605 int32_t fileno; /* Num. of current file */
606 int32_t blkno; /* Blk number in current file */
607 int32_t partition; /* Current partition */
608 pstatus eof; /* eof states */
609 posmode pmode; /* which pos. data is valid */
610 char pad[4];
611 }tapepos_t;
612
613 If the pmode is legacy,fileno and blkno fields are valid.
614 If the pmode is logical, lgclblkno field is valid.
615 .fi
616 .in -2
617
618 .sp
619 .LP
620 The \fBMTWEOF\fR ioctl is used for writing file marks to tape. Not only does
621 this signify the end of a file, but also usually has the side effect of
622 flushing all buffers in the tape drive to the tape medium. A zero count
623 \fBMTWEOF\fR will just flush all the buffers and will not write any file marks.
624 Because a successful completion of this tape operation will guarantee that all
625 tape data has been written to the tape medium, it is recommended that this tape
626 operation be issued before closing a tape device.
627 .sp
628 .LP
629 When spacing forward over a record (either data or \fBEOF),\fR the tape head is
630 positioned in the tape gap between the record just skipped and the next record.
631 When spacing forward over file marks (EOF records), the tape head is positioned
632 in the tape gap between the next \fBEOF\fR record and the record that follows
633 it.
634 .sp
635 .LP
636 When spacing backward over a record (either data or \fBEOF),\fR the tape head
637 is positioned in the tape gap immediately preceding the tape record where the
638 tape head is currently positioned. When spacing backward over file marks (EOF
639 records), the tape head is positioned in the tape gap preceding the \fBEOF.\fR
640 Thus the next read would fetch the \fBEOF.\fR
641 .sp
642 .LP
643 Record skipping does not go past a file mark; file skipping does not go past
644 the \fBEOM.\fR After an \fBMTFSR\fR <huge number> command, the driver leaves
645 the tape logically positioned \fIbefore\fR the \fBEOF.\fR A related feature is
646 that \fBEOFs\fR remain pending until the tape is closed. For example, a program
647 which first reads all the records of a file up to and including the \fBEOF\fR
648 and then performs an \fBMTFSF\fR command will leave the tape positioned just
649 after that same \fBEOF,\fR rather than skipping the next file.
650 .sp
651 .LP
652 The \fBMTNBSF\fR and \fBMTFSF\fR operations are inverses. Thus, an "
653 \fBMTFSF\fR \(mi1" is equivalent to an " \fBMTNBSF\fR 1". An " \fBMTNBSF\fR 0"
654 is the same as " \fBMTFSF\fR 0"; both position the tape device at the beginning
655 of the current file.
656 .sp
657 .LP
658 \fBMTBSF\fR moves the tape backwards by file marks. The tape position will end
659 on the beginning of the tape side of the desired file mark. An " \fBMTBSF\fR 0"
660 will position the tape at the end of the current file, before the filemark.
661 .sp
662 .LP
663 \fBMTBSR\fR and \fBMTFSR\fR operations perform much like space file operations,
664 except that they move by records instead of files. Variable-length I/O devices
665 (1/2" reel, for example) space actual records; fixed-length I/O devices space
666 physical records (blocks). 1/4" cartridge tape, for example, spaces 512 byte
667 physical records. The status ioctl residual count contains the number of files
668 or records not skipped.
669 .sp
670 .LP
671 MTFSSF and MTBSSF space forward or backward, respectively, to the next
672 occurrence of the requested number of file marks, one following another. If
673 there are more sequential file marks on tape than were requested, it spaces
674 over the requested number and positions after the requested file mark. Note
675 that not all drives support this command and if a request is sent to a drive
676 that does not, \fBENOTTY\fR is returned.
677 .sp
678 .LP
679 \fBMTOFFL\fR rewinds and, if appropriate, takes the device off-line by
680 unloading the tape. It is recommended that the device be closed after offlining
681 and then re-opened after a tape has been inserted to facilitate portability to
682 other platforms and other operating systems. Attempting to re-open the device
683 with no tape will result in an error unless the \fBO_NDELAY\fR flag is used.
684 (See \fBopen\fR(2).)
685 .sp
686 .LP
687 The \fBMTRETEN\fR retension ioctl applies only to 1/4" cartridge tape devices.
688 It is used to restore tape tension, improving the tape's soft error rate after
689 extensive start-stop operations or long-term storage.
690 .sp
691 .LP
692 \fBMTERASE\fR rewinds the tape, erases it completely, and returns to the
693 beginning of tape. Erasing may take a long time depending on the device and/or
694 tapes. For time details, refer to the drive specific manual.
695 .sp
696 .LP
697 \fBMTEOM\fR positions the tape at a location just after the last file written
698 on the tape. For 1/4" cartridge and 8mm tape, this is after the last file mark
699 on the tape. For 1/2" reel tape, this is just after the first file mark but
700 before the second (and last) file mark on the tape. Additional files can then
701 be appended onto the tape from that point.
702 .sp
703 .LP
704 Note the difference between \fBMTBSF\fR (backspace over file mark) and
705 \fBMTNBSF\fR (backspace file to beginning of file). The former moves the tape
706 backward until it crosses an \fBEOF\fR mark, leaving the tape positioned
707 \fIbefore\fR the file mark. The latter leaves the tape positioned \fIafter\fR
708 the file mark. Hence, "\fBMTNBSF\fR n" is equivalent to "\fBMTBSF\fR (n+1)"
709 followed by "\fBMTFSF\fR 1". The 1/4" cartridge tape devices do not support
710 \fBMTBSF.\fR
711 .sp
712 .LP
713 \fBMTSRSZ\fR and \fBMTGRSZ\fR are used to set and get fixed record lengths. The
714 \fBMTSRSZ\fR ioctl allows variable length and fixed length tape drives that
715 support multiple record sizes to set the record length. The \fBmt_count\fR
716 field of the \fBmtop\fR struct is used to pass the record size to/from the
717 \fBst\fR driver. A value of \fB0\fR indicates variable record size. The
718 \fBMTSRSZ\fR ioctl makes a variable-length tape device behave like a
719 fixed-length tape device. Refer to the specific tape driver man page for
720 details.
721 .sp
722 .LP
723 \fBMTLOAD\fR loads the next tape cartridge into the tape drive. This is
724 generally only used with stacker and tower type tape drives which handle
725 multiple tapes per tape drive. A tape device without a tape inserted can be
726 opened with the \fBO_NDELAY\fR flag, in order to execute this operation.
727 .sp
728 .LP
729 \fBMTIOCGETERROR\fR allows user-level applications to retrieve error records
730 from the \fBst\fR driver. An error record consists of the SCSI command cdb
731 which causes the error and a \fBscsi_arq_status\fR(9S) structure if available.
732 The user-level application is responsible for allocating and releasing the
733 memory for mtee_cdb_buf and scsi_arq_status of each mterror_entry. Before
734 issuing the ioctl, the mtee_arq_status_len value should be at least equal to
735 "sizeof(struct scsi_arq_status)." If more sense data than the size of
736 \fBscsi_arq_status\fR(9S) is desired, the mtee_arq_status_len may be larger
737 than "sizeof(struct scsi_arq_status)" by the amount of additional extended
738 sense data desired. The es_add_len field of \fBscsi_extended_sense\fR(9S) can
739 be used to determine the amount of valid sense data returned by the device.
740 .sp
741 .LP
742 The \fBMTIOCGET\fR get status \fBioctl\fR call returns the drive ID
743 (\fImt_type\fR), sense key error (\fImt_erreg\fR), file number
744 (\fImt_fileno\fR), optimum blocking factor (\fImt_bf\fR) and record number
745 (\fImt_blkno\fR) of the last error. The residual count (\fImt_resid\fR) is set
746 to the number of bytes not transferred or files/records not spaced. The flags
747 word (\fImt_flags\fR) contains information indicating if the device is SCSI, if
748 the device is a reel device and whether the device supports absolute file
749 positioning. The \fImt_flags\fR also indicates if the device is requesting
750 cleaning media be used, whether the device is capable of reporting the
751 requirement of cleaning media and if the currently loaded media is WORM (Write
752 Once Read Many) media.
753 .LP
754 Note -
755 .sp
756 .RS 2
757 When tape alert cleaning is managed by the st driver, the tape target driver
758 may continue to return a "drive needs cleaning" status unless an MTIOCGET
759 ioctl() call is made while the cleaning media is in the drive.
760 .RE
761 .sp
762 .LP
763 The \fBMTIOCGETDRIVETYPE\fR get drivetype ioctl call returns the name of the
764 tape drive as defined in \fBst.conf\fR (\fIname\fR), Vendor \fBID\fR and model
765 (\fIproduct\fR), \fBID\fR (\fIvid\fR), type of tape device (\fBtype\fR), block
766 size (\fIbsize\fR), drive options (\fIoptions\fR), maximum read retry count
767 (\fImax_rretries\fR), maximum write retry count (\fImax_wretries\fR), densities
768 supported by the drive (\fIdensities\fR), and default density of the tape drive
769 (\fIdefault_density\fR).
770 .sp
771 .LP
772 The MTIOCGETPOS ioctl returns the current tape position of the drive. It is
773 returned in struct tapepos as defined in
774 \fB/usr/include/sys/scsi/targets/stdef.h\fR.
775 .sp
776 .LP
777 The MTIOCRESTPOS ioctl restores a saved position from the MTIOCGETPOS.
778 .SS "Persistent Error Handling IOCTLs and Asynchronous Tape Operations"
779 .ne 2
780 .na
781 \fBMTIOCPERSISTENT\fR
782 .ad
783 .RS 25n
784 enables/disables persistent error handling
785 .RE
786
787 .sp
788 .ne 2
789 .na
790 \fBMTIOCPERSISTENTSTATUS\fR
791 .ad
792 .RS 25n
793 queries for persistent error handling
794 .RE
795
796 .sp
797 .ne 2
798 .na
799 \fBMTIOCLRERR\fR
800 .ad
801 .RS 25n
802 clears persistent error handling
803 .RE
804
805 .sp
806 .ne 2
807 .na
808 \fBMTIOCGUARANTEEDORDER\fR
809 .ad
810 .RS 25n
811 checks whether driver guarantees order of I/O's
812 .RE
813
814 .sp
815 .LP
816 The \fBMTIOCPERSISTENT\fR ioctl enables or disables persistent error handling.
817 It takes as an argument a pointer to an integer that turns it either on or off.
818 If the ioctl succeeds, the desired operation was successful. It will wait for
819 all outstanding I/O's to complete before changing the persistent error handling
820 status. For example,
821 .sp
822 .in +2
823 .nf
824 int on = 1;
825 ioctl(fd, MTIOCPERSISTENT, &on);
826 int off = 0;
827 ioctl(fd, MTIOCPERSISTENT, &off);
828 .fi
829 .in -2
830
831 .sp
832 .LP
833 The \fBMTIOCPERSISTENTSTATUS\fR ioctl enables or disables persistent error
834 handling. It takes as an argument a pointer to an integer inserted by the
835 driver. The integer can be either 1 if persistent error handling is 'on', or 0
836 if persistent error handling is 'off'. It will not wait for outstanding I/O's.
837 For example,
838 .sp
839 .in +2
840 .nf
841 int query;
842 ioctl(fd, MTIOCPERSISTENTSTATUS, &query);
843 .fi
844 .in -2
845
846 .sp
847 .LP
848 The \fBMTIOCLRERR\fR ioctl clears persistent error handling and allows tape
849 operations to continual normally. This ioctl requires no argument and will
850 always succeed, even if persistent error handling has not been enabled. It will
851 wait for any outstanding I/O's before it clears the error.
852 .sp
853 .LP
854 The \fBMTIOCGUARANTEEDORDER\fR ioctl is used to determine whether the driver
855 guarantees the order of I/O's. It takes no argument. If the ioctl succeeds, the
856 driver will support guaranteed order. If the driver does not support guaranteed
857 order, then it should not be used for asynchronous I/O with \fBlibaio\fR. It
858 will wait for any outstanding I/O's before it returns. For example,
859 .sp
860 .in +2
861 .nf
862 ioctl(fd, MTIOCGUARANTEEDORDER)
863 .fi
864 .in -2
865
866 .sp
867 .LP
868 See the \fBPersistent Error Handling\fR subsection above for more information
869 on persistent error handling.
870 .SS "Asynchronous and State Change IOCTLS"
871 .ne 2
872 .na
873 \fB\fBMTIOCSTATE\fR\fR
874 .ad
875 .RS 14n
876 This ioctl blocks until the state of the drive, inserted or ejected, is
877 changed. The argument is a pointer to a \fBmtio_state\fR, \fBenum\fR, whose
878 possible enumerations are listed below. The initial value should be either the
879 last reported state of the drive, or \fBMTIO_NONE\fR. Upon return, the
880 \fBenum\fR pointed to by the argument is updated with the current state of the
881 drive.
882 .RE
883
884 .sp
885 .in +2
886 .nf
887 enum mtio_state {
888 MTIO_NONE /* Return tape's current state */
889 MTIO_EJECTED /* Tape state is "ejected" */
890 MTIO_INSERTED /* Tape state is "inserted" */
891 ;
892 .fi
893 .in -2
894
895 .sp
896 .LP
897 When using asynchronous operations, most ioctls will wait for all outstanding
898 commands to complete before they are executed.
899 .SS "IOCTLS for Multi-initiator Configurations"
900 .ne 2
901 .na
902 \fBMTIOCRESERVE\fR
903 .ad
904 .RS 21n
905 reserve the tape drive
906 .RE
907
908 .sp
909 .ne 2
910 .na
911 \fBMTIOCRELEASE\fR
912 .ad
913 .RS 21n
914 revert back to the default behavior of reserve on open/release on close
915 .RE
916
917 .sp
918 .ne 2
919 .na
920 \fBMTIOCFORCERESERVE\fR
921 .ad
922 .RS 21n
923 reserve the tape unit by breaking reservation held by another host
924 .RE
925
926 .sp
927 .LP
928 The \fBMTIOCRESERVE\fR ioctl reserves the tape drive such that it does not
929 release the tape drive at close. This changes the default behavior of releasing
930 the device upon close. Reserving the tape drive that is already reserved has no
931 effect. For example,
932 .sp
933 .LP
934 \fBioctl(fd, MTIOCRESERVE);\fR
935 .sp
936 .LP
937 The \fBMTIOCRELEASE\fR ioctl reverts back to the default behavior of reserve on
938 open/release on close operation, and a release will occur during the next
939 close. Releasing the tape drive that is already released has no effect. For
940 example,
941 .sp
942 .LP
943 \fBioctl(fd, MTIOCRELEASE);\fR
944 .sp
945 .LP
946 The \fBMTIOCFORCERESERVE\fR ioctl breaks a reservation held by another host,
947 interrupting any I/O in progress by that other host, and then reserves the tape
948 unit. This ioctl can be executed only with super-user privileges. It is
949 recommended to open the tape device in \fBO_NDELAY\fR mode when this ioctl
950 needs to be executed, otherwise the open will fail if another host indeed has
951 it reserved. For example,
952 .sp
953 .in +2
954 .nf
955 ioctl(fd, MTIOCFORCERESERVE);
956 .fi
957 .in -2
958
959 .SS "IOCTLS for Handling Tape Configuration Options"
960 .ne 2
961 .na
962 \fBMTIOCSHORTFMK\fR
963 .ad
964 .RS 23n
965 enables/disables support for writing short filemarks. This is specific to
966 Exabyte drives.
967 .RE
968
969 .sp
970 .ne 2
971 .na
972 \fBMTIOCREADIGNOREILI\fR
973 .ad
974 .RS 23n
975 enables/disables suppress incorrect length indicator (SILI) support during reads
976 .RE
977
978 .sp
979 .ne 2
980 .na
981 \fBMTIOCREADIGNOREEOFS\fR
982 .ad
983 .RS 23n
984 enables/disables support for reading past two EOF marks which otherwise indicate
985 End-Of-recording-Media (EOM) in the case of 1/2" reel tape drives
986 .RE
987
988 .sp
989 .LP
990 The \fBMTIOCSHORTFMK\fR ioctl enables or disables support for short filemarks.
991 This ioctl is only applicable to Exabyte drives which support short filemarks.
992 As an argument, it takes a pointer to an integer. If 0 (zero) is the
993 specified integer, then long filemarks will be written. If 1 is the specified
994 integer, then short filemarks will be written. The specified tape behavior will
995 be in effect until the device is closed.
996 .sp
997 .LP
998 For example:
999 .sp
1000 .in +2
1001 .nf
1002 int on = 1;
1003 int off = 0;
1004 /* enable short filemarks */
1005 ioctl(fd, MTIOSHORTFMK, &on);
1006 /* disable short filemarks */
1007 ioctl(fd, MTIOCSHORTFMK, &off);
1008 .fi
1009 .in -2
1010
1011 .sp
1012 .LP
1013 Tape drives which do not support short filemarks will return an \fBerrno\fR of
1014 \fBENOTTY.\fR
1015 .sp
1016 .LP
1017 The \fBMTIOCREADIGNOREILI\fR ioctl enables or disables the suppress incorrect
1018 length indicator (SILI) support during reads. As an argument, it takes a
1019 pointer to an integer. If 0 (zero) is the specified integer, SILI will not be
1020 used during reads and incorrect length indicator will not be suppressed. If 1
1021 is the specified integer, SILI will be used during reads and incorrect length
1022 indicator will be suppressed. The specified tape behavior will be in effect
1023 until the device is closed.
1024 .sp
1025 .LP
1026 For example:
1027 .sp
1028 .in +2
1029 .nf
1030 int on = 1;
1031 int off = 0;
1032 ioctl(fd, MTIOREADIGNOREILI, &on);
1033 ioctl(fd, MTIOREADIGNOREILI, &off);
1034 .fi
1035 .in -2
1036
1037 .sp
1038 .LP
1039 The \fBMTIOCREADIGNOREEOFS\fR ioctl enables or disables support for reading
1040 past double EOF marks which otherwise indicate End-Of-recorded-media (EOM) in
1041 the case of 1/2" reel tape drives. As an argument, it takes a pointer to an
1042 integer. If 0 (zero) is the specified integer, then double EOF marks indicate
1043 End-Of-recodred-media (EOD). If 1 is the specified integer, the double EOF
1044 marks no longer indicate EOM, thus allowing applications to read past two EOF
1045 marks. In this case it is the responsibility of the application to detect
1046 end-of-recorded-media (EOM). The specified tape behavior will be in effect
1047 until the device is closed.
1048 .sp
1049 .LP
1050 For example:
1051 .sp
1052 .in +2
1053 .nf
1054 int on = 1;
1055 int off = 0;
1056 ioctl(fd, MTIOREADIGNOREEOFS, &on);
1057 ioctl(fd, MTIOREADIGNOREEOFS, &off);
1058 .fi
1059 .in -2
1060
1061 .sp
1062 .LP
1063 Tape drives other than 1/2" reel tapes will return an \fBerrno\fR of
1064 \fBENOTTY.\fR
1065 .SH EXAMPLES
1066 .LP
1067 \fBExample 1 \fRTape Positioning and Tape Drives
1068 .sp
1069 .LP
1070 Suppose you have written three files to the non-rewinding 1/2" tape device,
1071 \fB/dev/rmt/0ln,\fR and that you want to go back and \fBdd\fR(1M) the second
1072 file off the tape. The commands to do this are:
1073
1074 .sp
1075 .in +2
1076 .nf
1077 mt \fB-F\fR /dev/rmt/0lbn bsf 3
1078 mt \fB-F\fR /dev/rmt/0lbn fsf 1
1079 dd if=/dev/rmt/0ln
1080 .fi
1081 .in -2
1082
1083 .sp
1084 .LP
1085 To accomplish the same tape positioning in a C program, followed by a get
1086 status ioctl:
1087
1088 .sp
1089 .in +2
1090 .nf
1091 struct mtop mt_command;
1092 struct mtget mt_status;
1093 mt_command.mt_op = MTBSF;
1094 mt_command.mt_count = 3;
1095 ioctl(fd, MTIOCTOP, &mt_command);
1096 mt_command.mt_op = MTFSF;
1097 mt_command.mt_count = 1;
1098 ioctl(fd, MTIOCTOP, &mt_command);
1099 ioctl(fd, MTIOCGET, (char *)&mt_status);
1100 .fi
1101 .in -2
1102
1103 .sp
1104 .LP
1105 or
1106
1107 .sp
1108 .in +2
1109 .nf
1110 mt_command.mt_op = MTNBSF;
1111 mt_command.mt_count = 2;
1112 ioctl(fd, MTIOCTOP, &mt_command);
1113 ioctl(fd, MTIOCGET, (char *)&mt_status);
1114 .fi
1115 .in -2
1116
1117 .sp
1118 .LP
1119 To get information about the tape drive:
1120
1121 .sp
1122 .in +2
1123 .nf
1124 struct mtdrivetype mtdt;
1125 struct mtdrivetype_request mtreq;
1126 mtreq.size = sizeof(struct mtdrivetype);
1127 mtreq.mtdtp = &mtdt;
1128 ioctl(fd, MTIOCGETDRIVETYPE, &mtreq);
1129 .fi
1130 .in -2
1131
1132 .SH FILES
1133 .LP
1134 \fB/dev/rmt/\fR\fI<unit number><density>\fR[\fI<BSD behavior>\fR][\fI<no
1135 rewind>\fR]
1136 .sp
1137 .LP
1138 Where \fIdensity\fR can be \fBl,\fR \fBm,\fR \fBh,\fR \fBu/c\fR (low, medium,
1139 high, ultra/compressed, respectively), the \fIBSD behavior \fR option is
1140 \fBb\fR, and the \fIno rewind \fR option is \fBn\fR.
1141 .sp
1142 .LP
1143 For example, \fB/dev/rmt/0hbn\fR specifies unit 0, high density, \fBBSD\fR
1144 behavior and no rewind.
1145 .SH SEE ALSO
1146 .LP
1147 \fBmt\fR(1), \fBtar\fR(1), \fBdd\fR(1M), \fBopen\fR(2), \fBread\fR(2),
1148 \fBwrite\fR(2), \fBaioread\fR(3C), \fBaiowrite\fR(3C), \fBar.h\fR(3HEAD),
1149 \fBst\fR(7D)
1150 .sp
1151 .LP
1152 \fI1/4 Inch Tape Drive Tutorial\fR