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