2693a8ecf7
Rip out the (old) copy of sys/mtio.h that passed for documentation of the tape ioctls - if we're going to be that lame, just tell 'em to UTSL. Some other brave soul will have to do the documentation of each specific ioctl beyond the comments in that file. Write text about generic UNIX tape handling, which sucks and probably always will. This puts PR#5698 to bed.
174 lines
5.8 KiB
Groff
174 lines
5.8 KiB
Groff
.\" $NetBSD: mtio.4,v 1.9 1999/01/14 08:31:08 fair Exp $
|
|
.\"
|
|
.\" Copyright (c) 1983, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" from: @(#)mtio.4 8.1 (Berkeley) 6/5/93
|
|
.\"
|
|
.Dd Jaunary 14, 1999
|
|
.Dt MTIO 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mtio
|
|
.Nd generic magnetic tape I/O interface
|
|
.Sh SYNOPSIS
|
|
.Cd "#include <sys/mtio.h>"
|
|
.Sh DESCRIPTION
|
|
Magnetic tape has been the computer system backup and data transfer
|
|
medium of choice for decades, because it has historically been
|
|
cheaper in cost per bit stored, and the formats have been designed
|
|
for portability and storage.
|
|
However, tape drives have generally been the slowest mass
|
|
storage devices attached to any computer system.
|
|
.Pp
|
|
Magnetic tape comes in a wide variety of formats, from classic 9-track,
|
|
through various Quarter Inch Cartridge
|
|
.Pq Tn QIC
|
|
variants, to more modern systems using 8mm video tape, and
|
|
Digital Audio Tape
|
|
.Pq Tn DAT .
|
|
There have also been a variety of proprietary tape systems, including
|
|
.Tn DECtape ,
|
|
and
|
|
.Tn "IBM 3480" .
|
|
.Ss UNIX TAPE I/O
|
|
Regardless of the specific characteristics of the particular tape
|
|
transport mechanism (tape drive),
|
|
.Ux
|
|
tape I/O has two interfaces:
|
|
.Qq block
|
|
and
|
|
.Qq raw .
|
|
I/O through the block interface of a tape device is similar to I/O
|
|
through the block special device for a disk driver: the individual
|
|
.Xr read 2
|
|
and
|
|
.Xr write 2
|
|
calls can be done in any amount of bytes, but all data is buffered
|
|
through the system buffer cache, and I/O to the device is done in
|
|
1024 byte sized blocks.
|
|
This limitation is sufficiently restrictive that the block interface
|
|
to tape devices is rarely used.
|
|
.Pp
|
|
The
|
|
.Qq raw
|
|
interface differs in that all I/O can be done in arbitrary sized blocks,
|
|
within the limitations for the specific device and device driver,
|
|
and all I/O is synchronous.
|
|
This is the most flexible interface, but since there is very little
|
|
that is handled automatically by the kernel, user programs must
|
|
implement specific magnetic tape handling routines, which puts the onus
|
|
of correctness on the application programmer.
|
|
.Ss DEVICE NAME CONVENTIONS
|
|
Each magnetic tape subsystem has a couple of special devices
|
|
associated with it.
|
|
.Pp
|
|
The block device is usually named for the driver, e.g.
|
|
.Pa /dev/st0
|
|
for unit zero of a
|
|
.Xr st 4
|
|
.Tn SCSI
|
|
tape drive.
|
|
.Pp
|
|
The raw device name is the block device name with an
|
|
.Qq r
|
|
prepended, e.g.
|
|
.Pa /dev/rst0 .
|
|
.Pp
|
|
By default, the tape driver will rewind the tape drive when the
|
|
device is closed.
|
|
To make it possible for multiple program invocations to
|
|
sequentially write multiple files on the same tape, a
|
|
.Qq no rewind on close
|
|
device is provided, denoted by the letter
|
|
.Qq n
|
|
prepended to the name of the device, e.g.
|
|
.Pa /dev/nst0 ,
|
|
.Pa /dev/nrst0 .
|
|
.Pp
|
|
The
|
|
.Xr mt 1
|
|
command can be used to explicitly rewind, or otherwise position a
|
|
tape at a particular point with the no-rewind device.
|
|
.Ss FILE MARK HANDLING
|
|
Two end-of-file (EOF) markers mark the end of a tape (EOT), and
|
|
one end-of-file marker marks the end of a tape file.
|
|
.Pp
|
|
By default, the tape driver will write two End Of File (EOF) marks
|
|
and rewind the tape when the device is closed after the last write.
|
|
.Pp
|
|
If the tape is not to be rewound it is positioned with the
|
|
head in between the two tape marks, where the next write
|
|
will over write the second end-of-file marker.
|
|
.Pp
|
|
All of the magnetic tape devices may be manipulated with the
|
|
.Xr mt 1
|
|
command.
|
|
.Pp
|
|
A number of
|
|
.Xr ioctl 2
|
|
operations are available on raw magnetic tape.
|
|
Please see
|
|
.Aq Pa sys/mtio.h
|
|
for their definitions.
|
|
.\" The following definitions are from
|
|
.\" .Aq Pa sys/mtio.h :
|
|
.\" .Bd -literal
|
|
.\" there was a copy of sys/mtio.h here. silly.
|
|
.\" .Ed
|
|
.Pp
|
|
The manual pages for specific tape device drivers should list their
|
|
particular capabilities and limitations.
|
|
.Sh SEE ALSO
|
|
.Xr dd 1 ,
|
|
.Xr mt 1 ,
|
|
.Xr tar 1 ,
|
|
.Xr pax 1 ,
|
|
.Xr ht 4 ,
|
|
.Xr st 4 ,
|
|
.Xr tm 4 ,
|
|
.Xr ts 4 ,
|
|
.Xr mt 4 ,
|
|
.Xr ut 4
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
manual appeared in
|
|
.Bx 4.2 .
|
|
.Sh BUGS
|
|
The status should be returned in a device independent format.
|
|
.Pp
|
|
If and when
|
|
.Nx
|
|
is updated to deal with non-512 byte per sector disk media through the
|
|
system buffer cache, perhaps a more sane tape interface can be
|
|
implemented.
|