]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright 1995 Robert K. Nichols (Robert.K.Nichols@att.com) | |
2 | .\" Copyright 1999-2005 Kai Mäkisara (Kai.Makisara@kolumbus.fi) | |
3 | .\" | |
4 | .\" %%%LICENSE_START(VERBATIM) | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" %%%LICENSE_END | |
25 | .TH ST 4 2020-04-11 "Linux" "Linux Programmer's Manual" | |
26 | .SH NAME | |
27 | st \- SCSI tape device | |
28 | .SH SYNOPSIS | |
29 | .nf | |
30 | .B #include <sys/mtio.h> | |
31 | .PP | |
32 | .BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);" | |
33 | .BI "int ioctl(int " fd ", MTIOCTOP, (struct mtop *)" mt_cmd ); | |
34 | .BI "int ioctl(int " fd ", MTIOCGET, (struct mtget *)" mt_status ); | |
35 | .BI "int ioctl(int " fd ", MTIOCPOS, (struct mtpos *)" mt_pos ); | |
36 | .fi | |
37 | .SH DESCRIPTION | |
38 | The | |
39 | .B st | |
40 | driver provides the interface to a variety of SCSI tape devices. | |
41 | Currently, the driver takes control of all detected devices of type | |
42 | \(lqsequential-access\(rq. | |
43 | The | |
44 | .B st | |
45 | driver uses major device number 9. | |
46 | .PP | |
47 | Each device uses eight minor device numbers. | |
48 | The lowermost five bits | |
49 | in the minor numbers are assigned sequentially in the order of | |
50 | detection. | |
51 | In the 2.6 kernel, the bits above the eight lowermost bits are | |
52 | concatenated to the five lowermost bits to form the tape number. | |
53 | The minor numbers can be grouped into | |
54 | two sets of four numbers: the principal (auto-rewind) minor device numbers, | |
55 | .IR n , | |
56 | and the \(lqno-rewind\(rq device numbers, | |
57 | .RI ( n " + 128)." | |
58 | Devices opened using the principal device number will be sent a | |
59 | .BR REWIND | |
60 | command when they are closed. | |
61 | Devices opened using the \(lqno-rewind\(rq device number will not. | |
62 | (Note that using an auto-rewind device for positioning the tape with, | |
63 | for instance, mt does not lead to the desired result: the tape is | |
64 | rewound after the mt command and the next command starts from the | |
65 | beginning of the tape). | |
66 | .PP | |
67 | Within each group, four minor numbers are available to define | |
68 | devices with different characteristics (block size, compression, | |
69 | density, etc.) | |
70 | When the system starts up, only the first device is available. | |
71 | The other three are activated when the default | |
72 | characteristics are defined (see below). | |
73 | (By changing compile-time | |
74 | constants, it is possible to change the balance between the maximum | |
75 | number of tape drives and the number of minor numbers for each | |
76 | drive. | |
77 | The default allocation allows control of 32 tape drives. | |
78 | For instance, it is possible to control up to 64 tape drives | |
79 | with two minor numbers for different options.) | |
80 | .PP | |
81 | Devices are typically created by: | |
82 | .PP | |
83 | .in +4n | |
84 | .EX | |
85 | mknod \-m 666 /dev/st0 c 9 0 | |
86 | mknod \-m 666 /dev/st0l c 9 32 | |
87 | mknod \-m 666 /dev/st0m c 9 64 | |
88 | mknod \-m 666 /dev/st0a c 9 96 | |
89 | mknod \-m 666 /dev/nst0 c 9 128 | |
90 | mknod \-m 666 /dev/nst0l c 9 160 | |
91 | mknod \-m 666 /dev/nst0m c 9 192 | |
92 | mknod \-m 666 /dev/nst0a c 9 224 | |
93 | .EE | |
94 | .in | |
95 | .PP | |
96 | There is no corresponding block device. | |
97 | .PP | |
98 | The driver uses an internal buffer that has to be large enough to hold | |
99 | at least one tape block. | |
100 | In kernels before 2.1.121, the buffer is | |
101 | allocated as one contiguous block. | |
102 | This limits the block size to the | |
103 | largest contiguous block of memory the kernel allocator can provide. | |
104 | The limit is currently 128\ kB for 32-bit architectures and | |
105 | 256\ kB for 64-bit architectures. | |
106 | In newer kernels the driver | |
107 | allocates the buffer in several parts if necessary. | |
108 | By default, the | |
109 | maximum number of parts is 16. | |
110 | This means that the maximum block size | |
111 | is very large (2\ MB if allocation of 16 blocks of 128\ kB succeeds). | |
112 | .PP | |
113 | The driver's internal buffer size is determined by a compile-time | |
114 | constant which can be overridden with a kernel startup option. | |
115 | In addition to this, the driver tries to allocate a larger temporary | |
116 | buffer at run time if necessary. | |
117 | However, run-time allocation of large | |
118 | contiguous blocks of memory may fail and it is advisable not to rely | |
119 | too much on dynamic buffer allocation with kernels older than 2.1.121 | |
120 | (this applies also to demand-loading the driver with kerneld or kmod). | |
121 | .PP | |
122 | The driver does not specifically support any tape drive brand or | |
123 | model. | |
124 | After system start-up the tape device options are defined by | |
125 | the drive firmware. | |
126 | For example, if the drive firmware selects fixed-block mode, | |
127 | the tape device uses fixed-block mode. | |
128 | The options can | |
129 | be changed with explicit | |
130 | .BR ioctl (2) | |
131 | calls and remain in effect when the device is closed and reopened. | |
132 | Setting the options affects both the auto-rewind and the nonrewind | |
133 | device. | |
134 | .PP | |
135 | Different options can be specified for the different devices within | |
136 | the subgroup of four. | |
137 | The options take effect when the device is | |
138 | opened. | |
139 | For example, the system administrator can define | |
140 | one device that writes in fixed-block mode with a certain block size, | |
141 | and one which writes in variable-block mode (if the drive supports | |
142 | both modes). | |
143 | .PP | |
144 | The driver supports | |
145 | .B tape partitions | |
146 | if they are supported by the drive. | |
147 | (Note that the tape partitions | |
148 | have nothing to do with disk partitions. | |
149 | A partitioned tape can be | |
150 | seen as several logical tapes within one medium.) | |
151 | Partition support has to be enabled with an | |
152 | .BR ioctl (2). | |
153 | The tape | |
154 | location is preserved within each partition across partition changes. | |
155 | The partition used for subsequent tape operations is | |
156 | selected with an | |
157 | .BR ioctl (2). | |
158 | The partition switch is executed together with | |
159 | the next tape operation in order to avoid unnecessary tape | |
160 | movement. | |
161 | The maximum number of partitions on a tape is defined by a | |
162 | compile-time constant (originally four). | |
163 | The driver contains an | |
164 | .BR ioctl (2) | |
165 | that can format a tape with either one or two partitions. | |
166 | .PP | |
167 | Device | |
168 | .I /dev/tape | |
169 | is usually created as a hard or soft link to the default tape device | |
170 | on the system. | |
171 | .PP | |
172 | Starting from kernel 2.6.2, the driver exports in the sysfs directory | |
173 | .I /sys/class/scsi_tape | |
174 | the attached devices and some parameters assigned to the devices. | |
175 | .SS Data transfer | |
176 | The driver supports operation in both fixed-block mode and | |
177 | variable-block mode (if supported by the drive). | |
178 | In fixed-block mode the drive | |
179 | writes blocks of the specified size and the block size is not | |
180 | dependent on the byte counts of the write system calls. | |
181 | In variable-block mode one tape block is written for each write call | |
182 | and the byte | |
183 | count determines the size of the corresponding tape block. | |
184 | Note that | |
185 | the blocks on the tape don't contain any information about the | |
186 | writing mode: when reading, the only important thing is to use | |
187 | commands that accept the block sizes on the tape. | |
188 | .PP | |
189 | In variable-block mode the read byte count does not have to match | |
190 | the tape block size exactly. | |
191 | If the byte count is larger than the | |
192 | next block on tape, the driver returns the data and the function | |
193 | returns the actual block size. | |
194 | If the block size is larger than the | |
195 | byte count, an error is returned. | |
196 | .PP | |
197 | In fixed-block mode the read byte counts can be arbitrary if | |
198 | buffering is enabled, or a multiple of the tape block size if | |
199 | buffering is disabled. | |
200 | Kernels before 2.1.121 allow writes with | |
201 | arbitrary byte count if buffering is enabled. | |
202 | In all other cases | |
203 | (kernel before 2.1.121 with buffering disabled or newer kernel) the | |
204 | write byte count must be a multiple of the tape block size. | |
205 | .PP | |
206 | In the 2.6 kernel, the driver tries to use direct transfers between the user | |
207 | buffer and the device. | |
208 | If this is not possible, the driver's internal buffer | |
209 | is used. | |
210 | The reasons for not using direct transfers include improper alignment | |
211 | of the user buffer (default is 512 bytes but this can be changed by the HBA | |
212 | driver), one or more pages of the user buffer not reachable by the | |
213 | SCSI adapter, and so on. | |
214 | .PP | |
215 | A filemark is automatically written to tape if the last tape operation | |
216 | before close was a write. | |
217 | .PP | |
218 | When a filemark is encountered while reading, the following | |
219 | happens. | |
220 | If there are data remaining in the buffer when the filemark | |
221 | is found, the buffered data is returned. | |
222 | The next read returns zero | |
223 | bytes. | |
224 | The following read returns data from the next file. | |
225 | The end of | |
226 | recorded data is signaled by returning zero bytes for two consecutive | |
227 | read calls. | |
228 | The third read returns an error. | |
229 | .SS Ioctls | |
230 | The driver supports three | |
231 | .BR ioctl (2) | |
232 | requests. | |
233 | Requests not recognized by the | |
234 | .B st | |
235 | driver are passed to the | |
236 | .B SCSI | |
237 | driver. | |
238 | The definitions below are from | |
239 | .IR /usr/include/linux/mtio.h : | |
240 | .SS MTIOCTOP \(em perform a tape operation | |
241 | .PP | |
242 | This request takes an argument of type | |
243 | .IR "(struct mtop\ *)" . | |
244 | Not all drives support all operations. | |
245 | The driver returns an | |
246 | .B EIO | |
247 | error if the drive rejects an operation. | |
248 | .PP | |
249 | .in +4n | |
250 | .EX | |
251 | /* Structure for MTIOCTOP \- mag tape op command: */ | |
252 | struct mtop { | |
253 | short mt_op; /* operations defined below */ | |
254 | int mt_count; /* how many of them */ | |
255 | }; | |
256 | .EE | |
257 | .in | |
258 | .PP | |
259 | Magnetic tape operations for normal tape use: | |
260 | .TP | |
261 | .B MTBSF | |
262 | Backward space over | |
263 | .I mt_count | |
264 | filemarks. | |
265 | .TP | |
266 | .B MTBSFM | |
267 | Backward space over | |
268 | .I mt_count | |
269 | filemarks. | |
270 | Reposition the tape to the EOT side of the last filemark. | |
271 | .TP | |
272 | .B MTBSR | |
273 | Backward space over | |
274 | .I mt_count | |
275 | records (tape blocks). | |
276 | .TP | |
277 | .B MTBSS | |
278 | Backward space over | |
279 | .I mt_count | |
280 | setmarks. | |
281 | .TP | |
282 | .B MTCOMPRESSION | |
283 | Enable compression of tape data within the drive if | |
284 | .I mt_count | |
285 | is nonzero and disable compression if | |
286 | .I mt_count | |
287 | is zero. | |
288 | This command uses the MODE page 15 supported by most DATs. | |
289 | .TP | |
290 | .B MTEOM | |
291 | Go to the end of the recorded media (for appending files). | |
292 | .TP | |
293 | .B MTERASE | |
294 | Erase tape. | |
295 | With 2.6 kernel, short erase (mark tape empty) is performed if the | |
296 | argument is zero. | |
297 | Otherwise, long erase (erase all) is done. | |
298 | .TP | |
299 | .B MTFSF | |
300 | Forward space over | |
301 | .I mt_count | |
302 | filemarks. | |
303 | .TP | |
304 | .B MTFSFM | |
305 | Forward space over | |
306 | .I mt_count | |
307 | filemarks. | |
308 | Reposition the tape to the BOT side of the last filemark. | |
309 | .TP | |
310 | .B MTFSR | |
311 | Forward space over | |
312 | .I mt_count | |
313 | records (tape blocks). | |
314 | .TP | |
315 | .B MTFSS | |
316 | Forward space over | |
317 | .I mt_count | |
318 | setmarks. | |
319 | .TP | |
320 | .B MTLOAD | |
321 | Execute the SCSI load command. | |
322 | A special case is available for some HP | |
323 | autoloaders. | |
324 | If | |
325 | .I mt_count | |
326 | is the constant | |
327 | .B MT_ST_HPLOADER_OFFSET | |
328 | plus a number, the number is | |
329 | sent to the drive to control the autoloader. | |
330 | .TP | |
331 | .B MTLOCK | |
332 | Lock the tape drive door. | |
333 | .TP | |
334 | .B MTMKPART | |
335 | Format the tape into one or two partitions. | |
336 | If | |
337 | .I mt_count | |
338 | is positive, it gives the size of partition 1 and partition | |
339 | 0 contains the rest of the tape. | |
340 | If | |
341 | .I mt_count | |
342 | is zero, the tape is formatted into one partition. | |
343 | From kernel version 4.6, | |
344 | .\" commit 8038e6456a3e6f5c4759e0d73c4f9165b90c93e7 | |
345 | a negative | |
346 | .I mt_count | |
347 | specifies the size of partition 0 and | |
348 | the rest of the tape contains partition 1. | |
349 | The physical ordering of partitions depends on the drive. | |
350 | This command is not allowed for a drive unless the partition support | |
351 | is enabled for the drive (see | |
352 | .BR MT_ST_CAN_PARTITIONS | |
353 | below). | |
354 | .TP | |
355 | .B MTNOP | |
356 | No op\(emflushes the driver's buffer as a side effect. | |
357 | Should be used before reading status with | |
358 | .BR MTIOCGET . | |
359 | .TP | |
360 | .B MTOFFL | |
361 | Rewind and put the drive off line. | |
362 | .TP | |
363 | .B MTRESET | |
364 | Reset drive. | |
365 | .TP | |
366 | .B MTRETEN | |
367 | Re-tension tape. | |
368 | .TP | |
369 | .B MTREW | |
370 | Rewind. | |
371 | .TP | |
372 | .B MTSEEK | |
373 | Seek to the tape block number specified in | |
374 | .IR mt_count . | |
375 | This operation requires either a SCSI-2 drive that supports the | |
376 | .B LOCATE | |
377 | command (device-specific address) | |
378 | or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive | |
379 | Viper, Wangtek, ...). | |
380 | The block number should be one that was previously returned by | |
381 | .BR MTIOCPOS | |
382 | if device-specific addresses are used. | |
383 | .TP | |
384 | .B MTSETBLK | |
385 | Set the drive's block length to the value specified in | |
386 | .IR mt_count . | |
387 | A block length of zero sets the drive to variable block size mode. | |
388 | .TP | |
389 | .B MTSETDENSITY | |
390 | Set the tape density to the code in | |
391 | .IR mt_count . | |
392 | The density codes supported by a drive can be found from the drive | |
393 | documentation. | |
394 | .TP | |
395 | .B MTSETPART | |
396 | The active partition is switched to | |
397 | .IR mt_count . | |
398 | The partitions are numbered from zero. | |
399 | This command is not allowed for | |
400 | a drive unless the partition support is enabled for the drive (see | |
401 | .B MT_ST_CAN_PARTITIONS | |
402 | below). | |
403 | .TP | |
404 | .B MTUNLOAD | |
405 | Execute the SCSI unload command (does not eject the tape). | |
406 | .TP | |
407 | .B MTUNLOCK | |
408 | Unlock the tape drive door. | |
409 | .TP | |
410 | .B MTWEOF | |
411 | Write | |
412 | .I mt_count | |
413 | filemarks. | |
414 | .TP | |
415 | .B MTWSM | |
416 | Write | |
417 | .I mt_count | |
418 | setmarks. | |
419 | .PP | |
420 | Magnetic tape operations for setting of device options (by the superuser): | |
421 | .TP | |
422 | .B MTSETDRVBUFFER | |
423 | Set various drive and driver options according to bits encoded in | |
424 | .IR mt_count . | |
425 | These consist of the drive's buffering mode, a set of Boolean driver | |
426 | options, the buffer write threshold, defaults for the block size and | |
427 | density, and timeouts (only in kernels 2.1 and later). | |
428 | A single operation can affect only one item in the list below (the | |
429 | Booleans counted as one item.) | |
430 | .IP | |
431 | A value having zeros in the high-order 4 bits will be used to set the | |
432 | drive's buffering mode. | |
433 | The buffering modes are: | |
434 | .RS 12 | |
435 | .IP 0 4 | |
436 | The drive will not report | |
437 | .BR GOOD | |
438 | status on write commands until the data | |
439 | blocks are actually written to the medium. | |
440 | .IP 1 | |
441 | The drive may report | |
442 | .BR GOOD | |
443 | status on write commands as soon as all the | |
444 | data has been transferred to the drive's internal buffer. | |
445 | .IP 2 | |
446 | The drive may report | |
447 | .BR GOOD | |
448 | status on write commands as soon as (a) all | |
449 | the data has been transferred to the drive's internal buffer, and | |
450 | (b) all buffered data from different initiators has been successfully | |
451 | written to the medium. | |
452 | .RE | |
453 | .IP | |
454 | To control the write threshold the value in | |
455 | .I mt_count | |
456 | must include the constant | |
457 | .BR MT_ST_WRITE_THRESHOLD | |
458 | bitwise ORed with a block count in the low 28 bits. | |
459 | The block count refers to 1024-byte blocks, not the physical block | |
460 | size on the tape. | |
461 | The threshold cannot exceed the driver's internal buffer size (see | |
462 | DESCRIPTION, above). | |
463 | .IP | |
464 | To set and clear the Boolean options | |
465 | the value in | |
466 | .I mt_count | |
467 | must include one of the constants | |
468 | .BR MT_ST_BOOLEANS , | |
469 | .BR MT_ST_SETBOOLEANS , | |
470 | .BR MT_ST_CLEARBOOLEANS , | |
471 | or | |
472 | .BR MT_ST_DEFBOOLEANS | |
473 | bitwise ORed with | |
474 | whatever combination of the following options is desired. | |
475 | Using | |
476 | .BR MT_ST_BOOLEANS | |
477 | the options can be set to the values | |
478 | defined in the corresponding bits. | |
479 | With | |
480 | .BR MT_ST_SETBOOLEANS | |
481 | the options can be selectively set and with | |
482 | .BR MT_ST_DEFBOOLEANS | |
483 | selectively cleared. | |
484 | .IP "" | |
485 | The default options for a tape device are set with | |
486 | .BR MT_ST_DEFBOOLEANS . | |
487 | A nonactive tape device (e.g., device with | |
488 | minor 32 or 160) is activated when the default options for it are | |
489 | defined the first time. | |
490 | An activated device inherits from the device | |
491 | activated at start-up the options not set explicitly. | |
492 | .IP "" | |
493 | The Boolean options are: | |
494 | .RS | |
495 | .TP | |
496 | .BR MT_ST_BUFFER_WRITES " (Default: true)" | |
497 | Buffer all write operations in fixed-block mode. | |
498 | If this option is false and the drive uses a fixed block size, then | |
499 | all write operations must be for a multiple of the block size. | |
500 | This option must be set false to write reliable multivolume archives. | |
501 | .TP | |
502 | .BR MT_ST_ASYNC_WRITES " (Default: true)" | |
503 | When this option is true, write operations return immediately without | |
504 | waiting for the data to be transferred to the drive if the data fits | |
505 | into the driver's buffer. | |
506 | The write threshold determines how full the buffer must be before a | |
507 | new SCSI write command is issued. | |
508 | Any errors reported by the drive will be held until the next | |
509 | operation. | |
510 | This option must be set false to write reliable multivolume archives. | |
511 | .TP | |
512 | .BR MT_ST_READ_AHEAD " (Default: true)" | |
513 | This option causes the driver to provide read buffering and | |
514 | read-ahead in fixed-block mode. | |
515 | If this option is false and the drive uses a fixed block size, then | |
516 | all read operations must be for a multiple of the block size. | |
517 | .TP | |
518 | .BR MT_ST_TWO_FM " (Default: false)" | |
519 | This option modifies the driver behavior when a file is closed. | |
520 | The normal action is to write a single filemark. | |
521 | If the option is true, the driver will write two filemarks and | |
522 | backspace over the second one. | |
523 | .IP | |
524 | Note: | |
525 | This option should not be set true for QIC tape drives since they are | |
526 | unable to overwrite a filemark. | |
527 | These drives detect the end of recorded data by testing for blank tape | |
528 | rather than two consecutive filemarks. | |
529 | Most other current drives also | |
530 | detect the end of recorded data and using two filemarks is usually | |
531 | necessary only when interchanging tapes with some other systems. | |
532 | .TP | |
533 | .BR MT_ST_DEBUGGING " (Default: false)" | |
534 | This option turns on various debugging messages from the driver | |
535 | (effective only if the driver was compiled with | |
536 | .B DEBUG | |
537 | defined nonzero). | |
538 | .TP | |
539 | .BR MT_ST_FAST_EOM " (Default: false)" | |
540 | This option causes the | |
541 | .B MTEOM | |
542 | operation to be sent directly to the | |
543 | drive, potentially speeding up the operation but causing the driver to | |
544 | lose track of the current file number normally returned by the | |
545 | .B MTIOCGET | |
546 | request. | |
547 | If | |
548 | .B MT_ST_FAST_EOM | |
549 | is false, the driver will respond to an | |
550 | .B MTEOM | |
551 | request by forward spacing over files. | |
552 | .TP | |
553 | .BR MT_ST_AUTO_LOCK " (Default: false)" | |
554 | When this option is true, the drive door is locked when the device file is | |
555 | opened and unlocked when it is closed. | |
556 | .TP | |
557 | .BR MT_ST_DEF_WRITES " (Default: false)" | |
558 | The tape options (block size, mode, compression, etc.) may change | |
559 | when changing from one device linked to a drive to another device | |
560 | linked to the same drive depending on how the devices are | |
561 | defined. | |
562 | This option defines when the changes are enforced by the | |
563 | driver using SCSI-commands and when the drives auto-detection | |
564 | capabilities are relied upon. | |
565 | If this option is false, the driver | |
566 | sends the SCSI-commands immediately when the device is changed. | |
567 | If the | |
568 | option is true, the SCSI-commands are not sent until a write is | |
569 | requested. | |
570 | In this case, the drive firmware is allowed to detect the | |
571 | tape structure when reading and the SCSI-commands are used only to | |
572 | make sure that a tape is written according to the correct specification. | |
573 | .TP | |
574 | .BR MT_ST_CAN_BSR " (Default: false)" | |
575 | When read-ahead is used, the tape must sometimes be spaced backward to the | |
576 | correct position when the device is closed and the SCSI command to | |
577 | space backward over records is used for this purpose. | |
578 | Some older | |
579 | drives can't process this command reliably and this option can be used | |
580 | to instruct the driver not to use the command. | |
581 | The end result is that, | |
582 | with read-ahead and fixed-block mode, the tape may not be correctly | |
583 | positioned within a file when the device is closed. | |
584 | With 2.6 kernel, the | |
585 | default is true for drives supporting SCSI-3. | |
586 | .TP | |
587 | .BR MT_ST_NO_BLKLIMS " (Default: false)" | |
588 | Some drives don't accept the | |
589 | .B "READ BLOCK LIMITS" | |
590 | SCSI command. | |
591 | If this is used, the driver does not use the command. | |
592 | The drawback is | |
593 | that the driver can't check before sending commands if the selected | |
594 | block size is acceptable to the drive. | |
595 | .TP | |
596 | .BR MT_ST_CAN_PARTITIONS " (Default: false)" | |
597 | This option enables support for several partitions within a | |
598 | tape. | |
599 | The option applies to all devices linked to a drive. | |
600 | .TP | |
601 | .BR MT_ST_SCSI2LOGICAL " (Default: false)" | |
602 | This option instructs the driver to use the logical block addresses | |
603 | defined in the SCSI-2 standard when performing the seek and tell | |
604 | operations (both with | |
605 | .B MTSEEK | |
606 | and | |
607 | .B MTIOCPOS | |
608 | commands and when changing tape | |
609 | partition). | |
610 | Otherwise, the device-specific addresses are used. | |
611 | It is highly advisable to set this option if the drive supports the | |
612 | logical addresses because they count also filemarks. | |
613 | There are some | |
614 | drives that support only the logical block addresses. | |
615 | .TP | |
616 | .BR MT_ST_SYSV " (Default: false)" | |
617 | When this option is enabled, the tape devices use the System V | |
618 | semantics. | |
619 | Otherwise, the BSD semantics are used. | |
620 | The most important | |
621 | difference between the semantics is what happens when a device used | |
622 | for reading is closed: in System V semantics the tape is spaced forward | |
623 | past the next filemark if this has not happened while using the | |
624 | device. | |
625 | In BSD semantics the tape position is not changed. | |
626 | .TP | |
627 | .BR MT_NO_WAIT " (Default: false)" | |
628 | Enables immediate mode (i.e., don't wait for the command to finish) for some | |
629 | commands (e.g., rewind). | |
630 | .PP | |
631 | An example: | |
632 | .PP | |
633 | .in +4n | |
634 | .EX | |
635 | struct mtop mt_cmd; | |
636 | mt_cmd.mt_op = MTSETDRVBUFFER; | |
637 | mt_cmd.mt_count = MT_ST_BOOLEANS | | |
638 | MT_ST_BUFFER_WRITES | MT_ST_ASYNC_WRITES; | |
639 | ioctl(fd, MTIOCTOP, mt_cmd); | |
640 | .EE | |
641 | .in | |
642 | .RE | |
643 | .IP "" | |
644 | The default block size for a device can be set with | |
645 | .B MT_ST_DEF_BLKSIZE | |
646 | and the default density code can be set with | |
647 | .BR MT_ST_DEFDENSITY . | |
648 | The values for the parameters are or'ed | |
649 | with the operation code. | |
650 | .IP "" | |
651 | With kernels 2.1.x and later, the timeout values can be set with the | |
652 | subcommand | |
653 | .B MT_ST_SET_TIMEOUT | |
654 | ORed with the timeout in seconds. | |
655 | The long timeout (used for rewinds and other commands | |
656 | that may take a long time) can be set with | |
657 | .BR MT_ST_SET_LONG_TIMEOUT . | |
658 | The kernel defaults are very long to | |
659 | make sure that a successful command is not timed out with any | |
660 | drive. | |
661 | Because of this, the driver may seem stuck even if it is only | |
662 | waiting for the timeout. | |
663 | These commands can be used to set more | |
664 | practical values for a specific drive. | |
665 | The timeouts set for one device | |
666 | apply for all devices linked to the same drive. | |
667 | .IP "" | |
668 | Starting from kernels 2.4.19 and 2.5.43, the driver supports a status | |
669 | bit which indicates whether the drive requests cleaning. | |
670 | The method used by the | |
671 | drive to return cleaning information is set using the | |
672 | .B MT_ST_SEL_CLN | |
673 | subcommand. | |
674 | If the value is zero, the cleaning | |
675 | bit is always zero. | |
676 | If the value is one, the TapeAlert data defined | |
677 | in the SCSI-3 standard is used (not yet implemented). | |
678 | Values 2\(en17 are | |
679 | reserved. | |
680 | If the lowest eight bits are >= 18, bits from the extended | |
681 | sense data are used. | |
682 | The bits 9\(en16 specify a mask to select the bits | |
683 | to look at and the bits 17\(en23 specify the bit pattern to look for. | |
684 | If the bit pattern is zero, one or more bits under the mask indicate | |
685 | the cleaning request. | |
686 | If the pattern is nonzero, the pattern must match | |
687 | the masked sense data byte. | |
688 | .SS MTIOCGET \(em get status | |
689 | .PP | |
690 | This request takes an argument of type | |
691 | .IR "(struct mtget\ *)" . | |
692 | .PP | |
693 | .in +4n | |
694 | .EX | |
695 | /* structure for MTIOCGET \- mag tape get status command */ | |
696 | struct mtget { | |
697 | long mt_type; | |
698 | long mt_resid; | |
699 | /* the following registers are device dependent */ | |
700 | long mt_dsreg; | |
701 | long mt_gstat; | |
702 | long mt_erreg; | |
703 | /* The next two fields are not always used */ | |
704 | daddr_t mt_fileno; | |
705 | daddr_t mt_blkno; | |
706 | }; | |
707 | .EE | |
708 | .in | |
709 | .TP | |
710 | \fImt_type\fP | |
711 | The header file defines many values for | |
712 | .IR mt_type , | |
713 | but the current driver reports only the generic types | |
714 | .B MT_ISSCSI1 | |
715 | (Generic SCSI-1 tape) | |
716 | and | |
717 | .B MT_ISSCSI2 | |
718 | (Generic SCSI-2 tape). | |
719 | .TP | |
720 | \fImt_resid\fP | |
721 | contains the current tape partition number. | |
722 | .TP | |
723 | \fImt_dsreg\fP | |
724 | reports the drive's current settings for block size (in the low 24 | |
725 | bits) and density (in the high 8 bits). | |
726 | These fields are defined by | |
727 | .BR MT_ST_BLKSIZE_SHIFT , | |
728 | .BR MT_ST_BLKSIZE_MASK , | |
729 | .BR MT_ST_DENSITY_SHIFT , | |
730 | and | |
731 | .BR MT_ST_DENSITY_MASK . | |
732 | .TP | |
733 | \fImt_gstat\fP | |
734 | reports generic (device independent) status information. | |
735 | The header file defines macros for testing these status bits: | |
736 | .RS | |
737 | .HP 4 | |
738 | \fBGMT_EOF\fP(\fIx\fP): | |
739 | The tape is positioned just after a filemark | |
740 | (always false after an | |
741 | .B MTSEEK | |
742 | operation). | |
743 | .HP | |
744 | \fBGMT_BOT\fP(\fIx\fP): | |
745 | The tape is positioned at the beginning of the first file (always false | |
746 | after an | |
747 | .B MTSEEK | |
748 | operation). | |
749 | .HP | |
750 | \fBGMT_EOT\fP(\fIx\fP): | |
751 | A tape operation has reached the physical End Of Tape. | |
752 | .HP | |
753 | \fBGMT_SM\fP(\fIx\fP): | |
754 | The tape is currently positioned at a setmark | |
755 | (always false after an | |
756 | .B MTSEEK | |
757 | operation). | |
758 | .HP | |
759 | \fBGMT_EOD\fP(\fIx\fP): | |
760 | The tape is positioned at the end of recorded data. | |
761 | .HP | |
762 | \fBGMT_WR_PROT\fP(\fIx\fP): | |
763 | The drive is write-protected. | |
764 | For some drives this can also mean that the drive does not support | |
765 | writing on the current medium type. | |
766 | .HP | |
767 | \fBGMT_ONLINE\fP(\fIx\fP): | |
768 | The last | |
769 | .BR open (2) | |
770 | found the drive with a tape in place and ready for operation. | |
771 | .HP | |
772 | \fBGMT_D_6250\fP(\fIx\fP), \fBGMT_D_1600\fP(\fIx\fP), \fBGMT_D_800\fP(\fIx\fP): | |
773 | This \(lqgeneric\(rq status information reports the current | |
774 | density setting for 9-track \(12" tape drives only. | |
775 | .HP | |
776 | \fBGMT_DR_OPEN\fP(\fIx\fP): | |
777 | The drive does not have a tape in place. | |
778 | .HP | |
779 | \fBGMT_IM_REP_EN\fP(\fIx\fP): | |
780 | Immediate report mode. | |
781 | This bit is set if there are no guarantees that | |
782 | the data has been physically written to the tape when the write call | |
783 | returns. | |
784 | It is set zero only when the driver does not buffer data and | |
785 | the drive is set not to buffer data. | |
786 | .HP | |
787 | \fBGMT_CLN\fP(\fIx\fP): | |
788 | The drive has requested cleaning. | |
789 | Implemented in kernels since 2.4.19 and 2.5.43. | |
790 | .RE | |
791 | .TP | |
792 | \fImt_erreg\fP | |
793 | The only field defined in | |
794 | .I mt_erreg | |
795 | is the recovered error count in the low 16 bits (as defined by | |
796 | .BR MT_ST_SOFTERR_SHIFT | |
797 | and | |
798 | .BR MT_ST_SOFTERR_MASK ). | |
799 | Due to inconsistencies in the way drives report recovered errors, this | |
800 | count is often not maintained (most drives do not by default report | |
801 | soft errors but this can be changed with a SCSI MODE SELECT command). | |
802 | .TP | |
803 | \fImt_fileno\fP | |
804 | reports the current file number (zero-based). | |
805 | This value is set to \-1 when the file number is unknown (e.g., after | |
806 | .BR MTBSS | |
807 | or | |
808 | .BR MTSEEK ). | |
809 | .TP | |
810 | \fImt_blkno\fP | |
811 | reports the block number (zero-based) within the current file. | |
812 | This value is set to \-1 when the block number is unknown (e.g., after | |
813 | .BR MTBSF , | |
814 | .BR MTBSS , | |
815 | or | |
816 | .BR MTSEEK ). | |
817 | .SS MTIOCPOS \(em get tape position | |
818 | .PP | |
819 | This request takes an argument of type | |
820 | .I "(struct mtpos\ *)" | |
821 | and reports the drive's notion of the current tape block number, | |
822 | which is not the same as | |
823 | .I mt_blkno | |
824 | returned by | |
825 | .BR MTIOCGET . | |
826 | This drive must be a SCSI-2 drive that supports the | |
827 | .B "READ POSITION" | |
828 | command (device-specific address) | |
829 | or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive | |
830 | Viper, Wangtek, ... ). | |
831 | .PP | |
832 | .in +4n | |
833 | .EX | |
834 | /* structure for MTIOCPOS \- mag tape get position command */ | |
835 | struct mtpos { | |
836 | long mt_blkno; /* current block number */ | |
837 | }; | |
838 | .EE | |
839 | .in | |
840 | .SH RETURN VALUE | |
841 | .TP | |
842 | .B EACCES | |
843 | An attempt was made to write or erase a write-protected tape. | |
844 | (This error is not detected during | |
845 | .BR open (2).) | |
846 | .TP | |
847 | .B EBUSY | |
848 | The device is already in use or the driver was unable to allocate a | |
849 | buffer. | |
850 | .TP | |
851 | .B EFAULT | |
852 | The command parameters point to memory not belonging to the calling | |
853 | process. | |
854 | .TP | |
855 | .B EINVAL | |
856 | An | |
857 | .BR ioctl (2) | |
858 | had an invalid argument, or a requested block size was invalid. | |
859 | .TP | |
860 | .B EIO | |
861 | The requested operation could not be completed. | |
862 | .TP | |
863 | .B ENOMEM | |
864 | The byte count in | |
865 | .BR read (2) | |
866 | is smaller than the next physical block on the tape. | |
867 | (Before 2.2.18 and 2.4.0 the extra bytes have been | |
868 | .\" Precisely: Linux 2.6.0-test6 | |
869 | silently ignored.) | |
870 | .TP | |
871 | .B ENOSPC | |
872 | A write operation could not be completed because the tape reached | |
873 | end-of-medium. | |
874 | .TP | |
875 | .B ENOSYS | |
876 | Unknown | |
877 | .BR ioctl (2). | |
878 | .TP | |
879 | .B ENXIO | |
880 | During opening, the tape device does not exist. | |
881 | .TP | |
882 | .B EOVERFLOW | |
883 | An attempt was made to read or write a variable-length block that is | |
884 | larger than the driver's internal buffer. | |
885 | .TP | |
886 | .B EROFS | |
887 | Open is attempted with | |
888 | .B O_WRONLY | |
889 | or | |
890 | .B O_RDWR | |
891 | when the tape in the drive is write-protected. | |
892 | .SH FILES | |
893 | .TP | |
894 | .I /dev/st* | |
895 | the auto-rewind SCSI tape devices | |
896 | .TP | |
897 | .I /dev/nst* | |
898 | the nonrewind SCSI tape devices | |
899 | .\" .SH AUTHOR | |
900 | .\" The driver has been written by Kai M\(:akisara (Kai.Makisara@metla.fi) | |
901 | .\" starting from a driver written by Dwayne Forsyth. | |
902 | .\" Several other | |
903 | .\" people have also contributed to the driver. | |
904 | .SH NOTES | |
905 | .IP 1. 4 | |
906 | When exchanging data between systems, both systems have to agree on | |
907 | the physical tape block size. | |
908 | The parameters of a drive after startup | |
909 | are often not the ones most operating systems use with these | |
910 | devices. | |
911 | Most systems use drives in variable-block mode if the drive | |
912 | supports that mode. | |
913 | This applies to most modern drives, including | |
914 | DATs, 8mm helical scan drives, DLTs, etc. | |
915 | It may be advisable to use | |
916 | these drives in variable-block mode also in Linux (i.e., use | |
917 | .B MTSETBLK | |
918 | or | |
919 | .B MTSETDEFBLK | |
920 | at system startup to set the mode), at least when | |
921 | exchanging data with a foreign system. | |
922 | The drawback of | |
923 | this is that a fairly large tape block size has to be used to get | |
924 | acceptable data transfer rates on the SCSI bus. | |
925 | .IP 2. | |
926 | Many programs (e.g., | |
927 | .BR tar (1)) | |
928 | allow the user to specify the blocking | |
929 | factor on the command line. | |
930 | Note that this determines the physical block | |
931 | size on tape only in variable-block mode. | |
932 | .IP 3. | |
933 | In order to use SCSI tape drives, the basic SCSI driver, | |
934 | a SCSI-adapter driver and the SCSI tape driver must be either | |
935 | configured into the kernel or loaded as modules. | |
936 | If the SCSI-tape | |
937 | driver is not present, the drive is recognized but the tape support | |
938 | described in this page is not available. | |
939 | .IP 4. | |
940 | The driver writes error messages to the console/log. | |
941 | The SENSE | |
942 | codes written into some messages are automatically translated to text | |
943 | if verbose SCSI messages are enabled in kernel configuration. | |
944 | .IP 5. | |
945 | The driver's internal buffering allows good throughput in fixed-block | |
946 | mode also with small | |
947 | .BR read (2) | |
948 | and | |
949 | .BR write (2) | |
950 | byte counts. | |
951 | With direct transfers | |
952 | this is not possible and may cause a surprise when moving to the 2.6 | |
953 | kernel. | |
954 | The solution is to tell the software to use larger transfers (often | |
955 | telling it to use larger blocks). | |
956 | If this is not possible, direct transfers can be disabled. | |
957 | .SH SEE ALSO | |
958 | .BR mt (1) | |
959 | .PP | |
960 | The file | |
961 | .I drivers/scsi/README.st | |
962 | or | |
963 | .I Documentation/scsi/st.txt | |
964 | (kernel >= 2.6) in the Linux kernel source tree contains | |
965 | the most recent information about the driver and its configuration | |
966 | possibilities |