Ioctl Requests mtio(7I)
NAME
mtio - general magnetic tape interface
SYNOPSIS
#include
#include
#include
DESCRIPTION
1/2", 1/4", 4mm, and 8mm 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. SEOF 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 for-
mat 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.
SunOS 5.11 Last change: 15 Sep 2007 1
Ioctl Requests mtio(7I)
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 appre-
ciably 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 for-
mats available (check specific tape drive) are standard
2Gbyte, 5Gbyte, and compressed format.
4mm DAT Tape
Data is recorded either in Digital Data Storage (DS) tape
format or in Digital Data Storage, Data Compressed (DS-DC)
tape format. Since it is a variable-length tape device, the
number of bytes in a physical record may vary. The record-
ing formats available are standard 2Gbyte and compressed
format.
Persistent Error Handling
Persistent error handling is a modification of the current
error handling behaviors, BSD and SVR4. With persistent
error handling enabled, all tape operations after an error
or exception will return immediately with an error. Per-
sistent error handling can be most useful with asynchronous
tape operations that use the aioread(3C) and aiowrite(3C)
functions.
To enable persistent error handling, the ioctl MTIOCPER-
SISTENT must be issued. If this ioctl succeeds, then per-
sistent error handling is enabled and changes the current
error behavior. This ioctl will fail if the device driver
does not support persistent error handling.
With persistent error handling enabled, all tape operations
after an exception or error will return with the same error
as the first command that failed; the operations will not be
SunOS 5.11 Last change: 15 Sep 2007 2
Ioctl Requests mtio(7I)
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 MTIOCLRER ioctl must be issued to allow normal
tape operations to continue and to clear the error.
Disabling persistent error handling returns the error
behavior to normal SVR4 error handling, and will not occur
until all outstanding operations are completed. Applications
should wait for all outstanding operations to complete
before disabling persistent error handling. Closing the dev-
ice will also disable persistent error handling and clear
any errors or exceptions.
The Read Operation and Write Operation subsections contain
more pertinent information reguarding persistent error han-
dling.
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, pro-
vided 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 will
return an error and errno will be 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 dif-
ferent from the older BSD behavior, where another read will
fetch 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 will return EIO errors until the MTIOCLRER ioctl is
issued. An MTFSF ioctl can then he issued.
Two successful successive reads that both return zero byte
counts indicate 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 exam-
ple, 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.
SunOS 5.11 Last change: 15 Sep 2007 3
Ioctl Requests mtio(7I)
Most tape devices which support variable-length I/O opera-
tions 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 multiple 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
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 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.
SunOS 5.11 Last change: 15 Sep 2007 4
Ioctl Requests mtio(7I)
Most tape devices which support variable-length I/O opera-
tions 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 applications 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 will depend
on the type of device being used). The next write will
return a zero byte count. A third write will successfully
transfer some bytes (as indicated by the returned byte
count, which again could be a short write); the fourth will
transfer zero bytes, and so on, until the physical EOT is
reached and all writes will fail with EIO.
When logical EOT is encountered with persistent error han-
dling enabled, the current write may complete or be a short
write. The next write will return a zero byte count. At this
point an application should act appropriately for end of
tape cleanup or issue yet another write, which will return
the error ENOSPC. After clearing the exception with MTIOCLR-
ER, the next write will succeed (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 possi-
ble.
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.
SunOS 5.11 Last change: 15 Sep 2007 5
Ioctl Requests mtio(7I)
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 positioned 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 operation 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 speci-
fied, the tape will be rewound after the file mark is writ-
ten. 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 will always
write a file mark before closing to insure that the end of
recorded media is marked properly. If the non-rewinding dev-
ice 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(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 creat-
ing a null file.
After closing the device, persistent error handling will be
disabled and any error or exception will be cleared.
IOCTLS
Not all devices support all ioctls. The driver returns an
ENOTY error on unsupported ioctls.
SunOS 5.11 Last change: 15 Sep 2007 6
Ioctl Requests mtio(7I)
The following structure definitions for magnetic tape ioctl
commands are from .
The minor device byte structure is::
15 7 6 5 4 3 2 1 0
Unit # BSD Reserved Density Density No rewind Unit #
Bits 7-15 behavior Select Select on Close Bits 0-1
/*
* Layout of minor device byte:
*/
#define MTUNIT(dev) (((minor(dev) & 0xff80) >> 5) ]
(minor(dev) & 0x3))
#define MTNOREWIND (1 <<2)
#define MTDENSITYMASK (3 <<3)
#define MTDENSITY1 (0 <<3) /* Lowest density/format */
#define MTDENSITY2 (1 <<3)
#define MTDENSITY3 (2 <<3)
#define MTDENSITY4 (3 <<3) /* Highest density/format */
#define MTMINOR(unit) (((unit & 0x7fc) << 5) ] (unit & 0x3))
#define MTBSD (1 <<6) /* BSD behavior on close */
/* Structure for MTIOCTOP - magnetic tape operation command */
struct mtop {
short mtop; /* operation */
daddrt mtcount; /* number of operations */
};
/* Structure for MTIOCLTOP - magnetic tape operation command */
Works exactly like MTIOCTOP except passes 64 bit mtcount values.
struct mtlop {
short mtop;
short pad[3];
int64t mtcount;
};
The following operations of MTIOCTOP and MTIOCLTOP ioctls
are supported:
MTWEOF write an end-of-file record
SunOS 5.11 Last change: 15 Sep 2007 7
Ioctl Requests mtio(7I)
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
MTOFL 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
MTEL get current position
MTSEK go to requested position
MTFSF forward to requested number of sequential
file marks
MTBSF backward to requested number of sequential
file marks
SunOS 5.11 Last change: 15 Sep 2007 8
Ioctl Requests mtio(7I)
MTLOCK prevent media removal
MTUNLOCK allow media removal
MTLOAD load the next tape cartridge into the tape
drive
MTIOCGETEROR retrieve error records from the st driver
/* structure for MTIOCGET - magnetic tape get status command */
struct mtget {
short mttype; /* type of magtape device */
/* the following two registers are device dependent */
short mtdsreg; /* "drive status" register */
short mterreg; /* "error" register */
/* optional error info. */
daddrt mtresid; /* residual count */
daddrt mtfileno; /* file number of current position */
daddrt mtblkno; /* block number of current position */
ushortt mtflags;
short mtbf; /* optimum blocking factor */
};
/* structure for MTIOCGETDRIVETYPE - get tape config data command */
struct mtdrivetyperequest {
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 maxrretries; /* Max read retries */
int maxwretries; /* Max write retries */
uchart densities[MTNDENSITIES]; /* density codes,low->hi */
uchart defaultdensity; /* Default density chosen */
uchart speeds[MTNSPEDS]; /* speed codes, low->hi */
ushortt nonmotiontimeout; /* Seconds for non-motion */
ushortt iotimeout; /* Seconds for data to from tape */
ushortt rewindtimeout; /* Seconds to rewind */
ushortt spacetimeout; /* Seconds to space anywhere */
ushortt loadtimeout; /* Seconds to load tape and ready */
ushortt unloadtimeout; /* Seconds to unload */
ushortt erasetimeout; /* Seconds to do long erase */
};
SunOS 5.11 Last change: 15 Sep 2007 9
Ioctl Requests mtio(7I)
/* structure for MTIOCGETPOS and MTIOCRESTPOS - get/set tape position */
/*
* eof/eot/eom codes.
*/
typedef enum {
STNOEOF,
STEOFPENDING, /* filemrk pending */
STEOF, /* at filemark */
STEOTPENDING, /* logical eot pend. */
STEOT, /* at logical eot */
STEOM, /* at physical eot */
STWRITEAFTEREOM /* flag allowing writes after EOM */
}pstatus;
typedef enum { invalid, legacy, logical } posmode;
typedef struct tapepos {
uint64t lgclblkno; /* Blks from start of partition */
int32t fileno; /* Num. of current file */
int32t blkno; /* Blk number in current file */
int32t partition; /* Current partition */
pstatus eof; /* eof states */
posmode pmode; /* which pos. data is valid */
char pad[4];
}tapepost;
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 will just
flush all the buffers and will not write any file marks.
Because a successful completion of this tape operation will
guarantee 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
SunOS 5.11 Last change: 15 Sep 2007 10
Ioctl Requests mtio(7I)
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 com-
mand, 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 will leave the tape posi-
tioned 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 posi-
tion will end on the beginning of the tape side of the
desired file mark. An " MTBSF 0" will position 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 physi-
cal 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.
MTFSF and MTBSF 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, ENOTY is
returned.
MTOFL rewinds and, if appropriate, takes the device off-
line by unloading the tape. It is recommended that the dev-
ice be closed after offlining and then re-opened after a
tape has been inserted to facilitate portability to other
SunOS 5.11 Last change: 15 Sep 2007 11
Ioctl Requests mtio(7I)
platforms and other operating systems. Attempting to re-open
the device with no tape will result in an error unless the
ONDELAY flag is used. (See open(2).)
The MTRETEN retension 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 opera-
tions 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 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. 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, leav-
ing 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 mtcount 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 generally 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
ONDELAY flag, in order to execute this operation.
SunOS 5.11 Last change: 15 Sep 2007 12
Ioctl Requests mtio(7I)
MTIOCGETEROR 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
scsiarqstatus(9S) structure if available. The user-level
application is responsible for allocating and releasing the
memory for mteecdbbuf and scsiarqstatus of each
mterrorentry. Before issuing the ioctl, the
mteearqstatuslen value should be at least equal to
"sizeof(struct scsiarqstatus)." If more sense data than
the size of scsiarqstatus(9S) is desired, the
mteearqstatuslen may be larger than "sizeof(struct
scsiarqstatus)" by the amount of additional extended sense
data desired. The esaddlen field of
scsiextendedsense(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
(mttype), sense key error (mterreg), file number
(mtfileno), optimum blocking factor (mtbf) and record
number (mtblkno) of the last error. The residual count
(mtresid) is set to the number of bytes not transferred or
files/records not spaced. The flags word (mtflags) contains
information indicating if the device is SCSI, if the device
is a reel device and whether the device supports absolute
file positioning. The mtflags 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.
Note -
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), max-
imum read retry count (maxrretries), maximum write retry
count (maxwretries), densities supported by the drive (den-
sities), and default density of the tape drive
(defaultdensity).
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.
SunOS 5.11 Last change: 15 Sep 2007 13
Ioctl Requests mtio(7I)
The MTIOCRESTPOS ioctl restores a saved position from the
MTIOCGETPOS.
Persistent Error Handling IOCTLs and Asynchronous Tape Opera-
tions
MTIOCPERSISTENT enables/disables persistent error
handling
MTIOCPERSISTENTSTATUS queries for persistent error han-
dling
MTIOCLRER clears persistent error handling
MTIOCGUARANTEDORDER checks whether driver guarantees
order of I/O's
The MTIOCPERSISTENT ioctl enables or disables persistent
error handling. 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 successful. It will wait
for all outstanding I/O's 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 per-
sistent 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 will not wait for outstanding
I/O's. For example,
int query;
ioctl(fd, MTIOCPERSISTENTSTATUS, &query);
The MTIOCLRER ioctl clears persistent error handling and
allows tape operations to continual normally. This ioctl
requires no argument and will always succeed, even if per-
sistent error handling has not been enabled. It will wait
for any outstanding I/O's before it clears the error.
SunOS 5.11 Last change: 15 Sep 2007 14
Ioctl Requests mtio(7I)
The MTIOCGUARANTEDORDER ioctl is used to determine whether
the driver guarantees the order of I/O's. It takes no argu-
ment. If the ioctl succeeds, the driver will support
guaranteed order. If the driver does not support guaranteed
order, then it should not be used for asynchronous I/O with
libaio. It will wait for any outstanding I/O's before it
returns. For example,
ioctl(fd, MTIOCGUARANTEDORDER)
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 mtiostate, enum,
whose possible enumerations are listed below.
The initial value should be either the last
reported state of the drive, or MTIONONE.
Upon return, the enum pointed to by the argu-
ment is updated with the current state of the
drive.
enum mtiostate {
MTIONONE /* Return tape's current state */
MTIOEJECTED /* Tape state is "ejected" */
MTIOINSERTED /* Tape state is "inserted" */
;
When using asynchronous operations, most ioctls will wait
for all outstanding 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
SunOS 5.11 Last change: 15 Sep 2007 15
Ioctl Requests mtio(7I)
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. Reserv-
ing 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
will occur 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 super-user privileges. It is recommended
to open the tape device in ONDELAY mode when this ioctl
needs to be executed, otherwise the open will fail 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 filemarks. This is specific to
Exabyte drives.
MTIOCREADIGNOREILI enables/disable supress incorrect
length indicator support during reads
MTIOCREADIGNOREOFS 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 filemarks. 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 speci-
fied integer, then long filemarks will be written. If 1 is
SunOS 5.11 Last change: 15 Sep 2007 16
Ioctl Requests mtio(7I)
the specified integer, then short filemarks will be writ-
ten. The specified tape bahavior will be 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 will return
an errno of ENOTY.
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 will not be used
during reads and incorrect length indicator will not be
supressed. If 1 is the specified integer, SILI will be
used during reads and incorrect length indicator will be
supressed. The specified tape bahavior will be in effect
until the device is closed.
For example:
int on = 1;
int off = 0;
ioctl(fd, MTIOREADIGNOREILI, &on);
ioctl(fd, MTIOREADIGNOREILI, &off);
The MTIOCREADIGNOREOFS 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 double EOF marks
indicate End-Of-recodred-media (EOD). If 1 is the specified
integer, the double EOF marks no longer indicate EOM, thus
allowing 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 bahavior
will be in effect until the device is closed.
SunOS 5.11 Last change: 15 Sep 2007 17
Ioctl Requests mtio(7I)
For example:
int on = 1;
int off = 0;
ioctl(fd, MTIOREADIGNOREOFS, &on);
ioctl(fd, MTIOREADIGNOREOFS, &off);
Tape drives other than 1/2" reel tapes will return an errno
of ENOTY.
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(1M) 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, fol-
lowed by a get status ioctl:
struct mtop mtcommand;
struct mtget mtstatus;
mtcommand.mtop = MTBSF;
mtcommand.mtcount = 3;
ioctl(fd, MTIOCTOP, &mtcommand);
mtcommand.mtop = MTFSF;
mtcommand.mtcount = 1;
ioctl(fd, MTIOCTOP, &mtcommand);
ioctl(fd, MTIOCGET, (char *)&mtstatus);
or
mtcommand.mtop = MTNBSF;
mtcommand.mtcount = 2;
ioctl(fd, MTIOCTOP, &mtcommand);
ioctl(fd, MTIOCGET, (char *)&mtstatus);
SunOS 5.11 Last change: 15 Sep 2007 18
Ioctl Requests mtio(7I)
To get information about the tape drive:
struct mtdrivetype mtdt;
struct mtdrivetyperequest mtreq;
mtreq.size = sizeof(struct mtdrivetype);
mtreq.mtdtp = &mtdt;
ioctl(fd, MTIOCGETDRIVETYPE, &mtreq);
FILES
/dev/rmt/[][]
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), dd(1M), open(2), read(2), write(2),
aioread(3C), aiowrite(3C), ar.h(3HEAD), st(7D)
1/4 Inch Tape Drive Tutorial
SunOS 5.11 Last change: 15 Sep 2007 19
|
