mirror of https://github.com/mkerrisk/man-pages
692 lines
27 KiB
Groff
692 lines
27 KiB
Groff
|
.\" Copyright 1995 Robert K. Nichols (Robert.K.Nichols@att.com)
|
|||
|
.\" Copyright 1999 Kai M<>kisara (Kai.Makisara@metla.fi)
|
|||
|
.\"
|
|||
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|||
|
.\" manual provided the copyright notice and this permission notice are
|
|||
|
.\" preserved on all copies.
|
|||
|
.\"
|
|||
|
.\" Permission is granted to copy and distribute modified versions of this
|
|||
|
.\" 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
|
|||
|
.\" the use of the information contained herein. The author(s) may not
|
|||
|
.\" 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"
|
|||
|
.SH NAME
|
|||
|
st \- SCSI tape device
|
|||
|
.SH SYNOPSIS
|
|||
|
.nf
|
|||
|
.B #include <sys/mtio.h>
|
|||
|
.sp
|
|||
|
.BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);"
|
|||
|
.BI "int ioctl(int " fd ", \s-1MTIOCTOP\s+1, (struct mtop *)" mt_cmd );
|
|||
|
.BI "int ioctl(int " fd ", \s-1MTIOCGET\s+1, (struct mtget *)" mt_status );
|
|||
|
.BI "int ioctl(int " fd ", \s-1MTIOCPOS\s+1, (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
|
|||
|
\(lqsequential-access.\(rq
|
|||
|
The
|
|||
|
.B st
|
|||
|
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
|
|||
|
two sets of four numbers: the principal (auto-rewind) minor device numbers,
|
|||
|
.IR n ,
|
|||
|
and a \(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.
|
|||
|
Devices opened using the \(lqno-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).
|
|||
|
.PP
|
|||
|
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.)
|
|||
|
.PP
|
|||
|
Devices are typically created by:
|
|||
|
.RS
|
|||
|
.nf
|
|||
|
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
|
|||
|
.fi
|
|||
|
.RE
|
|||
|
.PP
|
|||
|
There is no corresponding block device.
|
|||
|
.PP
|
|||
|
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
|
|||
|
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).
|
|||
|
.PP
|
|||
|
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).
|
|||
|
.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
|
|||
|
be changed with explicit
|
|||
|
.B ioctl()
|
|||
|
calls and remain in effect when the device is closed and reopened.
|
|||
|
Setting the options affects both the auto-rewind and the non-rewind
|
|||
|
device.
|
|||
|
.PP
|
|||
|
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).
|
|||
|
.PP
|
|||
|
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 ioctl. The tape
|
|||
|
location is preserved within each partition across partition changes.
|
|||
|
The partition used for subsequent tape operations is
|
|||
|
selected with an ioctl. 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
|
|||
|
ioctl that can format a tape with either one or two partitions.
|
|||
|
.PP
|
|||
|
Device
|
|||
|
.B /dev/tape
|
|||
|
is usually created as a hard or soft link to the default tape device
|
|||
|
on the system.
|
|||
|
.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
|
|||
|
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 do 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
|
|||
|
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
|
|||
|
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
|
|||
|
A filemark is automatically written to tape if the last tape operation
|
|||
|
before close was a write.
|
|||
|
.PP
|
|||
|
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.
|
|||
|
.SH IOCTLS
|
|||
|
The driver supports three ioctl requests.
|
|||
|
Requests not recognized by the
|
|||
|
.B st
|
|||
|
driver are passed to the
|
|||
|
.B SCSI
|
|||
|
driver.
|
|||
|
The definitions below are from
|
|||
|
.BR /usr/include/linux/mtio.h :
|
|||
|
.SS "\s-1MTIOCTOP\s+1 \- Perform a tape operation"
|
|||
|
.PP
|
|||
|
This request takes an argument of type
|
|||
|
.BR "(struct mtop *)" .
|
|||
|
Not all drives support all operations.
|
|||
|
The driver returns an EIO error if the drive rejects an operation.
|
|||
|
.PP
|
|||
|
.nf
|
|||
|
.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 */
|
|||
|
};
|
|||
|
.fi
|
|||
|
.PP
|
|||
|
Magnetic Tape operations for normal tape use:
|
|||
|
.PD 0
|
|||
|
.IP MTBSF 14
|
|||
|
Backward space over
|
|||
|
.B mt_count
|
|||
|
filemarks.
|
|||
|
.IP MTBSFM
|
|||
|
Backward space over
|
|||
|
.B mt_count
|
|||
|
filemarks.
|
|||
|
Reposition the tape to the EOT side of the last filemark.
|
|||
|
.IP MTBSR
|
|||
|
Backward space over
|
|||
|
.B mt_count
|
|||
|
records (tape blocks).
|
|||
|
.IP MTBSS
|
|||
|
Backward space over
|
|||
|
.B mt_count
|
|||
|
setmarks.
|
|||
|
.IP MTCOMPRESSION
|
|||
|
Enable compression of tape data within the drive if
|
|||
|
.B mt_count
|
|||
|
is non-zero and disable compression if
|
|||
|
.B mt_count
|
|||
|
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.
|
|||
|
.IP MTFSF
|
|||
|
Forward space over
|
|||
|
.B mt_count
|
|||
|
filemarks.
|
|||
|
.IP MTFSFM
|
|||
|
Forward space over
|
|||
|
.B mt_count
|
|||
|
filemarks.
|
|||
|
Reposition the tape to the BOT side of the last filemark.
|
|||
|
.IP MTFSR
|
|||
|
Forward space over
|
|||
|
.B mt_count
|
|||
|
records (tape blocks).
|
|||
|
.IP MTFSS
|
|||
|
Forward space over
|
|||
|
.B mt_count
|
|||
|
setmarks.
|
|||
|
.IP MTLOAD
|
|||
|
Execute the SCSI load command. A special case is available for some HP
|
|||
|
autoloaders. If
|
|||
|
.B mt_count
|
|||
|
is the constant MT_ST_HPLOADER_OFFSET plus a number, the number is
|
|||
|
sent to the drive to control the autoloader.
|
|||
|
.IP MTLOCK
|
|||
|
Lock the tape drive door.
|
|||
|
.IP MTMKPART
|
|||
|
Format the tape into one or two partitions. If
|
|||
|
.B mt_count
|
|||
|
is non-zero, it gives the size of the first partition and the second
|
|||
|
partition contains the rest of the tape. If
|
|||
|
.B mt_count
|
|||
|
is zero, the tape is formatted into one partition.
|
|||
|
This command is not allowed for a drive unless the partition support
|
|||
|
is enabled for the drive (see MT_ST_CAN_PARTITIONS below).
|
|||
|
.IP MTNOP
|
|||
|
No op \- flushes the driver's buffer as a side effect.
|
|||
|
Should be used before reading status with \s-1MTIOCGET\s+1.
|
|||
|
.IP MTOFFL
|
|||
|
Rewind and put the drive off line.
|
|||
|
.IP MTRESET
|
|||
|
Reset drive.
|
|||
|
.IP MTRETEN
|
|||
|
Retension tape.
|
|||
|
.IP MTREW
|
|||
|
Rewind.
|
|||
|
.IP MTSEEK
|
|||
|
Seek to the tape block number specified in
|
|||
|
.BR mt_count .
|
|||
|
This operation requires either a SCSI-2 drive that supports the \s-1LOCATE\s+1
|
|||
|
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
|
|||
|
\s-1MTIOCPOS\s+1 if device-specific addresses are used.
|
|||
|
.IP MTSETBLK
|
|||
|
Set the drive's block length to the value specified in
|
|||
|
.BR mt_count .
|
|||
|
A block length of zero sets the drive to variable block size mode.
|
|||
|
.IP MTSETDENSITY
|
|||
|
Set the tape density to the code in
|
|||
|
.BR mt_count .
|
|||
|
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 .
|
|||
|
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).
|
|||
|
.IP MTUNLOAD
|
|||
|
Execute the SCSI unload command (does not eject the tape).
|
|||
|
.IP MTUNLOCK
|
|||
|
Unlock the tape drive door.
|
|||
|
.IP MTWEOF
|
|||
|
Write
|
|||
|
.B mt_count
|
|||
|
filemarks.
|
|||
|
.IP MTWSM
|
|||
|
Write
|
|||
|
.B mt_count
|
|||
|
setmarks.
|
|||
|
.PD
|
|||
|
.PP
|
|||
|
Magnetic Tape operations for setting of device options (by the superuser):
|
|||
|
.PD 0
|
|||
|
.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
|
|||
|
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
|
|||
|
Booleans counted as one item.)
|
|||
|
.PD
|
|||
|
.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 12
|
|||
|
.IP 0 4
|
|||
|
The drive will not report \s-1GOOD\s+1 status on write commands until the data
|
|||
|
blocks are actually written to the medium.
|
|||
|
.PD 0
|
|||
|
.IP 1
|
|||
|
The drive may report \s-1GOOD\s+1 status on write commands as soon as all the
|
|||
|
data has been transferred to the drive's internal buffer.
|
|||
|
.IP 2
|
|||
|
The drive may report \s-1GOOD\s+1 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.
|
|||
|
.PD
|
|||
|
.RE
|
|||
|
.IP ""
|
|||
|
To control the write threshold the value in
|
|||
|
.B mt_count
|
|||
|
must include the constant
|
|||
|
\s-1MT_ST_WRITE_THRESHOLD\s+1 logically 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
|
|||
|
.BR \s-1DESCRIPTION\s+1 ,
|
|||
|
above).
|
|||
|
.IP
|
|||
|
To set and clear the Boolean options
|
|||
|
the value in
|
|||
|
.B mt_count
|
|||
|
must include one 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
|
|||
|
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
|
|||
|
options can be selectively set and with \s-1MT_ST_DEFBOOLEANS\s+1
|
|||
|
selectively cleared.
|
|||
|
.IP ""
|
|||
|
The default options for a tape device are set with
|
|||
|
\s-1MT_ST_DEFBOOLEANS\s+1. A non-active 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:
|
|||
|
.IP
|
|||
|
.PD 0
|
|||
|
.RS
|
|||
|
.IP "\s-1MT_ST_BUFFER_WRITES\s+1 (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 multi-volume archives.
|
|||
|
.IP "\s-1MT_ST_ASYNC_WRITES\s+1 (Default: true)"
|
|||
|
When this options 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 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.
|
|||
|
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)"
|
|||
|
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.
|
|||
|
.PD
|
|||
|
.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.
|
|||
|
.PP
|
|||
|
.PD 0
|
|||
|
.IP "\s-1MT_ST_DEBUGGING\s+1 (Default: false)"
|
|||
|
This option turns on various debugging messages from the driver
|
|||
|
(effective only if the driver was compiled with \s-1DEBUG\s+1 defined
|
|||
|
non-zero).
|
|||
|
.IP "\s-1MT_ST_FAST_EOM\s+1 (Default: false)"
|
|||
|
This option causes the \s-1MTEOM\s+1 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
|
|||
|
\s-1MTIOCGET\s+1 request.
|
|||
|
If \s-1MT_ST_FAST_EOM\s+1 is false the driver will respond to an
|
|||
|
\s-1MTEOM\s+1 request by forward spacing over files.
|
|||
|
.IP "\s-1MT_ST_AUTO_LOCK\s+1 (Default: false)"
|
|||
|
When this option is true, the drive door is locked when the device is
|
|||
|
opened and unlocked when it is closed.
|
|||
|
.IP "\s-1MT_ST_DEF_WRITES\s+1 (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.
|
|||
|
.IP "\s-1MT_ST_CAN_BSR\s+1 (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 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.
|
|||
|
.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
|
|||
|
that the driver can't check before sending commands if the selected
|
|||
|
block size is acceptable to the drive.
|
|||
|
.IP "\s-1MT_ST_CAN_PARTITIONS\s+1 (Default: false)"
|
|||
|
This option enables support for several partitions within a
|
|||
|
tape. The option applies to all devices linked to a drive.
|
|||
|
.IP "\s-1MT_ST_SCSI2LOGICAL\s+1 (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 MTSEEK and 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 only support the logical block addresses.
|
|||
|
.IP "\s-1MT_ST_SYSV\s+1 (Default: false)"
|
|||
|
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 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-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;"
|
|||
|
.BI "ioctl(" fd ", \s-1MTIOCTOP\s+1, &" mt_cmd ");"
|
|||
|
.fi
|
|||
|
.RE
|
|||
|
.PD
|
|||
|
.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
|
|||
|
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.
|
|||
|
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
|
|||
|
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.
|
|||
|
.SS "\s-1MTIOCGET\s+1 \- Get status"
|
|||
|
.PP
|
|||
|
This request takes an argument of type
|
|||
|
.BR "(struct mtget *)" .
|
|||
|
.PP
|
|||
|
.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;
|
|||
|
};
|
|||
|
.fi
|
|||
|
.IP \fBmt_type\fP 11
|
|||
|
The header file defines many values for
|
|||
|
.BR mt_type ,
|
|||
|
but the current driver reports only the generic types
|
|||
|
\s-1MT_ISSCSI1\s+1 (Generic SCSI-1 tape) and \s-1MT_ISSCSI2\s+1 (Generic SCSI-2 tape).
|
|||
|
.PD 0
|
|||
|
.IP \fBmt_resid\fP
|
|||
|
contains the current tape partition number.
|
|||
|
.IP \fBmt_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 \s-1MT_ST_BLKSIZE_SHIFT\s+1, \s-1MT_ST_BLKSIZE_MASK\s+1,
|
|||
|
\s-1MT_ST_DENSITY_SHIFT\s+1, and \s-1MT_ST_DENSITY_MASK\s+1.
|
|||
|
.IP \fBmt_gstat\fP
|
|||
|
reports generic (device independent) status information.
|
|||
|
The header file defines macros for testing these status bits:
|
|||
|
.RS
|
|||
|
.HP 4
|
|||
|
\s-1GMT_EOF(\s+1\fIx\fP\s-1)\s+1:
|
|||
|
The tape is positioned just after a filemark
|
|||
|
(always false after an \s-1MTSEEK\s+1 operation).
|
|||
|
.HP
|
|||
|
\s-1GMT_BOT(\s+1\fIx\fP\s-1)\s+1:
|
|||
|
The tape is positioned at the beginning of the first file (always false
|
|||
|
after an \s-1MTSEEK\s+1 operation).
|
|||
|
.HP
|
|||
|
\s-1GMT_EOT(\s+1\fIx\fP\s-1)\s+1:
|
|||
|
A tape operation has reached the physical End Of Tape.
|
|||
|
.HP
|
|||
|
\s-1GMT_SM(\s+1\fIx\fP\s-1)\s+1:
|
|||
|
The tape is currently positioned at a setmark
|
|||
|
(always false after an \s-1MTSEEK\s+1 operation).
|
|||
|
.HP
|
|||
|
\s-1GMT_EOD(\s+1\fIx\fP\s-1)\s+1:
|
|||
|
The tape is positioned at the end of recorded data.
|
|||
|
.HP
|
|||
|
\s-1GMT_WR_PROT(\s+1\fIx\fP\s-1)\s+1:
|
|||
|
The drive is write-protected.
|
|||
|
For some drives this can also mean that the drive does not support
|
|||
|
writing on the current medium type.
|
|||
|
.HP
|
|||
|
\s-1GMT_ONLINE(\s+1\fIx\fP\s-1)\s+1:
|
|||
|
The last
|
|||
|
.B open()
|
|||
|
found the drive with a tape in place and ready for operation.
|
|||
|
.HP
|
|||
|
\s-1GMT_D_6250(\s+1\fIx\fP\s-1)\s+1, \s-1GMT_D_1600(\s+1\fIx\fP\s-1)\s+1, \s-1GMT_D_800(\s+1\fIx\fP\s-1)\s+1:
|
|||
|
This \(lqgeneric\(rq status information reports the current
|
|||
|
density setting for 9-track \(12" tape drives only.
|
|||
|
.HP
|
|||
|
\s-1GMT_DR_OPEN(\s+1\fIx\fP\s-1)\s+1:
|
|||
|
The drive does not have a tape in place.
|
|||
|
.HP
|
|||
|
\s-1GMT_IM_REP_EN(\s+1\fIx\fP\s-1)\s+1:
|
|||
|
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.
|
|||
|
.RE
|
|||
|
.IP \fBmt_erreg\fP
|
|||
|
The only field defined in
|
|||
|
.B mt_erreg
|
|||
|
is the recovered error count in the low 16 bits (as defined by
|
|||
|
\s-1MT_ST_SOFTERR_SHIFT\s+1 and \s-1MT_ST_SOFTERR_MASK\s+1).
|
|||
|
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).
|
|||
|
.IP \fBmt_fileno\fP
|
|||
|
reports the current file number (zero-based).
|
|||
|
This value is set to \-1 when the file number is unknown (e.g., after
|
|||
|
\s-1MTBSS\s+1
|
|||
|
or \s-1MTSEEK\s+1).
|
|||
|
.IP \fBmt_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
|
|||
|
\s-1MTBSF\s+1,
|
|||
|
\s-1MTBSS\s+1, or \s-1MTSEEK\s+1).
|
|||
|
.PD
|
|||
|
.SS "\s-1MTIOCPOS\s+1 \- Get tape position"
|
|||
|
.PP
|
|||
|
This request takes an argument of type
|
|||
|
.B "(struct mtpos *)"
|
|||
|
and reports the drive's notion of the current tape block number,
|
|||
|
which is not the same as
|
|||
|
.B mt_blkno
|
|||
|
returned by \s-1MTIOCGET\s+1.
|
|||
|
This drive must be a SCSI-2 drive that supports the \s-1READ POSITION\s+1
|
|||
|
command (device-specific address)
|
|||
|
or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive
|
|||
|
Viper, Wangtek, ... ).
|
|||
|
.PP
|
|||
|
.nf
|
|||
|
/* structure for \s-1MTIOCPOS\s+1 - mag tape get position command */
|
|||
|
struct mtpos {
|
|||
|
long mt_blkno; /* current block number */
|
|||
|
};
|
|||
|
|
|||
|
.fi
|
|||
|
.SH "RETURN VALUE"
|
|||
|
.IP EIO 14
|
|||
|
The requested operation could not be completed.
|
|||
|
.IP ENOSPC
|
|||
|
A write operation could not be completed because the tape reached
|
|||
|
end-of-medium.
|
|||
|
.IP EACCES
|
|||
|
An attempt was made to write or erase a write-protected tape.
|
|||
|
(This error is not detected during
|
|||
|
.BR open() .)
|
|||
|
.IP EFAULT
|
|||
|
The command parameters point to memory not belonging to the calling
|
|||
|
process.
|
|||
|
.IP ENXIO
|
|||
|
During opening, the tape device does not exist.
|
|||
|
.IP EBUSY
|
|||
|
The device is already in use or the driver was unable to allocate a
|
|||
|
buffer.
|
|||
|
.IP EOVERFLOW
|
|||
|
An attempt was made to read or write a variable-length block that is
|
|||
|
larger than the driver's internal buffer.
|
|||
|
.IP EINVAL
|
|||
|
An
|
|||
|
.B ioctl()
|
|||
|
had an illegal argument, or a requested block size was illegal.
|
|||
|
.IP ENOSYS
|
|||
|
Unknown
|
|||
|
.BR ioctl() .
|
|||
|
.IP EROFS
|
|||
|
Open is attempted with O_WRONLY or O_RDWR when the tape in the drive is
|
|||
|
write-protected.
|
|||
|
.SH FILES
|
|||
|
/dev/st* : the auto-rewind SCSI tape devices
|
|||
|
.br
|
|||
|
/dev/nst* : the non-rewind 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 "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
|
|||
|
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
|
|||
|
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
|
|||
|
or MTSETDEFBLK at system startup to set the mode), at least when
|
|||
|
exchanging data with 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.
|
|||
|
.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
|
|||
|
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.
|
|||
|
.PP
|
|||
|
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.
|
|||
|
.SH COPYRIGHT
|
|||
|
Copyright \(co 1995 Robert K. Nichols.
|
|||
|
.br
|
|||
|
Copyright \(co 1999 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
|
|||
|
preserved on all copies.
|
|||
|
Additional permissions are contained in the header of the source file.
|