 |
Index for
Section 7 |
|
 |
Alphabetical
listing for M |
|
 |
Bottom of
page |
|
mtio(7)
NAME
mtio - 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 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
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
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:
MTWEOF
Writes an end-of-file to the tape. Physically, an end of file consists
of a tape mark.
MTFSF
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.
MTBSF
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.
MTFSR
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.
MTBSR
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.
MTREW
Rewinds the tape. This command repositions to the beginning of the
tape.
MTOFFL
Rewinds and unloads the tape.
MTNOP
Does not perform any tape operation. Always returns success from a
tape file.
MTCACHE
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
automatically by the driver; the MTCACHE command is unnecessary.
MTNOCACHE
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.
MTCSE
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.
MTCLX
Clears a hardware or software error.
MTCLS
Clears the subsystem.
MTENAEOT
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.
MTDISEOT
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 command.
MTFLUSH
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.
MTRETEN
Retensions the tape by moving the tape one complete pass between EOT
and BOT.
MTSEOD
Moves the tape to the end of recorded data.
MTERASE
Erases the tape.
MTONLINE
Loads and rewinds the tape.
MTLOAD
Loads the tape.
MTUNLOAD
Unloads the tape.
MTENASGIO
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.
MTDISSGIO
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.
MTSEEK
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.
MTSEEKDS
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 definition of the
mtget structure.
The following list describes the fields of the mtget data structure:
mt_dsreg
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.
mt_erreg
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.
mt_resid
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.
mt_fileno
Contains the file position of the tape.
mt_blkno
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
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.
long_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
long data format.
dev_specific
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.
un 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 usually pre-processing
errors inside the device driver's ioctl code.
ERRORS
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:
[ESUCCESS]
The operation was successful.
[EFAULT]
An error occurred while trying to copy out ioctl data (FOP_IOCTL).
[ENODEV]
The device database structure was not present (no nexus).
[ENXIO]
The device-specific data structure was not present (device not opened).
[ENOMEM]
The device driver data structure was not present (device not opened).
[EINVAL]
The request was invalid or the requested function is not supported.
[ENOTSUP]
The requested function is not supported.
FILES
/dev/tape/dev?_d?
/dev/ntape/tape?_d?
SEE ALSO
lseek(2), SCSI(7), tz(7), MAKEDEV(8)
|
Index for
Section 7 |
|
|
Alphabetical
listing for M |
|
 |
Top of
page |
|