mt(7)mt(7)NAMEmt - magnetic tape interface and controls for stape and estape
DESCRIPTION
This entry describes the behavior of HP magnetic tape interfaces and
controls. The files refer to specific raw tape drives controlled by the
estape driver. The major number of these device special files is
dynamically allocated and the minor number does not encode any device
specific information.
The files refer to specific raw tape drives controlled by the legacy
stape driver, and the behavior of each given unit is specified in the
major and minor numbers of the DSF. The legacy driver and DSFs are
deprecated and will be removed in a future version of HP-UX.
Naming Conventions
The device special files (referred to as DSFs) for the driver have the
following naming conventions:
There are four such files (referred to as persistent DSFs) correspond‐
ing to each of the four different permutations of the and options.
These are claimed by the driver. See intro(7) for more details on per‐
sistent device special file names.
There are two naming conventions for legacy DSFs. The standard (pre‐
ferred) convention is used on systems that support long file names. An
alternate convention is provided for systems limited to short file
names. The following standard convention is recommended because it
allows for all possible configuration options in the device name and is
used by mksf(1M) and insf(1M):
#]][#]][
The following alternate naming convention is provided to support sys‐
tems in which the directory requires short file names. These DSF names
are less descriptive, but guarantee unique device naming and are used
by mksf(1M) and insf(1M) where required.
For each tape device present, twelve DSFs are automatically created
when the system is installed. If legacy mode is disabled (via the
option in only four DSFs in will be created post installation. These
are claimed by the driver.
Four legacy DSFs will be created in the directory using the following
naming convention. These are legacy DSFs and are claimed by the
driver.
Four more legacy DSFs with the format will be automatically created
when the system is installed using the pre-HP-UX 10.0 device file nam‐
ing convention. This includes an arbitrary number to distinguish this
tape device from others in the system, followed by the letter There are
four such DSFs because each of the four different permutations of the
and options (see below) are created. These files are created for com‐
patability with pre-HP-UX 10.0 scripts and for users who find the old
convention easier to remember.
Each of the automatically created DSFs which utilize the standard or
alternate naming conventions is linked to a device file which utilizes
the pre-HP-UX 10.0 naming convention. That is, the DSFs in the format
are created as hardlinks to the corresponding DSFs mentioned above.
Thus, the DSFs which utilize the pre-HP-UX 10.0 naming convention pro‐
vide the same functionality as the device files which contain the den‐
sity specification (standard naming convention).
Options
The options described here are common to all legacy tape drivers. The
notation in the legacy DSF name derives from output and is described in
the manpages for ioscan(1M) and intro(7).
Instance number assigned by the operating system to the interface card.
Target address on a remote bus (for example, SCSI address)
Device unit number at the target address (for example, SCSI LUN).
Writes wait for physical completion of the operation
before returning status. The default behavior (buffered mode
or immediate reporting mode) requires the tape device to buf‐
fer the data and return immediately with successful status.
density Density or format used in writing data to tape. This field
is designated by the following values:
Highest-capacity density or format will be used, including
data
compression, if the device supports compression.
Maintains the density used for data previously written to the
tape.
Behavior using this option is dependent on the
type of device. This option is only supported on
DDS drives.
DDS Selects one of the known DDS formats; can be used
to specify or as required.
DLT Selects one of the known DLT formats; can be used
to specify or as required.
D[#] Specifies density as a numeric value to be placed
in the SCSI mode select block descriptor. The
header file contains a list of the standard den‐
sity codes. The numeric value is used only for
density codes which be found in this list.
Write data in compressed mode,
on tape drives that support data compression. If a number is
included, use it to specify a compression algorithm specific
to the device. Note, compression is also provided when the
density field is set to
No rewind on close.
Unless this mode is requested, the tape is automatically
rewound upon close.
Specifies Berkeley-style tape behavior.
When the is absent, the tape drive follows AT&T-style behav‐
ior. The details are described in below.
Specify format (or density) value encoded in the minor
number. The meaning of the value is dependent on the type of
tape device in use. (Used for short file name notation
only.)
Specify an internal Property Table index value
maintained by the tape driver, containing an array of config‐
uration options. The contents of this table are not directly
accessible. Use the lssf(1M) command to determine which con‐
figuration options are invoked. (Used for short file name
notation only.)
Console message disabled. See
mksf(1M).
RTE compatible close. See
mksf(1M).
Exhaustive mode. See
section.
Tape partition. See
section.
Fixed-block mode. See
section.
For pre-HP-UX 10.x device file naming convention.
Sample Tape Device Special File Names
For a HP Ultrium-2 drive at card instance 1, target 2, LUN 3 the legacy
DSFs would be The corresponding persistent DSFs assuming an instance
number "1" allocated to the DSF would be Corresponding device special
files in the pre-HP-UX 10.0 naming convention would be In this particu‐
lar example, 0 (zero) in denotes an instance number of 0 (zero)
assigned to the DSF. The files in the format are created as hardlinks
to the corresponding DSFs.
Use the lssf(1M) command to determine which configuration options are
actually used with any device file. The naming convention defined
above should indicate the options used, but device files may be created
with any user defined name.
Tape Behavioral Characteristics
When opened for reading or writing, the tape is assumed to be posi‐
tioned as desired.
When a file opened for writing is closed, two consecutive EOF (End of
File) marks are written if, and only if, one or more writes to the file
have occurred. The tape is rewound unless the no-rewind mode has been
specified, in which case the tape is positioned before the second EOF
just written.
When a file open for reading (only) is closed and the no-rewind bit is
not set, the tape is rewound. If the no-rewind bit is set, the behav‐
iour depends on the style mode. For AT&T-style devices, the tape is
positioned after the EOF following the data just read (unless already
at BOT or Filemark). For Berkeley-style devices, the tape is not repo‐
sitioned in any way.
Each read(2) or write(2) call reads or writes the next record on the
tape. For writes, the record has the same length as the buffer given
(within the limits of the hardware).
During a read, the record size is passed back as the number of bytes
read, up to the buffer size specified. Since the minimum read length
on a tape device is a complete record (to the next record mark), the
number of bytes ignored (for records longer than the buffer size speci‐
fied) is available in the field of the structure via the call of
ioctl(2). Current restrictions require tape device application pro‐
grams to use 2-byte alignment for buffer locations and I/O sizes. To
allow for more stringent future restrictions (4-byte aligned, etc.)
and to maximize performance, page alignment is suggested. For example,
if the target buffer is contained within a structure, care must be
taken that structure elements before the buffer allow the target buffer
to begin on an even address. If need be, placing a filler integer
before the target buffer will insure its location on a 4-byte boundary.
The ascending hierarchy of tape marks is defined as follows: record
mark, filemark (EOF), setmark and EOD (End of Data). Not all devices
support all types of tape marks but the positioning within the hierar‐
chy holds true. Each type of mark is typically used to contain one or
more of the lesser marks.
When spacing over a number of a particular type of tape mark, hierar‐
chically superior marks (except EOD) do not terminate tape motion and
are included in the count. For instance, MTFSR can be used to pass over
record marks and filemarks.
Reading an EOF mark is returned as a successful zero-length read; that
is, the data count returned is zero and the tape is positioned after
the EOF, enabling the next read to return the next record.
DDS devices also support setmarks, which are used to delineate a group
(set) of files. Reading a setmark is also returned as a zero-length
read. Filemarks, setmarks and EOD can be distinguished by unique bits
in the field.
Spacing operations (back or forward space, setmark, file or record)
position past the object being spaced to in the direction of motion.
For example, back-spacing a file leaves the tape positioned before the
file mark; forward-spacing a file leaves the tape positioned after the
file mark. This is consistent with standard tape usage.
lseek(2) type seeks on a magnetic tape device are ignored. Instead,
the ioctl(2) operations below can be used to position the tape and
determine its status.
The header file has useful information for tape handling.
The minor number of the device ID of persistent tape device special
files no longer encode the tape device options (such as, density, style
of access and so on). Hence the macros given below, that are defined
in header file do not interpret the options correctly for persistent
(agile) DSFs. The macros are:
M_INSTANCE(dev)M_TARGET(dev)M_LUN(dev)M_BERKELEY(dev)M_NO_REWIND(dev)M_USER_CONFIG(dev)M_INDEX(dev) M_INDEX_PUT(dev,index)
M_DFLT_DENSITY(dev) M_DFLT_DENSITY_PUT(dev,density)
M_TRANSPARENT_MODE(dev)M_PROP_TBL_ACCESS(dev)
These macros continue to work on the legacy DSFs as before.
Applications should use the method described below to decode the tape
device options from persistent device files.
libIO(3X) API is used to decode the device options from the persistent
device files as given below:
#include <libIO.h>
#include <sys/_inttypes.h>
#include <fcntl.h>
Note: calls should be within calls to and Refer to libIO(3X) manpage
for more details. Applications have to link with libIO library to
access these APIs.
and are utility functions used by the code snippets below.
uint64_t
mt_get_newdev_options(dev_t dev, int dev_type) {
uint64_t options;
int err;
err = io_dev_to_options(dev, dev_type, &options);
if (err == IO_ERROR)
return 0;
return (options);
}
uint64_t
mt_check_newdev_options(dev_t dev, int dev_type, uint64_t bitmask) {
uint64_t options;
int err;
err = io_dev_to_options(dev, dev_type, &options);
if (err == IO_ERROR)
return 0;
return (options & bitmask);
}
For example, the macro given below decodes the device options of both
legacy and persistent (agile) DSFs. This macro returns true if the
device ID is that of a device special file supporting Berkeley style of
access.
File test.c :
#include <stdlib.h>
#include <sys/libIO.h>
#include <sys/_inttypes.h>
#include <sys/stat.h>
#include <sys/errno.h>
#include <fcntl.h>
#include <sys/mtio.h>
#define MT_IS_LEGACY_DEV 1
#define M_BERKELEY_AGILE(dev) \
((io_is_legacy_dev(dev, D_CHR) == MT_IS_LEGACY_DEV) ? \
(dev & MT_BSD_MASK) : \
(mt_check_newdev_options(dev, D_CHR, MT_BSD_MASK)))
/ *
* It is assumed that definitions of mt_get_newdev_options() and
* mt_check_newdev_options() are defined by the application and
* available. Omitted here for the sake of simplicity.
*/
int
main(int argc, char *argv[]) {
struct stat stbuf;
dev_t dev;
/* Device special file is passed as argv[1] */
if (stat(argv[1], &stbuf) < 0)
{
perror("stat(): ");
exit (1);
}
dev = stbuf.st_rdev;
io_init(O_RDWR);
if(M_BERKELEY_AGILE(dev))
printf(" This is a Berkeley style device file ");
else
printf(" This is not a Berkeley style device file ");
io_end();
exit(0);
}
Compile Line: cc -Ae -o test test.c -lIO
Sample Output:
# ./test /dev/rtape/tape1_BESTn
This is not a Berkeley style device file
# ./test /dev/rtape/tape1_BESTb
This is a Berkeley style device file
# ./test /dev/rmt/0mnb
This is a Berkeley style device file
# ./test /dev/rmt/c5t4d0BEST
This is not a Berkeley style device file
# ./test /dev/rmt/c5t4d0BESTnb
This is a Berkeley style device file
Macros similar to the one above, can be written in place of their
respective legacy macros as follows:
#define M_INSTANCE_AGILE(dev) \
((io_is_legacy_dev(dev, D_CHR) == MT_IS_LEGACY_DEV) ? \
(((dev) >> MT_INSTANCE_BIT_POS) & MT_INSTANCE_MASK) : \
(((mt_get_newdev_options(dev, D_CHR)) >> MT_INSTANCE_BIT_POS) \
& MT_INSTANCE_MASK))
#define M_TARGET_AGILE(dev) \
((io_is_legacy_dev(dev, D_CHR) == MT_IS_LEGACY_DEV) ? \
(((dev) >> MT_TARGET_BIT_POS) & MT_TARGET_MASK) : \
((mt_get_newdev_options(dev, D_CHR)) >> MT_TARGET_BIT_POS) \
& MT_TARGET_MASK))
#define M_LUN_AGILE(dev) \
((io_is_legacy_dev(dev, D_CHR) == MT_IS_LEGACY_DEV) ? \
(((dev) >> MT_LUN_BIT_POS) & MT_LUN_MASK) : \
((mt_get_newdev_options(dev, D_CHR) >> MT_LUN_BIT_POS) \
& MT_LUN_MASK))
#define M_USER_CONFIG_AGILE(dev) \
((io_is_legacy_dev(dev, D_CHR) == MT_IS_LEGACY_DEV) ? \
(dev & MT_USER_CONFIG_MASK) : \
(mt_check_newdev_options(dev, D_CHR, MT_USER_CONFIG_MASK)))
#define M_INDEX_AGILE(dev) \
((io_is_legacy_dev(dev, D_CHR) == MT_IS_LEGACY_DEV) ? \
(((dev) & MT_INDEX_MASK) >> MT_INDEX_BIT_POS) : \
((mt_check_newdev_options(dev, D_CHR, MT_INDEX_MASK)) >> \
MT_INDEX_BIT_POS));
#define M_INDEX_PUT_AGILE(dev,index) \
((io_is_legacy_dev(dev, D_CHR) == MT_IS_LEGACY_DEV) ? \
(((dev) & (~MT_INDEX_MASK)) | \
(index << MT_INDEX_BIT_POS) | \
MT_USER_CONFIG_MASK) : \
((mt_check_newdev_options(dev, D_CHR, ~MT_INDEX_MASK)) | \
(index << MT_INDEX_BIT_POS)))
#define M_DFLT_DENSITY_PUT_AGILE(dev,density) \
((io_is_legacy_dev(dev, D_CHR) == MT_IS_LEGACY_DEV) ? \
(((dev) & (~MT_DENSITY_MASK)) | \
(density << MT_DENSITY_BIT_POS)) : \
((mt_check_newdev_options(dev, D_CHR, ~MT_DENSITY_MASK)) | \
(density << MT_DENSITY_BIT_POS)))
#define M_TRANSPARENT_MODE_AGILE(dev) \
((io_is_legacy_dev(dev, D_CHR) == MT_IS_LEGACY_DEV) ? \
(((dev) & MT_TRANSPARENT_MASK) == \
MT_TRANSPARENT_VAL) : \
((mt_check_newdev_options(dev, D_CHR, MT_TRANSPARENT_MASK)) \
== MT_TRANSPARENT_VAL))
The following is included from and describes the possible tape opera‐
tions:
/* mag tape I/O control requests */
#define MTIOCTOP _IOW('m', 1, struct mtop) /* do mag tape op */
#define MTIOCGET _IOR('m', 2, struct mtget) /* get tape status */
/* structure for MTIOCTOP - mag tape op command */
struct mtop {
short mt_op; /* operations defined below */
int32_t mt_count; /* how many of them */
};
/* operations */
#define MTWEOF 0 /* write filemark (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 (may eject) */
#define MTNOP 7 /* no operation, may set status */
#define MTEOD 8 /* DDS, QIC and 8MM only - seek to end-of-data */
#define MTWSS 9 /* DDS and 8MM only - write setmark(s) */
#define MTFSS 10 /* DDS and 8MM only - space forward setmark(s) */
#define MTBSS 11 /* DDS and 8MM only - space backward setmark(s) */
#define MTSTARTVOL 12 /* Start a new volume (for ATS) */
#define MTENDVOL 13 /* Terminate a volume (for ATS) */
#define MTRES 14 /* Reserve Device */
#define MTREL 15 /* Release Device */
#define MTERASE 16 /* Erase media */
/* structure for MTIOCGET - mag tape get status command */
struct mtget {
long mt_type; /* type of magtape device */
long mt_resid; /* residual count */
/* The following two registers are device dependent */
long mt_dsreg1; /* status register (msb) */
long mt_dsreg2; /* status register (lsb) */
/* The following are device-independent status words */
long mt_gstat; /* generic status */
long mt_erreg; /* error register */
int32_t mt_fileno; /* No longer used - always set to -1 */
int32_t mt_blkno; /* No longer used - always set to -1 */
Information for decoding the field can be found in
Tape operations work the same way for both legacy and agile devices.
Other Tape Status Characteristics
Efficient use of streaming tape drives with large internal buffers and
immediate-reporting require the following end-of-tape procedures:
All writes near LEOT (Logical End of Tape) complete without
error if actually written to the tape. Once the tape driver
determines that LEOT has been passed, subsequent writes do not
occur and an error message is returned.
To write beyond this point (keep in mind that streaming drives
have already written well past LEOT), simply ask for status
using the ioctl. If status reflects the EOT condition, the
driver drops all write barriers.
Both the and drivers will flush the device buffers when a write
filemark (all devices) or write setmark (devices that support
setmarks) command is given with the count set to zero.
When immediate-reporting is disabled, the write encountering LEOT
returns an error with the tape driver automatically backing up over
that record.
When reading near the end-of-tape, the user is not informed of LEOT.
Instead, the typical double EOF marks or a pre-arranged data pattern
signals the logical end-of-tape.
Since magnetic tape drives vary in EOT sensing due to differences in
the physical placement of sensors, any application (such as multiple-
tape cpio(1) backups) requiring that data be continued from the EOT
area of one tape to another tape must be restricted. Therefore, the
tape drive type and mode should be identical for the creation and read‐
ing of the tapes.
The following macros are defined in for decoding the status field
returned from For each macro, the input parameter x is the field.
Returns TRUE at beginning of tape.
Returns TRUE if End-of-Data is encountered for DDS, QIC or 8MM.
Returns TRUE at an End-of-File mark.
Returns TRUE at end of tape.
Returns TRUE if immediate reporting mode is enabled.
Returns TRUE if drive is online.
Returns TRUE if setmark is encountered.
Returns TRUE if tape is write protected.
Returns TRUE if data compression is enabled.
Returns the currently configured 8-bit density value. Supported
values are
defined in
Returns TRUE if the density encoded in
is 800 bpi.
Returns TRUE if the density encoded in
is 1600 bpi.
Returns TRUE if the density encoded in
is 6250 bpi (with or without compression).
Returns TRUE if the density encoded in
is 6250 bpi plus compression.
Returns TRUE if the density encoded in
is DDS1 (with or without compression).
Returns TRUE if the density encoded in
is DDS1 plus compression.
Returns TRUE if the density encoded in
is DDS2 (with or without compression).
Returns TRUE if the density encoded in
is DDS2 plus compression.
Returns TRUE if the density encoded in
is 42500 bpi, 24 track pairs.
Returns TRUE if the density encoded in
is 42500 bpi, 56 track pairs.
Returns TRUE if the density encoded in
is 62500 bpi (with or without compression).
Returns TRUE if the density encoded in
is 62500 bpi plus compression.
Returns TRUE if the density encoded in
is 81633 bpi (with or without compression).
Returns TRUE if the density encoded in
is 81633 bpi plus compression.
Returns TRUE if the density encoded in
is 85937 bpi (with or without compression).
Returns TRUE if the density encoded in
is 85937 bpi plus compression.
Returns TRUE if the density encoded in
is for a 3480 device (with or without com‐
pression).
Returns TRUE if the density encoded in
is for a 3480 device with compression.
Does not apply to any currently supported devices.
Always returns FALSE.
HP-UX silently enforces a tape record blocking factor on
large I/O requests. For example, a user write request
with a length of ten times will actually reach the media
as ten separate records. A subsequent read (with ten
times as a length) will look like a single operation to
the user, even though HP-UX has broken it up into ten
separate read requests to the driver. The blocking func‐
tion is transparent to the user during writes. It is
also transparent during reads unless:
· The user picks an arbitrary read length greater
than
· The user attempts to read a third-party tape
containing records larger than
Since the value for is relatively large (usually >= 256K
bytes), this is typically not a problem.
The operation does not set the device-independent status
word.
EXAMPLES
Assuming that fd is a valid file descriptor, the follow‐
ing example writes two consecutive filemarks on the tape:
#include <sys/types.h>
#include <sys/mtio.h>
struct mtop mtop;
mtop.mt_op = MTWEOF;
mtop.mt_count = 2;
ioctl(fd, MTIOCTOP, &mtop);
If fd is a valid file descriptor for an open DDS drive,
the following example spaces forward to just past the
next setmark:
#include <sys/types.h>
#include <sys/mtio.h>
struct mtop mtop;
mtop.mt_op = MTFSS;
mtop.mt_count = 1;
ioctl(fd, MTIOCTOP, &mtop);
Given that fd is a valid file descriptor for an opened
tape device, and that it has just returned 0 from a
read(2) request. The following system call verifies that
the tape has just read a filemark:
#include <sys/types.h>
#include <sys/mtio.h>
struct mtget mtget;
ioctl(fd, MTIOCGET, &mtget);
if (GMT_EOF (mtget.mt_gstat)) {
/* code for filemark detection */
}
WARNINGS
Density specification (standard naming convention) acti‐
vate data compression on tape devices which support com‐
pression. This is also true for the files using the pre-
HP-UX 10.0 naming convention which are linked to these
files (see "Naming Conventions" above).
For the persistent tape DSFs the minor number does not
encode any configuration option. The minor number repre‐
sents an index into a persistent kernel database where
the configuration options are stored.
It is recommended that all legacy tape device files be
put in the directory. Legacy Device files using extended
configuration options located outside the directory may
not provide consistent behavior across system reboots.
Although persistent DSFs may be created in directories
other than HP recommends that persistent tape DSFs only
be created in
Use the rmsf(1M) command to clean up unused device files.
Otherwise, the property table may overflow and cause the
mksf(1M) command to fail.
Density codes listed in have device-dependent behaviors.
See the hardware manual for your tape device to find
which densities are valid. For some devices, these val‐
ues may be referred to as formats instead of densities.
Use of unbuffered mode can reduce performance and
increase media wear.
DEPENDENCIES
Driver-Specific Options for stape (Major Number 205)
The following options may be used in creating legacy DSFs
for tape drives that access the driver:
Exhaustive mode is enabled (default is disabled).
When exhaustive mode is enabled, the driver will,
if necessary, attempt several different configu‐
ration options when opening a device. The first
attempt follows the minor number configuration
exactly, but if that fails, the driver attempts
other likely configuration values.
With Exhaustive mode disabled, the driver makes
only one attempt to configure a device using the
configuration indicated in the minor number.
Specifies a partitioned tape whose currently active par‐
tition is
partition 1 (closest to BOT (beginning of tape)).
Optional partition 1 is closest to BOT for possi‐
ble use as a volume directory. The default par‐
tition without this option is partition 0. If
partitioning is unsupported, the entire tape is
referred to as partition 0.
Specifies fixed-block mode; the optional number indicates
the block size.
If the number is not present, the driver selects
a default block size appropriate to the device
type.
AUTHOR
was developed by HP and the University of California,
Berkeley.
FILES
persistent tape DSFs claimed by the estape driver
legacy tape DSFs
constants and macros for use with tapes
configuration property table for tapes
device files for accessing configuration properties table
-
for internal use only
SEE ALSOdd(1), mt(1), insf(1M), lssf(1M), mksf(1M), ioscan(1M),
rmsf(1M), ioctl(2), lseek(2), libIO(3X), intro(7).
mt(7)
