Added more missing manual pages from 1.1.5.

1 files changed, 308 insertions, 0 deletions

diff --git a/share/man/man4/sa.4 b/share/man/man4/sa.4
new file mode 100644
index 0000000..28f232b
--- /dev/null
+++ b/share/man/man4/sa.4
@@ -0,0 +1,308 @@
+.Dd August 27, 1993
+.Dt ST 4
+.Os FreeBSD
+.Sh NAME
+.Nm st
+.Nd scsi tape driver
+.Sh SYNOPSIS
+.Nm device-driver st
+.Op Ar count
+.Sh DESCRIPTION
+The
+.Xr st
+driver provides support for a 
+.Em scsi
+tape. It allows the tape
+to be run in upto four different modes depending on minor numbers
+and supports several different 'sub modes'.
+The device can have both a
+.Em raw
+interface
+and a
+.Em Block mode
+interface however only the raw interface is usually used (or recommended).
+In general the interfaces are similar to those described by 
+.Xr wt 4 
+or
+.Xr mt 4 .
+
+.Pp
+Where the 
+.Xr wt 4
+device has a fairly low level interface to the system, 
+.Em SCSI
+devices have a much higher level interface and talk to the system via
+a 
+.Em SCSI Adapter
+and a
+.Em Scsi Adapter driver
+e.g. 
+.Xr AHA1542 .
+A scsi adapter must also be separatly configured into the system
+before a scsi tape can be configured.
+.Pp
+As the scsi adapter is probed during boot, the 
+.Em SCSI
+bus is scanned for devices. Any devices found which answer as 'Sequential'
+type devices will be attached to the 
+.Nm
+driver. The first found will be attached as
+.Em st0
+and the next, 
+.Em st1
+etc.
+.Pp
+.Sh MOUNT SESSIONS
+The 
+.Nm
+driver is based around the concept of a 
+.Em Mount Session
+, which is defined as the period between the time that a tape is mounted,
+and the time when it is unmounted. Any parameters set during a 
+.Em Mount Session
+remain in effect for the remainder of the session or until replaced. The
+Tape can be unmounted, bringing the session to a close in several ways.
+These include:
+.Bl -tag -width ABOUT_THIS_BIG_BUT_REALLY_BIGGER
+.It Pa closing an 'unmount device'
+This is referred to as sub-mode 00 (see below). An example is /dev/rst0.
+.It Pa an MTOFFL ioctl
+Reachable throught the 'offline' command of 
+.Xr st 1
+.It Pa Openning another mode.
+Openning a different mode will implicitly unmount the tape, thereby closing
+off the mode that was previously mounted. All parameters will be loaded
+freshly from the new mode. (see below for more on 'modes').
+.El
+.Pp
+Parameters that are required to last across the unmounting of a tape,
+should be set on the control device. This is submode 3 (see below) and is
+reached through a file with a name of the form /dev/st{y}ctl.{x}, where
+{y} is the drive number and {x} is the mode number.
+.Pp
+.Sh MODES AND SUB MODES
+There are four Operation modes. These are  controlled by bits 2
+and 3 of the minor number and are designed to allow people to easily
+read and write different formats of tape on devices that allow
+multiple formats. The parameters for each mode can be set individually
+by hand with the
+.Xr st 1
+variant of the
+.Xr mt 1
+command. When a device corresponding to a particular mode is first mounted,
+The operating parameters for that
+.Em Mount Session
+Are copied from that mode. Further changes to the parameters during the
+session will change those in effect for the session but not those set
+in the Operating Mode. To change the parameters for an Operating Mode, 
+One must either assign the parameters to the control device, or compile
+them into the 'Rogues Gallery' table within the driver.
+.Pp
+In addition to the four Operation Modes mentionned above, 
+bits 0 and 1 of the minor number are interpretted as being 'sub-modes'.
+The following sub-modes are supported 
+.Bl -tag -width ABOUT_THIS_BIG
+.It Pa 00
+A close will rewind the device. If the tape has been 
+written, then a Filemark will be written before the rewind is requested.
+The device is UNMOUNTED.
+.It Pa 01
+A close will leave the tape MOUNTED.
+If the tape was written to a filemark will be written.
+No other head positioning takes place.
+Any further reads or writes will occur directly after the
+last read, or the written filemark.
+.It Pa 10
+A close will rewind the device. If the tape has been 
+written, then a Filemark will be written before the rewind is requested.
+On completion of the rewind an UNLOAD command will be issued.
+The device is UNMOUNTED.
+.It Pa 11
+This is a special mode.
+It is known as the 
+.Em CONTROL DEVICE
+for the mode. Parameters set for the mode while in this sub
+mode will be remembered from one mount to the next. This allows the
+system administrator to set different characteristics (e.g. density,
+blocksize, (and eventually compression)) on each mode, and have the
+different modes keep those parameters independent of any parameter
+changes a user may invoke during a single mount session. At the
+completion of the user's mount session, drive parameters will revert
+to those set by the administrator. IO operations cannot be performed
+on this device/submode. General 
+.Xr scsi 4
+ioctls 
+.Em MUST
+be performed against the control device.
+.El
+.Sh BLOCKING MODES
+Scsi Tapes may run in either 'variable' or 'fixed block' modes.
+Most QIC type devices run in Fixed block mode, where most 'reel to reel' tapes and 
+many new cartridge formats, allow variable blocksize. The difference between
+the two is as follows:
+.Bl -tag -width variable-blocksize
+.It Pa Variable Blocksize
+Each write made to the device results in a single logical record
+written to the tape. You can never read or write PART of a record
+from tape, (though you may request a larger block and read a smaller
+record). You cannot read multiple blocks either.  Data from a single
+write is therefore read by a single read. The block size used may
+be any value supported by the device, the scsi adapter and the
+system.  (often variable between 1 byte and 64k (sometimes more)).
+.Pp
+When reading a variable record/block from the tape, the head is
+logically considered to be immediately after the last item read,
+and before the next item after that. If the next item is a Filemark,
+but you never read it because you have all the data, then the next
+process to read will immediately read the filemark and return EOF.
+(assuming you were in non-rewind mode).
+.It Pa fixed Blocksize
+Data written by the user is passed to the tape as a succession of
+fixed size blocks. It may be contiguouse in ram and read in a single
+DMA pass, however it is considered to be a series of independent
+blocks. You may never write an amount of data that is not an exact
+multiple of the blocksize.  You may read and write the same data
+as a different set of records, In other words, blocks that were
+written together may be read separatly, and visa versa.
+.Pp
+If you ask for more blocks than there are left in the file, then
+the drive will encounter the filemark. Because there is some data
+to return to you (unless there were no records before the filemark)
+the driver will return the data to you (less than you requested),
+but hide from you the discovery of the Filemark. The  NEXT read
+will be returned immediately with an EOF. If you never Make the next
+read, but close the device, the next process to read will immediately
+read the filemark and return EOF. (assuming you were in non-rewind
+mode).
+.El
+.Sh FILEMARK HANDLING
+The handling of filemarks on write is pretty much automatic. If you
+have written to the tape, and not done a read since, then a filemark will
+be written to the tape when you close the device. If a rewind is requested
+after a write, then the driver assumes that you have written the last file
+on the tape and ensures that there are two filemarks written to the tape.
+It takes into account any filemarks already written (whether by close
+or by explicit ioctl). The exception to this is that there seems to be
+a standard (which we follow, but don't understand why) that certain
+types of tape do not actually write two filemarks to tape,
+but when read, report a 'phantom' filemark when the last file is read.
+These devices include the QIC family of devices. It might be that this
+set of devices is the same set as that of fixed block devices. This has not
+been detirmined yet, and they are treated as separate behaviors by the
+driver at this time.
+.Pp
+.SH KERNEL CONFIGURATION
+In configuring, if an optional
+.Ar count
+is given in
+the specification, that number of scsi tapes are configured;
+Most storage for them is allocated only when found so a large number 
+of configured devices is cheap. (once the first has included the driver).
+.Pp
+Because different tape drives behave differently, there is a mechanism 
+within the source to st, to quickly and conveniently recognise and deal
+with brands and models of drive that have special requirements.
+.Pp
+There is a table (called the rogues gallery) in which the indentification
+strings of known errant drives can be stored. Along with each is
+a set of flags that allows the setting of densities and blocksizes for each 
+of the 4 modes, along with a set of 'QUIRK' flags that can be
+used to enable or disable sections of code within the driver if a particular
+drive is recognised.
+.Pp
+.Sh IOCTLS
+The following 
+.Xr ioctl 2
+calls apply to scsi tapes. Some also apply to other tapes. They are defined
+in the header file
+.Em /sys/mtio.h.
+
+.Bl -tag -width MTIOCEEOT
+.It Pa MTIOCGET
+Get the mt control structure filled out by the driver, showing
+all the present settings.
+.It Pa MTIOCTOP
+Perform one of the following operations. These operations all have a 
+single argument, which is either a boolean, or a signed integer, depending
+on the operation.
+.Bl -tag -width MTSELDNSTY
+.It Pa MTWEOF
+Write N end of file marks at the present head position.
+.It Pa MTFSF
+Skip over N Filemarks. Leave the head on the EOM side of the last skipped
+Filemark.
+.It Pa MTBSF
+Skip BACKWARDS over N Filemarks. Leave the head on the BOM (beginning of media)
+side of the last skipped Filemark.
+.It Pa MTFSR
+Skip forwards over N records.
+.It Pa MTBSR
+Skip backwards over N records.
+.It Pa MTREW
+Rewind the device to the beginning of the media.
+.It Pa MTOFFL
+Rewind the media (and if possible eject). Even if the device cannot
+eject the media it will often no longer respond to normal requests.
+.It Pa MTNOP
+No Op, set status only..
+.It Pa MTCACHE
+Enable controller Buffering.
+.It Pa MTNOCACHE
+Disable controller Buffering.
+.It Pa MTSETBSIZ
+Set the blocksize to use for the device/mode. If the device is capable of
+variable blocksize operation, and the blocksize is set to 0, then the drive
+will be driven in variable mode. This parameter is in effect for the present
+mount session only, unless set on the control device.
+.It Pa MTSETDNSTY
+Set the Density value (see 
+.Xr st 1
+) to use when running in the mode openned (minor bits 2,3).
+This parameter is in effect for the present
+mount session only, unless set on the control device.
+.El
+.It Pa MTIOCIEOT
+?Set END of TAPE processing... not yet supported.
+.It Pa MTIOCEEOT
+?Set END of TAPE processing... not yet supported.
+.El
+.Pp
+In addition, The 
+.Nm
+driver will allow the use of any of the general 
+.Xr scsi 4
+ioctls, as long as the control device is used.
+
+.Sh FILES
+.Bl -tag -width /dev/[n][e]rst[0-9].[0-3] -compact
+.It Pa /dev/[n][e]rst[0-9].[0-3]
+general form:
+.It Pa /dev/rst0.0	
+Mode 0, rewind on close
+.It Pa /dev/nrst0.2	
+Mode 2, No rewind on close
+.It Pa /dev/erst0.3
+Mode 3, Eject on close (if capable)
+.It Pa /dev/rst0	
+Another name for rst0.0
+.It Pa /dev/nrst0	
+Another name for nrst0.0
+.It Pa /dev/st0ctl.0	
+Parameters set to this device become the default parameters for [en]rst0.0
+.It Pa /dev/st0ctl.1	
+Parameters set to this device become the default parameters for [en]rst0.1
+.It Pa /dev/st0ctl.2	
+Parameters set to this device become the default parameters for [en]rst0.2
+.It Pa /dev/st0ctl.3	
+Parameters set to this device become the default parameters for [en]rst0.3
+.El
+.Sh DIAGNOSTICS
+None.
+.Sh SEE ALSO
+.Xr mt 1
+.Xr st 1
+.Sh HISTORY
+This
+.Nm
+driver appeared in MACH 2.5 .
+