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