1.\" $NetBSD: mtio.4,v 1.10 1999/09/12 18:43:43 kleink Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" from: @(#)mtio.4 8.1 (Berkeley) 6/5/93 35.\" 36.Dd January 14, 1999 37.Dt MTIO 4 38.Os 39.Sh NAME 40.Nm mtio 41.Nd generic magnetic tape I/O interface 42.Sh SYNOPSIS 43.Cd "#include <sys/mtio.h>" 44.Sh DESCRIPTION 45Magnetic tape has been the computer system backup and data transfer 46medium of choice for decades, because it has historically been 47cheaper in cost per bit stored, and the formats have been designed 48for portability and storage. 49However, tape drives have generally been the slowest mass 50storage devices attached to any computer system. 51.Pp 52Magnetic tape comes in a wide variety of formats, from classic 9-track, 53through various Quarter Inch Cartridge 54.Pq Tn QIC 55variants, to more modern systems using 8mm video tape, and 56Digital Audio Tape 57.Pq Tn DAT . 58There have also been a variety of proprietary tape systems, including 59.Tn DECtape , 60and 61.Tn "IBM 3480" . 62.Ss UNIX TAPE I/O 63Regardless of the specific characteristics of the particular tape 64transport mechanism (tape drive), 65.Ux 66tape I/O has two interfaces: 67.Qq block 68and 69.Qq raw . 70I/O through the block interface of a tape device is similar to I/O 71through the block special device for a disk driver: the individual 72.Xr read 2 73and 74.Xr write 2 75calls can be done in any amount of bytes, but all data is buffered 76through the system buffer cache, and I/O to the device is done in 771024 byte sized blocks. 78This limitation is sufficiently restrictive that the block interface 79to tape devices is rarely used. 80.Pp 81The 82.Qq raw 83interface differs in that all I/O can be done in arbitrary sized blocks, 84within the limitations for the specific device and device driver, 85and all I/O is synchronous. 86This is the most flexible interface, but since there is very little 87that is handled automatically by the kernel, user programs must 88implement specific magnetic tape handling routines, which puts the onus 89of correctness on the application programmer. 90.Ss DEVICE NAME CONVENTIONS 91Each magnetic tape subsystem has a couple of special devices 92associated with it. 93.Pp 94The block device is usually named for the driver, e.g. 95.Pa /dev/st0 96for unit zero of a 97.Xr st 4 98.Tn SCSI 99tape drive. 100.Pp 101The raw device name is the block device name with an 102.Qq r 103prepended, e.g. 104.Pa /dev/rst0 . 105.Pp 106By default, the tape driver will rewind the tape drive when the 107device is closed. 108To make it possible for multiple program invocations to 109sequentially write multiple files on the same tape, a 110.Qq no rewind on close 111device is provided, denoted by the letter 112.Qq n 113prepended to the name of the device, e.g. 114.Pa /dev/nst0 , 115.Pa /dev/nrst0 . 116.Pp 117The 118.Xr mt 1 119command can be used to explicitly rewind, or otherwise position a 120tape at a particular point with the no-rewind device. 121.Ss FILE MARK HANDLING 122Two end-of-file (EOF) markers mark the end of a tape (EOT), and 123one end-of-file marker marks the end of a tape file. 124.Pp 125By default, the tape driver will write two End Of File (EOF) marks 126and rewind the tape when the device is closed after the last write. 127.Pp 128If the tape is not to be rewound it is positioned with the 129head in between the two tape marks, where the next write 130will over write the second end-of-file marker. 131.Pp 132All of the magnetic tape devices may be manipulated with the 133.Xr mt 1 134command. 135.Pp 136A number of 137.Xr ioctl 2 138operations are available on raw magnetic tape. 139Please see 140.Aq Pa sys/mtio.h 141for their definitions. 142.\" The following definitions are from 143.\" .Aq Pa sys/mtio.h : 144.\" .Bd -literal 145.\" there was a copy of sys/mtio.h here. silly. 146.\" .Ed 147.Pp 148The manual pages for specific tape device drivers should list their 149particular capabilities and limitations. 150.Sh SEE ALSO 151.Xr dd 1 , 152.Xr mt 1 , 153.Xr tar 1 , 154.Xr pax 1 , 155.Xr ht 4 , 156.Xr st 4 , 157.Xr tm 4 , 158.Xr ts 4 , 159.Xr mt 4 , 160.Xr ut 4 161.Sh HISTORY 162The 163.Nm 164manual appeared in 165.Bx 4.2 . 166.Sh BUGS 167The status should be returned in a device independent format. 168.Pp 169If and when 170.Nx 171is updated to deal with non-512 byte per sector disk media through the 172system buffer cache, perhaps a more sane tape interface can be 173implemented. 174