mtio - magnetic tape interface
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 [Toc] [Back]
This release supports revised device special file names
for tape devices. Device file names have the base name
tapeN, where N is a decimal 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 density 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 automatically 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 [Toc] [Back]
Magnetic tape ioctl system calls perform tape operations.
The operations 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 information from
the tape drive.
MTIOCTOP ioctl Commands [Toc] [Back]
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 physically 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. Repositions
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 hardwarebased
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 automatically
by the driver; the MTCACHE command is
unnecessary. Disables use of the controller's
hardware-based write-back cache. Tape operations
using this command are slower than tape operations
using the MTCACHE command, but do not require use
of the MTFLUSH command to guarantee that the data
is immediately written 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 operations
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 command. 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 endof-tape
detection is enabled with the MTENAEOT command.
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. Disables 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 [Toc] [Back]
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 definition 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 transferred. 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/common/deveei.h header file.
MTIOCRDPOS ioctl Requests [Toc] [Back]
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 definition of the mtrdpos, mtrdposs, and
mtrdposl structures.
The following two structure members of the mtrdpos structure
are information 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 [Toc] [Back]
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 endof-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).
The MTRETEN ioctl is supported only by the SCSI QIC tape
drive.
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 usually pre-processing
errors inside the device driver's ioctl code.
The MTIOCTOP ioctl commands set errno to [ENXIO] if the
command specified 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.
/dev/tape/dev?_d?
/dev/ntape/tape?_d?
lseek(2), SCSI(7), tz(7), MAKEDEV(8)
mtio(7)
[ Back ] |
