Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 950 insertions, 0 deletions

diff --git a/man/man4/st.4 b/man/man4/st.4
new file mode 100644
index 0000000..2186e64
--- /dev/null
+++ b/man/man4/st.4
@@ -0,0 +1,950 @@
+.\" Copyright 1995 Robert K. Nichols (Robert.K.Nichols@att.com)
+.\" Copyright 1999-2005 Kai Mäkisara (Kai.Makisara@kolumbus.fi)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.TH st 4 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+st \- SCSI tape device
+.SH SYNOPSIS
+.nf
+.B #include <sys/mtio.h>
+.P
+.BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);"
+.BI "int ioctl(int " fd ", MTIOCTOP, (struct mtop *)" mt_cmd );
+.BI "int ioctl(int " fd ", MTIOCGET, (struct mtget *)" mt_status );
+.BI "int ioctl(int " fd ", MTIOCPOS, (struct mtpos *)" mt_pos );
+.fi
+.SH DESCRIPTION
+The
+.B st
+driver provides the interface to a variety of SCSI tape devices.
+Currently, the driver takes control of all detected devices of type
+\[lq]sequential-access\[rq].
+The
+.B st
+driver uses major device number 9.
+.P
+Each device uses eight minor device numbers.
+The lowermost five bits
+in the minor numbers are assigned sequentially in the order of
+detection.
+In the 2.6 kernel, the bits above the eight lowermost bits are
+concatenated to the five lowermost bits to form the tape number.
+The minor numbers can be grouped into
+two sets of four numbers: the principal (auto-rewind) minor device numbers,
+.IR n ,
+and the \[lq]no-rewind\[rq] device numbers,
+.RI ( n " + 128)."
+Devices opened using the principal device number will be sent a
+.B REWIND
+command when they are closed.
+Devices opened using the \[lq]no-rewind\[rq] device number will not.
+(Note that using an auto-rewind device for positioning the tape with,
+for instance, mt does not lead to the desired result: the tape is
+rewound after the mt command and the next command starts from the
+beginning of the tape).
+.P
+Within each group, four minor numbers are available to define
+devices with different characteristics (block size, compression,
+density, etc.)
+When the system starts up, only the first device is available.
+The other three are activated when the default
+characteristics are defined (see below).
+(By changing compile-time
+constants, it is possible to change the balance between the maximum
+number of tape drives and the number of minor numbers for each
+drive.
+The default allocation allows control of 32 tape drives.
+For instance, it is possible to control up to 64 tape drives
+with two minor numbers for different options.)
+.P
+Devices are typically created by:
+.P
+.in +4n
+.EX
+mknod \-m 666 /dev/st0 c 9 0
+mknod \-m 666 /dev/st0l c 9 32
+mknod \-m 666 /dev/st0m c 9 64
+mknod \-m 666 /dev/st0a c 9 96
+mknod \-m 666 /dev/nst0 c 9 128
+mknod \-m 666 /dev/nst0l c 9 160
+mknod \-m 666 /dev/nst0m c 9 192
+mknod \-m 666 /dev/nst0a c 9 224
+.EE
+.in
+.P
+There is no corresponding block device.
+.P
+The driver uses an internal buffer that has to be large enough to hold
+at least one tape block.
+Before Linux 2.1.121, the buffer is
+allocated as one contiguous block.
+This limits the block size to the
+largest contiguous block of memory the kernel allocator can provide.
+The limit is currently 128\ kB for 32-bit architectures and
+256\ kB for 64-bit architectures.
+In newer kernels the driver
+allocates the buffer in several parts if necessary.
+By default, the
+maximum number of parts is 16.
+This means that the maximum block size
+is very large (2\ MB if allocation of 16 blocks of 128\ kB succeeds).
+.P
+The driver's internal buffer size is determined by a compile-time
+constant which can be overridden with a kernel startup option.
+In addition to this, the driver tries to allocate a larger temporary
+buffer at run time if necessary.
+However, run-time allocation of large
+contiguous blocks of memory may fail and it is advisable not to rely
+too much on dynamic buffer allocation before Linux 2.1.121
+(this applies also to demand-loading the driver with kerneld or kmod).
+.P
+The driver does not specifically support any tape drive brand or
+model.
+After system start-up the tape device options are defined by
+the drive firmware.
+For example, if the drive firmware selects fixed-block mode,
+the tape device uses fixed-block mode.
+The options can
+be changed with explicit
+.BR ioctl (2)
+calls and remain in effect when the device is closed and reopened.
+Setting the options affects both the auto-rewind and the nonrewind
+device.
+.P
+Different options can be specified for the different devices within
+the subgroup of four.
+The options take effect when the device is
+opened.
+For example, the system administrator can define
+one device that writes in fixed-block mode with a certain block size,
+and one which writes in variable-block mode (if the drive supports
+both modes).
+.P
+The driver supports
+.B tape partitions
+if they are supported by the drive.
+(Note that the tape partitions
+have nothing to do with disk partitions.
+A partitioned tape can be
+seen as several logical tapes within one medium.)
+Partition support has to be enabled with an
+.BR ioctl (2).
+The tape
+location is preserved within each partition across partition changes.
+The partition used for subsequent tape operations is
+selected with an
+.BR ioctl (2).
+The partition switch is executed together with
+the next tape operation in order to avoid unnecessary tape
+movement.
+The maximum number of partitions on a tape is defined by a
+compile-time constant (originally four).
+The driver contains an
+.BR ioctl (2)
+that can format a tape with either one or two partitions.
+.P
+Device
+.I /dev/tape
+is usually created as a hard or soft link to the default tape device
+on the system.
+.P
+Starting from Linux 2.6.2, the driver exports in the sysfs directory
+.I /sys/class/scsi_tape
+the attached devices and some parameters assigned to the devices.
+.SS Data transfer
+The driver supports operation in both fixed-block mode and
+variable-block mode (if supported by the drive).
+In fixed-block mode the drive
+writes blocks of the specified size and the block size is not
+dependent on the byte counts of the write system calls.
+In variable-block mode one tape block is written for each write call
+and the byte
+count determines the size of the corresponding tape block.
+Note that
+the blocks on the tape don't contain any information about the
+writing mode: when reading, the only important thing is to use
+commands that accept the block sizes on the tape.
+.P
+In variable-block mode the read byte count does not have to match
+the tape block size exactly.
+If the byte count is larger than the
+next block on tape, the driver returns the data and the function
+returns the actual block size.
+If the block size is larger than the
+byte count, an error is returned.
+.P
+In fixed-block mode the read byte counts can be arbitrary if
+buffering is enabled, or a multiple of the tape block size if
+buffering is disabled.
+Before Linux 2.1.121 allow writes with
+arbitrary byte count if buffering is enabled.
+In all other cases
+(before Linux 2.1.121 with buffering disabled or newer kernel) the
+write byte count must be a multiple of the tape block size.
+.P
+In Linux 2.6, the driver tries to use direct transfers between the user
+buffer and the device.
+If this is not possible, the driver's internal buffer
+is used.
+The reasons for not using direct transfers include improper alignment
+of the user buffer (default is 512 bytes but this can be changed by the HBA
+driver), one or more pages of the user buffer not reachable by the
+SCSI adapter, and so on.
+.P
+A filemark is automatically written to tape if the last tape operation
+before close was a write.
+.P
+When a filemark is encountered while reading, the following
+happens.
+If there are data remaining in the buffer when the filemark
+is found, the buffered data is returned.
+The next read returns zero
+bytes.
+The following read returns data from the next file.
+The end of
+recorded data is signaled by returning zero bytes for two consecutive
+read calls.
+The third read returns an error.
+.SS Ioctls
+The driver supports three
+.BR ioctl (2)
+requests.
+Requests not recognized by the
+.B st
+driver are passed to the
+.B SCSI
+driver.
+The definitions below are from
+.IR /usr/include/linux/mtio.h :
+.SS MTIOCTOP \[em] perform a tape operation
+This request takes an argument of type
+.IR "(struct mtop\ *)" .
+Not all drives support all operations.
+The driver returns an
+.B EIO
+error if the drive rejects an operation.
+.P
+.in +4n
+.EX
+/* Structure for MTIOCTOP \- mag tape op command: */
+struct mtop {
+    short   mt_op;       /* operations defined below */
+    int     mt_count;    /* how many of them */
+};
+.EE
+.in
+.P
+Magnetic tape operations for normal tape use:
+.TP
+.B MTBSF
+Backward space over
+.I mt_count
+filemarks.
+.TP
+.B MTBSFM
+Backward space over
+.I mt_count
+filemarks.
+Reposition the tape to the EOT side of the last filemark.
+.TP
+.B MTBSR
+Backward space over
+.I mt_count
+records (tape blocks).
+.TP
+.B MTBSS
+Backward space over
+.I mt_count
+setmarks.
+.TP
+.B MTCOMPRESSION
+Enable compression of tape data within the drive if
+.I mt_count
+is nonzero and disable compression if
+.I mt_count
+is zero.
+This command uses the MODE page 15 supported by most DATs.
+.TP
+.B MTEOM
+Go to the end of the recorded media (for appending files).
+.TP
+.B MTERASE
+Erase tape.
+With Linux 2.6, short erase (mark tape empty) is performed if the
+argument is zero.
+Otherwise, long erase (erase all) is done.
+.TP
+.B MTFSF
+Forward space over
+.I mt_count
+filemarks.
+.TP
+.B MTFSFM
+Forward space over
+.I mt_count
+filemarks.
+Reposition the tape to the BOT side of the last filemark.
+.TP
+.B MTFSR
+Forward space over
+.I mt_count
+records (tape blocks).
+.TP
+.B MTFSS
+Forward space over
+.I mt_count
+setmarks.
+.TP
+.B MTLOAD
+Execute the SCSI load command.
+A special case is available for some HP
+autoloaders.
+If
+.I mt_count
+is the constant
+.B MT_ST_HPLOADER_OFFSET
+plus a number, the number is
+sent to the drive to control the autoloader.
+.TP
+.B MTLOCK
+Lock the tape drive door.
+.TP
+.B MTMKPART
+Format the tape into one or two partitions.
+If
+.I mt_count
+is positive, it gives the size of partition 1 and partition
+0 contains the rest of the tape.
+If
+.I mt_count
+is zero, the tape is formatted into one partition.
+From Linux 4.6,
+.\" commit 8038e6456a3e6f5c4759e0d73c4f9165b90c93e7
+a negative
+.I mt_count
+specifies the size of partition 0 and
+the rest of the tape contains partition 1.
+The physical ordering of partitions depends on the drive.
+This command is not allowed for a drive unless the partition support
+is enabled for the drive (see
+.B MT_ST_CAN_PARTITIONS
+below).
+.TP
+.B MTNOP
+No op\[em]flushes the driver's buffer as a side effect.
+Should be used before reading status with
+.BR MTIOCGET .
+.TP
+.B MTOFFL
+Rewind and put the drive off line.
+.TP
+.B MTRESET
+Reset drive.
+.TP
+.B MTRETEN
+Re-tension tape.
+.TP
+.B MTREW
+Rewind.
+.TP
+.B MTSEEK
+Seek to the tape block number specified in
+.IR mt_count .
+This operation requires either a SCSI-2 drive that supports the
+.B LOCATE
+command (device-specific address)
+or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive
+Viper, Wangtek, ...).
+The block number should be one that was previously returned by
+.B MTIOCPOS
+if device-specific addresses are used.
+.TP
+.B MTSETBLK
+Set the drive's block length to the value specified in
+.IR mt_count .
+A block length of zero sets the drive to variable block size mode.
+.TP
+.B MTSETDENSITY
+Set the tape density to the code in
+.IR mt_count .
+The density codes supported by a drive can be found from the drive
+documentation.
+.TP
+.B MTSETPART
+The active partition is switched to
+.IR mt_count .
+The partitions are numbered from zero.
+This command is not allowed for
+a drive unless the partition support is enabled for the drive (see
+.B MT_ST_CAN_PARTITIONS
+below).
+.TP
+.B MTUNLOAD
+Execute the SCSI unload command (does not eject the tape).
+.TP
+.B MTUNLOCK
+Unlock the tape drive door.
+.TP
+.B MTWEOF
+Write
+.I mt_count
+filemarks.
+.TP
+.B MTWSM
+Write
+.I mt_count
+setmarks.
+.P
+Magnetic tape operations for setting of device options (by the superuser):
+.TP
+.B MTSETDRVBUFFER
+Set various drive and driver options according to bits encoded in
+.IR mt_count .
+These consist of the drive's buffering mode, a set of Boolean driver
+options, the buffer write threshold, defaults for the block size and
+density, and timeouts (only since Linux 2.1).
+A single operation can affect only one item in the list below (the
+Booleans counted as one item.)
+.IP
+A value having zeros in the high-order 4 bits will be used to set the
+drive's buffering mode.
+The buffering modes are:
+.RS
+.TP
+.B 0
+The drive will not report
+.B GOOD
+status on write commands until the data
+blocks are actually written to the medium.
+.TP
+.B 1
+The drive may report
+.B GOOD
+status on write commands as soon as all the
+data has been transferred to the drive's internal buffer.
+.TP
+.B 2
+The drive may report
+.B GOOD
+status on write commands as soon as (a) all
+the data has been transferred to the drive's internal buffer, and
+(b) all buffered data from different initiators has been successfully
+written to the medium.
+.RE
+.IP
+To control the write threshold the value in
+.I mt_count
+must include the constant
+.B MT_ST_WRITE_THRESHOLD
+bitwise ORed with a block count in the low 28 bits.
+The block count refers to 1024-byte blocks, not the physical block
+size on the tape.
+The threshold cannot exceed the driver's internal buffer size (see
+DESCRIPTION, above).
+.IP
+To set and clear the Boolean options
+the value in
+.I mt_count
+must include one of the constants
+.BR MT_ST_BOOLEANS ,
+.BR MT_ST_SETBOOLEANS ,
+.BR MT_ST_CLEARBOOLEANS ,
+or
+.B MT_ST_DEFBOOLEANS
+bitwise ORed with
+whatever combination of the following options is desired.
+Using
+.B MT_ST_BOOLEANS
+the options can be set to the values
+defined in the corresponding bits.
+With
+.B MT_ST_SETBOOLEANS
+the options can be selectively set and with
+.B MT_ST_DEFBOOLEANS
+selectively cleared.
+.IP
+The default options for a tape device are set with
+.BR MT_ST_DEFBOOLEANS .
+A nonactive tape device (e.g., device with
+minor 32 or 160) is activated when the default options for it are
+defined the first time.
+An activated device inherits from the device
+activated at start-up the options not set explicitly.
+.IP
+The Boolean options are:
+.RS
+.TP
+.BR MT_ST_BUFFER_WRITES " (Default: true)"
+Buffer all write operations in fixed-block mode.
+If this option is false and the drive uses a fixed block size, then
+all write operations must be for a multiple of the block size.
+This option must be set false to write reliable multivolume archives.
+.TP
+.BR MT_ST_ASYNC_WRITES " (Default: true)"
+When this option is true, write operations return immediately without
+waiting for the data to be transferred to the drive if the data fits
+into the driver's buffer.
+The write threshold determines how full the buffer must be before a
+new SCSI write command is issued.
+Any errors reported by the drive will be held until the next
+operation.
+This option must be set false to write reliable multivolume archives.
+.TP
+.BR MT_ST_READ_AHEAD " (Default: true)"
+This option causes the driver to provide read buffering and
+read-ahead in fixed-block mode.
+If this option is false and the drive uses a fixed block size, then
+all read operations must be for a multiple of the block size.
+.TP
+.BR MT_ST_TWO_FM " (Default: false)"
+This option modifies the driver behavior when a file is closed.
+The normal action is to write a single filemark.
+If the option is true, the driver will write two filemarks and
+backspace over the second one.
+.IP
+Note:
+This option should not be set true for QIC tape drives since they are
+unable to overwrite a filemark.
+These drives detect the end of recorded data by testing for blank tape
+rather than two consecutive filemarks.
+Most other current drives also
+detect the end of recorded data and using two filemarks is usually
+necessary only when interchanging tapes with some other systems.
+.TP
+.BR MT_ST_DEBUGGING " (Default: false)"
+This option turns on various debugging messages from the driver
+(effective only if the driver was compiled with
+.B DEBUG
+defined nonzero).
+.TP
+.BR MT_ST_FAST_EOM " (Default: false)"
+This option causes the
+.B MTEOM
+operation to be sent directly to the
+drive, potentially speeding up the operation but causing the driver to
+lose track of the current file number normally returned by the
+.B MTIOCGET
+request.
+If
+.B MT_ST_FAST_EOM
+is false, the driver will respond to an
+.B MTEOM
+request by forward spacing over files.
+.TP
+.BR MT_ST_AUTO_LOCK " (Default: false)"
+When this option is true, the drive door is locked when the device file is
+opened and unlocked when it is closed.
+.TP
+.BR MT_ST_DEF_WRITES " (Default: false)"
+The tape options (block size, mode, compression, etc.) may change
+when changing from one device linked to a drive to another device
+linked to the same drive depending on how the devices are
+defined.
+This option defines when the changes are enforced by the
+driver using SCSI-commands and when the drives auto-detection
+capabilities are relied upon.
+If this option is false, the driver
+sends the SCSI-commands immediately when the device is changed.
+If the
+option is true, the SCSI-commands are not sent until a write is
+requested.
+In this case, the drive firmware is allowed to detect the
+tape structure when reading and the SCSI-commands are used only to
+make sure that a tape is written according to the correct specification.
+.TP
+.BR MT_ST_CAN_BSR " (Default: false)"
+When read-ahead is used, the tape must sometimes be spaced backward to the
+correct position when the device is closed and the SCSI command to
+space backward over records is used for this purpose.
+Some older
+drives can't process this command reliably and this option can be used
+to instruct the driver not to use the command.
+The end result is that,
+with read-ahead and fixed-block mode, the tape may not be correctly
+positioned within a file when the device is closed.
+With Linux 2.6, the
+default is true for drives supporting SCSI-3.
+.TP
+.BR MT_ST_NO_BLKLIMS " (Default: false)"
+Some drives don't accept the
+.B "READ BLOCK LIMITS"
+SCSI command.
+If this is used, the driver does not use the command.
+The drawback is
+that the driver can't check before sending commands if the selected
+block size is acceptable to the drive.
+.TP
+.BR MT_ST_CAN_PARTITIONS " (Default: false)"
+This option enables support for several partitions within a
+tape.
+The option applies to all devices linked to a drive.
+.TP
+.BR MT_ST_SCSI2LOGICAL " (Default: false)"
+This option instructs the driver to use the logical block addresses
+defined in the SCSI-2 standard when performing the seek and tell
+operations (both with
+.B MTSEEK
+and
+.B MTIOCPOS
+commands and when changing tape
+partition).
+Otherwise, the device-specific addresses are used.
+It is highly advisable to set this option if the drive supports the
+logical addresses because they count also filemarks.
+There are some
+drives that support only the logical block addresses.
+.TP
+.BR MT_ST_SYSV " (Default: false)"
+When this option is enabled, the tape devices use the System V
+semantics.
+Otherwise, the BSD semantics are used.
+The most important
+difference between the semantics is what happens when a device used
+for reading is closed: in System V semantics the tape is spaced forward
+past the next filemark if this has not happened while using the
+device.
+In BSD semantics the tape position is not changed.
+.TP
+.BR MT_NO_WAIT " (Default: false)"
+Enables immediate mode (i.e., don't wait for the command to finish) for some
+commands (e.g., rewind).
+.P
+An example:
+.P
+.in +4n
+.EX
+struct mtop mt_cmd;
+mt_cmd.mt_op = MTSETDRVBUFFER;
+mt_cmd.mt_count = MT_ST_BOOLEANS |
+        MT_ST_BUFFER_WRITES | MT_ST_ASYNC_WRITES;
+ioctl(fd, MTIOCTOP, mt_cmd);
+.EE
+.in
+.P
+The default block size for a device can be set with
+.B MT_ST_DEF_BLKSIZE
+and the default density code can be set with
+.BR MT_ST_DEFDENSITY .
+The values for the parameters are or'ed
+with the operation code.
+.P
+With Linux 2.1.x and later, the timeout values can be set with the
+subcommand
+.B MT_ST_SET_TIMEOUT
+ORed with the timeout in seconds.
+The long timeout (used for rewinds and other commands
+that may take a long time) can be set with
+.BR MT_ST_SET_LONG_TIMEOUT .
+The kernel defaults are very long to
+make sure that a successful command is not timed out with any
+drive.
+Because of this, the driver may seem stuck even if it is only
+waiting for the timeout.
+These commands can be used to set more
+practical values for a specific drive.
+The timeouts set for one device
+apply for all devices linked to the same drive.
+.P
+Starting from Linux 2.4.19 and Linux 2.5.43, the driver supports a status
+bit which indicates whether the drive requests cleaning.
+The method used by the
+drive to return cleaning information is set using the
+.B MT_ST_SEL_CLN
+subcommand.
+If the value is zero, the cleaning
+bit is always zero.
+If the value is one, the TapeAlert data defined
+in the SCSI-3 standard is used (not yet implemented).
+Values 2\[en]17 are
+reserved.
+If the lowest eight bits are >= 18, bits from the extended
+sense data are used.
+The bits 9\[en]16 specify a mask to select the bits
+to look at and the bits 17\[en]23 specify the bit pattern to look for.
+If the bit pattern is zero, one or more bits under the mask indicate
+the cleaning request.
+If the pattern is nonzero, the pattern must match
+the masked sense data byte.
+.RE
+.SS MTIOCGET \[em] get status
+This request takes an argument of type
+.IR "(struct mtget\ *)" .
+.P
+.in +4n
+.EX
+/* structure for MTIOCGET \- mag tape get status command */
+struct mtget {
+    long     mt_type;
+    long     mt_resid;
+    /* the following registers are device dependent */
+    long     mt_dsreg;
+    long     mt_gstat;
+    long     mt_erreg;
+    /* The next two fields are not always used */
+    daddr_t  mt_fileno;
+    daddr_t  mt_blkno;
+};
+.EE
+.in
+.TP
+\fImt_type\fP
+The header file defines many values for
+.IR mt_type ,
+but the current driver reports only the generic types
+.B MT_ISSCSI1
+(Generic SCSI-1 tape)
+and
+.B MT_ISSCSI2
+(Generic SCSI-2 tape).
+.TP
+\fImt_resid\fP
+contains the current tape partition number.
+.TP
+\fImt_dsreg\fP
+reports the drive's current settings for block size (in the low 24
+bits) and density (in the high 8 bits).
+These fields are defined by
+.BR MT_ST_BLKSIZE_SHIFT ,
+.BR MT_ST_BLKSIZE_MASK ,
+.BR MT_ST_DENSITY_SHIFT ,
+and
+.BR MT_ST_DENSITY_MASK .
+.TP
+\fImt_gstat\fP
+reports generic (device independent) status information.
+The header file defines macros for testing these status bits:
+.RS
+.TP
+\fBGMT_EOF\fP(\fIx\fP)
+The tape is positioned just after a filemark
+(always false after an
+.B MTSEEK
+operation).
+.TP
+\fBGMT_BOT\fP(\fIx\fP)
+The tape is positioned at the beginning of the first file (always false
+after an
+.B MTSEEK
+operation).
+.TP
+\fBGMT_EOT\fP(\fIx\fP)
+A tape operation has reached the physical End Of Tape.
+.TP
+\fBGMT_SM\fP(\fIx\fP)
+The tape is currently positioned at a setmark
+(always false after an
+.B MTSEEK
+operation).
+.TP
+\fBGMT_EOD\fP(\fIx\fP)
+The tape is positioned at the end of recorded data.
+.TP
+\fBGMT_WR_PROT\fP(\fIx\fP)
+The drive is write-protected.
+For some drives this can also mean that the drive does not support
+writing on the current medium type.
+.TP
+\fBGMT_ONLINE\fP(\fIx\fP)
+The last
+.BR open (2)
+found the drive with a tape in place and ready for operation.
+.TP
+\fBGMT_D_6250\fP(\fIx\fP)
+.TQ
+\fBGMT_D_1600\fP(\fIx\fP)
+.TQ
+\fBGMT_D_800\fP(\fIx\fP)
+This \[lq]generic\[rq] status information reports the current
+density setting for 9-track \(12" tape drives only.
+.TP
+\fBGMT_DR_OPEN\fP(\fIx\fP)
+The drive does not have a tape in place.
+.TP
+\fBGMT_IM_REP_EN\fP(\fIx\fP)
+Immediate report mode.
+This bit is set if there are no guarantees that
+the data has been physically written to the tape when the write call
+returns.
+It is set zero only when the driver does not buffer data and
+the drive is set not to buffer data.
+.TP
+\fBGMT_CLN\fP(\fIx\fP)
+The drive has requested cleaning.
+Implemented since Linux 2.4.19 and Linux 2.5.43.
+.RE
+.TP
+\fImt_erreg\fP
+The only field defined in
+.I mt_erreg
+is the recovered error count in the low 16 bits (as defined by
+.B MT_ST_SOFTERR_SHIFT
+and
+.BR MT_ST_SOFTERR_MASK ).
+Due to inconsistencies in the way drives report recovered errors, this
+count is often not maintained (most drives do not by default report
+soft errors but this can be changed with a SCSI MODE SELECT command).
+.TP
+\fImt_fileno\fP
+reports the current file number (zero-based).
+This value is set to \-1 when the file number is unknown (e.g., after
+.B MTBSS
+or
+.BR MTSEEK ).
+.TP
+\fImt_blkno\fP
+reports the block number (zero-based) within the current file.
+This value is set to \-1 when the block number is unknown (e.g., after
+.BR MTBSF ,
+.BR MTBSS ,
+or
+.BR MTSEEK ).
+.SS MTIOCPOS \[em] get tape position
+This request takes an argument of type
+.I "(struct mtpos\ *)"
+and reports the drive's notion of the current tape block number,
+which is not the same as
+.I mt_blkno
+returned by
+.BR MTIOCGET .
+This drive must be a SCSI-2 drive that supports the
+.B "READ POSITION"
+command (device-specific address)
+or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive
+Viper, Wangtek, ... ).
+.P
+.in +4n
+.EX
+/* structure for MTIOCPOS \- mag tape get position command */
+struct mtpos {
+    long mt_blkno;    /* current block number */
+};
+.EE
+.in
+.SH RETURN VALUE
+.TP
+.B EACCES
+An attempt was made to write or erase a write-protected tape.
+(This error is not detected during
+.BR open (2).)
+.TP
+.B EBUSY
+The device is already in use or the driver was unable to allocate a
+buffer.
+.TP
+.B EFAULT
+The command parameters point to memory not belonging to the calling
+process.
+.TP
+.B EINVAL
+An
+.BR ioctl (2)
+had an invalid argument, or a requested block size was invalid.
+.TP
+.B EIO
+The requested operation could not be completed.
+.TP
+.B ENOMEM
+The byte count in
+.BR read (2)
+is smaller than the next physical block on the tape.
+(Before Linux 2.2.18 and Linux 2.4.0 the extra bytes have been
+.\" Precisely: Linux 2.6.0-test6
+silently ignored.)
+.TP
+.B ENOSPC
+A write operation could not be completed because the tape reached
+end-of-medium.
+.TP
+.B ENOSYS
+Unknown
+.BR ioctl (2).
+.TP
+.B ENXIO
+During opening, the tape device does not exist.
+.TP
+.B EOVERFLOW
+An attempt was made to read or write a variable-length block that is
+larger than the driver's internal buffer.
+.TP
+.B EROFS
+Open is attempted with
+.B O_WRONLY
+or
+.B O_RDWR
+when the tape in the drive is write-protected.
+.SH FILES
+.TP
+.I /dev/st*
+the auto-rewind SCSI tape devices
+.TP
+.I /dev/nst*
+the nonrewind SCSI tape devices
+.\" .SH AUTHOR
+.\" The driver has been written by Kai M\(:akisara (Kai.Makisara@metla.fi)
+.\" starting from a driver written by Dwayne Forsyth.
+.\" Several other
+.\" people have also contributed to the driver.
+.SH NOTES
+.IP \[bu] 3
+When exchanging data between systems, both systems have to agree on
+the physical tape block size.
+The parameters of a drive after startup
+are often not the ones most operating systems use with these
+devices.
+Most systems use drives in variable-block mode if the drive
+supports that mode.
+This applies to most modern drives, including
+DATs, 8mm helical scan drives, DLTs, etc.
+It may be advisable to use
+these drives in variable-block mode also in Linux (i.e., use
+.B MTSETBLK
+or
+.B MTSETDEFBLK
+at system startup to set the mode), at least when
+exchanging data with a foreign system.
+The drawback of
+this is that a fairly large tape block size has to be used to get
+acceptable data transfer rates on the SCSI bus.
+.IP \[bu]
+Many programs (e.g.,
+.BR tar (1))
+allow the user to specify the blocking
+factor on the command line.
+Note that this determines the physical block
+size on tape only in variable-block mode.
+.IP \[bu]
+In order to use SCSI tape drives, the basic SCSI driver,
+a SCSI-adapter driver and the SCSI tape driver must be either
+configured into the kernel or loaded as modules.
+If the SCSI-tape
+driver is not present, the drive is recognized but the tape support
+described in this page is not available.
+.IP \[bu]
+The driver writes error messages to the console/log.
+The SENSE
+codes written into some messages are automatically translated to text
+if verbose SCSI messages are enabled in kernel configuration.
+.IP \[bu]
+The driver's internal buffering allows good throughput in fixed-block
+mode also with small
+.BR read (2)
+and
+.BR write (2)
+byte counts.
+With direct transfers
+this is not possible and may cause a surprise when moving to the 2.6
+kernel.
+The solution is to tell the software to use larger transfers (often
+telling it to use larger blocks).
+If this is not possible, direct transfers can be disabled.
+.SH SEE ALSO
+.BR mt (1)
+.P
+The file
+.I drivers/scsi/README.st
+or
+.I Documentation/scsi/st.txt
+(kernel >= 2.6) in the Linux kernel source tree contains
+the most recent information about the driver and its configuration
+possibilities