mtio(7) mtio(7)
NAME
mtio - Magnetic Tape Interface
DESCRIPTION
The IOS tape subsystem /dev/iosb/[r]stapeppu[c][h][n][o][v][g] is the
supported magnetic tape interface. Refer to the stape(7) manual page
for more information.
Magnetic tape filenames have the following format for the I/O subsys-
tems:
/dev/iosb/[r]stapeppu[c][h][n][o][v][g]
b Bus number (always 0).
r Designates the raw device.
pp Depending on the subsystem, designates the controller number(s).
Refer to the stape(7) manual pages for more information.
u The SCSI tape drive number. This number ranges from 0 to 15. For
values 10 to 15 the hex representation a to f will be used. It is
important that the device address does not conflict with the SCSI
ID of the host adapter.
h designates the high density device.
n Designates the no-rewind on close device.
c Designates the compression density device.
o Designates the OSX compatibility no-rewind on close device.
v Designates the variable block mode for devices which allow both
variable and fixed block mode.
g With these devices, the drive can be written to or read from
directly via an ioctl interface with the relevant SCSI commands.
If desired, the files /dev/rmt0, /dev/rmt4, /dev/rmt8 and /dev/rmt12
may be created as links to the device in /dev/ios0 as appropriate. The
rmt files are linked as follows:
rmt0 designates the default, low density device.
rmt4 designates the no-rewind on close device.
rmt8 designates the high density device.
rmt12 designates the high density device, no-rewind on close
device.
Page 1 Reliant UNIX 5.44 Printed 11/98
mtio(7) mtio(7)
For nine-track tape drives, low- and high-density are either 800/1600
or 1600/6250 bpi, depending on the device type. For Quarter-Inch Com-
patible (QIC) tape drives, low- and high-density depends on the tape
used and the device type. For DDS (Digital Data Storage) DAT (Digital
Audio Tape) drives, low and high density are the same (it is not an
error to specify the high density device, but the drive does nothing
different).
The actions taken by the tape drive at close depend on how the drive
was opened and what it was used for.
The default tape drive (for example, /dev/ios0/rstape004) will write 2
file marks (1 file mark if it is a QIC tape device) and rewind to the
Beginning-of-Tape (BOT) at device close if the device was opened for
writing. If reading the tape, it will be rewound to BOT at close. The
tape will be written using the drive's default density.
The high density tape (for example, /dev/ios0/rstape004h) will act the
same as the default tape detailed above, except the tape will be writ-
ten using the drive's high density.
The no-rewind tape (for example, /dev/ios0/rstape004hn or
/dev/ios0/rstape004n) behaves very differently than the default tape.
If writing the tape, 2 file marks will be written to the tape at close
(1 file mark if it's a QIC drive) and the tape will be positioned
after the first file mark at close. If reading the tape, it will be
positioned after the file mark. So, if you are reading, do a close and
the tape is not currently just after a file mark, the driver will do a
forward space file to position the tape after the next file mark. If
you are reading, do a close, and the tape is currently just after a
file mark, the position will not be changed. The density the tape is
written will depend on whether the h device was used.
The OSX no-rewind tape (for example, /dev/ios0/rstape004o) will behave
like the standard no-rewind tape with the difference, that the tape
will not be positioned after reads.
Currently, only the raw (character) interface is supported by the IOS
tape subsystem. An attempt to open the IOS block tape device will
result in EINVAL error returned by the open routine.
Reading a tape as a block device requires that the tape was written
using 2048-byte records. This can be done with the character device.
Then, if supported, the block device can be read. The tape will be
read using 2048-byte record size. Using this method, the system makes
it possible, if inefficient, to treat the block tape device like any
other file. Seeks have their usual meaning and it is possible to read
a byte at a time. Writing in very small units is inadvisable, however,
because it tends to create monstrous record gaps in variable block-
sized tapes and can have a negative effect on performance.
Page 2 Reliant UNIX 5.44 Printed 11/98
mtio(7) mtio(7)
Each read or write call reads or writes the next record on the tape.
In the write case, the record has the same length as the buffer given.
During a read, 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
longer, an error is indicated. In raw tape, I/O seeks are ignored. A
zero byte count is returned when a tape mark is read. Subsequent reads
will continue until another file mark is encountered or another error
is detected (such as End-of-Tape).
A number of ioctl operations are available on raw magnetic tape. The
following definitions are from </usr/include/sys/mtio.h>:
/*
* Structures and definitions for mag tape io control commands
*/
/* structure for MTIOCTOP - mag tape op command */
struct mtop
{
short mtop; /* operations defined below */
daddrt mtcount; /* how many of them */
};
/* operations */
#define MTWEOF 0 /* write an end-of-file record */
#define MTFSF 1 /* forward space file */
#define MTBSF 2 /* backward space file */
#define MTFSR 3 /* forward space record */
#define MTBSR 4 /* backward space record */
#define MTREW 5 /* rewind */
#define MTOFFL 6 /* rewind and put the drive offline */
#define MTNOP 7 /* no operation, sets status only */
#define MTRET 8 /* retension operation */
#define MTRST 9 /* reset operation */
#define MTBLKSIZE 10 /* get block size */
#define MTONL 11 /* put drive online */
#define MTAPP 12 /* space to end of data */
#define MTERA 13 /* erase fixed length of tape */
#define MTRETEN 14 /* retension (Cartridge tape only) */
#define MTWSM 15 /* currently unused */
#define MTFSSM 16 /* currently unused */
#define MTBSSM 17 /* currently unused */
#define MTRELOF 18 /* permanently reserved */
/* structure for MTIOCGET - mag tape get status command */
struct mtget
{
short mttype; /* type of magtape device */
/* the following two registers are grossly device dependent */
short mtdsreg; /* "drive status" register */
short mterreg; /* "error" register */
/* end device-dependent registers */
Page 3 Reliant UNIX 5.44 Printed 11/98
mtio(7) mtio(7)
daddrt mtresid; /* residual count */
/* the following two are not yet implemented */
daddrt mtfileno; /* file number of current position */
daddrt mtblkno; /* block number of current position */
/* end not yet implemented */
};
/*
* Constants for mttype byte
*/
#define MTTIOC 0x08 /* IOC/Tapemaster tape drive */
#define MTTTPE 0x09 /* TPE/Pertec tape drive */
#define MTTIOS 0x0a /* IOS/Tape drive */
/* mag tape io control commands */
#define MTIOC ('t'<<8)
#define MTIOCTOP (MTIOC|1) /* do a mag tape op */
#define MTIOCGET (MTIOC|2) /* get tape status */
#define MTIOCPOSTEOTOK (MTIOC|3) /* allow post-eot writes */
#define MTIOCEOTCOMPAT (MTIOC|4) /* enable EOT compatibility */
#define MTIOCGETIOSTAT (MTIOC|5) /* get iotime */
#define MTIOSGETERROR (MTIOC|6) /* get error stats */
If the node of a tape device is opened, the tape driver reserves this
device for the duration of the job and frees it again when the job is
finished. High-performance tape drives sometimes have two independent
SCSI buses which enable connection to two different systems at the
same time. The ioctl command MTRELOF was introduced for this purpose
so that one of the connected systems can permanently reserve the tape
drive for the duration of several jobs. The ioctl command MTRELOF has
its own structure for communicating with the operating system. Apart
from permanently reserving and freeing the drive, the reservation
status of a tape device can also be queried.
/* Structure of MTRELOF command for permanently reserving
tape devices */
struct resrel {
short rescmd; /* command for reserving, querying */
/* or determining the status */
short stat; /* return of reservation status */
};
/* Definitions of commands and returned status */
#define RESRELEASE 0
/* command for freeing a reservation */
#define RESRESERVE 1
/* command for permanent reservation */
#define RESSTATUS 2
/* command for querying the reservation status */
Page 4 Reliant UNIX 5.44 Printed 11/98
mtio(7) mtio(7)
#define RESRESERVELOCAL 3
/* status in resrel.stat, if the device */
was reserved from the local system */
#define RESRESERVEREMOTE 4
/* status in resrel.stat, if the device */
was reserved from the remote system */
#define RESUNDEF 5
/* status in resrel.stat, if the reservation status */
could not be determined */
If a drive could not be reserved or freed, the errno variable is set
to the value EIO or EACCES. If the value is EACCES (no access permis-
sion), the device was reserved from another system.
In addition to the ioctl(2) operations represented here, all opera-
tions of the generic sgen driver are also available in the tape
driver. This can be used for all tape devices with a connected media
jukebox if the media jukebox and the tape device have a common SCSI-ID
and can therefore be addressed via a single node. With the help of
this interface, data media can, for example, be loaded in the actual
drive and unloaded in the appropriate slot. If the tape is to be writ-
ten to or read from directly by means of SCSI commands, the node with
the ending "g" should be used (e.g. /dev/ios0/rstape0XXg). However,
nodes with this ending only exist for high-performance drives. All
required information on this ioctl interface can be found in the
sgenio(7) manual page.
DIAGNOSTICS
The following is a list of all error conditions that may be encoun-
tered during tape operations. Each is followed by a short description,
documenting the error returned to the user and the state of the tape
after the error occurs.
Beginning-of-Tape (BOT) encountered
During the last tape operation, the physical BOT marker (foil)
was detected by the drive. The operation in progress is con-
sidered to have failed and an EIO error is returned. If the drive
is accessed as the block device, detection of BOT sets internal
state such that no further operations are allowed until the drive
is closed and reopened. Since the tape location over the drive
head is indeterminate after BOT, enforcement of this state
prevents inaccurate seeking.
Attempt to read blank tape or density mismatch
After beginning the current operation, the drive was unable to
detect the presence of formatted data on the tape within a
predetermined length. (NOTE: the actual length is entirely drive
dependent.) EIO is returned to the user and all data found should
be discarded. If the drive is accessed as the block device,
detection of blank tape sets internal state such that no further
operations are allowed until the drive is closed and reopened.
Since the tape location over the drive head is indeterminate
Page 5 Reliant UNIX 5.44 Printed 11/98
mtio(7) mtio(7)
after this error, enforcement of this state prevents inaccurate
seeking. This error may also be returned if the density selection
is changed manually after a tape is mounted and the burst is
read. Some tapes may appear blank to the drive after this hap-
pens, in which case a blank tape error is returned.
Correctable error
During the last tape operation the drive encountered a correct-
able error condition. In the case of reads, the data is unaf-
fected and no error is returned to the user, though an error is
logged for the system. In the case of writes and wfms, an EIO is
returned to the user only after a series of retry attempts are
made. The tape is backspaced one record and a fixed length erase
is performed and the I/O is tried again. If the retry sequence
fails, the driver is left in a state that prevents further opera-
tions until the device is closed and reopened.
Drive not ready (offline)
The drive has been taken physically offline during the last tape
operation or before it began and an ENXIO is returned to the
user. The condition is corrected by putting the drive back online
before the next operation is initiated. If the drive is accessed
as the block device, taking the drive offline marks the unit with
a hard error and no further operations are allowed until the
drive is closed and reopened. Since the tape location over the
drive head is indeterminate after being offline, enforcement of
this state prevents inaccurate seeking.
Drive is already in use
The drive was already opened by another process. An EBUSY is
returned to the user.
Drive write protected
The drive was opened for writing but the tape had write protected
(for example, no write ring or tab was set). An ENXIO is returned
to the user and the drive remains unopened. The tape must be
remounted with the write ring (or tab set correctly) or the drive
may be opened for read-only access.
End-of-File (EOF/FM) encountered
During the last tape operation a file mark was detected by the
drive. This is translated as a zero byte return value at the user
interface. The drive head is guaranteed to be at the beginning of
the next record. If the drive is accessed as the block device,
detection of a file mark sets the internal state such that no
further forward reads or seeks are allowed until the tape is
repositioned backwards (an lseek back) and additional data is
written over the file mark.
End-of-Tape (EOT) encountered
The behavior of tape I/O with regards to EOT is defined as fol-
lows:
Page 6 Reliant UNIX 5.44 Printed 11/98
mtio(7) mtio(7)
WRITES:
Writes proceed until the EOT (reel termination) condition is
detected. The software driver internally notes this condition,
but assuming the write was complete (return byte counts equals
request byte count), no error is returned to the user. Any subse-
quent writes cause the posting of an error (ENOSPC) to the user
without moving the tape.
READS:
Reads proceed until the EOT condition is detected. No error is
posted to the user. Reading may continue until input is satis-
fied, a filemark (zero byte return count) is encountered, or a
blank tape error is returned by the driver.
Previous versions of the operating system handled EOT in a dif-
ferent manner than that just described. As a result, some multi-
reel backups, generated by programs that used EOT as a reel ter-
mination signal (e.g. cpio), may require special handling to be
read back with the new subsystems. A new ioctl, MTIOCEOTCOMPAT,
is implemented for this purpose. MTIOCEOTCOMPAT forces the
software driver to generate an error in conjunction with the
event. An argument is also required that directs the software
driver to delay the EOT report by a corresponding number of
reads. Typically, the value supplied should be a 1; however,
tapes written on Kennedy tape drives at 6250 bpi may require a
value of 2. This is due to the variation in which drives detect
and report the EOT event and the effects of block size and den-
sity on that report. The MTIOCEOTCOMPAT ioctl may be issued any
time after open and before EOT is encountered.
FIFO over/underflow
During the last tape operation the drive FIFO was underrun (write
was in progress) or overrun (read was in progress). An EIO is
returned to the user only after a series of retry attempts are
made. In both underrun and overrun cases, the tape is backspaced
one record and the I/O is tried again. If the retry sequence
fails, the driver is left in a state that prevents further opera-
tions until the device is closed and reopened.
Hard error
During the last tape operation a media defect was encountered. An
EIO is returned to the user only after a series of retry attempts
are made. For reads, the tape is backspaced one record and the
I/O is tried again. For writes, the tape is backspaced one
record, a fixed length erase is performed and the I/O is tried
again. If the retry sequence fails, the driver is left in a state
that prevents further operations until the device is closed and
reopened.
Page 7 Reliant UNIX 5.44 Printed 11/98
mtio(7) mtio(7)
Reservation conflict
A tape drive was accessed that had already been reserved by
another system. Modern high-performance tape drives sometimes
enable connection to two systems at the same time because they
have two independent SCSI buses. If one of the systems has per-
manently reserved the tape drive, and if the second system tries
to access the drive, a Reservation conflict is reported.
Parity error
During the last tape operation, a parity error occurred during
data transfer to the tape. An EIO is returned to the user only
after a series of retry attempts are made. The tape is backspaced
one record and the I/O is tried again. If the retry sequence
fails, the driver is left in a state that prevents further opera-
tions until the device is closed and reopened.
Timeout on formatter - busy true
During a previous operation, the tape drive formatter had an
error and left the interface in an undefined state. The next
operation could not be initiated because one of the interface
signals (formatter - busy) failed to return to the false state
after a fixed timeout period. The most common cause of this error
is an attempt to write blocks larger than can be accepted by the
memory management firmware of a cached tape drive.
NOTES
Post-EOT I/O:
Post-EOT I/O is a feature that allows the writing of non-UNIX
format tapes that expect to place post-amble information (e.g.
volume marks) on a tape after EOT is encountered. Tapes made with
this type of format may now be read back. This feature works as
follows:
WRITES:
After EOT is reached, further I/O is allowed under either of two
conditions. In the first method, the tape unit in question must
be opened as the no-rewind device (minor device number bit 2 is
set). Closing the drive at EOT sets a state that allows post-EOT
I/O on the subsequent open. Note that 1 filemark remains on the
tape between the pre- and post-EOT sections of the tape. In the
second method, no special device is required at open, but upon
encountering the EOT condition, an ioctl, MTIOCPOSTEOTOK, must be
issued. This allows further I/O without closing the device and
leaves no interleaving filemark. In both cases, only eight more
I/Os are allowed, after which an EIO is returned. This state
remains set for all further writes and across opens until either
of two actions occur: the drive is closed and/or rewinds, or a
BSR/BSF ioctl is issued that repositions the drive before EOT.
Page 8 Reliant UNIX 5.44 Printed 11/98
mtio(7) mtio(7)
READS:
Reads proceed until the EOT condition is detected. No error is
posted to the user. Reading may continue until input is satis-
fied, a filemark (zero byte return count) is encountered, or a
blank tape error is returned by the driver. NOTE that if the tape
was created on a system like this one and the first method (clos-
ing and re-opening the no-rewind device at EOT; see the above
paragraph) was used, the intervening filemark will be encoun-
tered. Programs designed to read these tapes should expect this
event.
DIAGNOSTICS
The status should be returned in a device independent format.
The SCSI status bytes are not returned for IOS tapes.
FILES
/dev/iosb/[r]stapeppu[c][h][n][o][v][g]
/dev/rmt*
SEE ALSO
cpio(1), mt(1), tar(1), sgenio(7), stape(7), autoconf(8), tpsetup(8).
Page 9 Reliant UNIX 5.44 Printed 11/98