man4/st.4

   1 .\" Copyright 1995 Robert K. Nichols (Robert.K.Nichols@att.com)
   2 .\" Copyright 1999-2005 Kai Mäkisara (Kai.Makisara@kolumbus.fi)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .TH st 4 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 st \- SCSI tape device
   8 .SH SYNOPSIS
   9 .nf
  10 .B #include <sys/mtio.h>
  11 .PP
  12 .BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);"
  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 );
  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
  22 \(lqsequential-access\(rq.
  23 The
  24 .B st
  25 driver uses major device number 9.
  26 .PP
  27 Each device uses eight minor device numbers.
  28 The lowermost five bits
  29 in the minor numbers are assigned sequentially in the order of
  30 detection.
  31 In the 2.6 kernel, the bits above the eight lowermost bits are
  32 concatenated to the five lowermost bits to form the tape number.
  33 The minor numbers can be grouped into
  34 two sets of four numbers: the principal (auto-rewind) minor device numbers,
  35 .IR n ,
  36 and the \(lqno-rewind\(rq device numbers,
  37 .RI ( n " + 128)."
  38 Devices opened using the principal device number will be sent a
  39 .B REWIND
  40 command when they are closed.
  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,
  49 density, etc.)
  50 When the system starts up, only the first device is available.
  51 The other three are activated when the default
  52 characteristics are defined (see below).
  53 (By changing compile-time
  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
  56 drive.
  57 The default allocation allows control of 32 tape drives.
  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:
  62 .PP
  63 .in +4n
  64 .EX
  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
  73 .EE
  74 .in
  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
  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
  83 largest contiguous block of memory the kernel allocator can provide.
  84 The limit is currently 128\ kB for 32-bit architectures and
  85 256\ kB for 64-bit architectures.
  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
  91 is very large (2\ MB if allocation of 16 blocks of 128\ kB succeeds).
  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
  96 buffer at run time if necessary.
  97 However, run-time allocation of large
  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
 103 model.
 104 After system start-up the tape device options are defined by
 105 the drive firmware.
 106 For example, if the drive firmware selects fixed-block mode,
 107 the tape device uses fixed-block mode.
 108 The options can
 109 be changed with explicit
 110 .BR ioctl (2)
 111 calls and remain in effect when the device is closed and reopened.
 112 Setting the options affects both the auto-rewind and the nonrewind
 113 device.
 114 .PP
 115 Different options can be specified for the different devices within
 116 the subgroup of four.
 117 The options take effect when the device is
 118 opened.
 119 For example, the system administrator can define
 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
 122 both modes).
 123 .PP
 124 The driver supports
 125 .B tape partitions
 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
 132 .BR ioctl (2).
 133 The tape
 134 location is preserved within each partition across partition changes.
 135 The partition used for subsequent tape operations is
 136 selected with an
 137 .BR ioctl (2).
 138 The partition switch is executed together with
 139 the next tape operation in order to avoid unnecessary tape
 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
 144 .BR ioctl (2)
 145 that can format a tape with either one or two partitions.
 146 .PP
 147 Device
 148 .I /dev/tape
 149 is usually created as a hard or soft link to the default tape device
 150 on the system.
 151 .PP
 152 Starting from kernel 2.6.2, the driver exports in the sysfs directory
 153 .I /sys/class/scsi_tape
 154 the attached devices and some parameters assigned to the devices.
 155 .SS Data transfer
 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
 159 writes blocks of the specified size and the block size is not
 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
 163 count determines the size of the corresponding tape block.
 164 Note that
 165 the blocks on the tape don't contain any information about the
 166 writing mode: when reading, the only important thing is to use
 167 commands that accept the block sizes on the tape.
 168 .PP
 169 In variable-block mode the read byte count does not have to match
 170 the tape block size exactly.
 171 If the byte count is larger than the
 172 next block on tape, the driver returns the data and the function
 173 returns the actual block size.
 174 If the block size is larger than the
 175 byte count, an error is returned.
 176 .PP
 177 In fixed-block mode the read byte counts can be arbitrary if
 178 buffering is enabled, or a multiple of the tape block size if
 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
 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
 186 In the 2.6 kernel, the driver tries to use direct transfers between the user
 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
 191 of the user buffer (default is 512 bytes but this can be changed by the HBA
 192 driver), one or more pages of the user buffer not reachable by the
 193 SCSI adapter, and so on.
 194 .PP
 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
 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
 206 recorded data is signaled by returning zero bytes for two consecutive
 207 read calls.
 208 The third read returns an error.
 209 .SS Ioctls
 210 The driver supports three
 211 .BR ioctl (2)
 212 requests.
 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
 219 .IR /usr/include/linux/mtio.h :
 220 .SS MTIOCTOP \(em perform a tape operation
 221 This request takes an argument of type
 222 .IR "(struct mtop\ *)" .
 223 Not all drives support all operations.
 224 The driver returns an
 225 .B EIO
 226 error if the drive rejects an operation.
 227 .PP
 228 .in +4n
 229 .EX
 230 /* Structure for MTIOCTOP \- mag tape op command: */
 231 struct mtop {
 232     short   mt_op;       /* operations defined below */
 233     int     mt_count;    /* how many of them */
 234 };
 235 .EE
 236 .in
 237 .PP
 238 Magnetic tape operations for normal tape use:
 239 .TP
 240 .B MTBSF
 241 Backward space over
 242 .I mt_count
 243 filemarks.
 244 .TP
 245 .B MTBSFM
 246 Backward space over
 247 .I mt_count
 248 filemarks.
 249 Reposition the tape to the EOT side of the last filemark.
 250 .TP
 251 .B MTBSR
 252 Backward space over
 253 .I mt_count
 254 records (tape blocks).
 255 .TP
 256 .B MTBSS
 257 Backward space over
 258 .I mt_count
 259 setmarks.
 260 .TP
 261 .B MTCOMPRESSION
 262 Enable compression of tape data within the drive if
 263 .I mt_count
 264 is nonzero and disable compression if
 265 .I mt_count
 266 is zero.
 267 This command uses the MODE page 15 supported by most DATs.
 268 .TP
 269 .B MTEOM
 270 Go to the end of the recorded media (for appending files).
 271 .TP
 272 .B MTERASE
 273 Erase tape.
 274 With 2.6 kernel, short erase (mark tape empty) is performed if the
 275 argument is zero.
 276 Otherwise, long erase (erase all) is done.
 277 .TP
 278 .B MTFSF
 279 Forward space over
 280 .I mt_count
 281 filemarks.
 282 .TP
 283 .B MTFSFM
 284 Forward space over
 285 .I mt_count
 286 filemarks.
 287 Reposition the tape to the BOT side of the last filemark.
 288 .TP
 289 .B MTFSR
 290 Forward space over
 291 .I mt_count
 292 records (tape blocks).
 293 .TP
 294 .B MTFSS
 295 Forward space over
 296 .I mt_count
 297 setmarks.
 298 .TP
 299 .B MTLOAD
 300 Execute the SCSI load command.
 301 A special case is available for some HP
 302 autoloaders.
 303 If
 304 .I mt_count
 305 is the constant
 306 .B MT_ST_HPLOADER_OFFSET
 307 plus a number, the number is
 308 sent to the drive to control the autoloader.
 309 .TP
 310 .B MTLOCK
 311 Lock the tape drive door.
 312 .TP
 313 .B MTMKPART
 314 Format the tape into one or two partitions.
 315 If
 316 .I mt_count
 317 is positive, it gives the size of partition 1 and partition
 318 0 contains the rest of the tape.
 319 If
 320 .I mt_count
 321 is zero, the tape is formatted into one partition.
 322 From kernel version 4.6,
 323 .\" commit 8038e6456a3e6f5c4759e0d73c4f9165b90c93e7
 324 a negative
 325 .I mt_count
 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.
 329 This command is not allowed for a drive unless the partition support
 330 is enabled for the drive (see
 331 .B MT_ST_CAN_PARTITIONS
 332 below).
 333 .TP
 334 .B MTNOP
 335 No op\(emflushes the driver's buffer as a side effect.
 336 Should be used before reading status with
 337 .BR MTIOCGET .
 338 .TP
 339 .B MTOFFL
 340 Rewind and put the drive off line.
 341 .TP
 342 .B MTRESET
 343 Reset drive.
 344 .TP
 345 .B MTRETEN
 346 Re-tension tape.
 347 .TP
 348 .B MTREW
 349 Rewind.
 350 .TP
 351 .B MTSEEK
 352 Seek to the tape block number specified in
 353 .IR mt_count .
 354 This operation requires either a SCSI-2 drive that supports the
 355 .B LOCATE
 356 command (device-specific address)
 357 or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive
 358 Viper, Wangtek, ...).
 359 The block number should be one that was previously returned by
 360 .B MTIOCPOS
 361 if device-specific addresses are used.
 362 .TP
 363 .B MTSETBLK
 364 Set the drive's block length to the value specified in
 365 .IR mt_count .
 366 A block length of zero sets the drive to variable block size mode.
 367 .TP
 368 .B MTSETDENSITY
 369 Set the tape density to the code in
 370 .IR mt_count .
 371 The density codes supported by a drive can be found from the drive
 372 documentation.
 373 .TP
 374 .B MTSETPART
 375 The active partition is switched to
 376 .IR mt_count .
 377 The partitions are numbered from zero.
 378 This command is not allowed for
 379 a drive unless the partition support is enabled for the drive (see
 380 .B MT_ST_CAN_PARTITIONS
 381 below).
 382 .TP
 383 .B MTUNLOAD
 384 Execute the SCSI unload command (does not eject the tape).
 385 .TP
 386 .B MTUNLOCK
 387 Unlock the tape drive door.
 388 .TP
 389 .B MTWEOF
 390 Write
 391 .I mt_count
 392 filemarks.
 393 .TP
 394 .B MTWSM
 395 Write
 396 .I mt_count
 397 setmarks.
 398 .PP
 399 Magnetic tape operations for setting of device options (by the superuser):
 400 .TP
 401 .B MTSETDRVBUFFER
 402 Set various drive and driver options according to bits encoded in
 403 .IR mt_count .
 404 These consist of the drive's buffering mode, a set of Boolean driver
 405 options, the buffer write threshold, defaults for the block size and
 406 density, and timeouts (only in kernels 2.1 and later).
 407 A single operation can affect only one item in the list below (the
 408 Booleans counted as one item.)
 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:
 413 .RS
 414 .TP
 415 .B 0
 416 The drive will not report
 417 .B GOOD
 418 status on write commands until the data
 419 blocks are actually written to the medium.
 420 .TP
 421 .B 1
 422 The drive may report
 423 .B GOOD
 424 status on write commands as soon as all the
 425 data has been transferred to the drive's internal buffer.
 426 .TP
 427 .B 2
 428 The drive may report
 429 .B GOOD
 430 status on write commands as soon as (a) all
 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.
 434 .RE
 435 .IP
 436 To control the write threshold the value in
 437 .I mt_count
 438 must include the constant
 439 .B MT_ST_WRITE_THRESHOLD
 440 bitwise ORed with a block count in the low 28 bits.
 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
 444 DESCRIPTION, above).
 445 .IP
 446 To set and clear the Boolean options
 447 the value in
 448 .I mt_count
 449 must include one of the constants
 450 .BR MT_ST_BOOLEANS ,
 451 .BR MT_ST_SETBOOLEANS ,
 452 .BR MT_ST_CLEARBOOLEANS ,
 453 or
 454 .B MT_ST_DEFBOOLEANS
 455 bitwise ORed with
 456 whatever combination of the following options is desired.
 457 Using
 458 .B MT_ST_BOOLEANS
 459 the options can be set to the values
 460 defined in the corresponding bits.
 461 With
 462 .B MT_ST_SETBOOLEANS
 463 the options can be selectively set and with
 464 .B MT_ST_DEFBOOLEANS
 465 selectively cleared.
 466 .IP
 467 The default options for a tape device are set with
 468 .BR MT_ST_DEFBOOLEANS .
 469 A nonactive tape device (e.g., device with
 470 minor 32 or 160) is activated when the default options for it are
 471 defined the first time.
 472 An activated device inherits from the device
 473 activated at start-up the options not set explicitly.
 474 .IP
 475 The Boolean options are:
 476 .RS
 477 .TP
 478 .BR MT_ST_BUFFER_WRITES " (Default: true)"
 479 Buffer all write operations in fixed-block mode.
 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.
 482 This option must be set false to write reliable multivolume archives.
 483 .TP
 484 .BR MT_ST_ASYNC_WRITES " (Default: true)"
 485 When this option is true, write operations return immediately without
 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.
 492 This option must be set false to write reliable multivolume archives.
 493 .TP
 494 .BR MT_ST_READ_AHEAD " (Default: true)"
 495 This option causes the driver to provide read buffering and
 496 read-ahead in fixed-block mode.
 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.
 499 .TP
 500 .BR MT_ST_TWO_FM " (Default: false)"
 501 This option modifies the driver behavior when a file is closed.
 502 The normal action is to write a single filemark.
 503 If the option is true, the driver will write two filemarks and
 504 backspace over the second one.
 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
 510 rather than two consecutive filemarks.
 511 Most other current drives also
 512 detect the end of recorded data and using two filemarks is usually
 513 necessary only when interchanging tapes with some other systems.
 514 .TP
 515 .BR MT_ST_DEBUGGING " (Default: false)"
 516 This option turns on various debugging messages from the driver
 517 (effective only if the driver was compiled with
 518 .B DEBUG
 519 defined nonzero).
 520 .TP
 521 .BR MT_ST_FAST_EOM " (Default: false)"
 522 This option causes the
 523 .B MTEOM
 524 operation to be sent directly to the
 525 drive, potentially speeding up the operation but causing the driver to
 526 lose track of the current file number normally returned by the
 527 .B MTIOCGET
 528 request.
 529 If
 530 .B MT_ST_FAST_EOM
 531 is false, the driver will respond to an
 532 .B MTEOM
 533 request by forward spacing over files.
 534 .TP
 535 .BR MT_ST_AUTO_LOCK " (Default: false)"
 536 When this option is true, the drive door is locked when the device file is
 537 opened and unlocked when it is closed.
 538 .TP
 539 .BR MT_ST_DEF_WRITES " (Default: false)"
 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
 543 defined.
 544 This option defines when the changes are enforced by the
 545 driver using SCSI-commands and when the drives auto-detection
 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
 550 option is true, the SCSI-commands are not sent until a write is
 551 requested.
 552 In this case, the drive firmware is allowed to detect the
 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.
 555 .TP
 556 .BR MT_ST_CAN_BSR " (Default: false)"
 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
 559 space backward over records is used for this purpose.
 560 Some older
 561 drives can't process this command reliably and this option can be used
 562 to instruct the driver not to use the command.
 563 The end result is that,
 564 with read-ahead and fixed-block mode, the tape may not be correctly
 565 positioned within a file when the device is closed.
 566 With 2.6 kernel, the
 567 default is true for drives supporting SCSI-3.
 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.
 574 The drawback is
 575 that the driver can't check before sending commands if the selected
 576 block size is acceptable to the drive.
 577 .TP
 578 .BR MT_ST_CAN_PARTITIONS " (Default: false)"
 579 This option enables support for several partitions within a
 580 tape.
 581 The option applies to all devices linked to a drive.
 582 .TP
 583 .BR MT_ST_SCSI2LOGICAL " (Default: false)"
 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
 586 operations (both with
 587 .B MTSEEK
 588 and
 589 .B MTIOCPOS
 590 commands and when changing tape
 591 partition).
 592 Otherwise, the device-specific addresses are used.
 593 It is highly advisable to set this option if the drive supports the
 594 logical addresses because they count also filemarks.
 595 There are some
 596 drives that support only the logical block addresses.
 597 .TP
 598 .BR MT_ST_SYSV " (Default: false)"
 599 When this option is enabled, the tape devices use the System V
 600 semantics.
 601 Otherwise, the BSD semantics are used.
 602 The most important
 603 difference between the semantics is what happens when a device used
 604 for reading is closed: in System V semantics the tape is spaced forward
 605 past the next filemark if this has not happened while using the
 606 device.
 607 In BSD semantics the tape position is not changed.
 608 .TP
 609 .BR MT_NO_WAIT " (Default: false)"
 610 Enables immediate mode (i.e., don't wait for the command to finish) for some
 611 commands (e.g., rewind).
 612 .PP
 613 An example:
 614 .PP
 615 .in +4n
 616 .EX
 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);
 622 .EE
 623 .in
 624 .PP
 625 The default block size for a device can be set with
 626 .B MT_ST_DEF_BLKSIZE
 627 and the default density code can be set with
 628 .BR MT_ST_DEFDENSITY .
 629 The values for the parameters are or'ed
 630 with the operation code.
 631 .PP
 632 With kernels 2.1.x and later, the timeout values can be set with the
 633 subcommand
 634 .B MT_ST_SET_TIMEOUT
 635 ORed with the timeout in seconds.
 636 The long timeout (used for rewinds and other commands
 637 that may take a long time) can be set with
 638 .BR MT_ST_SET_LONG_TIMEOUT .
 639 The kernel defaults are very long to
 640 make sure that a successful command is not timed out with any
 641 drive.
 642 Because of this, the driver may seem stuck even if it is only
 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
 647 apply for all devices linked to the same drive.
 648 .PP
 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
 653 .B MT_ST_SEL_CLN
 654 subcommand.
 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).
 659 Values 2\(en17 are
 660 reserved.
 661 If the lowest eight bits are >= 18, bits from the extended
 662 sense data are used.
 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.
 665 If the bit pattern is zero, one or more bits under the mask indicate
 666 the cleaning request.
 667 If the pattern is nonzero, the pattern must match
 668 the masked sense data byte.
 669 .RE
 670 .SS MTIOCGET \(em get status
 671 This request takes an argument of type
 672 .IR "(struct mtget\ *)" .
 673 .PP
 674 .in +4n
 675 .EX
 676 /* structure for MTIOCGET \- mag tape get status command */
 677 struct mtget {
 678     long     mt_type;
 679     long     mt_resid;
 680     /* the following registers are device dependent */
 681     long     mt_dsreg;
 682     long     mt_gstat;
 683     long     mt_erreg;
 684     /* The next two fields are not always used */
 685     daddr_t  mt_fileno;
 686     daddr_t  mt_blkno;
 687 };
 688 .EE
 689 .in
 690 .TP
 691 \fImt_type\fP
 692 The header file defines many values for
 693 .IR mt_type ,
 694 but the current driver reports only the generic types
 695 .B MT_ISSCSI1
 696 (Generic SCSI-1 tape)
 697 and
 698 .B MT_ISSCSI2
 699 (Generic SCSI-2 tape).
 700 .TP
 701 \fImt_resid\fP
 702 contains the current tape partition number.
 703 .TP
 704 \fImt_dsreg\fP
 705 reports the drive's current settings for block size (in the low 24
 706 bits) and density (in the high 8 bits).
 707 These fields are defined by
 708 .BR MT_ST_BLKSIZE_SHIFT ,
 709 .BR MT_ST_BLKSIZE_MASK ,
 710 .BR MT_ST_DENSITY_SHIFT ,
 711 and
 712 .BR MT_ST_DENSITY_MASK .
 713 .TP
 714 \fImt_gstat\fP
 715 reports generic (device independent) status information.
 716 The header file defines macros for testing these status bits:
 717 .RS
 718 .TP
 719 \fBGMT_EOF\fP(\fIx\fP)
 720 The tape is positioned just after a filemark
 721 (always false after an
 722 .B MTSEEK
 723 operation).
 724 .TP
 725 \fBGMT_BOT\fP(\fIx\fP)
 726 The tape is positioned at the beginning of the first file (always false
 727 after an
 728 .B MTSEEK
 729 operation).
 730 .TP
 731 \fBGMT_EOT\fP(\fIx\fP)
 732 A tape operation has reached the physical End Of Tape.
 733 .TP
 734 \fBGMT_SM\fP(\fIx\fP)
 735 The tape is currently positioned at a setmark
 736 (always false after an
 737 .B MTSEEK
 738 operation).
 739 .TP
 740 \fBGMT_EOD\fP(\fIx\fP)
 741 The tape is positioned at the end of recorded data.
 742 .TP
 743 \fBGMT_WR_PROT\fP(\fIx\fP)
 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.
 747 .TP
 748 \fBGMT_ONLINE\fP(\fIx\fP)
 749 The last
 750 .BR open (2)
 751 found the drive with a tape in place and ready for operation.
 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)
 758 This \(lqgeneric\(rq status information reports the current
 759 density setting for 9-track \(12" tape drives only.
 760 .TP
 761 \fBGMT_DR_OPEN\fP(\fIx\fP)
 762 The drive does not have a tape in place.
 763 .TP
 764 \fBGMT_IM_REP_EN\fP(\fIx\fP)
 765 Immediate report mode.
 766 This bit is set if there are no guarantees that
 767 the data has been physically written to the tape when the write call
 768 returns.
 769 It is set zero only when the driver does not buffer data and
 770 the drive is set not to buffer data.
 771 .TP
 772 \fBGMT_CLN\fP(\fIx\fP)
 773 The drive has requested cleaning.
 774 Implemented in kernels since 2.4.19 and 2.5.43.
 775 .RE
 776 .TP
 777 \fImt_erreg\fP
 778 The only field defined in
 779 .I mt_erreg
 780 is the recovered error count in the low 16 bits (as defined by
 781 .B MT_ST_SOFTERR_SHIFT
 782 and
 783 .BR MT_ST_SOFTERR_MASK ).
 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).
 787 .TP
 788 \fImt_fileno\fP
 789 reports the current file number (zero-based).
 790 This value is set to \-1 when the file number is unknown (e.g., after
 791 .B MTBSS
 792 or
 793 .BR MTSEEK ).
 794 .TP
 795 \fImt_blkno\fP
 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
 798 .BR MTBSF ,
 799 .BR MTBSS ,
 800 or
 801 .BR MTSEEK ).
 802 .SS MTIOCPOS \(em get tape position
 803 This request takes an argument of type
 804 .I "(struct mtpos\ *)"
 805 and reports the drive's notion of the current tape block number,
 806 which is not the same as
 807 .I mt_blkno
 808 returned by
 809 .BR MTIOCGET .
 810 This drive must be a SCSI-2 drive that supports the
 811 .B "READ POSITION"
 812 command (device-specific address)
 813 or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive
 814 Viper, Wangtek, ... ).
 815 .PP
 816 .in +4n
 817 .EX
 818 /* structure for MTIOCPOS \- mag tape get position command */
 819 struct mtpos {
 820     long mt_blkno;    /* current block number */
 821 };
 822 .EE
 823 .in
 824 .SH RETURN VALUE
 825 .TP
 826 .B EACCES
 827 An attempt was made to write or erase a write-protected tape.
 828 (This error is not detected during
 829 .BR open (2).)
 830 .TP
 831 .B EBUSY
 832 The device is already in use or the driver was unable to allocate a
 833 buffer.
 834 .TP
 835 .B EFAULT
 836 The command parameters point to memory not belonging to the calling
 837 process.
 838 .TP
 839 .B EINVAL
 840 An
 841 .BR ioctl (2)
 842 had an invalid argument, or a requested block size was invalid.
 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.
 851 (Before 2.2.18 and 2.4.0 the extra bytes have been
 852 .\" Precisely: Linux 2.6.0-test6
 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
 860 Unknown
 861 .BR ioctl (2).
 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.
 876 .SH FILES
 877 .TP
 878 .I /dev/st*
 879 the auto-rewind SCSI tape devices
 880 .TP
 881 .I /dev/nst*
 882 the nonrewind SCSI tape devices
 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.
 888 .SH NOTES
 889 .IP \(bu 3
 890 When exchanging data between systems, both systems have to agree on
 891 the physical tape block size.
 892 The parameters of a drive after startup
 893 are often not the ones most operating systems use with these
 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
 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
 905 exchanging data with a foreign system.
 906 The drawback of
 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.
 909 .IP \(bu
 910 Many programs (e.g.,
 911 .BR tar (1))
 912 allow the user to specify the blocking
 913 factor on the command line.
 914 Note that this determines the physical block
 915 size on tape only in variable-block mode.
 916 .IP \(bu
 917 In order to use SCSI tape drives, the basic SCSI driver,
 918 a SCSI-adapter driver and the SCSI tape driver must be either
 919 configured into the kernel or loaded as modules.
 920 If the SCSI-tape
 921 driver is not present, the drive is recognized but the tape support
 922 described in this page is not available.
 923 .IP \(bu
 924 The driver writes error messages to the console/log.
 925 The SENSE
 926 codes written into some messages are automatically translated to text
 927 if verbose SCSI messages are enabled in kernel configuration.
 928 .IP \(bu
 929 The driver's internal buffering allows good throughput in fixed-block
 930 mode also with small
 931 .BR read (2)
 932 and
 933 .BR write (2)
 934 byte counts.
 935 With direct transfers
 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.
 941 .SH SEE ALSO
 942 .BR mt (1)
 943 .PP
 944 The file
 945 .I drivers/scsi/README.st
 946 or
 947 .I Documentation/scsi/st.txt
 948 (kernel >= 2.6) in the Linux kernel source tree contains
 949 the most recent information about the driver and its configuration
 950 possibilities