2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright 1995 Robert K. Nichols (Robert.K.Nichols@att.com)
|
2005-04-05 12:20:49 +00:00
|
|
|
.\" Copyright 1999-2005 Kai Mäkisara (Kai.Makisara@kolumbus.fi)
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
2005-04-05 12:20:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
2005-04-05 12:20:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TH ST 4 2007-12-16 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
st \- SCSI tape device
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <sys/mtio.h>
|
|
|
|
.sp
|
|
|
|
.BI "int ioctl(int " fd ", int " request " [, (void *)" arg3 "]);"
|
2007-12-16 15:34:59 +00:00
|
|
|
.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 );
|
2004-11-03 13:51:07 +00:00
|
|
|
.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
|
2007-10-03 06:17:53 +00:00
|
|
|
\(lqsequential-access\(rq.
|
2004-11-03 13:51:07 +00:00
|
|
|
The
|
|
|
|
.B st
|
|
|
|
driver uses major device number 9.
|
|
|
|
.PP
|
2007-04-12 22:42:49 +00:00
|
|
|
Each device uses eight minor device numbers.
|
|
|
|
The lowermost five bits
|
2004-11-03 13:51:07 +00:00
|
|
|
in the minor numbers are assigned sequentially in the order of
|
2007-04-12 22:42:49 +00:00
|
|
|
detection.
|
|
|
|
In the 2.6 kernel, the bits above the eight lowermost bits are
|
2005-04-07 08:00:31 +00:00
|
|
|
concatenated to the five lowermost bits to form the tape number.
|
2005-04-05 12:20:49 +00:00
|
|
|
The minor numbers can be grouped into
|
2004-11-03 13:51:07 +00:00
|
|
|
two sets of four numbers: the principal (auto-rewind) minor device numbers,
|
|
|
|
.IR n ,
|
2005-04-05 12:20:49 +00:00
|
|
|
and the \(lqno-rewind\(rq device numbers,
|
2007-10-03 06:17:53 +00:00
|
|
|
.RI ( n " + 128)."
|
2004-11-03 13:51:07 +00:00
|
|
|
Devices opened using the principal device number will be sent a
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR REWIND
|
|
|
|
command when they are closed.
|
2004-11-03 13:51:07 +00:00
|
|
|
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,
|
2007-04-12 22:42:49 +00:00
|
|
|
density, etc.)
|
|
|
|
When the system starts up, only the first device is available.
|
|
|
|
The other three are activated when the default
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
drive.
|
|
|
|
The default allocation allows control of 32 tape drives.
|
2004-11-03 13:51:07 +00:00
|
|
|
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:
|
2007-12-19 07:19:23 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
2007-04-05 12:36:57 +00:00
|
|
|
|
2005-07-06 12:57:38 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
.fi
|
2007-12-19 07:19:23 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
There is no corresponding block device.
|
|
|
|
.PP
|
|
|
|
The driver uses an internal buffer that has to be large enough to hold
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
largest contiguous block of memory the kernel allocator can provide.
|
2005-04-05 12:20:49 +00:00
|
|
|
The limit is currently 128 kB for 32-bit architectures and
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
buffer at run-time if necessary.
|
|
|
|
However, run-time allocation of large
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
model.
|
|
|
|
After system start-up the tape device options are defined by
|
2005-04-05 12:20:49 +00:00
|
|
|
the drive firmware.
|
|
|
|
For example, if the drive firmware selects fixed-block mode,
|
2007-04-12 22:42:49 +00:00
|
|
|
the tape device uses fixed-block mode.
|
|
|
|
The options can
|
2004-11-03 13:51:07 +00:00
|
|
|
be changed with explicit
|
2007-05-11 23:18:56 +00:00
|
|
|
.BR ioctl (2)
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
the subgroup of four.
|
|
|
|
The options take effect when the device is
|
|
|
|
opened.
|
|
|
|
For example, the system administrator can define
|
2005-04-05 12:20:49 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
both modes).
|
|
|
|
.PP
|
|
|
|
The driver supports
|
|
|
|
.B tape partitions
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2007-05-11 23:18:56 +00:00
|
|
|
.BR ioctl (2).
|
2005-10-20 15:11:10 +00:00
|
|
|
The tape
|
2004-11-03 13:51:07 +00:00
|
|
|
location is preserved within each partition across partition changes.
|
|
|
|
The partition used for subsequent tape operations is
|
2007-04-12 22:42:49 +00:00
|
|
|
selected with an
|
2007-05-11 23:18:56 +00:00
|
|
|
.BR ioctl (2).
|
2005-10-20 15:11:10 +00:00
|
|
|
The partition switch is executed together with
|
2004-11-03 13:51:07 +00:00
|
|
|
the next tape operation in order to avoid unnecessary tape
|
2007-04-12 22:42:49 +00:00
|
|
|
movement.
|
|
|
|
The maximum number of partitions on a tape is defined by a
|
|
|
|
compile-time constant (originally four).
|
|
|
|
The driver contains an
|
2007-05-11 23:18:56 +00:00
|
|
|
.BR ioctl (2)
|
2005-10-20 15:11:10 +00:00
|
|
|
that can format a tape with either one or two partitions.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
Device
|
2005-11-02 13:55:25 +00:00
|
|
|
.I /dev/tape
|
2004-11-03 13:51:07 +00:00
|
|
|
is usually created as a hard or soft link to the default tape device
|
|
|
|
on the system.
|
2005-04-05 12:20:49 +00:00
|
|
|
.PP
|
|
|
|
Starting from kernel 2.6.2, the driver exports in the sysfs directory
|
2007-09-20 16:26:31 +00:00
|
|
|
.I /sys/class/scsi_tape
|
2005-04-05 12:20:49 +00:00
|
|
|
the attached devices and some parameters assigned to the devices.
|
2007-05-19 04:30:20 +00:00
|
|
|
.SS "Data Transfer"
|
2005-04-05 12:20:49 +00:00
|
|
|
The driver supports operation in both fixed-block mode and
|
|
|
|
variable-block mode (if supported by the drive).
|
|
|
|
In fixed-block mode the drive
|
2004-11-03 13:51:07 +00:00
|
|
|
writes blocks of the specified size and the block size is not
|
2005-04-05 12:20:49 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
count determines the size of the corresponding tape block.
|
|
|
|
Note that
|
2005-04-05 12:20:49 +00:00
|
|
|
the blocks on the tape don't contain any information about the
|
2004-11-03 13:51:07 +00:00
|
|
|
writing mode: when reading, the only important thing is to use
|
|
|
|
commands that accept the block sizes on the tape.
|
|
|
|
.PP
|
2005-04-05 12:20:49 +00:00
|
|
|
In variable-block mode the read byte count does not have to match
|
2007-04-12 22:42:49 +00:00
|
|
|
the tape block size exactly.
|
|
|
|
If the byte count is larger than the
|
2004-11-03 13:51:07 +00:00
|
|
|
next block on tape, the driver returns the data and the function
|
2007-04-12 22:42:49 +00:00
|
|
|
returns the actual block size.
|
|
|
|
If the block size is larger than the
|
2004-11-03 13:51:07 +00:00
|
|
|
byte count, the requested amount of data from the start of the block
|
|
|
|
is returned and the rest of the block is discarded.
|
|
|
|
.PP
|
2005-04-05 12:20:49 +00:00
|
|
|
In fixed-block mode the read byte counts can be arbitrary if
|
2004-11-03 13:51:07 +00:00
|
|
|
buffering is enabled, or a multiple of the tape block size if
|
2007-04-12 22:42:49 +00:00
|
|
|
buffering is disabled.
|
|
|
|
Kernels before 2.1.121 allow writes with
|
|
|
|
arbitrary byte count if buffering is enabled.
|
|
|
|
In all other cases
|
2004-11-03 13:51:07 +00:00
|
|
|
(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
|
2005-04-05 12:20:49 +00:00
|
|
|
In the 2.6 kernel, the driver tries to use direct transfers between the user
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2005-04-05 12:20:49 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
recorded data is signaled by returning zero bytes for two consecutive
|
2007-04-12 22:42:49 +00:00
|
|
|
read calls.
|
|
|
|
The third read returns an error.
|
2007-05-19 04:30:20 +00:00
|
|
|
.SS Ioctls
|
2007-04-12 22:42:49 +00:00
|
|
|
The driver supports three
|
2007-05-11 23:18:56 +00:00
|
|
|
.BR ioctl (2)
|
2005-10-20 15:11:10 +00:00
|
|
|
requests.
|
2004-11-03 13:51:07 +00:00
|
|
|
Requests not recognized by the
|
|
|
|
.B st
|
|
|
|
driver are passed to the
|
|
|
|
.B SCSI
|
|
|
|
driver.
|
|
|
|
The definitions below are from
|
2005-11-02 13:55:25 +00:00
|
|
|
.IR /usr/include/linux/mtio.h :
|
2007-12-16 15:34:59 +00:00
|
|
|
.SS "MTIOCTOP \(em Perform a tape operation"
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
This request takes an argument of type
|
2005-11-02 13:55:25 +00:00
|
|
|
.IR "(struct mtop *)" .
|
2004-11-03 13:51:07 +00:00
|
|
|
Not all drives support all operations.
|
2007-07-09 20:07:44 +00:00
|
|
|
The driver returns an
|
|
|
|
.B EIO
|
|
|
|
error if the drive rejects an operation.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
2007-12-16 15:34:59 +00:00
|
|
|
/* Structure for MTIOCTOP \- mag tape op command: */
|
2004-11-03 13:51:07 +00:00
|
|
|
struct mtop {
|
2007-04-05 12:36:57 +00:00
|
|
|
short mt_op; /* operations defined below */
|
|
|
|
int mt_count; /* how many of them */
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
2007-12-16 15:34:59 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
Magnetic Tape operations for normal tape use:
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP 14
|
|
|
|
.TP
|
|
|
|
.B MTBSF
|
2004-11-03 13:51:07 +00:00
|
|
|
Backward space over
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
filemarks.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTBSFM
|
2004-11-03 13:51:07 +00:00
|
|
|
Backward space over
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
filemarks.
|
|
|
|
Reposition the tape to the EOT side of the last filemark.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTBSR
|
2004-11-03 13:51:07 +00:00
|
|
|
Backward space over
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
records (tape blocks).
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTBSS
|
2004-11-03 13:51:07 +00:00
|
|
|
Backward space over
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
setmarks.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTCOMPRESSION
|
2004-11-03 13:51:07 +00:00
|
|
|
Enable compression of tape data within the drive if
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
is non-zero and disable compression if
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2007-04-12 22:42:49 +00:00
|
|
|
is zero.
|
|
|
|
This command uses the MODE page 15 supported by most DATs.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTEOM
|
2004-11-03 13:51:07 +00:00
|
|
|
Go to the end of the recorded media (for appending files).
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTERASE
|
2007-04-12 22:42:49 +00:00
|
|
|
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.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTFSF
|
2004-11-03 13:51:07 +00:00
|
|
|
Forward space over
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
filemarks.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTFSFM
|
2004-11-03 13:51:07 +00:00
|
|
|
Forward space over
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
filemarks.
|
|
|
|
Reposition the tape to the BOT side of the last filemark.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTFSR
|
2004-11-03 13:51:07 +00:00
|
|
|
Forward space over
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
records (tape blocks).
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTFSS
|
2004-11-03 13:51:07 +00:00
|
|
|
Forward space over
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
setmarks.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTLOAD
|
2007-04-12 22:42:49 +00:00
|
|
|
Execute the SCSI load command.
|
|
|
|
A special case is available for some HP
|
|
|
|
autoloaders.
|
|
|
|
If
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2007-12-16 13:49:24 +00:00
|
|
|
is the constant
|
|
|
|
.B MT_ST_HPLOADER_OFFSET
|
|
|
|
plus a number, the number is
|
2004-11-03 13:51:07 +00:00
|
|
|
sent to the drive to control the autoloader.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTLOCK
|
2004-11-03 13:51:07 +00:00
|
|
|
Lock the tape drive door.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTMKPART
|
2007-04-12 22:42:49 +00:00
|
|
|
Format the tape into one or two partitions.
|
|
|
|
If
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
is non-zero, it gives the size of the first partition and the second
|
2007-04-12 22:42:49 +00:00
|
|
|
partition contains the rest of the tape.
|
|
|
|
If
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
is zero, the tape is formatted into one partition.
|
|
|
|
This command is not allowed for a drive unless the partition support
|
2007-12-16 15:34:59 +00:00
|
|
|
is enabled for the drive (see
|
|
|
|
.BR MT_ST_CAN_PARTITIONS
|
|
|
|
below).
|
|
|
|
.TP
|
|
|
|
.B MTNOP
|
2005-07-18 12:43:00 +00:00
|
|
|
No op \(em flushes the driver's buffer as a side effect.
|
2007-12-17 10:22:31 +00:00
|
|
|
Should be used before reading status with
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MTIOCGET .
|
|
|
|
.TP
|
|
|
|
.B MTOFFL
|
2004-11-03 13:51:07 +00:00
|
|
|
Rewind and put the drive off line.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTRESET
|
2004-11-03 13:51:07 +00:00
|
|
|
Reset drive.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTRETEN
|
2006-05-29 01:20:08 +00:00
|
|
|
Re-tension tape.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTREW
|
2004-11-03 13:51:07 +00:00
|
|
|
Rewind.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTSEEK
|
2004-11-03 13:51:07 +00:00
|
|
|
Seek to the tape block number specified in
|
2007-06-23 07:56:56 +00:00
|
|
|
.IR mt_count .
|
2007-12-16 15:34:59 +00:00
|
|
|
This operation requires either a SCSI-2 drive that supports the
|
|
|
|
.B LOCATE
|
2004-11-03 13:51:07 +00:00
|
|
|
command (device-specific address)
|
|
|
|
or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive
|
2007-12-16 15:34:59 +00:00
|
|
|
Viper, Wangtek, ...).
|
2004-11-03 13:51:07 +00:00
|
|
|
The block number should be one that was previously returned by
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MTIOCPOS
|
|
|
|
if device-specific addresses are used.
|
|
|
|
.TP
|
|
|
|
.B MTSETBLK
|
2004-11-03 13:51:07 +00:00
|
|
|
Set the drive's block length to the value specified in
|
2007-06-23 07:56:56 +00:00
|
|
|
.IR mt_count .
|
2004-11-03 13:51:07 +00:00
|
|
|
A block length of zero sets the drive to variable block size mode.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTSETDENSITY
|
2004-11-03 13:51:07 +00:00
|
|
|
Set the tape density to the code in
|
2007-06-23 07:56:56 +00:00
|
|
|
.IR mt_count .
|
2004-11-03 13:51:07 +00:00
|
|
|
The density codes supported by a drive can be found from the drive
|
|
|
|
documentation.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTSETPART
|
2004-11-03 13:51:07 +00:00
|
|
|
The active partition is switched to
|
2007-06-23 07:56:56 +00:00
|
|
|
.IR mt_count .
|
2007-04-12 22:42:49 +00:00
|
|
|
The partitions are numbered from zero.
|
|
|
|
This command is not allowed for
|
2004-11-03 13:51:07 +00:00
|
|
|
a drive unless the partition support is enabled for the drive (see
|
2007-12-16 15:34:59 +00:00
|
|
|
.B MT_ST_CAN_PARTITIONS
|
|
|
|
below).
|
|
|
|
.TP
|
|
|
|
.B MTUNLOAD
|
2004-11-03 13:51:07 +00:00
|
|
|
Execute the SCSI unload command (does not eject the tape).
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTUNLOCK
|
2004-11-03 13:51:07 +00:00
|
|
|
Unlock the tape drive door.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTWEOF
|
2005-04-05 12:20:49 +00:00
|
|
|
Write
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
filemarks.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B MTWSM
|
2004-11-03 13:51:07 +00:00
|
|
|
Write
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
setmarks.
|
|
|
|
.PP
|
|
|
|
Magnetic Tape operations for setting of device options (by the superuser):
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP 8
|
|
|
|
.B MTSETDRVBUFFER
|
2004-11-03 13:51:07 +00:00
|
|
|
Set various drive and driver options according to bits encoded in
|
2007-06-23 07:56:56 +00:00
|
|
|
.IR mt_count .
|
2005-04-05 12:20:49 +00:00
|
|
|
These consist of the drive's buffering mode, a set of Boolean driver
|
2004-11-03 13:51:07 +00:00
|
|
|
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.)
|
|
|
|
.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
|
2007-12-17 10:22:31 +00:00
|
|
|
The drive will not report
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR GOOD
|
|
|
|
status on write commands until the data
|
2004-11-03 13:51:07 +00:00
|
|
|
blocks are actually written to the medium.
|
|
|
|
.IP 1
|
2007-12-17 10:22:31 +00:00
|
|
|
The drive may report
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR GOOD
|
|
|
|
status on write commands as soon as all the
|
2004-11-03 13:51:07 +00:00
|
|
|
data has been transferred to the drive's internal buffer.
|
|
|
|
.IP 2
|
2007-12-17 10:22:31 +00:00
|
|
|
The drive may report
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR GOOD
|
|
|
|
status on write commands as soon as (a) all
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-12-16 15:34:59 +00:00
|
|
|
.IP
|
2004-11-03 13:51:07 +00:00
|
|
|
To control the write threshold the value in
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2004-11-03 13:51:07 +00:00
|
|
|
must include the constant
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_WRITE_THRESHOLD
|
|
|
|
logically ORed with a block count in the low 28 bits.
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-12-16 15:34:59 +00:00
|
|
|
DESCRIPTION, above).
|
2004-11-03 13:51:07 +00:00
|
|
|
.IP
|
|
|
|
To set and clear the Boolean options
|
|
|
|
the value in
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_count
|
2007-12-16 15:34:59 +00:00
|
|
|
must include one of the constants
|
|
|
|
.BR MT_ST_BOOLEANS ,
|
2007-12-17 10:22:31 +00:00
|
|
|
.BR MT_ST_SETBOOLEANS ,
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_CLEARBOOLEANS ,
|
|
|
|
or
|
|
|
|
.BR MT_ST_DEFBOOLEANS
|
|
|
|
logically or'ed with
|
2004-11-03 13:51:07 +00:00
|
|
|
whatever combination of the following options is desired.
|
2007-12-16 15:34:59 +00:00
|
|
|
Using
|
|
|
|
.BR MT_ST_BOOLEANS
|
|
|
|
the options can be set to the values
|
2007-04-12 22:42:49 +00:00
|
|
|
defined in the corresponding bits.
|
2007-12-16 15:34:59 +00:00
|
|
|
With
|
|
|
|
.BR MT_ST_SETBOOLEANS
|
2007-12-17 10:22:31 +00:00
|
|
|
the options can be selectively set and with
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_DEFBOOLEANS
|
2004-11-03 13:51:07 +00:00
|
|
|
selectively cleared.
|
|
|
|
.IP ""
|
|
|
|
The default options for a tape device are set with
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_DEFBOOLEANS .
|
2007-04-12 22:42:49 +00:00
|
|
|
A non-active tape device (e.g., device with
|
2004-11-03 13:51:07 +00:00
|
|
|
minor 32 or 160) is activated when the default options for it are
|
2007-04-12 22:42:49 +00:00
|
|
|
defined the first time.
|
|
|
|
An activated device inherits from the device
|
2004-11-03 13:51:07 +00:00
|
|
|
activated at start-up the options not set explicitly.
|
|
|
|
.IP ""
|
|
|
|
The Boolean options are:
|
|
|
|
.RS
|
2007-12-17 10:22:31 +00:00
|
|
|
.TP
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_BUFFER_WRITES " (Default: true)"
|
2005-04-05 12:20:49 +00:00
|
|
|
Buffer all write operations in fixed-block mode.
|
2004-11-03 13:51:07 +00:00
|
|
|
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.
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_ASYNC_WRITES " (Default: true)"
|
2005-04-05 12:20:49 +00:00
|
|
|
When this option is true, write operations return immediately without
|
2004-11-03 13:51:07 +00:00
|
|
|
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.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.BR MT_ST_READ_AHEAD " (Default: true)"
|
2004-11-03 13:51:07 +00:00
|
|
|
This option causes the driver to provide read buffering and
|
2005-04-05 12:20:49 +00:00
|
|
|
read-ahead in fixed-block mode.
|
2004-11-03 13:51:07 +00:00
|
|
|
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.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.BR MT_ST_TWO_FM " (Default: false)"
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
rather than two consecutive filemarks.
|
|
|
|
Most other current drives also
|
2004-11-03 13:51:07 +00:00
|
|
|
detect the end of recorded data and using two filemarks is usually
|
|
|
|
necessary only when interchanging tapes with some other systems.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.BR MT_ST_DEBUGGING " (Default: false)"
|
2004-11-03 13:51:07 +00:00
|
|
|
This option turns on various debugging messages from the driver
|
2007-12-16 15:34:59 +00:00
|
|
|
(effective only if the driver was compiled with
|
|
|
|
.B DEBUG
|
|
|
|
defined non-zero).
|
|
|
|
.TP
|
|
|
|
.BR MT_ST_FAST_EOM " (Default: false)"
|
2007-12-17 10:22:31 +00:00
|
|
|
This option causes the
|
2007-12-16 15:34:59 +00:00
|
|
|
.B MTEOM
|
|
|
|
operation to be sent directly to the
|
2004-11-03 13:51:07 +00:00
|
|
|
drive, potentially speeding up the operation but causing the driver to
|
|
|
|
lose track of the current file number normally returned by the
|
2007-12-16 15:34:59 +00:00
|
|
|
.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.
|
2007-12-17 10:22:31 +00:00
|
|
|
.TP
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_AUTO_LOCK " (Default: false)"
|
2004-11-03 13:51:07 +00:00
|
|
|
When this option is true, the drive door is locked when the device is
|
|
|
|
opened and unlocked when it is closed.
|
2007-12-17 10:22:31 +00:00
|
|
|
.TP
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_DEF_WRITES " (Default: false)"
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
defined.
|
|
|
|
This option defines when the changes are enforced by the
|
2004-11-03 13:51:07 +00:00
|
|
|
driver using SCSI-commands and when the drives auto-detection
|
2007-04-12 22:42:49 +00:00
|
|
|
capabilities are relied upon.
|
|
|
|
If this option is false, the driver
|
|
|
|
sends the SCSI-commands immediately when the device is changed.
|
|
|
|
If the
|
2004-11-03 13:51:07 +00:00
|
|
|
option is true, the SCSI-commands are not sent until a write is
|
2007-04-12 22:42:49 +00:00
|
|
|
requested.
|
|
|
|
In this case the drive firmware is allowed to detect the
|
2004-11-03 13:51:07 +00:00
|
|
|
tape structure when reading and the SCSI-commands are used only to
|
|
|
|
make sure that a tape is written according to the correct specification.
|
2007-12-17 10:22:31 +00:00
|
|
|
.TP
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_CAN_BSR " (Default: false)"
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
space backwards over records is used for this purpose.
|
|
|
|
Some older
|
2004-11-03 13:51:07 +00:00
|
|
|
drives can't process this command reliably and this option can be used
|
2007-04-12 22:42:49 +00:00
|
|
|
to instruct the driver not to use the command.
|
|
|
|
The end result is that,
|
2005-04-05 12:20:49 +00:00
|
|
|
with read-ahead and fixed-block mode, the tape may not be correctly
|
2007-04-12 22:42:49 +00:00
|
|
|
positioned within a file when the device is closed.
|
|
|
|
With 2.6 kernel, the
|
2005-04-05 12:20:49 +00:00
|
|
|
default is true for drives supporting SCSI-3.
|
2007-12-16 15:34:59 +00:00
|
|
|
.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.
|
2007-04-12 22:42:49 +00:00
|
|
|
The drawback is
|
2004-11-03 13:51:07 +00:00
|
|
|
that the driver can't check before sending commands if the selected
|
|
|
|
block size is acceptable to the drive.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.BR MT_ST_CAN_PARTITIONS " (Default: false)"
|
2004-11-03 13:51:07 +00:00
|
|
|
This option enables support for several partitions within a
|
2007-04-12 22:42:49 +00:00
|
|
|
tape.
|
|
|
|
The option applies to all devices linked to a drive.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.BR MT_ST_SCSI2LOGICAL " (Default: false)"
|
2004-11-03 13:51:07 +00:00
|
|
|
This option instructs the driver to use the logical block addresses
|
|
|
|
defined in the SCSI-2 standard when performing the seek and tell
|
2007-12-16 15:34:59 +00:00
|
|
|
operations (both with
|
|
|
|
.B MTSEEK
|
|
|
|
and
|
|
|
|
.B MTIOCPOS
|
|
|
|
commands and when changing tape
|
2007-04-12 22:42:49 +00:00
|
|
|
partition).
|
|
|
|
Otherwise the device-specific addresses are used.
|
2004-11-03 13:51:07 +00:00
|
|
|
It is highly advisable to set this option if the drive supports the
|
2007-04-12 22:42:49 +00:00
|
|
|
logical addresses because they count also filemarks.
|
|
|
|
There are some
|
2004-11-03 13:51:07 +00:00
|
|
|
drives that only support the logical block addresses.
|
2007-12-17 10:22:31 +00:00
|
|
|
.TP
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_SYSV " (Default: false)"
|
2004-11-03 13:51:07 +00:00
|
|
|
When this option is enabled, the tape devices use the SystemV
|
2007-04-12 22:42:49 +00:00
|
|
|
semantics.
|
|
|
|
Otherwise the BSD semantics are used.
|
|
|
|
The most important
|
2004-11-03 13:51:07 +00:00
|
|
|
difference between the semantics is what happens when a device used
|
2006-01-13 09:44:53 +00:00
|
|
|
for reading is closed: in System V semantics the tape is spaced forward
|
2004-11-03 13:51:07 +00:00
|
|
|
past the next filemark if this has not happened while using the
|
2007-04-12 22:42:49 +00:00
|
|
|
device.
|
|
|
|
In BSD semantics the tape position is not changed.
|
2007-12-17 10:22:31 +00:00
|
|
|
.TP
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_NO_WAIT " (Default: false)"
|
2005-04-05 12:20:49 +00:00
|
|
|
Enables immediate mode (i.e., don't wait for the command to finish) for some
|
|
|
|
commands (e.g., rewind).
|
2007-12-16 15:34:59 +00:00
|
|
|
.PP
|
|
|
|
An example:
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
2007-12-16 15:34:59 +00:00
|
|
|
|
|
|
|
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);
|
2004-11-03 13:51:07 +00:00
|
|
|
.fi
|
2007-12-16 15:34:59 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
.RE
|
|
|
|
.IP ""
|
|
|
|
The default block size for a device can be set with
|
2007-12-16 15:34:59 +00:00
|
|
|
.B MT_ST_DEF_BLKSIZE
|
|
|
|
and the default density code can be set with
|
|
|
|
.BR MT_ST_DEFDENSITY .
|
2007-04-12 22:42:49 +00:00
|
|
|
The values for the parameters are or'ed
|
2004-11-03 13:51:07 +00:00
|
|
|
with the operation code.
|
|
|
|
.IP ""
|
|
|
|
With kernels 2.1.x and later, the timeout values can be set with the
|
2007-12-16 15:34:59 +00:00
|
|
|
subcommand
|
|
|
|
.B MT_ST_SET_TIMEOUT
|
|
|
|
ORed with the timeout in seconds.
|
2004-11-03 13:51:07 +00:00
|
|
|
The long timeout (used for rewinds and other commands
|
|
|
|
that may take a long time) can be set with
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_SET_LONG_TIMEOUT .
|
2007-04-12 22:42:49 +00:00
|
|
|
The kernel defaults are very long to
|
2004-11-03 13:51:07 +00:00
|
|
|
make sure that a successful command is not timed out with any
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
apply for all devices linked to the same drive.
|
2005-04-05 12:20:49 +00:00
|
|
|
.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
|
2007-12-16 15:34:59 +00:00
|
|
|
.B MT_ST_SEL_CLN
|
|
|
|
subcommand.
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2005-04-05 12:20:49 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
the cleaning request.
|
|
|
|
If the pattern is non-zero, the pattern must match
|
2005-04-05 12:20:49 +00:00
|
|
|
the masked sense data byte.
|
2007-12-16 15:34:59 +00:00
|
|
|
.SS "MTIOCGET \(em Get status"
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
This request takes an argument of type
|
2005-11-02 13:55:25 +00:00
|
|
|
.IR "(struct mtget *)" .
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
2007-12-16 15:34:59 +00:00
|
|
|
/* structure for MTIOCGET \- mag tape get status command */
|
2004-11-03 13:51:07 +00:00
|
|
|
struct mtget {
|
2007-04-05 12:36:57 +00:00
|
|
|
long mt_type;
|
|
|
|
long mt_resid;
|
2005-04-05 12:20:49 +00:00
|
|
|
/* the following registers are device dependent */
|
2007-04-05 12:36:57 +00:00
|
|
|
long mt_dsreg;
|
|
|
|
long mt_gstat;
|
|
|
|
long mt_erreg;
|
2005-04-05 12:20:49 +00:00
|
|
|
/* The next two fields are not always used */
|
2007-04-05 12:36:57 +00:00
|
|
|
daddr_t mt_fileno;
|
|
|
|
daddr_t mt_blkno;
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
2007-12-16 15:34:59 +00:00
|
|
|
.in
|
2007-06-23 07:56:56 +00:00
|
|
|
.IP \fImt_type\fP 11
|
2004-11-03 13:51:07 +00:00
|
|
|
The header file defines many values for
|
2007-06-23 07:56:56 +00:00
|
|
|
.IR mt_type ,
|
2004-11-03 13:51:07 +00:00
|
|
|
but the current driver reports only the generic types
|
2007-12-16 15:34:59 +00:00
|
|
|
.B MT_ISSCSI1
|
|
|
|
(Generic SCSI-1 tape)
|
|
|
|
and
|
|
|
|
.B MT_ISSCSI2
|
|
|
|
(Generic SCSI-2 tape).
|
2007-06-23 07:56:56 +00:00
|
|
|
.IP \fImt_resid\fP
|
2004-11-03 13:51:07 +00:00
|
|
|
contains the current tape partition number.
|
2007-06-23 07:56:56 +00:00
|
|
|
.IP \fImt_dsreg\fP
|
2004-11-03 13:51:07 +00:00
|
|
|
reports the drive's current settings for block size (in the low 24
|
|
|
|
bits) and density (in the high 8 bits).
|
2007-12-16 15:34:59 +00:00
|
|
|
These fields are defined by
|
2007-12-17 10:22:31 +00:00
|
|
|
.BR MT_ST_BLKSIZE_SHIFT ,
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_BLKSIZE_MASK ,
|
|
|
|
.BR MT_ST_DENSITY_SHIFT ,
|
|
|
|
and
|
|
|
|
.BR MT_ST_DENSITY_MASK .
|
2007-06-23 07:56:56 +00:00
|
|
|
.IP \fImt_gstat\fP
|
2004-11-03 13:51:07 +00:00
|
|
|
reports generic (device independent) status information.
|
|
|
|
The header file defines macros for testing these status bits:
|
|
|
|
.RS
|
|
|
|
.HP 4
|
2007-12-16 15:34:59 +00:00
|
|
|
\fBGMT_EOF\fP(\fIx\fP):
|
2004-11-03 13:51:07 +00:00
|
|
|
The tape is positioned just after a filemark
|
2007-12-17 10:22:31 +00:00
|
|
|
(always false after an
|
2007-12-16 15:34:59 +00:00
|
|
|
.B MTSEEK
|
|
|
|
operation).
|
2004-11-03 13:51:07 +00:00
|
|
|
.HP
|
2007-12-16 15:34:59 +00:00
|
|
|
\fBGMT_BOT\fP(\fIx\fP):
|
2004-11-03 13:51:07 +00:00
|
|
|
The tape is positioned at the beginning of the first file (always false
|
2007-12-16 15:34:59 +00:00
|
|
|
after an
|
|
|
|
.B MTSEEK
|
|
|
|
operation).
|
2004-11-03 13:51:07 +00:00
|
|
|
.HP
|
2007-12-16 15:34:59 +00:00
|
|
|
\fBGMT_EOT\fP(\fIx\fP):
|
2004-11-03 13:51:07 +00:00
|
|
|
A tape operation has reached the physical End Of Tape.
|
|
|
|
.HP
|
2007-12-16 15:34:59 +00:00
|
|
|
\fBGMT_SM\fP(\fIx\fP):
|
2004-11-03 13:51:07 +00:00
|
|
|
The tape is currently positioned at a setmark
|
2007-12-16 15:34:59 +00:00
|
|
|
(always false after an
|
|
|
|
.B MTSEEK
|
|
|
|
operation).
|
2004-11-03 13:51:07 +00:00
|
|
|
.HP
|
2007-12-16 15:34:59 +00:00
|
|
|
\fBGMT_EOD\fP(\fIx\fP):
|
2004-11-03 13:51:07 +00:00
|
|
|
The tape is positioned at the end of recorded data.
|
|
|
|
.HP
|
2007-12-16 15:34:59 +00:00
|
|
|
\fBGMT_WR_PROT\fP(\fIx\fP):
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-12-16 15:34:59 +00:00
|
|
|
\fBGMT_ONLINE\fP(\fIx\fP):
|
2004-11-03 13:51:07 +00:00
|
|
|
The last
|
2007-05-11 23:18:56 +00:00
|
|
|
.BR open (2)
|
2004-11-03 13:51:07 +00:00
|
|
|
found the drive with a tape in place and ready for operation.
|
|
|
|
.HP
|
2007-12-16 15:34:59 +00:00
|
|
|
\fBGMT_D_6250\fP(\fIx\fP), \fBGMT_D_1600\fP(\fIx\fP), \fBGMT_D_800\fP(\fIx\fP):
|
2004-11-03 13:51:07 +00:00
|
|
|
This \(lqgeneric\(rq status information reports the current
|
|
|
|
density setting for 9-track \(12" tape drives only.
|
|
|
|
.HP
|
2007-12-16 15:34:59 +00:00
|
|
|
\fBGMT_DR_OPEN\fP(\fIx\fP):
|
2004-11-03 13:51:07 +00:00
|
|
|
The drive does not have a tape in place.
|
|
|
|
.HP
|
2007-12-16 15:34:59 +00:00
|
|
|
\fBGMT_IM_REP_EN\fP(\fIx\fP):
|
2007-04-12 22:42:49 +00:00
|
|
|
Immediate report mode.
|
|
|
|
This bit is set if there are no guarantees that
|
2004-11-03 13:51:07 +00:00
|
|
|
the data has been physically written to the tape when the write call
|
2007-04-12 22:42:49 +00:00
|
|
|
returns.
|
|
|
|
It is set zero only when the driver does not buffer data and
|
2004-11-03 13:51:07 +00:00
|
|
|
the drive is set not to buffer data.
|
2005-04-05 12:20:49 +00:00
|
|
|
.HP
|
2007-12-16 15:34:59 +00:00
|
|
|
\fBGMT_CLN\fP(\fIx\fP):
|
2007-04-12 22:42:49 +00:00
|
|
|
The drive has requested cleaning.
|
|
|
|
Implemented in kernels >= 2.4.19 and 2.5.43.
|
2004-11-03 13:51:07 +00:00
|
|
|
.RE
|
2007-06-23 07:56:56 +00:00
|
|
|
.IP \fImt_erreg\fP
|
2004-11-03 13:51:07 +00:00
|
|
|
The only field defined in
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_erreg
|
2004-11-03 13:51:07 +00:00
|
|
|
is the recovered error count in the low 16 bits (as defined by
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MT_ST_SOFTERR_SHIFT
|
|
|
|
and
|
|
|
|
.BR MT_ST_SOFTERR_MASK .
|
2004-11-03 13:51:07 +00:00
|
|
|
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).
|
2007-06-23 07:56:56 +00:00
|
|
|
.IP \fImt_fileno\fP
|
2004-11-03 13:51:07 +00:00
|
|
|
reports the current file number (zero-based).
|
|
|
|
This value is set to \-1 when the file number is unknown (e.g., after
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MTBSS
|
|
|
|
or
|
|
|
|
.BR MTSEEK ).
|
2007-06-23 07:56:56 +00:00
|
|
|
.IP \fImt_blkno\fP
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-12-16 15:34:59 +00:00
|
|
|
.BR MTBSF ,
|
|
|
|
.BR MTBSS ,
|
|
|
|
or
|
|
|
|
.BR MTSEEK ).
|
|
|
|
.SS "MTIOCPOS \(em Get tape position"
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
This request takes an argument of type
|
2005-11-02 13:55:25 +00:00
|
|
|
.I "(struct mtpos *)"
|
2004-11-03 13:51:07 +00:00
|
|
|
and reports the drive's notion of the current tape block number,
|
|
|
|
which is not the same as
|
2007-06-23 07:56:56 +00:00
|
|
|
.I mt_blkno
|
2007-12-16 15:34:59 +00:00
|
|
|
returned by
|
|
|
|
.BR MTIOCGET .
|
2007-12-17 10:22:31 +00:00
|
|
|
This drive must be a SCSI-2 drive that supports the
|
2007-12-16 15:34:59 +00:00
|
|
|
.B "READ POSITION"
|
2004-11-03 13:51:07 +00:00
|
|
|
command (device-specific address)
|
|
|
|
or a Tandberg-compatible SCSI-1 drive (Tandberg, Archive
|
|
|
|
Viper, Wangtek, ... ).
|
|
|
|
.PP
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
2007-12-16 15:34:59 +00:00
|
|
|
/* structure for MTIOCPOS \- mag tape get position command */
|
2007-04-05 12:36:57 +00:00
|
|
|
struct mtpos {
|
|
|
|
long mt_blkno; /* current block number */
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
2007-12-16 15:34:59 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP 14
|
|
|
|
.TP
|
|
|
|
.B EACCES
|
2004-11-03 13:51:07 +00:00
|
|
|
An attempt was made to write or erase a write-protected tape.
|
|
|
|
(This error is not detected during
|
2007-05-11 23:18:56 +00:00
|
|
|
.BR open (2).)
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B EBUSY
|
2004-11-03 13:51:07 +00:00
|
|
|
The device is already in use or the driver was unable to allocate a
|
|
|
|
buffer.
|
2007-12-16 15:34:59 +00:00
|
|
|
.TP
|
|
|
|
.B EFAULT
|
|
|
|
The command parameters point to memory not belonging to the calling
|
|
|
|
process.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
2004-11-03 13:51:07 +00:00
|
|
|
An
|
2007-05-11 23:18:56 +00:00
|
|
|
.BR ioctl (2)
|
2004-11-03 13:51:07 +00:00
|
|
|
had an illegal argument, or a requested block size was illegal.
|
2007-12-16 15:34:59 +00:00
|
|
|
.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 2.2.18 and 2.4.0-test6 the extra bytes have been
|
|
|
|
silently ignored.)
|
|
|
|
.TP
|
|
|
|
.B ENOSPC
|
|
|
|
A write operation could not be completed because the tape reached
|
|
|
|
end-of-medium.
|
|
|
|
.TP
|
|
|
|
.B ENOSYS
|
2004-11-03 13:51:07 +00:00
|
|
|
Unknown
|
2007-05-11 23:18:56 +00:00
|
|
|
.BR ioctl (2).
|
2007-12-16 15:34:59 +00:00
|
|
|
.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.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH FILES
|
2007-10-03 06:17:53 +00:00
|
|
|
.TP 12
|
|
|
|
.I /dev/st*
|
|
|
|
the auto-rewind SCSI tape devices
|
|
|
|
.TP 12
|
|
|
|
.I /dev/nst*
|
|
|
|
the non-rewind SCSI tape devices
|
2007-06-08 12:01:06 +00:00
|
|
|
.\" .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.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
2007-12-16 15:34:59 +00:00
|
|
|
.IP 1. 4
|
|
|
|
When exchanging data between systems, both systems have to agree on
|
2007-04-12 22:42:49 +00:00
|
|
|
the physical tape block size.
|
|
|
|
The parameters of a drive after startup
|
2004-11-03 13:51:07 +00:00
|
|
|
are often not the ones most operating systems use with these
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2007-12-16 15:34:59 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
exchanging data with a foreign system.
|
|
|
|
The drawback of
|
2004-11-03 13:51:07 +00:00
|
|
|
this is that a fairly large tape block size has to be used to get
|
|
|
|
acceptable data transfer rates on the SCSI bus.
|
2007-12-16 15:34:59 +00:00
|
|
|
.IP 2.
|
|
|
|
Many programs (e.g.,
|
|
|
|
.BR tar (1))
|
|
|
|
allow the user to specify the blocking
|
2007-04-12 22:42:49 +00:00
|
|
|
factor on the command line.
|
|
|
|
Note that this determines the physical block
|
2005-04-05 12:20:49 +00:00
|
|
|
size on tape only in variable-block mode.
|
2007-12-16 15:34:59 +00:00
|
|
|
.IP 3.
|
|
|
|
In order to use SCSI tape drives, the basic SCSI driver,
|
2004-11-03 13:51:07 +00:00
|
|
|
a SCSI-adapter driver and the SCSI tape driver must be either
|
2007-04-12 22:42:49 +00:00
|
|
|
configured into the kernel or loaded as modules.
|
|
|
|
If the SCSI-tape
|
2004-11-03 13:51:07 +00:00
|
|
|
driver is not present, the drive is recognized but the tape support
|
|
|
|
described in this page is not available.
|
2007-12-16 15:34:59 +00:00
|
|
|
.IP 4.
|
|
|
|
The driver writes error messages to the console/log.
|
2007-04-12 22:42:49 +00:00
|
|
|
The SENSE
|
2004-11-03 13:51:07 +00:00
|
|
|
codes written into some messages are automatically translated to text
|
|
|
|
if verbose SCSI messages are enabled in kernel configuration.
|
2007-12-16 15:34:59 +00:00
|
|
|
.IP 5.
|
|
|
|
The driver's internal buffering allows good throughput in fixed-block
|
2007-04-12 22:42:49 +00:00
|
|
|
mode also with small
|
2007-05-11 23:18:56 +00:00
|
|
|
.BR read (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
and
|
2007-05-11 23:18:56 +00:00
|
|
|
.BR write (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
byte counts.
|
|
|
|
With direct transfers
|
2005-04-05 12:20:49 +00:00
|
|
|
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.
|
2007-05-19 04:30:20 +00:00
|
|
|
.\" .SH COPYRIGHT
|
2007-05-16 18:25:50 +00:00
|
|
|
.\" Copyright \(co 1995 Robert K. Nichols.
|
|
|
|
.\" .br
|
|
|
|
.\" 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
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\" Additional permissions are contained in the header of the source file.
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR mt (1)
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2007-10-03 06:17:53 +00:00
|
|
|
The file
|
|
|
|
.I drivers/scsi/README.st
|
|
|
|
or
|
|
|
|
.I Documentation/scsi/st.txt
|
|
|
|
(kernel >= 2.6) in the kernel sources contains
|
2007-05-16 18:25:50 +00:00
|
|
|
the most recent information about the driver and its configuration
|
|
|
|
possibilities.
|