1.\" $OpenBSD: st.4,v 1.20 2016/09/04 14:42:58 naddy 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: September 4 2016 $ 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. 44.Pp 45.Tn SCSI 46devices have a relatively high level interface and talk to the system via a 47.Tn SCSI 48adapter and a 49.Tn SCSI 50adapter driver 51e.g.\& 52.Xr ahc 4 . 53The 54.Tn SCSI 55adapter must be separately configured into the system before a 56.Tn SCSI 57tape can be configured. 58.Pp 59As the 60.Tn SCSI 61adapter is probed during boot, the 62.Tn SCSI 63bus is scanned for devices. 64Any devices found which answer as 65.Em Sequential 66type devices will be attached to the 67.Nm 68driver. 69.Sh MOUNT SESSIONS 70The 71.Nm 72driver is based around the concept of a 73.Em mount session , 74which is defined as the period between the time that a tape is 75mounted and the time when it is unmounted. 76Any parameters set during a mount session remain in effect for the remainder 77of the session or until replaced. 78The tape can be unmounted, bringing the session to a close in several ways. 79These include: 80.Bl -enum 81.It 82Closing an 83.Dq unmount device . 84.It 85Using the 86.Dv MTOFFL 87.Xr ioctl 2 88command, reachable through the 89.Cm offline 90command of 91.Xr mt 1 . 92.El 93.Sh EJECT and REWIND 94Bit 0 of the minor number specifies whether a rewind is attempted when the 95device is closed. 96When it is set, the device will not attempt a rewind on close 97and the device will have an 98.Sq n 99in its name. 100For example, 101.Pa /dev/rst0 102will rewind on close but 103.Pa /dev/nrst0 104will not. 105.Pp 106Bit 1 of the minor number specifies whether an eject is attempted when the 107device is closed. 108When it is set, the device will attempt to eject its media on close 109and the device will have an 110.Sq e 111in its name. 112For example, 113.Pa /dev/erst0 114will eject its media on close but 115.Pa /dev/rst0 116will not. 117.Pp 118If both bit 0 and bit 1 are set then an eject will 119be attempted without a rewind and the device will have both an 120.Sq e 121and an 122.Sq n 123in its name. 124For example, 125.Pa /dev/enrst0 126will eject its media without first rewinding it on close. 127.Pp 128There is no guarantee that the attempted eject or rewind will be supported 129by the actual hardware. 130.Sh BLOCKING MODES 131.Tn SCSI 132tapes may run in either 133.Em variable 134or 135.Em fixed 136block-size modes. 137Most 138.Tn QIC Ns -type 139devices run in fixed block-size mode, whereas most nine-track tapes 140and many new cartridge formats allow variable block-size. 141The difference between the two is as follows: 142.Bl -inset 143.It Variable block-size: 144Each write made to the device results in a single logical record 145written to the tape. 146One can never read or write 147.Em part 148of a record from tape (though you may request a larger block and 149read a smaller record); nor can one read multiple blocks. 150Data from a single write is therefore read by a single read. 151The block size used may be any value supported by the device, the 152.Tn SCSI 153adapter and the system (usually between 1 byte and 64 Kbytes, 154sometimes more). 155.Pp 156When reading a variable record/block from the tape, the head is 157logically considered to be immediately after the last item read, 158and before the next item after that. 159If the next item is a file mark, but it was never read, then the next 160process to read will immediately hit the file mark and receive an 161end-of-file notification. 162.It Fixed block-size 163data written by the user is passed to the tape as a succession of 164fixed size blocks. 165It may be contiguous in memory, but it is considered to be a series of 166independent blocks. 167One may never write an amount of data that is not an exact multiple of the 168blocksize. 169One may read and write the same data as a different set of records. 170In other words, blocks that were written together may be read separately, 171and vice-versa. 172.Pp 173If one requests more blocks than remain in the file, the drive will 174encounter the file mark. 175Because there is some data to return (unless there were no records before 176the file mark), the read will succeed, returning that data. 177The next read will return immediately with an 178.Dv EOF . 179(As above, if the file mark is never read, it remains for the next process 180to read if in no-rewind mode.) 181.El 182.Sh FILE MARK HANDLING 183The handling of file marks on write is automatic. 184If the user has written to the tape, and has not done a read since the last 185write, then a file mark will be written to the tape when the device is closed. 186If a rewind is requested after a write, then the driver 187assumes that the last file on the tape has been written, and ensures 188that there are two file marks written to the tape. 189The exception to this is that there seems to be a standard (which we follow, 190but don't understand why) that certain types of tape do not actually 191write two file marks to tape, but when read, report a 192.Dq phantom 193file mark when the last file is read. 194These devices include the QIC family of devices. 195(It might be that this set of devices is the same set as that of fixed. 196This has not yet been determined, and they are treated as separate 197behaviors by the driver at this time.) 198.Sh IOCTLS 199The following 200.Xr ioctl 2 201calls apply to 202.Tn SCSI 203tapes. 204Some also apply to other tapes. 205They are defined in the header file 206.In sys/mtio.h . 207.\" 208.\" Almost all of this discussion belongs in a separate mt(4) 209.\" manual page, since it is common to all magnetic tapes. 210.\" 211.Bl -tag -width MTIOCEEOT 212.It Dv MTIOCGET Fa "struct mtget *" 213Retrieve the status and parameters of the tape. 214.It Dv MTIOCTOP "struct mtop *" 215Perform a multiplexed operation. 216The argument structure is as follows: 217.Bd -literal -offset indent 218struct mtop { 219 short mt_op; 220 int mt_count; 221}; 222.Ed 223.Pp 224The following operation values are defined for 225.Va mt_op : 226.Bl -tag -width MTSELDNSTY 227.It Dv MTWEOF 228Write 229.Va mt_count 230end of file marks at the present head position. 231.It Dv MTFSF 232Skip over 233.Va mt_count 234file marks. 235Leave the head on the EOM side of the last skipped file mark. 236.It Dv MTBSF 237Skip 238.Em backwards 239over 240.Va mt_count 241file marks. 242Leave the head on the BOM (beginning of media) side of the last skipped 243file mark. 244.It Dv MTFSR 245Skip forwards over 246.Va mt_count 247records. 248.It Dv MTBSR 249Skip backwards over 250.Va mt_count 251records. 252.It Dv MTREW 253Rewind the device to the beginning of the media. 254.It Dv MTOFFL 255Rewind the media (and, if possible, eject). 256Even if the device cannot eject the media it will often no longer respond 257to normal requests. 258.It Dv MTNOP 259No-op; set status only. 260.It Dv MTCACHE 261Enable controller buffering. 262.It Dv MTNOCACHE 263Disable controller buffering. 264.It Dv MTSETBSIZ 265Set the blocksize to use for the device/mode. 266If the device is capable of variable blocksize operation, and the blocksize 267is set to 0, then the drive will be driven in variable mode. 268This parameter is in effect for the present mount session only. 269.It Dv MTSETDNSTY 270Set the density value (see 271.Xr mt 1 ) 272to use when running in the mode opened (minor bits 2 and 3). 273This parameter is in effect for the present 274mount session only. 275.El 276.It Dv MTIOCIEOT 277Set end-of-tape processing (not presently supported for 278.Nm 279devices). 280.It Dv MTIOCEEOT 281Set end-of-tape processing (not presently supported for 282.Nm 283devices). 284.El 285.Sh FILES 286.Bl -tag -width /dev/[e][n][r]st[0-9] -compact 287.It Pa /dev/[e][n][r]st[0-9] 288General form. 289.It Pa /dev/rst0 290No eject, rewind on close. 291.It Pa /dev/nrst0 292No eject, no rewind on close. 293.It Pa /dev/erst0 294Eject, rewind on close. 295.It Pa /dev/enrst0 296Eject, no rewind on close. 297.El 298.Sh SEE ALSO 299.Xr chio 1 , 300.Xr mt 1 , 301.Xr intro 4 , 302.Xr mtio 4 , 303.Xr scsi 4 304.Sh HISTORY 305This 306.Nm 307driver was originally written for 308.Tn Mach 3092.5 by Julian Elischer, and was ported to 310.Nx 311by Charles Hannum. 312This man page was edited for 313.Nx 314by Jon Buller. 315