share/man/man4/mtio.4

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