1.\" Copyright (c) 1996 2.\" Julian Elischer <julian@FreeBSD.org>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD: src/share/man/man4/sa.4,v 1.22.2.7 2001/08/17 13:08:39 ru Exp $ 27.\" $DragonFly: src/share/man/man4/sa.4,v 1.4 2006/02/17 19:37:09 swildner Exp $ 28.\" 29.Dd June 6, 1999 30.Dt SA 4 31.Os 32.Sh NAME 33.Nm sa 34.Nd SCSI Sequential Access device driver 35.Sh SYNOPSIS 36.Cd device sa 37.Cd device sa1 at scbus0 target 4 unit 0 38.Sh DESCRIPTION 39The 40.Nm 41driver provides support for all 42.Tn SCSI 43devices of the sequential access class that are attached to the system 44through a supported 45.Tn SCSI 46Host Adapter. 47The sequential access class includes tape and other linear access devices. 48.Pp 49A 50.Tn SCSI 51Host 52adapter must also be separately configured into the system 53before a 54.Tn SCSI 55sequential access device can be configured. 56.Sh MOUNT SESSIONS 57The 58.Nm 59driver is based around the concept of a 60.Dq Em mount session , 61which is defined as the period between the time that a tape is 62mounted, and the time when it is unmounted. 63Any parameters set during 64a mount session remain in effect for the remainder of the session or 65until replaced. 66The tape can be unmounted, bringing the session to a 67close in several ways. 68These include: 69.Bl -enum 70.It 71Closing a `rewind device', 72referred to as sub-mode 00 below. 73An example is 74.Pa /dev/sa0 . 75.It 76Using the MTOFFL 77.Xr ioctl 2 78command, reachable through the 79.Sq Cm offline 80command of 81.Xr mt 1 . 82.El 83.Pp 84It should be noted that tape devices are exclusive open devices, except in 85the case where a control mode device is opened. 86In the latter case, exclusive 87access is only sought when needed (e.g., to set parameters). 88.Sh SUB-MODES 89Bits 0 and 1 of the minor number are interpreted as 90.Sq sub-modes . 91The sub-modes differ in the action taken when the device is closed: 92.Bl -tag -width XXXX 93.It 00 94A close will rewind the device; if the tape has been 95written, then a file mark will be written before the rewind is requested. 96The device is unmounted. 97.It 01 98A close will leave the tape mounted. 99If the tape was written to, a file mark will be written. 100No other head positioning takes place. 101Any further reads or writes will occur directly after the 102last read, or the written file mark. 103.It 10 104A close will rewind the device. 105If the tape has been 106written, then a file mark will be written before the rewind is requested. 107On completion of the rewind an unload command will be issued. 108The device is unmounted. 109.El 110.Sh BLOCKING MODES 111.Tn SCSI 112tapes may run in either 113.Sq Em variable 114or 115.Sq Em fixed 116block-size modes. Most 117.Tn QIC Ns -type 118devices run in fixed block-size mode, where most nine-track tapes and 119many new cartridge formats allow variable block-size. 120The difference between the two is as follows: 121.Bl -inset 122.It Variable block-size: 123Each write made to the device results in a single logical record 124written to the tape. 125One can never read or write 126.Em part 127of a record from tape (though you may request a larger block and read 128a smaller record); nor can one read multiple blocks. 129Data from a single write is therefore read by a single read. 130The block size used 131may be any value supported by the device, the 132.Tn SCSI 133adapter and the system (usually between 1 byte and 64 Kbytes, 134sometimes more). 135.Pp 136When reading a variable record/block from the tape, the head is 137logically considered to be immediately after the last item read, 138and before the next item after that. 139If the next item is a file mark, 140but it was never read, then the next 141process to read will immediately hit the file mark and receive an end-of-file notification. 142.It Fixed block-size: 143Data written by the user is passed to the tape as a succession of 144fixed size blocks. 145It may be contiguous in memory, but it is 146considered to be a series of independent blocks. 147One may never write 148an amount of data that is not an exact multiple of the blocksize. 149One may read and write the same data as a different set of records. 150In other words, blocks that were written together may be read separately, 151and vice-versa. 152.Pp 153If one requests more blocks than remain in the file, the drive will 154encounter the file mark. 155Because there is some data to return (unless 156there were no records before the file mark), the read will succeed, 157returning that data. 158The next read will return immediately with a value 159of 0. 160(As above, if the file mark is never read, it remains for the next 161process to read if in no-rewind mode.) 162.El 163.Sh FILE MARK HANDLING 164The handling of file marks on write is automatic. 165If the user has 166written to the tape, and has not done a read since the last write, 167then a file mark will be written to the tape when the device is 168closed. 169If a rewind is requested after a write, then the driver 170assumes that the last file on the tape has been written, and ensures 171that there are two file marks written to the tape. 172The exception to 173this is that there seems to be a standard (which we follow, but don't 174understand why) that certain types of tape do not actually write two 175file marks to tape, but when read, report a `phantom' file mark when the 176last file is read. 177These devices include the QIC family of devices. 178(It might be that this set of devices is the same set as that of fixed 179block devices. 180This has not been determined yet, and they are treated 181as separate behaviors by the driver at this time.) 182.Sh IOCTLS 183The 184.Nm 185driver supports all of the ioctls of 186.Xr mtio 4 . 187.Sh FILES 188.Bl -tag -width /dev/[n][e]sa[0-9] -compact 189.It Pa /dev/[n][e]sa[0-9] 190general form: 191.It Pa /dev/sa0 192Rewind on close 193.It Pa /dev/nsa0 194No rewind on close 195.It Pa /dev/esa0 196Eject on close (if capable) 197.It Pa /dev/sa0.ctl 198Control mode device (to examine state while another program is 199accessing the device, e.g.). 200.El 201.Sh DIAGNOSTICS 202None. 203.Sh SEE ALSO 204.Xr mt 1 , 205.Xr scsi 4 206.Sh AUTHORS 207.An -nosplit 208The 209.Nm 210driver was written for the 211.Tn CAM 212.Tn SCSI 213subsystem by 214.An Justin T. Gibbs 215and 216.An Kenneth Merry . 217Many ideas were gleaned from the 218.Nm st 219device driver written and ported from 220.Tn Mach 2212.5 222by 223.An Julian Elischer . 224.Pp 225The current owner of record is 226.An Matthew Jacob 227who has suffered too many 228years of breaking tape drivers. 229.Sh BUGS 230This driver lacks many of the hacks required to deal with older devices. 231Many older 232.Tn SCSI-1 233devices may not work properly with this driver yet. 234.Pp 235Additionally, certain 236tapes (QIC tapes mostly) that were written under 237.Fx 2382.X 239aren't automatically read correctly with this driver: you may need to 240explicitly set variable block mode or set to the blocksize that works best 241for your device in order to read tapes written under 242.Fx 2432.X. 244.Pp 245Fine grained density and compression mode support that is bound to specific 246device names needs to be added. 247.Pp 248Support for fast indexing by use of partitions is missing. 249