[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4 Files Reference

rmt Special File

Purpose

Provides access to the sequential-access bulk storage medium device driver.

Description

Magnetic tapes are used primarily for backup, file archives, and other off-line storage. Tapes are accessed through the /dev/rmt0, ... , /dev/rmt255 special files. The r in the special file name indicates raw access through the character special file interface. A tape device does not lend itself well to the category of a block device. Thus, only character interface special files are provided.

Special files associated with each tape device determine which action is taken during open or close operations. These files also dictate, for applicable devices, at what density data is to be written to tape. The following table shows the names of these special files and their corresponding characteristics:

Tape Drive Special File Characteristics
Special File Name Rewind-on-Close Retension-on-Open Bytes per Inch
/dev/rmt* Yes No Density setting #1
/dev/rmt*.1 No No Density setting #1
/dev/rmt*.2 Yes Yes Density setting #1
/dev/rmt*.3 No Yes Density setting #1
/dev/rmt*.4 Yes No Density setting #2
/dev/rmt*.5 No No Density setting #2
/dev/rmt*.6 Yes Yes Density setting #2
/dev/rmt*.7 No Yes Density setting #2
  1. The values of density setting #1 and density setting #2 come from tape drive attributes that can be set using SMIT. Typically density setting #1 is set to the highest possible density for the tape drive while density setting #2 is set to a lower density. However, density settings are not required to follow this pattern.
  2. The density value (bytes per inch) is ignored when using a magnetic tape device that does not support multiple densities. For tape drives that do support multiple densities, the density value only applies when writing to the tape. When reading, the drive defaults to the density at which the tape is written.
  3. Most tape drives use 512-byte block size. The 8mm tape drive uses a minimum block size of 1024 bytes. Using SMIT to lower the block size, will waste space.

Usage Considerations

Most tape operations are implemented using the open, read, write, and close subroutines. However, for diagnostic purposes, the openx subroutine is required.

open and close Subroutines

Care should be taken when closing a file after writing. If the application reverses over the data just written, no file marks will be written. However, for tape devices that allow for block update, unless the application spaces in the reverse direction or returns the tape position to the beginning of tape (BOT), one or two file marks will be written upon closing the device. (The number of file marks depends on the special file type.)

For multitape jobs, the special file must be opened and closed for each tape. The user is not allowed to continue if the special file is opened and the tape has been changed.

The openx subroutine is intended primarily for use by the diagnostic commands and utilities. Appropriate authority is required for execution. Executing this subroutine without the proper authority results in a return value of -1, with the errno global variable set to EPERM.

read and write Subroutines

When opened for reading or writing, the tape is assumed to be positioned as desired. When the tape is opened as no-rewind-on-close (/dev/rmt*.1) and a file is written, a single file mark is written upon closing the tape. When the tape is opened as rewind-on-close (/dev/rmt*) and a file is written, a double file mark is written upon closing the tape. When the tape is opened as no-rewind-on-close and reads from a file, the tape is positioned upon closing after the end-of-file (EOF) mark following the data just read.

By specifically choosing the rmt file, it is possible to create multiple file tapes.

Although tapes are accessed through character interface special files, the number of bytes required by either a read or write operation must be a multiple of the block size defined for the magnetic tape device. When the tape drive is in variable block mode, read requests for less than the tape's block size return the number of bytes requested and set the errno global variable to a value of 0. In this case, the readx subroutine's Extension parameter must be set to TAPE_SHORT_READ.

During a read, the record size is returned as the number of bytes read, up to the buffer size specified. If an EOF condition is encountered, then a zero-length read is returned, with the tape positioned after the EOF.

An end-of-media (EOM) condition encountered during a read or write operation results in the return of the number of bytes successfully ready or written. When a write is attempted after the device has reached the EOM, a value of -1 is returned with the errno global variable set to the ENXIO value. When a read is attempted after the device has reached the EOM, a zero-length read is returned. Successive reads continue to return a zero-length read.

Data Buffering With a Tape Device: Some tape devices contain a data buffer to maximize data transfer speed when writing to tape. A write operation sent to tape is returned as complete when the data is transferred to the data buffer of the tape device. The data in the buffer is then written to tape asynchronously. As a result, data-transfer speed increases since the host need not wait for I/O completion.

Two modes are provided by the tape device driver to facilitate use of these data buffers. The non-buffered mode causes writes to tape to bypass the data buffer and go directly to tape. In buffered mode, all write subroutines are returned as complete when the transfer data has been successfully written to the tape device buffer. The device driver does not flush the data buffer until the special file is closed or an EOM condition is encountered.

If an EOM condition is encountered while running in buffered mode, the device attempts to flush the device data buffer. The residual count can exceed the write transfer length in buffered mode. In some cases, the flushing of residual data may actually run the tape off the reel. Either case is considered a failure and results in a return value of -1, with the errno global variable set to EIO. These errors can require the user to run in non-buffered mode.

rmt Special File Considerations: Failures that result in a device reset while reading or writing to tape require the special file to be closed and the job restarted. Any commands issued after this condition occurs and until the special file is closed result in a return value of -1, with the errno global variable set to EIO. Non-reset type errors (that is, media or hardware errors) result in the tape being left positioned where the error occurred.

For multi-tape jobs, the special file must be opened and closed for each tape. The user is not allowed to continue if the special file is opened and the tape has been changed.

A signal received by the tape device driver will cause the current command to abort. As a result, the application halts time-consuming commands (for instance, an erase operation) without recycling the drive power or waiting for a timeout to occur.

Use of zero (0) as a block-size parameter indicates the blocksize is of variable length.

ioctl Subroutine

A single ioctl operation, IOCINFO, is defined for all device drivers that use the ioctl subroutine. For the rmt special file, the STIOCTOP operation has also been defined.

The IOCINFO ioctl operation: The IOCINFO ioctl operation returns a structure defined in the /usr/include/sys/devinfo.h file.

The STIOCTOP ioctl operation: The STIOCTOP ioctl operation provides for command execution operations, such as erase and retension. The parameter to the ioctl subroutine using the STIOCTOP operation specifies the address of a stop structure, as defined in the /usr/include/sys/tape.h file.

The operation found in the st_op field in the stop structure is performed st_count times, except for rewind, erase, and retension operations. The available operations are:

STREW Rewind.
STOFFL Rewind and unload the tape. A tape must be inserted before the device can be used again.
STERASE Erase tape; leave at load point.
STRETEN Retension tape; leave at load point.
STWEOF Write and end-of-file mark.
STFSF Forward space file.
STFSR Forward space record.
STRSF Reverse space file.
STRSR Reverse space record.
STDEOF Disable end-of-file check.
Note: Use of the STDEOF command enables an application to write beyond the end of the tape. When disabling end-of-file checking by issuing the STDEOF command, it is the responsibility of the application to guard against error conditions that can arise from the use of this command.
Note: Execution of the preceding commands depends on the particular tape device and which commands are supported. If the command is not supported on a particular device, a value of -1 is returned, with the errno global variable set to EINVAL.

Error Codes

In addition to general error codes listed for ioctl, open, read, and write subroutines, the following specific error codes may also occur:

EAGAIN An open operation was attempted to a device that is already open.
EBUSY The target device is reserved by another initiator.
EINVAL O_APPEND is supplied as a mode in which to open.
EINVAL An nbyte parameter to a read or write subroutine is not an even multiple of the blocksize.
EINVAL A parameter to the ioctl subroutine is invalid.
EINVAL The requested ioctl operation is not supported on the current device.
EIO Could not space forward or reverse st_count records before encountering an EOM condition or a file mark.
EIO Could not space forward or reverse st_count file marks before encountering an EOM condition.
EMEDIA The tape device has encountered an unrecoverable media error.
ENOMEM The number of bytes requested for a read of a variable-length record on tape is less than the actual size (in bytes) of the variable-length record.
ENOTREADY There is no tape in the drive or the drive is not ready.
ENXIO A write operation was attempted while the tape was at the EOM.
EPERM The requested subroutine requires appropriate authority.
ETIMEDOUT A command has timed out.
EWRPROTECT An open operation for read/write was attempted on a read-only tape.
EWRPROTECT An ioctl operation that effects media was attempted on a read-only tape.

Implementation Specifics

The rmt SCSI device driver provides further information about implementation specifics.

The rmt special file is part of Base Operating System (BOS) Runtime.

Related Information

Special Files Overview.

The rmt SCSI Device Driver in AIX Technical Reference: Kernel and Subsystems Volume 1.

The close subroutine, ioctl subroutine, open subroutine, openx subroutine, read subroutine, write subroutine.


[ Previous | Next | Contents | Glossary | Home | Search ]