mtio(7)mtio(7)NAMEmtio - magnetic tape interface
DESCRIPTION
This description applies to all mass storage tape drives. The /dev/tape
directory special files, such as tape0, tape20_d0, tape3_d7, refer to
the mass storage tape drives. Tape drives can exist on different buses,
and have different bus/formatter/controller dependencies.
Special Files
This release supports revised device special file names for tape
devices. Device file names have the base name tapeN, where N is a dec‐
imal number denoting the instance of the device, and a suffix comprised
of the characters _d followed by a single digit. For example tape0_d0.
This suffix determines the density of the tape device, according to the
entry for the device in the /etc/ddr.dbase file.
There are also two forms of device special files that allow you to
specify the defult density for a device and to enable compression, if
supported on a particular device:
Device Special File Function /dev/tape/tapeN default den‐
sity for a rewind device /dev/tape/tapeNc enable compression for
a rewind device /dev/ntape/tapeN default density for a non-
rewind device /dev/ntape/tapeNc enable compression for a non-
rewind device
Note that with the new device special file naming, there is a direct
mapping from the old name suffix to the new name suffix as follows:
Old Suffix New suffix l (low) _d0 m (medium)
_d2 h (high) _d1 a (alternate) _d3
There are two sets of device names for tape that both conform to the
new naming convention. The /dev/tape directory for rewind devices and
the /dev/ntape directory (for no rewind). To determine which device
special file to use, you can look in the /etc/ddr.dbase file.
The special files in /dev/tape cause a loaded and on-line tape to auto‐
matically rewind to the beginning-of-tape (BOT) when closed. Low,
medium, and high density are relative to the densities supported on a
particular tape drive. See tz(7) for more information. The special
files in /dev/ntape do not cause a rewind when closed, regardless of
density. The tape remains in the same position as it was when it was
last accessed.
These special files are available to all operating system utilities
that can perform I/O to tape.
Magnetic Tape Operations
Magnetic tape ioctl system calls perform tape operations. The opera‐
tions come under three ioctl request groups. The MTIOCTOP ioctl is used
to issue tape operation commands. The MTIOCGET ioctl is used to obtain
status. The MTIOCRDPOS ioctl is used to obtain tape position informa‐
tion from the tape drive.
MTIOCTOP ioctl Commands
The mtop data structure is passed as a parameter to the MTIOCTOP ioctl.
Please see the /usr/include/sys/mtio.h header file for a definition of
the mtop structure.
The mt_op field specifies the MTIOCTOP tape command to be performed.
The mt_count field specifies the number of times the command should be
performed (where applicable).
The following MTIOCTOP tape commands are supported: Writes an end-of-
file to the tape. Physically, an end of file consists of a tape mark.
Repositions forward the number of files specified in the mt_count
field. This command repositions the tape forward the specified number
of tape marks. (Tape marks delimit files.) Upon successful completion
of this command, the tape is physically positioned at the end of the
specified number of tape marks. Repositions backward the number of
files specified in the mt_count field. This command repositions the
tape backward the specified number of tape marks. (Tape marks delimit
files.) Upon successful completion of the command, the tape is physi‐
cally positioned at the beginning of the specified number of tape
marks.
Note
Because MTFSF leaves the tape positioned at the end of a tape
mark and MTBSF leaves it positioned at the beginning, these two
commands are not strictly reciprocal operations. For example,
if a tape is initially positioned at the beginning of tape (BOT)
and the command MTFSF 1 is issued followed by the command MTBSF
1, the tape does not return to the BOT position. Instead, the
tape is positioned on the BOT side of the first tape mark. Re‐
positions forward the number of records specified in the
mt_count field. This command returns a failure if a tape mark
is encountered to indicate that there were not as many records
remaining in the file as there were records specified by the
mt_count field. Repositions backward the number of records
specified in the mt_count field. This command returns a failure
if a tape mark is encountered to indicate that there were not as
many records between the present position and the beginning of
the file as specified in the mt_count field. Rewinds the tape.
This command repositions to the beginning of the tape. Rewinds
and unloads the tape. Does not perform any tape operation.
Always returns success from a tape file. Enables the use of
hardware-based write-back caching for better performance.
Caching can speed tape transfer operations, thereby keeping the
unit streaming more effectively. If you use the MTCACHE command,
use the MTFLUSH command to flush cached data to media. SCSI tape
drives that support caching have their cache turned on automati‐
cally by the driver; the MTCACHE command is unnecessary. Dis‐
ables use of the controller's hardware-based write-back cache.
Tape operations using this command are slower than tape opera‐
tions using the MTCACHE command, but do not require use of the
MTFLUSH command to guarantee that the data is immediately writ‐
ten to tape. Clears a serious exception. Certain operations
cause the tape unit to go into a serious exception state. This
can happen, for example, when the physical end-of-media foil is
encountered. Typically, when a tape is in a serious exception
state, all data transfer operations fail. Use the MTCSE command
to acknowledge the exception condition and allow further opera‐
tions to proceed. Clears a hardware or software error. Clears
the subsystem. Enables end-of-tape detection. When the end-of-
tape markers are reached, the tape is halted on the reel between
the two end-of-tape markers. Only the superuser can issue this
command. The MTENAEOT command remains in effect for the device
until end-of-tape detection is disabled with the MTDISEOT com‐
mand. This is the default mode after a system boot. Disables
end-of-tape detection. When the end of tape is reached, the
tape will run off the reel. Only the superuser can issue this
command. The MTDISEOT command remains in effect for the device
until end-of-tape detection is enabled with the MTENAEOT com‐
mand. Flushes the hardware-based write-back cache. For tapes
that have controller-based caching (for example, TMSCP tapes),
use this command with the MTCACHE command. For tapes that have
device-based caching (for example, SCSI tapes), use this command
by itself. When caching has been enabled, writes to the tape
receive a completion status when the data has been transferred
to the cache, not when the data is transferred to the media. Use
the MTFLUSH command to force a flush of the cache to physical
media. Failure of this command with errno set to ENXIO means
that the drive does not support the flush command. However, SCSI
devices do not return ENXIO; therefore you cannot rely on the
MTFLUSH command to determine whether caching is enabled. Failure
with errno set to EIO indicates that the cache flush has failed.
In this case, the application should retry writing records that
have been written since the last successful MTFLUSH command.
Retensions the tape by moving the tape one complete pass between
EOT and BOT. Moves the tape to the end of recorded data.
Erases the tape. Loads and rewinds the tape. Loads the tape.
Unloads the tape. Enables scatter/gather IO for the readv() and
writev() system calls. After this command, any readv() or
writev() system calls will cause the tape driver to transfer all
iovec buffers in the list in a single transfer to tape. Dis‐
ables scatter/gather IO for the readv() and writev() system
calls. After this command, each buffer provided in a readv() or
writev() system call will be transferred by itself. Sends a
SCSI LOCATE command to the tape drive, telling it to position
the tape to the SCSI logical block address specified by the
mt_count field. Sends a SCSI LOCATE command to the tape drive,
telling it to position the tape to the device specific address
specified by the mt_count field.
MTIOCGET ioctl Requests
The mtget data structure is passed as a parameter to the MTIOCGET
ioctl. Please see the /usr/include/sys/mtio.h header file for a defi‐
nition of the mtget structure.
The following list describes the fields of the mtget data structure:
Provides driver-specific drive status information. This is the same
information provided in the stat member of the devget structure used by
the DEVIOCGET ioctl.
For the TMSCP driver, please see the /usr/include/sys/devio.h>
header file for bit definitions of the stat member.
For the SCSI tape driver, please see the
/usr/include/io/cam/cam_tape.h header file for bit definitions
of the ts_flags member of the TAPE_SPECIFIC structure. Provides
driver-specific error information.
For the TMSCP driver, please see table B-1 in the
/usr/include/io/dec/sysap/mscp_msg.h header file for error code
definitions.
For the SCSI tape driver, the mt_erreg member contains the sense
key byte of the sense data from a SCSI REQUEST SENSE command.
Please see the /usr/include/io/cam/scsi_all.h header file or the
SCSI-2 standard for definitions of the sense key. Also included
in this byte are the Filemark, EOM, and ILI bits as defined in
the SCSI-2 standard. Contains command-specific results. For
example, after a read command using a variable block-length
tape, mt_resid contains the residual number of bytes not trans‐
ferred. Another example is the space command. After a space
command, mt_resid contains the number of blocks or files not
spaced over. Contains the file position of the tape. Contains
the record position within a file.
Extended error information can be found in the /usr/include/io/com‐
mon/deveei.h header file.
MTIOCRDPOS ioctl Requests
The mtrdpos data structure is passed as a parameter to the MTIOCRDPOS
ioctl. Please see the /usr/include/sys/mtio.h header file for a defi‐
nition of the mtrdpos, mtrdposs, and mtrdposl structures.
The following two structure members of the mtrdpos structure are infor‐
mation provided by the application to control the format of the data
returned by the tape drive. The un member of this structure contains
data passed back to the application from the tape drive.
This is a single bit which, if set, tells the SCSI tape driver to send
the READ POSITION command, requesting that the tape drive return the
long data format. This is a single bit which, if set, tells the SCSI
tape driver to send the READ POSITION command, requesting that the tape
drive return the short data format with device specific addresses,
rather than the SCSI logical block addresses. If the long_format field
is set, then this bit is ignored by the tape driver. This is a union
of the short (mtrdposs) and the long (mtrdposl) data format structures.
The values in the members of these data structures are copies of the
information in the short and long data formats returned by the SCSI
READ POSITION command as specified in the SCSI standard documentation.
Please note that the first_blk member of the mtrdposs structure and the
blk_num member of the mtrdposl structure return information in the form
which may be used with the MTSEEK and MTSEEKDS commands of the MTIOCTOP
ioctl.
System Call Behavior
Each read() or write() system call reads or writes the next record on
the tape. In the case of a write() system call, the record has the same
length as the buffer given. During a read() system call, the record
size is passed back as the number of bytes read, provided it is no
greater than the buffer size. If the record is long, an error is
returned. Seeks are ignored. Positioning is done with a tape ioctl
call. A zero byte count is returned when a tape mark is read, but
another read fetches the first record of the next tape file. When a
file open for writing is closed and the last user command was a write,
two end-of-file marks (EOF) are written. If a tape reaches the end-of-
tape (EOT) marker, the ENOSPC errno value is set.
Each read() or write() system call causes the file offset associated
with the device special file to be incremented. This file offset is
reset to 0 when the file is closed. If a program does an unusually
large number or reads and writes to the tape, it is possible to cause
the file offset to be incremented beyond the maximum allowable value.
When this happens, any further read() or write() system calls fail with
an error number of EINVAL. This situation can occur only if the tape
is read or written to several times over, using repositioning commands
such as MTREW to reposition backwards on the tape. It is recommended
that any application which expects to make numerous passes over the
tape use the lseek() system call to reset the file offset to zero, for
example, lseek(fd,0,0).
RESTRICTIONS
The MTRETEN ioctl is supported only by the SCSI QIC tape drive.
RETURN VALUES
For the DEVIOCGET and MTIOCGET ioctls, the DEV_TPMARK, DEV_SHRTREC,
DEV_EOM, DEV_OFFLINE, DEV_SOFTERR, and DEV_HARDERR tape driver flags
are in an indeterminate state unless the application has gotten an
unexpected return value from a system call (that is, read x bytes from
tape, and if the return value does not equal x, then the flags are not
in an indeterminate state).
The MTIOCGET ioctl call is non-intrusive. This means that the device
driver implements support for MTIOCGET solely by interrogating its data
structures. The device should not be perturbed. This also means that
the MTIOCGET ioctl call always returns ESUCCESS. However, because the
implementation of the MTIOCGET ioctl is dependent upon each device
driver, and upon each device driver's ioctl code, an errno status is
sometimes returned. An errno status returned from a MTIOCGET call
indicates an error condition inside the driver itself. These are usu‐
ally pre-processing errors inside the device driver's ioctl code.
ERRORS
The MTIOCTOP ioctl commands set errno to [ENXIO] if the command speci‐
fied in mt_op is not recognized or not supported by the respective tape
driver.
The following list describes the possible errno status returned from
MTIOCGET: The operation was successful. An error occurred while trying
to copy out ioctl data (FOP_IOCTL). The device database structure was
not present (no nexus). The device-specific data structure was not
present (device not opened). The device driver data structure was not
present (device not opened). The request was invalid or the requested
function is not supported. The requested function is not supported.
FILES
/dev/tape/dev?_d?
/dev/ntape/tape?_d?
SEE ALSOlseek(2), SCSI(7), tz(7), MAKEDEV(8)mtio(7)