1.\" $OpenBSD: st.4,v 1.17 2011/03/12 19:24:20 krw Exp $ 2.\" $NetBSD: st.4,v 1.2 1996/10/20 23:15:24 explorer Exp $ 3.\" 4.\" Copyright (c) 1996 5.\" Julian Elischer <julian@freebsd.org>. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd $Mdocdate: March 12 2011 $ 30.Dt ST 4 31.Os 32.Sh NAME 33.Nm st 34.Nd SCSI tape driver 35.Sh SYNOPSIS 36.Cd "st* at scsibus?" 37.Cd "#st0 at scsibus0 target 4 lun 0" Pq fixed-configuration example 38.Sh DESCRIPTION 39The 40.Nm 41driver provides support for 42.Tn SCSI 43tape drives. 44The device can have both a 45.Em raw 46interface and a 47.Em block 48interface; however, only the raw interface is usually used (or recommended). 49The raw interface devices will have an 50.Sq r 51in their names 52e.g.\& 53.Pa /dev/rst0 . 54.Pp 55.Tn SCSI 56devices have a relatively high level interface and talk to the system via a 57.Tn SCSI 58adapter and a 59.Tn SCSI 60adapter driver 61e.g.\& 62.Xr ahc 4 . 63The 64.Tn SCSI 65adapter must be separately configured into the system before a 66.Tn SCSI 67tape can be configured. 68.Pp 69As the 70.Tn SCSI 71adapter is probed during boot, the 72.Tn SCSI 73bus is scanned for devices. 74Any devices found which answer as 75.Em Sequential 76type devices will be attached to the 77.Nm 78driver. 79.Sh MOUNT SESSIONS 80The 81.Nm 82driver is based around the concept of a 83.Em mount session , 84which is defined as the period between the time that a tape is 85mounted and the time when it is unmounted. 86Any parameters set during a mount session remain in effect for the remainder 87of the session or until replaced. 88The tape can be unmounted, bringing the session to a close in several ways. 89These include: 90.Bl -enum 91.It 92Closing an 93.Dq unmount device . 94.It 95Using the 96.Dv MTOFFL 97.Xr ioctl 2 98command, reachable through the 99.Cm offline 100command of 101.Xr mt 1 . 102.El 103.Sh EJECT and REWIND 104Bit 0 of the minor number specifies whether a rewind is attempted when the 105device is closed. 106When it is set, the device will not attempt a rewind on close 107and the device will have an 108.Sq n 109in its name. 110For example, 111.Pa /dev/rst0 112will rewind on close but 113.Pa /dev/nrst0 114will not. 115.Pp 116Bit 1 of the minor number specifies whether an eject is attempted when the 117device is closed. 118When it is set, the device will attempt to eject its media on close 119and the device will have an 120.Sq e 121in its name. 122For example, 123.Pa /dev/erst0 124will eject its media on close but 125.Pa /dev/rst0 126will not. 127.Pp 128If both bit 0 and bit 1 are set then an eject will 129be attempted without a rewind and the device will have both an 130.Sq e 131and an 132.Sq n 133in its name. 134For example, 135.Pa /dev/enrst0 136will eject its media without first rewinding it on close. 137.Pp 138There is no guarantee that the attempted eject or rewind will be supported 139by the actual hardware. 140.Sh BLOCKING MODES 141.Tn SCSI 142tapes may run in either 143.Em variable 144or 145.Em fixed 146block-size modes. 147Most 148.Tn QIC Ns -type 149devices run in fixed block-size mode, whereas most nine-track tapes 150and many new cartridge formats allow variable block-size. 151The difference between the two is as follows: 152.Bl -inset 153.It Variable block-size: 154Each write made to the device results in a single logical record 155written to the tape. 156One can never read or write 157.Em part 158of a record from tape (though you may request a larger block and 159read a smaller record); nor can one read multiple blocks. 160Data from a single write is therefore read by a single read. 161The block size used may be any value supported by the device, the 162.Tn SCSI 163adapter and the system (usually between 1 byte and 64 Kbytes, 164sometimes more). 165.Pp 166When reading a variable record/block from the tape, the head is 167logically considered to be immediately after the last item read, 168and before the next item after that. 169If the next item is a file mark, but it was never read, then the next 170process to read will immediately hit the file mark and receive an 171end-of-file notification. 172.It Fixed block-size 173data written by the user is passed to the tape as a succession of 174fixed size blocks. 175It may be contiguous in memory, but it is considered to be a series of 176independent blocks. 177One may never write an amount of data that is not an exact multiple of the 178blocksize. 179One may read and write the same data as a different set of records. 180In other words, blocks that were written together may be read separately, 181and vice-versa. 182.Pp 183If one requests more blocks than remain in the file, the drive will 184encounter the file mark. 185Because there is some data to return (unless there were no records before 186the file mark), the read will succeed, returning that data. 187The next read will return immediately with an 188.Dv EOF . 189(As above, if the file mark is never read, it remains for the next process 190to read if in no-rewind mode.) 191.El 192.Sh FILE MARK HANDLING 193The handling of file marks on write is automatic. 194If the user has written to the tape, and has not done a read since the last 195write, then a file mark will be written to the tape when the device is closed. 196If a rewind is requested after a write, then the driver 197assumes that the last file on the tape has been written, and ensures 198that there are two file marks written to the tape. 199The exception to this is that there seems to be a standard (which we follow, 200but don't understand why) that certain types of tape do not actually 201write two file marks to tape, but when read, report a 202.Dq phantom 203file mark when the last file is read. 204These devices include the QIC family of devices. 205(It might be that this set of devices is the same set as that of fixed. 206This has not yet been determined, and they are treated as separate 207behaviors by the driver at this time.) 208.Sh IOCTLS 209The following 210.Xr ioctl 2 211calls apply to 212.Tn SCSI 213tapes. 214Some also apply to other tapes. 215They are defined in the header file 216.Aq Pa sys/mtio.h . 217.\" 218.\" Almost all of this discussion belongs in a separate mt(4) 219.\" manual page, since it is common to all magnetic tapes. 220.\" 221.Bl -tag -width MTIOCEEOT 222.It Dv MTIOCGET 223.Pq Li "struct mtget" 224Retrieve the status and parameters of the tape. 225.It Dv MTIOCTOP 226.Pq Li "struct mtop" 227Perform a multiplexed operation. 228The argument structure is as follows: 229.Bd -literal -offset indent 230struct mtop { 231 short mt_op; 232 int mt_count; 233}; 234.Ed 235.Pp 236The following operation values are defined for 237.Va mt_op : 238.Bl -tag -width MTSELDNSTY 239.It Dv MTWEOF 240Write 241.Va mt_count 242end of file marks at the present head position. 243.It Dv MTFSF 244Skip over 245.Va mt_count 246file marks. 247Leave the head on the EOM side of the last skipped file mark. 248.It Dv MTBSF 249Skip 250.Em backwards 251over 252.Va mt_count 253file marks. 254Leave the head on the BOM (beginning of media) side of the last skipped 255file mark. 256.It Dv MTFSR 257Skip forwards over 258.Va mt_count 259records. 260.It Dv MTBSR 261Skip backwards over 262.Va mt_count 263records. 264.It Dv MTREW 265Rewind the device to the beginning of the media. 266.It Dv MTOFFL 267Rewind the media (and, if possible, eject). 268Even if the device cannot eject the media it will often no longer respond 269to normal requests. 270.It Dv MTNOP 271No-op; set status only. 272.It Dv MTCACHE 273Enable controller buffering. 274.It Dv MTNOCACHE 275Disable controller buffering. 276.It Dv MTSETBSIZ 277Set the blocksize to use for the device/mode. 278If the device is capable of variable blocksize operation, and the blocksize 279is set to 0, then the drive will be driven in variable mode. 280This parameter is in effect for the present mount session only. 281.It Dv MTSETDNSTY 282Set the density value (see 283.Xr mt 1 ) 284to use when running in the mode opened (minor bits 2 and 3). 285This parameter is in effect for the present 286mount session only. 287.El 288.It Dv MTIOCIEOT 289Set end-of-tape processing (not presently supported for 290.Nm 291devices). 292.It Dv MTIOCEEOT 293Set end-of-tape processing (not presently supported for 294.Nm 295devices). 296.El 297.Sh FILES 298.Bl -tag -width /dev/[e][n][r]st[0-9] -compact 299.It Pa /dev/[e][n][r]st[0-9] 300General form. 301.It Pa /dev/rst0 302No eject, rewind on close. 303.It Pa /dev/nrst0 304No eject, no rewind on close. 305.It Pa /dev/erst0 306Eject, rewind on close. 307.It Pa /dev/enrst0 308Eject, no rewind on close. 309.El 310.Sh SEE ALSO 311.Xr chio 1 , 312.Xr mt 1 , 313.Xr intro 4 , 314.Xr mtio 4 , 315.Xr scsi 4 316.Sh HISTORY 317This 318.Nm 319driver was originally written for 320.Tn Mach 3212.5 by Julian Elischer, and was ported to 322.Nx 323by Charles Hannum. 324This man page was edited for 325.Nx 326by Jon Buller. 327