MTIO(4)

NAME
mtio - general magnetic tape interface

SYNOPSIS
#include <sys/types.h>
#include <sys/ioctl.h>
#include <sys/mtio.h>

DESCRIPTION

1/2”, 1/4” and 8 mm magnetic tape drives all share the same general character device interface.

There are two types of tape records: data records and end-of-file (EOF) records. EOF records are also known as tape marks and file marks. A record is separated by interrecord (or tape) gaps on a tape.

End-of-recorded-media (EOM) is indicated by two EOF marks on 1/2” tape; by one on 1/4” and 8 mm cartridge tapes.

  1/2” Reel Tape

Data bytes are recorded in parallel onto the 9-track tape. The number of bytes in a physical record varies between 1 and 65535 bytes.

The recording formats available (check specific tape drive) are 800 BPI, 1600 BPI, and 6250 BPI, and data compression. Actual storage capacity is a function of the recording format and the length of the tape reel. For example, using a 2400 foot tape, 20 MB can be stored using 800 BPI, 40 MB using 1600 BPI, 140 MB using 6250 BPI, or up to 700 MB using data compression.

  1/4” Cartridge Tape

Data is recorded serially onto 1/4” cartridge tape. The number of bytes per record is determined by the physical record size of the device. The I/O request size must be a multiple of the physical record size of the device. For QIC-11, QIC-24, and QIC-150 tape drives the block size is 512 bytes.

The records are recorded on tracks in a serpentine motion. As one track is completed, the drive switches to the next and begins writing in the opposite direction, eliminating the wasted motion of rewinding. Each file, including the last, ends with one file mark.

Storage capacity is based on the number of tracks the drive is capable of recording. For example, 4-track drives can only record 20 MB of data on a 450 foot tape; 9-track drives can record up to 45 MB of data on a tape of the same length. QIC-11 is the only tape format available for 4-track tape drives. In contrast, 9-track tape drives can use either QIC-24 or QIC-11. Storage capacity is not appreciably affected by using either format. QIC-24 is preferable to QIC-11 because it records a reference signal to mark the position of the first track on the tape, and each block has a unique block number.

The QIC-150 tape drives require DC-6150 (or equivalent) tape cartridges for writing. However, they can read other tape cartridges in QIC-11, QIC-24, QIC-120, or QIC-150 tape formats.

  8 mm Cartridge Tape

Data is recorded serially onto 8 mm helical scan cartridge tape. The number of bytes in a physical record varies between 1 and 65535 bytes.

  Read Operation

read(2V) reads the next record on the tape. The record size is passed back as the number of bytes read, provided it is no greater than the number requested. When a tape mark is read, a zero byte count is returned; another read will fetch the first record of the next tape file. Two successive reads returning zero byte counts indicate the EOM. No further reading should be performed past the EOM.

Fixed-length I/O tape devices require the number of bytes read to be a multiple of the physical record size. For example, 1/4” cartridge tape devices only read multiples of 512 bytes. If the blocking factor is greater than 64512 bytes (minphys limit), fixed-length I/O tape devices read multiple records.

Tape devices which support variable-length I/O operations, such as 1/2” and 8mm tape, may read a range of 1 to 65535 bytes. If the record size exceeds 65535 bytes, the driver reads multiple records to satisfy the request. These multiple records are limited to 65534 bytes.

  Write Operation
write(2V) writes the next record on the tape. The record has the same length as the given buffer.

Writing is allowed on 1/4” tape at either the beginning of tape or after the last written file on the tape.

Writing is not so restricted on 1/2” and 8 mm cartridge tape. Care should be used when appending files onto 1/2” reel tape devices, since an extra file mark is appended after the last file to mark the EOM. This extra file mark must be overwritten to prevent the creation of a null file. To facilitate write append operations, a space to the EOM ioctl is provided. Care should be taken when overwriting records; the erase head is just forward of the write head and any following records will also be erased.

Fixed-length I/O tape devices require the number of bytes written to be a multiple of the physical record size. For example, 1/4” cartridge tape devices only write multiples of 512 bytes. Fixed-length I/O tape devices write multiple records if the blocking factor is greater than 64512 bytes (minphys limit). These multiple writes are limited to 64512 bytes. For example, if a write request is issued for 65536 bytes using a 1/4” cartridge tape, two writes are issued; the first for 64512 bytes and the second for 1024 bytes.

Tape devices which support variable-length I/O operations, such as 1/2” and 8mm tape, may write a range of 1 to 65535 bytes. If the record size exceeds 65535 bytes, the driver writes multiple records to satisfy the request. These multiple records are limited to 65534 bytes. As an example, if a write request for 65540 bytes is issued using 1/2” reel tape, two records are written; one for 65534 bytes followed by one for 6 bytes.

EOT handling on write is different among the various devices; see the appropriate device manual page. Reading past EOT is transparent to the user.

Seeks are ignored in tape I/O.

  Close Operation

Magnetic tapes are rewound when closed, except when the “no-rewind” devices have been specified. The names of no-rewind device files use the letter n as the beginning of the final component. The no-rewind version of /dev/rmt0 is /dev/nrmt0.

If data was written, a file mark is automatically written by the driver upon close. If the rewinding device was specified, the tape will be rewound after the file mark is written. If the user wrote a file mark prior to closing, then no file mark is written upon close. If a file positioning ioctl, like rewind, is issued after writing, a file mark is written before repositioning the tape.

Note: for 1/2” reel tape devices, two file marks are written to mark the EOM before rewinding or performing a file positioning ioctl. If the user wrote a file mark before closing a 1/2” reel tape device, the driver will always write a file mark before closing to insure that the end of recorded media is marked properly. If the non-rewinding xt device was specified, two file marks are written and the tape is left positioned between the two so that the second one is overwritten on a subsequent open(2V) and write(2V). For performance reasons, some st drivers postpone writing the second tape mark until just before a file positioning ioctl is issued (for example, rewind). This means that the user must not manually rewind the tape because the tape will be missing the second tape mark which marks EOM.

If no data was written and the driver was opened for WRITE-ONLY access, a file mark is written thus creating a null file.

  Ioctls
Not all devices support all ioctls. The driver returns an ENOTTY error on unsupported ioctls.

The following structure definitions for magnetic tape ioctl commands are from <sys/mtio.h>:

The minor device byte structure looks as follows:
7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
Reserved | Unit # | Reserved | Density | Density | No rewind | Unit #
 | High Bit* |  | Select | Select | on Close | Lower 2 Bits

/*
 * Layout of minor device byte:
 */
#define MTUNIT(dev)		(((minor(dev) & 0x40) >> 4) + (minor(dev) & 0x3))
#define MT_NOREWIND	(1 <<2)
#define MT_DENSITY_MASK	(3 <<3)
#define MT_DENSITY1		(0 <<3)         /* Lowest density/format */
#define MT_DENSITY2		(1 <<3)
#define MT_DENSITY3		(2 <<3)
#define MT_DENSITY4		(3 <<3)         /* Highest density/format */
#define MTMINOR(unit)	(((unit & 0x04) << 4) + (unit & 0x3))

*NOTE that bit 6 of the minor device byte is always 0 for 4.1-based systems, since 4.1 supports a maximum of 4 SCSI tape drives. However, 4.1 PSR A-based systems support a maximum of 8 SCSI tape drives; thus this bit is 1 for st4 - st7. Note also that both 4.1 and 4.1 PSR A ship with the 4.1 version of /usr/include/sys/mtio.h. The additional bit with MTUNIT and MTMINOR macros is defined in the 4.1 PSR A version of mtio.h, found in /sys/sys/mtio.h on machines running 4.1 PSR A.

/* structure for MTIOCTOP - magnetic tape operation command */
struct	mtop	{
	short	mt_op;   	/* operation */
	daddr_t	mt_count;	/* number of operations */
};
The following ioctls are supported:
	MTWEOF	write an end-of-file record
	MTFSF	forward space over file mark
	MTBSF	backward space over file mark (1/2", 8 mm only)
	MTFSR	forward space to inter-record gap
	MTBSR	backward space to inter-record gap
	MTREW	rewind
	MTOFFL	rewind and take the drive offline
	MTNOP	no operation, sets status only
	MTRETEN	retension the tape (cartridge tape only)
	MTERASE	erase the entire tape and rewind
	MTEOM	position to EOM
	MTNBSF	backward space file to beginning of file
/* structure for MTIOCGET - magnetic tape get status command */
struct	mtget {
	short	mt_type;  		/* type of magtape device */

/* the following two registers are device dependent */
	short	mt_dsreg;  		/* “drive status” register */
	short	mt_erreg;  		/* “error” register */

/* optional error info. */
	daddr_t	mt_resid;  		/* residual count */
	daddr_t	mt_fileno;  		/* file number of current position */
	daddr_t	mt_blkno;  		/* block number of current position */
	u_short mt_flags;
	short   mt_bf;			/* optimum blocking factor */
};

When spacing forward over a record (either data or EOF), the tape head is positioned in the tape gap between the record just skipped and the next record. When spacing forward over file marks (EOF records), the tape head is positioned in the tape gap between the next EOF record and the record that follows it.

When spacing backward over a record (either data or EOF), the tape head is positioned in the tape gap immediately preceding the tape record where the tape head is currently positioned. When spacing backward over file marks (EOF records), the tape head is positioned in the tape gap preceding the EOF. Thus the next read would fetch the EOF.

Note, the following features are unique to the st driver: record skipping does not go past a file mark; file skipping does not go past the EOM. Both the st and xt drivers stop upon encountering EOF during a record skipping command, but leave the tape positioned differently. For example, after an MTFSR <huge number> command the st driver leaves the tape positioned before the EOF. After the same command, the xt driver leaves the tapes positioned after the EOF. Consequently on the next read, the xt driver fetches the first record of the next file whereas the st driver fetches the EOF. A related st feature is that EOFs remain pending until the tape is closed. For example, a program which first reads all the records of a file up to and including the EOF and then performs an MTFSF command will leave the tape positioned just after that same EOF, rather than skipping the next file.

The MTNBSF and MTFSF operations are inverses. Thus, an MTFSF “-1” is equivalent to an MTNBSF “1”. An MTNBSF “0” is the same as MTFSF “0”; both position the tape device to the beginning of the current file.

MTBSF moves the tape backwards by file marks. The tape position will end on the beginning of tape side of the desired file mark.

MTBSR and MTFSR operations perform much like space file operations, except that they move by records instead of files. Variable-length I/O devices (1/2” reel, for example) space actual records; fixed-length I/O devices space physical records (blocks). 1/4” cartridge tape, for example, spaces 512 byte physical records. The status ioctl residual count contains the number of files or records not skipped.

MTOFFL rewinds and, if appropriate, takes the device offline by unloading the tape. The tape must be inserted before the tape device can be used again.

MTRETEN The retension ioctl only applies to 1/4” cartridge tape devices. It is used to restore tape tension improving the tape's soft error rate after extensive start-stop operations or long-term storage.

MTERASE rewinds the tape, erases it completely, and returns to the beginning of tape.

MTEOM positions the tape at a location just after the last file written on the tape. For 1/4” cartridge and 8 mm tape, this is after the last file mark on the tape. For 1/2” reel tape, this is just after the first file mark but before the second (and last) file mark on the tape. Additional files can then be appended onto the tape from that point.

Note the difference between MTBSF (backspace over file mark) and MTNBSF (backspace file to beginning of file). The former moves the tape backward until it crosses an EOF mark, leaving the tape positioned before the file mark. The latter leaves the tape positioned after the file mark. Hence, "MTNBSF n" is equivalent to "MTBSF (n+1)" followed by "MTFSF 1". 1/4 ” cartridge tape devices do not support MTBSF.

The MTIOCGET get status ioctl call returns the drive id (mt_type), sense key error (mt_erreg), file number (mt_fileno), optimum blocking factor (mt_bf) and record number (mt_blkno) of the last error. The residual count (mt_resid) is set to the number of bytes not transferred or files/records not spaced. The flags word (mt_flags) contains information such as whether the device is SCSI, whether it is a reel device and whether the device supports absolute file positioning.

EXAMPLES

Suppose you have written 3 files to the non-rewinding 1/2” tape device, /dev/nrmt0, and that you want to go back and dd(1) the second file off the tape. The commands to do this are:

    mt -f /dev/nrmt0 bsf 3
    mt -f /dev/nrmt0 fsf 1
    dd if=/dev/nrmt0

To accomplish the same tape positioning in a C program, followed by a get status ioctl:

    struct mtop mt_command;
    struct mtget mt_status;
    mt_command.mt_op = MTBSF;
    mt_command.mt_count = 3;
    ioctl(fd, MTIOCTOP, &mt_command);
    mt_command.mt_op = MTFSF;
    mt_command.mt_count = 1;
    ioctl(fd, MTIOCTOP, &mt_command);
    ioctl(fd, MTIOCGET, (char *)&mt_status);

or

    struct mtop mt_command;
    struct mtget mt_status;
    mt_command.mt_op = MTNBSF;
    mt_command.mt_count = 2;
    ioctl(fd, MTIOCTOP, &mt_command);
    ioctl(fd, MTIOCGET, (char *)&mt_status);

FILES
/dev/rmt*
/dev/rst*
/dev/rar*
/dev/nrmt*
/dev/nrst*
/dev/nrar*

SEE ALSO
dd(1), mt(1), tar(1), read(2V), write(2V), ar(4S), st(4S), tm(4S), xt(4S)

1/4 Inch Tape Drive Tutorial

WARNINGS

Avoid the use of device files /dev/rmt4 and /dev/rmt12, as they are going away in a future release.