1223 lines
33 KiB
HTML
1223 lines
33 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of ST</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>ST</H1>
|
|
Section: Linux Programmer's Manual (4)<BR>Updated: 2019-03-06<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
st - SCSI tape device
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/sys/mtio.h">sys/mtio.h</A>></B>
|
|
|
|
<B>int ioctl(int </B><I>fd</I><B>, int </B><I>request</I><B> [, (void *)</B><I>arg3</I><B>]);</B>
|
|
<B>int ioctl(int </B><I>fd</I><B>, MTIOCTOP, (struct mtop *)</B><I>mt_cmd</I><B>);</B>
|
|
<B>int ioctl(int </B><I>fd</I><B>, MTIOCGET, (struct mtget *)</B><I>mt_status</I><B>);</B>
|
|
<B>int ioctl(int </B><I>fd</I><B>, MTIOCPOS, (struct mtpos *)</B><I>mt_pos</I><B>);</B>
|
|
</PRE>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
The
|
|
<B>st</B>
|
|
|
|
driver provides the interface to a variety of SCSI tape devices.
|
|
Currently, the driver takes control of all detected devices of type
|
|
"sequential-access".
|
|
The
|
|
<B>st</B>
|
|
|
|
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,
|
|
<I>n</I>,
|
|
|
|
and the "no-rewind" device numbers,
|
|
(<I>n</I> + 128).
|
|
|
|
Devices opened using the principal device number will be sent a
|
|
<B>REWIND</B>
|
|
|
|
command when they are closed.
|
|
Devices opened using the "no-rewind" 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>
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
<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.
|
|
In kernels before 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 with kernels older than 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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A></B>(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</B>
|
|
|
|
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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A></B>(2).
|
|
|
|
The tape
|
|
location is preserved within each partition across partition changes.
|
|
The partition used for subsequent tape operations is
|
|
selected with an
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A></B>(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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A></B>(2)
|
|
|
|
that can format a tape with either one or two partitions.
|
|
<P>
|
|
|
|
Device
|
|
<I>/dev/tape</I>
|
|
|
|
is usually created as a hard or soft link to the default tape device
|
|
on the system.
|
|
<P>
|
|
|
|
Starting from kernel 2.6.2, the driver exports in the sysfs directory
|
|
<I>/sys/class/scsi_tape</I>
|
|
|
|
the attached devices and some parameters assigned to the devices.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Data transfer</H3>
|
|
|
|
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.
|
|
Kernels before 2.1.121 allow writes with
|
|
arbitrary byte count if buffering is enabled.
|
|
In all other cases
|
|
(kernel before 2.1.121 with buffering disabled or newer kernel) the
|
|
write byte count must be a multiple of the tape block size.
|
|
<P>
|
|
|
|
In the 2.6 kernel, 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.
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Ioctls</H3>
|
|
|
|
The driver supports three
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A></B>(2)
|
|
|
|
requests.
|
|
Requests not recognized by the
|
|
<B>st</B>
|
|
|
|
driver are passed to the
|
|
<B>SCSI</B>
|
|
|
|
driver.
|
|
The definitions below are from
|
|
<I>/usr/include/linux/mtio.h</I>:
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H3>MTIOCTOP --- perform a tape operation</H3>
|
|
|
|
<P>
|
|
|
|
This request takes an argument of type
|
|
<I>(struct mtop *)</I>.
|
|
|
|
Not all drives support all operations.
|
|
The driver returns an
|
|
<B>EIO</B>
|
|
|
|
error if the drive rejects an operation.
|
|
<P>
|
|
|
|
|
|
|
|
/* Structure for MTIOCTOP - mag tape op command: */
|
|
struct mtop {
|
|
<BR> short mt_op; /* operations defined below */
|
|
<BR> int mt_count; /* how many of them */
|
|
};
|
|
|
|
|
|
<P>
|
|
|
|
Magnetic Tape operations for normal tape use:
|
|
<DL COMPACT>
|
|
<DT id="1"><B>MTBSF</B>
|
|
|
|
<DD>
|
|
Backward space over
|
|
<I>mt_count</I>
|
|
|
|
filemarks.
|
|
<DT id="2"><B>MTBSFM</B>
|
|
|
|
<DD>
|
|
Backward space over
|
|
<I>mt_count</I>
|
|
|
|
filemarks.
|
|
Reposition the tape to the EOT side of the last filemark.
|
|
<DT id="3"><B>MTBSR</B>
|
|
|
|
<DD>
|
|
Backward space over
|
|
<I>mt_count</I>
|
|
|
|
records (tape blocks).
|
|
<DT id="4"><B>MTBSS</B>
|
|
|
|
<DD>
|
|
Backward space over
|
|
<I>mt_count</I>
|
|
|
|
setmarks.
|
|
<DT id="5"><B>MTCOMPRESSION</B>
|
|
|
|
<DD>
|
|
Enable compression of tape data within the drive if
|
|
<I>mt_count</I>
|
|
|
|
is nonzero and disable compression if
|
|
<I>mt_count</I>
|
|
|
|
is zero.
|
|
This command uses the MODE page 15 supported by most DATs.
|
|
<DT id="6"><B>MTEOM</B>
|
|
|
|
<DD>
|
|
Go to the end of the recorded media (for appending files).
|
|
<DT id="7"><B>MTERASE</B>
|
|
|
|
<DD>
|
|
Erase tape.
|
|
With 2.6 kernel, short erase (mark tape empty) is performed if the
|
|
argument is zero.
|
|
Otherwise, long erase (erase all) is done.
|
|
<DT id="8"><B>MTFSF</B>
|
|
|
|
<DD>
|
|
Forward space over
|
|
<I>mt_count</I>
|
|
|
|
filemarks.
|
|
<DT id="9"><B>MTFSFM</B>
|
|
|
|
<DD>
|
|
Forward space over
|
|
<I>mt_count</I>
|
|
|
|
filemarks.
|
|
Reposition the tape to the BOT side of the last filemark.
|
|
<DT id="10"><B>MTFSR</B>
|
|
|
|
<DD>
|
|
Forward space over
|
|
<I>mt_count</I>
|
|
|
|
records (tape blocks).
|
|
<DT id="11"><B>MTFSS</B>
|
|
|
|
<DD>
|
|
Forward space over
|
|
<I>mt_count</I>
|
|
|
|
setmarks.
|
|
<DT id="12"><B>MTLOAD</B>
|
|
|
|
<DD>
|
|
Execute the SCSI load command.
|
|
A special case is available for some HP
|
|
autoloaders.
|
|
If
|
|
<I>mt_count</I>
|
|
|
|
is the constant
|
|
<B>MT_ST_HPLOADER_OFFSET</B>
|
|
|
|
plus a number, the number is
|
|
sent to the drive to control the autoloader.
|
|
<DT id="13"><B>MTLOCK</B>
|
|
|
|
<DD>
|
|
Lock the tape drive door.
|
|
<DT id="14"><B>MTMKPART</B>
|
|
|
|
<DD>
|
|
Format the tape into one or two partitions.
|
|
If
|
|
<I>mt_count</I>
|
|
|
|
is positive, it gives the size of partition 1 and partition
|
|
0 contains the rest of the tape.
|
|
If
|
|
<I>mt_count</I>
|
|
|
|
is zero, the tape is formatted into one partition.
|
|
From kernel version 4.6,
|
|
|
|
a negative
|
|
<I>mt_count</I>
|
|
|
|
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</B>
|
|
|
|
below).
|
|
<DT id="15"><B>MTNOP</B>
|
|
|
|
<DD>
|
|
No op---flushes the driver's buffer as a side effect.
|
|
Should be used before reading status with
|
|
<B>MTIOCGET</B>.
|
|
|
|
<DT id="16"><B>MTOFFL</B>
|
|
|
|
<DD>
|
|
Rewind and put the drive off line.
|
|
<DT id="17"><B>MTRESET</B>
|
|
|
|
<DD>
|
|
Reset drive.
|
|
<DT id="18"><B>MTRETEN</B>
|
|
|
|
<DD>
|
|
Re-tension tape.
|
|
<DT id="19"><B>MTREW</B>
|
|
|
|
<DD>
|
|
Rewind.
|
|
<DT id="20"><B>MTSEEK</B>
|
|
|
|
<DD>
|
|
Seek to the tape block number specified in
|
|
<I>mt_count</I>.
|
|
|
|
This operation requires either a SCSI-2 drive that supports the
|
|
<B>LOCATE</B>
|
|
|
|
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</B>
|
|
|
|
if device-specific addresses are used.
|
|
<DT id="21"><B>MTSETBLK</B>
|
|
|
|
<DD>
|
|
Set the drive's block length to the value specified in
|
|
<I>mt_count</I>.
|
|
|
|
A block length of zero sets the drive to variable block size mode.
|
|
<DT id="22"><B>MTSETDENSITY</B>
|
|
|
|
<DD>
|
|
Set the tape density to the code in
|
|
<I>mt_count</I>.
|
|
|
|
The density codes supported by a drive can be found from the drive
|
|
documentation.
|
|
<DT id="23"><B>MTSETPART</B>
|
|
|
|
<DD>
|
|
The active partition is switched to
|
|
<I>mt_count</I>.
|
|
|
|
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</B>
|
|
|
|
below).
|
|
<DT id="24"><B>MTUNLOAD</B>
|
|
|
|
<DD>
|
|
Execute the SCSI unload command (does not eject the tape).
|
|
<DT id="25"><B>MTUNLOCK</B>
|
|
|
|
<DD>
|
|
Unlock the tape drive door.
|
|
<DT id="26"><B>MTWEOF</B>
|
|
|
|
<DD>
|
|
Write
|
|
<I>mt_count</I>
|
|
|
|
filemarks.
|
|
<DT id="27"><B>MTWSM</B>
|
|
|
|
<DD>
|
|
Write
|
|
<I>mt_count</I>
|
|
|
|
setmarks.
|
|
</DL>
|
|
<P>
|
|
|
|
Magnetic Tape operations for setting of device options (by the superuser):
|
|
<DL COMPACT>
|
|
<DT id="28"><B>MTSETDRVBUFFER</B>
|
|
|
|
<DD>
|
|
Set various drive and driver options according to bits encoded in
|
|
<I>mt_count</I>.
|
|
|
|
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 in kernels 2.1 and later).
|
|
A single operation can affect only one item in the list above (the
|
|
Booleans counted as one item.)
|
|
<DT id="29"><DD>
|
|
A value having zeros in the high-order 4 bits will be used to set the
|
|
drive's buffering mode.
|
|
The buffering modes are:
|
|
<DL COMPACT><DT id="30"><DD>
|
|
<DL COMPACT>
|
|
<DT id="31">0<DD>
|
|
The drive will not report
|
|
<B>GOOD</B>
|
|
|
|
status on write commands until the data
|
|
blocks are actually written to the medium.
|
|
<DT id="32">1<DD>
|
|
The drive may report
|
|
<B>GOOD</B>
|
|
|
|
status on write commands as soon as all the
|
|
data has been transferred to the drive's internal buffer.
|
|
<DT id="33">2<DD>
|
|
The drive may report
|
|
<B>GOOD</B>
|
|
|
|
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.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="34"><DD>
|
|
To control the write threshold the value in
|
|
<I>mt_count</I>
|
|
|
|
must include the constant
|
|
<B>MT_ST_WRITE_THRESHOLD</B>
|
|
|
|
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).
|
|
<DT id="35"><DD>
|
|
To set and clear the Boolean options
|
|
the value in
|
|
<I>mt_count</I>
|
|
|
|
must include one of the constants
|
|
<B>MT_ST_BOOLEANS</B>,
|
|
|
|
<B>MT_ST_SETBOOLEANS</B>,
|
|
|
|
<B>MT_ST_CLEARBOOLEANS</B>,
|
|
|
|
or
|
|
<B>MT_ST_DEFBOOLEANS</B>
|
|
|
|
bitwise ORed with
|
|
whatever combination of the following options is desired.
|
|
Using
|
|
<B>MT_ST_BOOLEANS</B>
|
|
|
|
the options can be set to the values
|
|
defined in the corresponding bits.
|
|
With
|
|
<B>MT_ST_SETBOOLEANS</B>
|
|
|
|
the options can be selectively set and with
|
|
<B>MT_ST_DEFBOOLEANS</B>
|
|
|
|
selectively cleared.
|
|
<DT id="36"><DD>
|
|
The default options for a tape device are set with
|
|
<B>MT_ST_DEFBOOLEANS</B>.
|
|
|
|
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.
|
|
<DT id="37"><DD>
|
|
The Boolean options are:
|
|
<DL COMPACT><DT id="38"><DD>
|
|
<DL COMPACT>
|
|
<DT id="39"><B>MT_ST_BUFFER_WRITES</B> (Default: true)
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="40"><B>MT_ST_ASYNC_WRITES</B> (Default: true)
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="41"><B>MT_ST_READ_AHEAD</B> (Default: true)
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="42"><B>MT_ST_TWO_FM</B> (Default: false)
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="43"><DD>
|
|
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.
|
|
<DT id="44"><B>MT_ST_DEBUGGING</B> (Default: false)
|
|
|
|
<DD>
|
|
This option turns on various debugging messages from the driver
|
|
(effective only if the driver was compiled with
|
|
<B>DEBUG</B>
|
|
|
|
defined nonzero).
|
|
<DT id="45"><B>MT_ST_FAST_EOM</B> (Default: false)
|
|
|
|
<DD>
|
|
This option causes the
|
|
<B>MTEOM</B>
|
|
|
|
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</B>
|
|
|
|
request.
|
|
If
|
|
<B>MT_ST_FAST_EOM</B>
|
|
|
|
is false, the driver will respond to an
|
|
<B>MTEOM</B>
|
|
|
|
request by forward spacing over files.
|
|
<DT id="46"><B>MT_ST_AUTO_LOCK</B> (Default: false)
|
|
|
|
<DD>
|
|
When this option is true, the drive door is locked when the device is
|
|
opened and unlocked when it is closed.
|
|
<DT id="47"><B>MT_ST_DEF_WRITES</B> (Default: false)
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="48"><B>MT_ST_CAN_BSR</B> (Default: false)
|
|
|
|
<DD>
|
|
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 2.6 kernel, the
|
|
default is true for drives supporting SCSI-3.
|
|
<DT id="49"><B>MT_ST_NO_BLKLIMS</B> (Default: false)
|
|
|
|
<DD>
|
|
Some drives don't accept the
|
|
<B>READ BLOCK LIMITS</B>
|
|
|
|
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.
|
|
<DT id="50"><B>MT_ST_CAN_PARTITIONS</B> (Default: false)
|
|
|
|
<DD>
|
|
This option enables support for several partitions within a
|
|
tape.
|
|
The option applies to all devices linked to a drive.
|
|
<DT id="51"><B>MT_ST_SCSI2LOGICAL</B> (Default: false)
|
|
|
|
<DD>
|
|
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</B>
|
|
|
|
and
|
|
<B>MTIOCPOS</B>
|
|
|
|
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.
|
|
<DT id="52"><B>MT_ST_SYSV</B> (Default: false)
|
|
|
|
<DD>
|
|
When this option is enabled, the tape devices use the SystemV
|
|
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.
|
|
<DT id="53"><B>MT_NO_WAIT</B> (Default: false)
|
|
|
|
<DD>
|
|
Enables immediate mode (i.e., don't wait for the command to finish) for some
|
|
commands (e.g., rewind).
|
|
</DL>
|
|
<P>
|
|
|
|
An example:
|
|
<P>
|
|
|
|
|
|
|
|
struct mtop mt_cmd;
|
|
mt_cmd.mt_op = MTSETDRVBUFFER;
|
|
mt_cmd.mt_count = MT_ST_BOOLEANS |
|
|
<BR> MT_ST_BUFFER_WRITES | MT_ST_ASYNC_WRITES;
|
|
ioctl(fd, MTIOCTOP, mt_cmd);
|
|
|
|
|
|
</DL>
|
|
|
|
<DT id="54"><DD>
|
|
The default block size for a device can be set with
|
|
<B>MT_ST_DEF_BLKSIZE</B>
|
|
|
|
and the default density code can be set with
|
|
<B>MT_ST_DEFDENSITY</B>.
|
|
|
|
The values for the parameters are or'ed
|
|
with the operation code.
|
|
<DT id="55"><DD>
|
|
With kernels 2.1.x and later, the timeout values can be set with the
|
|
subcommand
|
|
<B>MT_ST_SET_TIMEOUT</B>
|
|
|
|
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
|
|
<B>MT_ST_SET_LONG_TIMEOUT</B>.
|
|
|
|
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.
|
|
<DT id="56"><DD>
|
|
Starting from kernels 2.4.19 and 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</B>
|
|
|
|
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-17 are
|
|
reserved.
|
|
If the lowest eight bits are >= 18, bits from the extended
|
|
sense data are used.
|
|
The bits 9-16 specify a mask to select the bits
|
|
to look at and the bits 17-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.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H3>MTIOCGET --- get status</H3>
|
|
|
|
<P>
|
|
|
|
This request takes an argument of type
|
|
<I>(struct mtget *)</I>.
|
|
|
|
<P>
|
|
|
|
|
|
|
|
/* structure for MTIOCGET - mag tape get status command */
|
|
struct mtget {
|
|
<BR> long mt_type;
|
|
<BR> long mt_resid;
|
|
<BR> /* the following registers are device dependent */
|
|
<BR> long mt_dsreg;
|
|
<BR> long mt_gstat;
|
|
<BR> long mt_erreg;
|
|
<BR> /* The next two fields are not always used */
|
|
<BR> daddr_t mt_fileno;
|
|
<BR> daddr_t mt_blkno;
|
|
};
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="57"><I>mt_type</I><DD>
|
|
The header file defines many values for
|
|
<I>mt_type</I>,
|
|
|
|
but the current driver reports only the generic types
|
|
<B>MT_ISSCSI1</B>
|
|
|
|
(Generic SCSI-1 tape)
|
|
and
|
|
<B>MT_ISSCSI2</B>
|
|
|
|
(Generic SCSI-2 tape).
|
|
<DT id="58"><I>mt_resid</I><DD>
|
|
contains the current tape partition number.
|
|
<DT id="59"><I>mt_dsreg</I><DD>
|
|
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
|
|
<B>MT_ST_BLKSIZE_SHIFT</B>,
|
|
|
|
<B>MT_ST_BLKSIZE_MASK</B>,
|
|
|
|
<B>MT_ST_DENSITY_SHIFT</B>,
|
|
|
|
and
|
|
<B>MT_ST_DENSITY_MASK</B>.
|
|
|
|
<DT id="60"><I>mt_gstat</I><DD>
|
|
reports generic (device independent) status information.
|
|
The header file defines macros for testing these status bits:
|
|
<DL COMPACT><DT id="61"><DD>
|
|
<DL COMPACT>
|
|
<DT id="62">
|
|
<B>GMT_EOF</B>(<I>x</I>):
|
|
<DD>The tape is positioned just after a filemark
|
|
(always false after an
|
|
<B>MTSEEK</B>
|
|
|
|
operation).
|
|
<DT id="63">
|
|
<B>GMT_BOT</B>(<I>x</I>):
|
|
<DD>The tape is positioned at the beginning of the first file (always false
|
|
after an
|
|
<B>MTSEEK</B>
|
|
|
|
operation).
|
|
<DT id="64">
|
|
<B>GMT_EOT</B>(<I>x</I>):
|
|
<DD>A tape operation has reached the physical End Of Tape.
|
|
<DT id="65">
|
|
<B>GMT_SM</B>(<I>x</I>):
|
|
<DD>The tape is currently positioned at a setmark
|
|
(always false after an
|
|
<B>MTSEEK</B>
|
|
|
|
operation).
|
|
<DT id="66">
|
|
<B>GMT_EOD</B>(<I>x</I>):
|
|
<DD>The tape is positioned at the end of recorded data.
|
|
<DT id="67">
|
|
<B>GMT_WR_PROT</B>(<I>x</I>):
|
|
<DD>The drive is write-protected.
|
|
For some drives this can also mean that the drive does not support
|
|
writing on the current medium type.
|
|
<DT id="68">
|
|
<B>GMT_ONLINE</B>(<I>x</I>):
|
|
<DD>The last
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2)
|
|
|
|
found the drive with a tape in place and ready for operation.
|
|
<DT id="69">
|
|
<B>GMT_D_6250</B>(<I>x</I>), <B>GMT_D_1600</B>(<I>x</I>), <B>GMT_D_800</B>(<I>x</I>):
|
|
<DD>This "generic" status information reports the current
|
|
density setting for 9-track ½" tape drives only.
|
|
<DT id="70">
|
|
<B>GMT_DR_OPEN</B>(<I>x</I>):
|
|
<DD>The drive does not have a tape in place.
|
|
<DT id="71">
|
|
<B>GMT_IM_REP_EN</B>(<I>x</I>):
|
|
<DD>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.
|
|
<DT id="72">
|
|
<B>GMT_CLN</B>(<I>x</I>):
|
|
<DD>The drive has requested cleaning.
|
|
Implemented in kernels since 2.4.19 and 2.5.43.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="73"><I>mt_erreg</I><DD>
|
|
The only field defined in
|
|
<I>mt_erreg</I>
|
|
|
|
is the recovered error count in the low 16 bits (as defined by
|
|
<B>MT_ST_SOFTERR_SHIFT</B>
|
|
|
|
and
|
|
<B>MT_ST_SOFTERR_MASK</B>.
|
|
|
|
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).
|
|
<DT id="74"><I>mt_fileno</I><DD>
|
|
reports the current file number (zero-based).
|
|
This value is set to -1 when the file number is unknown (e.g., after
|
|
<B>MTBSS</B>
|
|
|
|
or
|
|
<B>MTSEEK</B>).
|
|
|
|
<DT id="75"><I>mt_blkno</I><DD>
|
|
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
|
|
<B>MTBSF</B>,
|
|
|
|
<B>MTBSS</B>,
|
|
|
|
or
|
|
<B>MTSEEK</B>).
|
|
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H3>MTIOCPOS --- get tape position</H3>
|
|
|
|
<P>
|
|
|
|
This request takes an argument of type
|
|
<I>(struct mtpos *)</I>
|
|
|
|
and reports the drive's notion of the current tape block number,
|
|
which is not the same as
|
|
<I>mt_blkno</I>
|
|
|
|
returned by
|
|
<B>MTIOCGET</B>.
|
|
|
|
This drive must be a SCSI-2 drive that supports the
|
|
<B>READ POSITION</B>
|
|
|
|
command (device-specific address)
|
|
or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive
|
|
Viper, Wangtek, ... ).
|
|
<P>
|
|
|
|
|
|
|
|
/* structure for MTIOCPOS - mag tape get position command */
|
|
struct mtpos {
|
|
<BR> long mt_blkno; /* current block number */
|
|
};
|
|
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="76"><DT><B>EACCES</B>
|
|
|
|
<DD>
|
|
<DD>
|
|
An attempt was made to write or erase a write-protected tape.
|
|
(This error is not detected during
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2).)
|
|
|
|
<DT id="77"><B>EBUSY</B>
|
|
|
|
<DD>
|
|
The device is already in use or the driver was unable to allocate a
|
|
buffer.
|
|
<DT id="78"><B>EFAULT</B>
|
|
|
|
<DD>
|
|
The command parameters point to memory not belonging to the calling
|
|
process.
|
|
<DT id="79"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
An
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A></B>(2)
|
|
|
|
had an invalid argument, or a requested block size was invalid.
|
|
<DT id="80"><B>EIO</B>
|
|
|
|
<DD>
|
|
The requested operation could not be completed.
|
|
<DT id="81"><B>ENOMEM</B>
|
|
|
|
<DD>
|
|
The byte count in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+read">read</A></B>(2)
|
|
|
|
is smaller than the next physical block on the tape.
|
|
(Before 2.2.18 and 2.4.0 the extra bytes have been
|
|
|
|
silently ignored.)
|
|
<DT id="82"><B>ENOSPC</B>
|
|
|
|
<DD>
|
|
A write operation could not be completed because the tape reached
|
|
end-of-medium.
|
|
<DT id="83"><B>ENOSYS</B>
|
|
|
|
<DD>
|
|
Unknown
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ioctl">ioctl</A></B>(2).
|
|
|
|
<DT id="84"><B>ENXIO</B>
|
|
|
|
<DD>
|
|
During opening, the tape device does not exist.
|
|
<DT id="85"><B>EOVERFLOW</B>
|
|
|
|
<DD>
|
|
An attempt was made to read or write a variable-length block that is
|
|
larger than the driver's internal buffer.
|
|
<DT id="86"><B>EROFS</B>
|
|
|
|
<DD>
|
|
Open is attempted with
|
|
<B>O_WRONLY</B>
|
|
|
|
or
|
|
<B>O_RDWR</B>
|
|
|
|
when the tape in the drive is write-protected.
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="87"><I>/dev/st*</I>
|
|
|
|
<DD>
|
|
the auto-rewind SCSI tape devices
|
|
<DT id="88"><I>/dev/nst*</I>
|
|
|
|
<DD>
|
|
the nonrewind SCSI tape devices
|
|
|
|
|
|
|
|
|
|
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="89">1.<DD>
|
|
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</B>
|
|
|
|
or
|
|
<B>MTSETDEFBLK</B>
|
|
|
|
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.
|
|
<DT id="90">2.<DD>
|
|
Many programs (e.g.,
|
|
<B><A HREF="/cgi-bin/man/man2html?1+tar">tar</A></B>(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.
|
|
<DT id="91">3.<DD>
|
|
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.
|
|
<DT id="92">4.<DD>
|
|
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.
|
|
<DT id="93">5.<DD>
|
|
The driver's internal buffering allows good throughput in fixed-block
|
|
mode also with small
|
|
<B><A HREF="/cgi-bin/man/man2html?2+read">read</A></B>(2)
|
|
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(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.
|
|
</DL>
|
|
<A NAME="lbAM"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+mt">mt</A></B>(1)
|
|
|
|
<P>
|
|
|
|
The file
|
|
<I>drivers/scsi/README.st</I>
|
|
|
|
or
|
|
<I>Documentation/scsi/st.txt</I>
|
|
|
|
(kernel >= 2.6) in the Linux kernel source tree contains
|
|
the most recent information about the driver and its configuration
|
|
possibilities
|
|
<A NAME="lbAN"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="94"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="95"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="96"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="97"><A HREF="#lbAE">Data transfer</A><DD>
|
|
<DT id="98"><A HREF="#lbAF">Ioctls</A><DD>
|
|
<DT id="99"><A HREF="#lbAG">MTIOCTOP --- perform a tape operation</A><DD>
|
|
<DT id="100"><A HREF="#lbAH">MTIOCGET --- get status</A><DD>
|
|
<DT id="101"><A HREF="#lbAI">MTIOCPOS --- get tape position</A><DD>
|
|
</DL>
|
|
<DT id="102"><A HREF="#lbAJ">RETURN VALUE</A><DD>
|
|
<DT id="103"><A HREF="#lbAK">FILES</A><DD>
|
|
<DT id="104"><A HREF="#lbAL">NOTES</A><DD>
|
|
<DT id="105"><A HREF="#lbAM">SEE ALSO</A><DD>
|
|
<DT id="106"><A HREF="#lbAN">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:02 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|