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