mirror of https://github.com/mkerrisk/man-pages
Updates from Kai Makisara <Kai.Makisara@kolumbus.fi>, the author
of the st driver.
This commit is contained in:
parent
b6dd43ba57
commit
e2af0daf4a
162
man4/st.4
162
man4/st.4
|
@ -1,5 +1,5 @@
|
|||
.\" Copyright 1995 Robert K. Nichols (Robert.K.Nichols@att.com)
|
||||
.\" Copyright 1999 Kai Mäkisara (Kai.Makisara@metla.fi)
|
||||
.\" Copyright 1999-2005 Kai Mäkisara (Kai.Makisara@kolumbus.fi)
|
||||
.\"
|
||||
.\" Permission is granted to make and distribute verbatim copies of this
|
||||
.\" manual provided the copyright notice and this permission notice are
|
||||
|
@ -9,7 +9,7 @@
|
|||
.\" manual under the conditions for verbatim copying, provided that the
|
||||
.\" entire resulting derived work is distributed under the terms of a
|
||||
.\" permission notice identical to this one.
|
||||
.\"
|
||||
.\"
|
||||
.\" Since the Linux kernel and libraries are constantly changing, this
|
||||
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
||||
.\" responsibility for errors or omissions, or for damages resulting from
|
||||
|
@ -17,10 +17,10 @@
|
|||
.\" have taken the same level of care in the production of this manual,
|
||||
.\" which is licensed free of charge, as they might when working
|
||||
.\" professionally.
|
||||
.\"
|
||||
.\"
|
||||
.\" Formatted or processed versions of this manual, if unaccompanied by
|
||||
.\" the source, must acknowledge the copyright and authors of this work.
|
||||
.TH ST 4 1999-01-18 "Linux 2.0 - 2.2" "Linux Programmer's Manual"
|
||||
.TH ST 4 2005-03-13 "Linux 2.0 - 2.6" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
st \- SCSI tape device
|
||||
.SH SYNOPSIS
|
||||
|
@ -44,10 +44,12 @@ driver uses major device number 9.
|
|||
.PP
|
||||
Each device uses eight minor device numbers. The lower-most five bits
|
||||
in the minor numbers are assigned sequentially in the order of
|
||||
detection. The minor numbers can be grouped into
|
||||
detection. In the 2.6 kernel, the bits above the eight lower-most bits are
|
||||
concatenated to the five lower-most 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 a \(lqno-rewind\(rq device numbers,
|
||||
and the \(lqno-rewind\(rq device numbers,
|
||||
.IR "" ( n "+ 128)."
|
||||
Devices opened using the principal device number will be sent a
|
||||
\s-1REWIND\s+1 command when they are closed.
|
||||
|
@ -88,8 +90,8 @@ 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 the 32-bit architectures and
|
||||
256 kB for the 64-bit architectures. In newer kernels the driver
|
||||
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).
|
||||
|
@ -104,8 +106,9 @@ too much on dynamic buffer allocation with kernels older than 2.1.121
|
|||
.PP
|
||||
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
|
||||
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 ioctl()
|
||||
calls and remain in effect when the device is closed and reopened.
|
||||
|
@ -115,8 +118,8 @@ device.
|
|||
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
|
||||
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).
|
||||
.PP
|
||||
The driver supports
|
||||
|
@ -137,31 +140,44 @@ Device
|
|||
.B /dev/tape
|
||||
is usually created as a hard or soft link to the default tape device
|
||||
on the system.
|
||||
.PP
|
||||
Starting from kernel 2.6.2, the driver exports in the sysfs directory
|
||||
.BR /sys/class/scsi_tape
|
||||
the attached devices and some parameters assigned to the devices.
|
||||
.SH "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
|
||||
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
|
||||
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 do don't contain any information about the
|
||||
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.
|
||||
.PP
|
||||
In variable block mode the read byte count does not have to match
|
||||
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, the requested amount of data from the start of the block
|
||||
is returned and the rest of the block is discarded.
|
||||
.PP
|
||||
In fixed block mode the read byte counts can be arbitrary if
|
||||
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.
|
||||
.PP
|
||||
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 of more pages of the user buffer not reachable by the
|
||||
SCSI adapter, etc.
|
||||
.PP
|
||||
A filemark is automatically written to tape if the last tape operation
|
||||
before close was a write.
|
||||
.PP
|
||||
|
@ -191,8 +207,8 @@ The driver returns an EIO error if the drive rejects an operation.
|
|||
.ta +.4i +.7i +1i
|
||||
/* Structure for \s-1MTIOCTOP\s+1 \- mag tape op command: */
|
||||
struct mtop {
|
||||
short mt_op; /* operations defined below */
|
||||
int mt_count; /* how many of them */
|
||||
short mt_op; /* operations defined below */
|
||||
int mt_count; /* how many of them */
|
||||
};
|
||||
.fi
|
||||
.PP
|
||||
|
@ -224,7 +240,8 @@ is zero. This command uses the MODE page 15 supported by most DATs.
|
|||
.IP MTEOM
|
||||
Go to the end of the recorded media (for appending files).
|
||||
.IP MTERASE
|
||||
Erase tape.
|
||||
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.
|
||||
.IP MTFSF
|
||||
Forward space over
|
||||
.B mt_count
|
||||
|
@ -290,7 +307,7 @@ The density codes supported by a drive can be found from the drive
|
|||
documentation.
|
||||
.IP MTSETPART
|
||||
The active partition is switched to
|
||||
.B mt_count .
|
||||
.BR 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
|
||||
MT_ST_CAN_PARTITIONS below).
|
||||
|
@ -299,7 +316,7 @@ Execute the SCSI unload command (does not eject the tape).
|
|||
.IP MTUNLOCK
|
||||
Unlock the tape drive door.
|
||||
.IP MTWEOF
|
||||
Write
|
||||
Write
|
||||
.B mt_count
|
||||
filemarks.
|
||||
.IP MTWSM
|
||||
|
@ -313,7 +330,7 @@ Magnetic Tape operations for setting of device options (by the superuser):
|
|||
.IP MTSETDRVBUFFER 8
|
||||
Set various drive and driver options according to bits encoded in
|
||||
.BR mt_count .
|
||||
These consist of the drive's buffering mode, 13 Boolean driver
|
||||
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).
|
||||
A single operation can affect only one item in the list above (the
|
||||
|
@ -353,9 +370,9 @@ above).
|
|||
To set and clear the Boolean options
|
||||
the value in
|
||||
.B mt_count
|
||||
must include one the constants \s-1MT_ST_BOOLEANS\s+1,
|
||||
must include one of the constants \s-1MT_ST_BOOLEANS\s+1,
|
||||
\s-1MT_ST_SETBOOLEANS\s+1, \s-1MT_ST_CLEARBOOLEANS\s+1, or
|
||||
\s-1MT_ST_DEFBOOLEANS\s+1 logically ORed with
|
||||
\s-1MT_ST_DEFBOOLEANS\s+1 logically or'ed with
|
||||
whatever combination of the following options is desired.
|
||||
Using \s-1MT_ST_BOOLEANS\s+1 the options can be set to the values
|
||||
defined in the corresponding bits. With \s-1MT_ST_SETBOOLEANS\s+1 the
|
||||
|
@ -373,12 +390,12 @@ The Boolean options are:
|
|||
.PD 0
|
||||
.RS
|
||||
.IP "\s-1MT_ST_BUFFER_WRITES\s+1 (Default: true)"
|
||||
Buffer all write operations in fixed block mode.
|
||||
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 multi-volume archives.
|
||||
.IP "\s-1MT_ST_ASYNC_WRITES\s+1 (Default: true)"
|
||||
When this options is true write operations return immediately without
|
||||
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
|
||||
|
@ -388,7 +405,7 @@ operation.
|
|||
This option must be set false to write reliable multi-volume archives.
|
||||
.IP "\s-1MT_ST_READ_AHEAD\s+1 (Default: true)"
|
||||
This option causes the driver to provide read buffering and
|
||||
read-ahead in fixed block mode.
|
||||
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.
|
||||
.IP "\s-1MT_ST_TWO_FM\s+1 (Default: false)"
|
||||
|
@ -439,8 +456,9 @@ correct position when the device is closed and the SCSI command to
|
|||
space backwards 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 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.
|
||||
.IP "\s-1MT_ST_NO_BLKLIMS\s+1 (Default: false)"
|
||||
Some drives don't accept the READ BLOCK LIMITS SCSI command. If
|
||||
this is used, the driver does not use the command. The drawback is
|
||||
|
@ -464,14 +482,17 @@ difference between the semantics is what happens when a device used
|
|||
for reading is closed: in SYSV 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.
|
||||
.IP "\s-1MT_NO_WAIT\s+1 (Default: false)"
|
||||
Enables immediate mode (i.e., don't wait for the command to finish) for some
|
||||
commands (e.g., rewind).
|
||||
.IP \s-1EXAMPLE\s+1
|
||||
.nf
|
||||
.ta +.4i +.7i +1i
|
||||
.BI "struct mtop " mt_cmd ;
|
||||
.IB "mt_cmd.mt_op" " = \s-1MTSETDRVBUFFER\s+1;"
|
||||
.IB "mt_cmd.mt_count" " = \s-1MT_ST_BOOLEANS\s+1 |"
|
||||
.B " \s-1MT_ST_BUFFER_WRITES\s+1 |"
|
||||
.B " \s-1MT_ST_ASYNC_WRITES\s+1;"
|
||||
.B " \s-1MT_ST_BUFFER_WRITES\s+1 |"
|
||||
.B " \s-1MT_ST_ASYNC_WRITES\s+1;"
|
||||
.BI "ioctl(" fd ", \s-1MTIOCTOP\s+1, &" mt_cmd ");"
|
||||
.fi
|
||||
.RE
|
||||
|
@ -479,11 +500,11 @@ device. In BSD semantics the tape position is not changed.
|
|||
.IP ""
|
||||
The default block size for a device can be set with
|
||||
\s-1MT_ST_DEF_BLKSIZE\s+1 and the default density code can be set with
|
||||
\s-1MT_ST_DEFDENSITY\s+1. The values for the parameters are ORed
|
||||
\s-1MT_ST_DEFDENSITY\s+1. The values for the parameters are or'ed
|
||||
with the operation code.
|
||||
.IP ""
|
||||
With kernels 2.1.x and later, the timeout values can be set with the
|
||||
subcommand \s-1MT_ST_SET_TIMEOUT\s+1 or'ed with the timeout in seconds.
|
||||
subcommand \s-1MT_ST_SET_TIMEOUT\s+1 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
|
||||
\s-1MT_ST_SET_LONG_TIMEOUT\s+1. The kernel defaults are very long to
|
||||
|
@ -492,6 +513,20 @@ 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.
|
||||
.IP ""
|
||||
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
|
||||
\s-1MT_ST_SEL_CLN\s+1 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 non-zero, the pattern must match
|
||||
the masked sense data byte.
|
||||
.SS "\s-1MTIOCGET\s+1 \- Get status"
|
||||
.PP
|
||||
This request takes an argument of type
|
||||
|
@ -500,15 +535,15 @@ This request takes an argument of type
|
|||
.nf
|
||||
/* structure for \s-1MTIOCGET\s+1 - 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;
|
||||
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;
|
||||
};
|
||||
.fi
|
||||
.IP \fBmt_type\fP 11
|
||||
|
@ -569,6 +604,9 @@ 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.
|
||||
.HP
|
||||
\s-1GMT_CLN(\s+1\fIx\fP\s-1)\s+1:
|
||||
The drive has requested cleaning. Implemented in kernels >= 2.4.19 and 2.5.43.
|
||||
.RE
|
||||
.IP \fBmt_erreg\fP
|
||||
The only field defined in
|
||||
|
@ -604,8 +642,8 @@ Viper, Wangtek, ... ).
|
|||
.PP
|
||||
.nf
|
||||
/* structure for \s-1MTIOCPOS\s+1 - mag tape get position command */
|
||||
struct mtpos {
|
||||
long mt_blkno; /* current block number */
|
||||
struct mtpos {
|
||||
long mt_blkno; /* current block number */
|
||||
};
|
||||
|
||||
.fi
|
||||
|
@ -615,6 +653,10 @@ The requested operation could not be completed.
|
|||
.IP ENOSPC
|
||||
A write operation could not be completed because the tape reached
|
||||
end-of-medium.
|
||||
.IP ENOMEM
|
||||
The byte count in read() is smaller than the next physical block on
|
||||
the tape. (Before 2.2.18 and 2.4.0-test6 the extra bytes have been
|
||||
silently ignored.)
|
||||
.IP EACCES
|
||||
An attempt was made to write or erase a write-protected tape.
|
||||
(This error is not detected during
|
||||
|
@ -651,25 +693,25 @@ people have also contributed to the driver.
|
|||
.SH "SEE ALSO"
|
||||
.BR mt (1)
|
||||
.PP
|
||||
The file README.st in the kernel sources contains the most recent
|
||||
information about the driver and its configuration
|
||||
The file README.st or st.txt (kernel >= 2.6) in the kernel sources contains
|
||||
the most recent information about the driver and its configuration
|
||||
possibilities.
|
||||
.SH NOTES
|
||||
1. 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
|
||||
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 use
|
||||
these drives in variable block mode also in Linux (i.e., use MTSETBLK
|
||||
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 MTSETBLK
|
||||
or MTSETDEFBLK at system startup to set the mode), at least when
|
||||
exchanging data with foreign system. The drawback of
|
||||
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.
|
||||
.PP
|
||||
2. Many programs (e.g., tar) allow the user to specify the blocking
|
||||
factor on command line. Note that this determines the physical block
|
||||
size on tape only in variable block mode.
|
||||
factor on the command line. Note that this determines the physical block
|
||||
size on tape only in variable-block mode.
|
||||
.PP
|
||||
3. In order to use SCSI tape drives, the basic SCSI driver,
|
||||
a SCSI-adapter driver and the SCSI tape driver must be either
|
||||
|
@ -680,10 +722,18 @@ described in this page is not available.
|
|||
4. 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.
|
||||
.PP
|
||||
5. The driver's internal buffering allows good throughput in fixed-block
|
||||
mode also with small read() and write() 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 COPYRIGHT
|
||||
Copyright \(co 1995 Robert K. Nichols.
|
||||
.br
|
||||
Copyright \(co 1999 Kai M\(:akisara.
|
||||
Copyright \(co 1999-2005 Kai M\(:akisara.
|
||||
.PP
|
||||
Permission is granted to make and distribute verbatim copies of this
|
||||
manual provided the copyright notice and this permission notice are
|
||||
|
|
Loading…
Reference in New Issue