svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
mtio(4i)
Ioctls for a class of drivers or subsystems mtio(4I)
NAME
mtio - general magnetic tape interface
SYNOPSIS
#include <sys/types.h>
#include <sys/ioctl.h>
#include <sys/mtio.h>
DESCRIPTION
1/2", 1/4", 4mm, and 8mm magnetic tape drives all share the same gen‐
eral 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 EOF mark on 1/4", 4mm, and 8mm cartridge tapes.
1/2 Reel Tape"
Data bytes are recorded in parallel onto the 9-track tape. Since it is
a variable-length tape device, the number of bytes in a physical record
may vary.
The recording formats available (check specific tape drive) are 800
BPI, 1600 BPI, 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 Mbyte can be stored using 800
BPI, 40 Mbyte using 1600 BPI, 140 Mbyte using 6250 BPI, or up to 700
Mbyte 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 Mbyte of
data on a 450 foot tape; 9-track drives can record up to 45 Mbyte 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, or QIC-120 tape formats.
8mm Cartridge Tape
Data is recorded serially onto 8mm helical scan cartridge tape. Since
it is a variable-length tape device, the number of bytes in a physical
record may vary. The recording formats available (check specific tape
drive) are standard 2Gbyte, 5Gbyte, and compressed format.
4mm DAT Tape
Data is recorded either in Digital Data Storage (DDS) tape format or in
Digital Data Storage, Data Compressed (DDS-DC) tape format. Since it is
a variable-length tape device, the number of bytes in a physical record
may vary. The recording formats available are standard 2Gbyte and com‐
pressed format.
Persistent Error Handling
Persistent error handling is a modification of the current error han‐
dling behaviors, BSD and SVR4. With persistent error handling enabled,
all tape operations after an error or exception return immediately with
an error. Persistent error handling can be most useful with asynchro‐
nous tape operations that use the aioread(3C) and aiowrite(3C) func‐
tions.
To enable persistent error handling, the ioctl MTIOCPERSISTENT must be
issued. If this ioctl succeeds, then persistent error handling is
enabled and changes the current error behavior. This ioctl fails if the
device driver does not support persistent error handling.
With persistent error handling enabled, all tape operations after an
exception or error return with the same error as the first command that
failed; the operations is not executed. An exception is some event that
might stop normal tape operations, such as an End Of File (EOF) mark or
an End Of Tape (EOT) mark. An example of an error is a media error. The
MTIOCLRERR ioctl must be issued to allow normal tape operations to con‐
tinue and to clear the error.
Disabling persistent error handling returns the error behavior to nor‐
mal SVR4 error handling, and does not occur until all outstanding oper‐
ations are completed. Applications should wait for all outstanding
operations to complete before disabling persistent error handling.
Closing the device also disables persistent error handling and clear
any errors or exceptions.
The Read Operation and Write Operation subsections contain more perti‐
nent information regarding persistent error handling.
Read Operation
The read(2) function reads the next record on the tape. The record size
is passed back as the number of bytes read, provided it is not greater
than the number requested. When a tape mark or end of data is read, a
zero byte count is returned; all successive reads after the zero read
return an error and errno is set to EIO. To move to the next file, an
MTFSF ioctl can be issued before or after the read causing the error.
This error handling behavior is different from the older BSD behavior,
where another read fetches the first record of the next tape file. If
the BSD behavior is required, device names containing the letter b (for
BSD behavior) in the final component should be used. If persistent
error handling was enabled with either the BSD or SVR4 tape device
behavior, all operations after this read error return EIO errors until
the MTIOCLRERR ioctl is issued. An MTFSF ioctl can then be issued.
Two successful successive reads that both return zero byte counts indi‐
cate EOM on the tape. 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 64,512 bytes (minphys limit), fixed-length I/O tape
devices read multiple records.
Most tape devices which support variable-length I/O operations may read
a range of 1 to 65,535 bytes. If the record size exceeds 65,535 bytes,
the driver reads multiple records to satisfy the request. These multi‐
ple records are limited to 65,534 bytes. Newer variable-length tape
drivers may relax the above limitation and allow applications to read
record sizes larger than 65,534. Refer to the specific tape driver man
page for details.
Reading past logical EOT is transparent to the user. A read operation
should never hit physical EOT.
Read requests that are lesser than a physical tape record are not
allowed. Appropriate error is returned.
Write Operation
The write(2) function 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. With the Exabyte 8200, data
may be appended only at the beginning of tape, before a filemark, or
after the last written file on the tape.
Writing is not so restricted on 1/2", 4mm, and the other 8mm cartridge
tape drives. 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 overwrit‐
ing records; the erase head is just forward of the write head and any
following records is 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 64,512 bytes (minphys limit). These multiple
writes are limited to 64,512 bytes. For example, if a write request is
issued for 65,536 bytes using a 1/4" cartridge tape, two writes are
issued; the first for 64,512 bytes and the second for 1024 bytes.
Most tape devices which support variable-length I/O operations may
write a range of 1 to 65,535 bytes. If the record size exceeds 65,535
bytes, the driver writes multiple records to satisfy the request. These
multiple records are limited to 65,534 bytes. As an example, if a write
request for 65,540 bytes is issued, two records are written; one for
65,534 bytes followed by another record for 6 bytes. Newer variable-
length tape drivers may relax the above limitation and allow applica‐
tions to write record sizes larger than 65,534. Refer to the specific
tape driver man page for details.
When logical EOT is encountered during a write, that write operation
completes and the number of bytes successfully transferred is returned
(note that a 'short write' may have occurred and not all the requested
bytes would have been transferred. The actual amount of data written
depends on the type of device being used). The next write returns a
zero byte count. A third write successfully transfers some bytes (as
indicated by the returned byte count, which again could be a short
write); the fourth transfers zero bytes, and so on, until the physical
EOT is reached and all writes fails with EIO.
When logical EOT is encountered with persistent error handling enabled,
the current write may complete or be a short write. The next write
returns a zero byte count. At this point an application should act
appropriately for end of tape cleanup or issue yet another write, which
returns the error ENOSPC. After clearing the exception with MTIOCLRERR,
the next write succeeds (possibly short), followed by another zero byte
write count, and then another ENOSPC error.
Allowing writes after LEOT has been encountered enables the flushing of
buffers. However, it is strongly recommended to terminate the writing
and close the file as soon as possible.
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 end of the final component. The no-rewind version
of /dev/rmt/0l is /dev/rmt/0ln. In case of error for a no-rewind
device, the next open rewinds the device.
If the driver was opened for reading and a no-rewind device has been
specified, the close advances the tape past the next filemark (unless
the current file position is at EOM), leaving the tape correctly posi‐
tioned to read the first record of the next file. However, if the tape
is at the first record of a file it doesn't advance again to the first
record of the next file. These semantics are different from the older
BSD behavior. If BSD behavior is required where no implicit space oper‐
ation is executed on close, the non-rewind device name containing the
letter b (for BSD behavior) in the final component should be specified.
If data was written, a file mark is automatically written by the driver
upon close. If the rewinding device was specified, the tape is 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.
All buffers are flushed on closing a tape device. Hence, it is strongly
recommended that the application wait for all buffers to be flushed
before closing the device. This can be done by writing a filemark via
MTWEOF, even with a zero count.
Note that 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 always writes a file mark before closing to ensure that the
end of recorded media is marked properly. If the non-rewinding device
was specified, two file marks are written and the tape is left posi‐
tioned between the two so that the second one is overwritten on a sub‐
sequent open(2) and write(2).
If no data was written and the driver was opened for WRITE-ONLY access,
one or two file marks are written, thus creating a null file.
After closing the device, persistent error handling is disabled and any
error or exception is cleared.
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 is::
15 7 6 5 4 3 2 1 0
________________________________________________________________________
Unit # BSD Data Density Density No rewind Unit #
Bits 7-15 behavior Protect Select Select on Close Bits 0-1
/*
* Layout of minor device byte:
*/
#define MTUNIT(dev) (((minor(dev) & 0xff80) >> 5) +
(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 & 0x7fc) << 5) + (unit & 0x3))
#define MT_DADP (1 <<5) /* DADP enabled bit */
#define MT_BSD (1 <<6) /* BSD behavior on close */
/* Structure for MTIOCTOP − magnetic tape operation command */
struct mtop {
short mt_op; /* operation */
daddr_t mt_count; /* number of operations */
};
/* Structure for MTIOCLTOP - magnetic tape operation command */
Works exactly like MTIOCTOP except passes 64 bit mt_count values.
struct mtlop {
short mt_op;
short pad[3];
int64_t mt_count;
};
The following operations of MTIOCTOP and MTIOCLTOP ioctls are sup‐
ported:
MTWEOF write an end-of-file record
MTFSF forward space over file mark
MTBSF backward space over file mark (1/2", 8mm only)
MTFSR forward space to inter-record gap
MTBSR backward space to inter-record gap
MTREW rewind
MTOFFL rewind and take the drive off-line
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
MTSRSZ set record size
MTGRSZ get record size
MTTELL get current position
MTSEEK go to requested position
MTFSSF forward to requested number of sequential file marks
MTBSSF backward to requested number of sequential file marks
MTLOCK prevent media removal
MTUNLOCK allow media removal
MTLOAD load the next tape cartridge into the tape drive
MTIOCGETERROR retrieve error records from the st driver
MTDADP Enable or disable Data Protection mode Values for
mt_count are as follows.
DADP_DISABLE, /* 0 */
DADP_RBDP, /* 1 */
DADP_RD_ENABLE, /* 2 */
DADP_RBDP_RD_ENABLE, /* 3 */
DADP_WT_ENABLE, /* 4 */
DADP_RBDP_WT_ENABLE, /* 5 */
DADP_RW_ENABLE, /* 6 */
DADP_RBDP_RW_ENABLE, /* 7 */
The *RBDP* values enable use of the SCSI Recover
Buffered Data command to read back the data trapped in
the device's buffer when a write error is detected.
MTVERIFY Issues a scsi(5) Verify command. When issued with DADP
reads enabled causes the drive to read data from tape
and compare the stored
When issued with DADP reads enabled causes the drive
to read data from tape and compare the stored data
protection CRC with one generated at read time to con‐
firm data integrity. Issuing it on a drive that does
not have DADP reads enabled or does not support data
protection reads the tape and verify that it can be
read. The value passed in mt_count is used as bytes to
read of the drive in variable block mode or blocks to
read in fixed block mode. On return mt_count contains
the residual of your request, that being bytes or
blocks not read of your request.
/* 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 */
ushort_t mt_flags;
short mt_bf; /* optimum blocking factor */
};
/* structure for MTIOCGETDRIVETYPE − get tape config data command */
struct mtdrivetype_request {
int size;
struct mtdrivetype *mtdtp;
};
struct mtdrivetype {
char name[64]; /* Name, for debug */
char vid[25]; /* Vendor id and product id */
char type; /* Drive type for driver */
int bsize; /* Block size */
int options; /* Drive options */
int max_rretries; /* Max read retries */
int max_wretries; /* Max write retries */
uchar_t densities[MT_NDENSITIES]; /* density codes,low->hi */
uchar_t default_density; /* Default density chosen */
uchar_t speeds[MT_NSPEEDS]; /* speed codes, low->hi */
ushort_t non_motion_timeout; /* Seconds for non-motion */
ushort_t io_timeout; /* Seconds for data to from tape */
ushort_t rewind_timeout; /* Seconds to rewind */
ushort_t space_timeout; /* Seconds to space anywhere */
ushort_t load_timeout; /* Seconds to load tape and ready */
ushort_t unload_timeout; /* Seconds to unload */
ushort_t erase_timeout; /* Seconds to do long erase */
};
/* structure for MTIOCGETPOS and MTIOCRESTPOS - get/set tape position */
/*
* eof/eot/eom codes.
*/
typedef enum {
ST_NO_EOF,
ST_EOF_PENDING, /* filemark pending */
ST_EOF, /* at filemark */
ST_EOT_PENDING, /* logical eot pend. */
ST_EOT, /* at logical eot */
ST_EOM, /* at physical eot */
ST_WRITE_AFTER_EOM /* flag allowing writes after EOM */
} pstatus;
typedef enum { invalid, legacy, logical } posmode;
typedef struct tapepos {
uint64_t lgclblkno; /* Blks from start of partition */
int32_t fileno; /* Num. of current file */
int32_t blkno; /* Blk number in current file */
int32_t partition; /* Current partition */
pstatus eof; /* eof states */
posmode pmode; /* which pos. data is valid */
char pad[4];
} tapepos_t;
If the pmode is legacy, fileno and blkno fields are valid.
If the pmode is logical, lgclblkno field is valid.
The MTWEOF ioctl is used for writing file marks to tape. Not only does
this signify the end of a file, but also usually has the side effect of
flushing all buffers in the tape drive to the tape medium. A zero count
MTWEOF just flushes all the buffers and does not write any file marks.
Because a successful completion of this tape operation guarantees that
all tape data has been written to the tape medium, it is recommended
that this tape operation be issued before closing a tape device.
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.
Record skipping does not go past a file mark; file skipping does not go
past the EOM. After an MTFSR <huge number> command, the driver leaves
the tape logically positioned before the EOF. A related 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 leaves 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 at the beginning of the current file.
MTBSF moves the tape backwards by file marks. The tape position ends on
the beginning of the tape side of the desired file mark. An " MTBSF 0"
positions the tape at the end of the current file, before the filemark.
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 exam‐
ple, spaces 512 byte physical records. The status ioctl residual count
contains the number of files or records not skipped.
MTFSSF and MTBSSF space forward or backward, respectively, to the next
occurrence of the requested number of file marks, one following
another. If there are more sequential file marks on tape than were
requested, it spaces over the requested number and positions after the
requested file mark. Note that not all drives support this command and
if a request is sent to a drive that does not, ENOTTY is returned.
MTOFFL rewinds and, if appropriate, takes the device off-line by
unloading the tape. It is recommended that the device be closed after
offlining and then re-opened after a tape has been inserted to facili‐
tate portability to other platforms and other operating systems.
Attempting to re-open the device with no tape results in an error
unless the O_NDELAY flag is used. (See open(2).)
The MTRETEN retention ioctl applies only 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. Erasing may take a long time depending on the device
and/or tapes. For time details, refer to the drive specific manual.
MTEOM positions the tape at a location just after the last file written
on the tape. For 1/4" cartridge and 8mm 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. Addi‐
tional 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 back‐
ward 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.
The 1/4" cartridge tape devices do not support MTBSF.
MTSRSZ and MTGRSZ are used to set and get fixed record lengths. The
MTSRSZ ioctl allows variable length and fixed length tape drives that
support multiple record sizes to set the record length. The mt_count
field of the mtop struct is used to pass the record size to/from the st
driver. A value of 0 indicates variable record size. The MTSRSZ ioctl
makes a variable-length tape device behave like a fixed-length tape
device. Refer to the specific tape driver man page for details.
MTLOAD loads the next tape cartridge into the tape drive. This is gen‐
erally only used with stacker and tower type tape drives which handle
multiple tapes per tape drive. A tape device without a tape inserted
can be opened with the O_NDELAY flag, in order to execute this opera‐
tion.
MTIOCGETERROR allows user-level applications to retrieve error records
from the st driver. An error record consists of the SCSI command cdb
which causes the error and a scsi_arq_status(9S) structure if avail‐
able. The user-level application is responsible for allocating and
releasing the memory for mtee_cdb_buf and scsi_arq_status of each mter‐
ror_entry. Before issuing the ioctl, the mtee_arq_status_len value
should be at least equal to sizeof(struct scsi_arq_status). If more
sense data than the size of scsi_arq_status(9S) is desired, the
mtee_arq_status_len may be larger than sizeof(struct scsi_arq_status)
by the amount of additional extended sense data desired. The es_add_len
field of scsi_extended_sense(9S) can be used to determine the amount of
valid sense data returned by the device.
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 infor‐
mation indicating if the device is SCSI, if the device is a reel device
and whether the device supports absolute file positioning. The mt_flags
also indicates if the device is requesting cleaning media be used,
whether the device is capable of reporting the requirement of cleaning
media and if the currently loaded media is WORM (Write Once Read Many)
media.
When tape alert cleaning is managed by the st driver, the tape target
driver may continue to return a drive needs cleaning status unless an
MTIOCGET ioctl() call is made while the cleaning media is in the drive.
The MTIOCGETDRIVETYPE get drivetype ioctl call returns the name of the
tape drive as defined in st.conf (name), Vendor ID and model (product),
ID (vid), type of tape device (type), block size (bsize), drive options
(options), maximum read retry count (max_rretries), maximum write retry
count (max_wretries), densities supported by the drive (densities), and
default density of the tape drive (default_density).
The MTIOCGETPOS ioctl returns the current tape position of the drive.
It is returned in struct tapepos as defined in
/usr/include/sys/scsi/targets/stdef.h.
The MTIOCRESTPOS ioctl restores a saved position from the MTIOCGETPOS.
Persistent Error Handling IOCTLs and Asynchronous Tape Operations
MTIOCPERSISTENT enables/disables persistent error handling
MTIOCPERSISTENTSTATUS queries for persistent error handling
MTIOCLRERR clears persistent error handling
MTIOCGUARANTEEDORDER checks whether driver guarantees order of
I/O's
The MTIOCPERSISTENT ioctl enables or disables persistent error han‐
dling. It takes as an argument a pointer to an integer that turns it
either on or off. If the ioctl succeeds, the desired operation was suc‐
cessful. It waits for all outstanding I/Os to complete before changing
the persistent error handling status. For example,
int on = 1;
ioctl(fd, MTIOCPERSISTENT, &on);
int off = 0;
ioctl(fd, MTIOCPERSISTENT, &off);
The MTIOCPERSISTENTSTATUS ioctl enables or disables persistent error
handling. It takes as an argument a pointer to an integer inserted by
the driver. The integer can be either 1 if persistent error handling is
'on', or 0 if persistent error handling is 'off'. It does not wait for
outstanding I/O's. For example,
int query;
ioctl(fd, MTIOCPERSISTENTSTATUS, &query);
The MTIOCLRERR ioctl clears persistent error handling and allows tape
operations to continual normally. This ioctl requires no argument and
always succeeds, even if persistent error handling has not been
enabled. It waits for any outstanding I/O's before it clears the error.
The MTIOCGUARANTEEDORDER ioctl is used to determine whether the driver
guarantees the order of I/O's. It takes no argument. If the ioctl suc‐
ceeds, the driver supports guaranteed order. If the driver does not
support guaranteed order, then it should not be used for asynchronous
I/O with libaio. It waits for any outstanding I/O's before it returns.
For example,
ioctl(fd, MTIOCGUARANTEEDORDER)
See the Persistent Error Handling subsection above for more information
on persistent error handling.
Asynchronous and State Change IOCTLS
MTIOCSTATE This ioctl blocks until the state of the drive, inserted
or ejected, is changed. The argument is a pointer to a
mtio_state, enum, whose possible enumerations are listed
below. The initial value should be either the last
reported state of the drive, or MTIO_NONE. Upon return,
the enum pointed to by the argument is updated with the
current state of the drive.
enum mtio_state {
MTIO_NONE, /* Return tape's current state */
MTIO_EJECTED, /* Tape state is "ejected" */
MTIO_INSERTED /* Tape state is "inserted" */
};
When using asynchronous operations, most ioctls wait for all outstand‐
ing commands to complete before they are executed.
IOCTLS for Multi-initiator Configurations
MTIOCRESERVE reserve the tape drive
MTIOCRELEASE revert back to the default behavior of reserve on
open/release on close
MTIOCFORCERESERVE reserve the tape unit by breaking reservation held
by another host
The MTIOCRESERVE ioctl reserves the tape drive such that it does not
release the tape drive at close. This changes the default behavior of
releasing the device upon close. Reserving the tape drive that is
already reserved has no effect. For example,
ioctl(fd, MTIOCRESERVE);
The MTIOCRELEASE ioctl reverts back to the default behavior of reserve
on open/release on close operation, and a release occurs during the
next close. Releasing the tape drive that is already released has no
effect. For example,
ioctl(fd, MTIOCRELEASE);
The MTIOCFORCERESERVE ioctl breaks a reservation held by another host,
interrupting any I/O in progress by that other host, and then reserves
the tape unit. This ioctl can be executed only with the
{PRIV_SYS_DEVICES} privilege. It is recommended to open the tape device
in O_NDELAY mode when this ioctl needs to be executed, otherwise the
open fails if another host indeed has it reserved. For example,
ioctl(fd, MTIOCFORCERESERVE);
IOCTLS for Handling Tape Configuration Options
MTIOCSHORTFMK enables/disable support for writing short file‐
marks. This is specific to Exabyte drives.
MTIOCREADIGNOREILI enables/disable suppress incorrect length indi‐
cator support during reads
MTIOCREADIGNOREEOFS enables/disable support for reading past two EOF
marks which otherwise indicate End-Of-recording-
Media (EOM) in the case of 1/2" reel tape drives
The MTIOCSHORTFMK ioctl enables or disables support for short file‐
marks. This ioctl is only applicable to Exabyte drives which support
short filemarks. As an argument, it takes a pointer to an integer. If 0
(zero) is the specified integer, long filemarks are written. If 1 is
the specified integer, then short filemarks are written. The specified
tape behavior is in effect until the device is closed.
For example,
int on = 1;
int off = 0;
/* enable short filemarks */
ioctl(fd, MTIOSHORTFMK, &on);
/* disable short filemarks */
ioctl(fd, MTIOCSHORTFMK, &off);
Tape drives which do not support short filemarks return an errno of
ENOTTY.
The MTIOCREADIGNOREILI ioctl enables or disables the suppress incorrect
length indicator (SILI) support during reads. As an argument, it takes
a pointer to an integer. If 0 (zero) is the specified integer, SILI is
not used during reads and incorrect length indicator is not suppressed.
If 1 is the specified integer, SILI is used during reads and incorrect
length indicator is suppressed. The specified tape behavior is in
effect until the device is closed.
For example:
int on = 1;
int off = 0;
ioctl(fd, MTIOREADIGNOREILI, &on);
ioctl(fd, MTIOREADIGNOREILI, &off);
The MTIOCREADIGNOREEOFS ioctl enables or disables support for reading
past double EOF marks which otherwise indicate End-Of-recorded-media
(EOM) in the case of 1/2" reel tape drives. As an argument, it takes a
pointer to an integer. If 0 (zero) is the specified integer, then dou‐
ble EOF marks indicate End-Of-recorded-media (EOD). If 1 is the speci‐
fied integer, the double EOF marks no longer indicate EOM, thus allow‐
ing applications to read past two EOF marks. In this case it is the
responsibility of the application to detect end-of-recorded-media
(EOM). The specified tape behavior is in effect until the device is
closed.
For example:
int on = 1;
int off = 0;
ioctl(fd, MTIOREADIGNOREEOFS, &on);
ioctl(fd, MTIOREADIGNOREEOFS, &off);
Tape drives other than 1/2" reel tapes return an errno of ENOTTY.
EXAMPLES
Example 1 Tape Positioning and Tape Drives
Suppose you have written three files to the non-rewinding 1/2" tape
device, /dev/rmt/0ln, and that you want to go back and dd(8) the second
file off the tape. The commands to do this are:
mt -F /dev/rmt/0lbn bsf 3
mt -F /dev/rmt/0lbn fsf 1
dd if=/dev/rmt/0ln
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
mt_command.mt_op = MTNBSF;
mt_command.mt_count = 2;
ioctl(fd, MTIOCTOP, &mt_command);
ioctl(fd, MTIOCGET, (char *)&mt_status);
To get information about the tape drive:
struct mtdrivetype mtdt;
struct mtdrivetype_request mtreq;
mtreq.size = sizeof(struct mtdrivetype);
mtreq.mtdtp = &mtdt;
ioctl(fd, MTIOCGETDRIVETYPE, &mtreq);
FILES
/dev/rmt/<unit number>[data protect>]<density>[<BSD behavior>][<no rewind>]
Where density can be l, m, h, u/c (low, medium, high, ultra/compressed,
respectively), the BSD behavior option is b, and the no rewind option
is n.
For example, /dev/rmt/0hbn specifies unit 0, high density, BSD behavior
and no rewind.
SEE ALSO
mt(1), tar(1), write(2), open(2), read(2), aioread(3C), aiowrite(3C),
ar.h(3HEAD), st(4D), scsi(5), privileges(7), dd(8)
1/4 Inch Tape Drive Tutorial
Oracle Solaris 11.4 3 Nov 2021 mtio(4I)