mt-st/stinit.8

.TH STINIT 8 "April 2008" \" -*- nroff -*-
.SH NAME
stinit \- initialize SCSI magnetic tape drives
.SH SYNOPSIS
.B stinit
[\-f conf-file] [\-h] [-p] [-r] [-v] [devices...]
.SH DESCRIPTION
This manual page documents the tape control program
.BR stinit
can used to initialize SCSI tape drive modes at system startup, after
loading the tape driver as module, or after introduction of new device
to the SCSI subsystem at run-time. The initialization is performed by
sending ioctl commands to the drive. The commands are defined in a
text file that is indexed using the inquiry data the drive returns
(manufacturer, device, revision). Values for all of the general and
mode-specific SCSI tape parameters up to Linux version 2.6.0 can be
initialized.
.PP
.SH OPTIONS
.TP
.I \-f conf-file
Specifies the name of the text file containing the definitions for
different tape drive types. By default
.B stinit
tries to find the definition file
.IR /etc/stinit.def .
.TP
.I \-h
Print the usage information.
.TP
.I \-p
The definition file is parsed but no tape drive initialization is
attempted. This option can be used for testing the integrity of a
definition file after changes have been made.
.TP
.I \-r
Rewind every device being initialized.
.TP
.I \-v
The more -v options (currently up to two), the more verbose output.
.TP
.I \-\-version
Print the program version.
.PP
.SH THE DEVICES BEING INITIALIZED
If the program is started without arguments, it tries to find all
accessible SCSI tape devices and the device files for the different
modes of the devices. The tape drives are searched in the scanning
order of the kernel and searching is stopped at the first non-existing
tape. All of the found devices are initialized if a matching
description is found from the parameter file. Note that a mode for a
device is not initialized if the corresponding device file is not
found even if a matching description for the mode exists. The
non-rewind device is preferred over the auto-rewind device for each
mode. If the directory
.I /dev/tapes
is found, the devfs filesystem is assumed to be mounted on /dev. Otherwise,
the directories
.I /dev/scsi
and
.I /dev
are scanned for device files.
.PP
SCSI tape drives can be initialized selectively using program
arguments. A numeric argument specifies the number of the tape drive
in the scanning order of the kernel. A file name specifies that the
device corresponding to this name is to be initialized. If the file name
is given without the directory specification, the program searches for
the name in the device directories
.I
/dev/scsi
and
.I /dev.
Only full path names are supported with devfs.
.PP
.SH THE CONFIGURATION FILE
The configuration file is a simple text file that contains
descriptions of tape drives and the corresponding initialization
parameters. The parameter definition blocks are delimited by
.I {}.
Specification of the drive description is restarted after each
parameter definition block.
.PP
The drive descriptions and the parameter definitions consist of pairs
.I name = value.
The value is either a numeric parameter, a string not containing
blanks, or a quoted string. In case of a numeric parameter, the
postfix
.I k
or
.I M
can be used to give the value in units of 1024 or 1024 * 1024,
respectively. If the
.I =value
-part is omitted, the value
.I
"1"
is used. If the character
.I #
is found from an input line, the rest of the line is discarded. This
allows use of comments in the definition file. The following example
contains definitions for one type of tape drives:
.PP
.RS
.nf
# The XY dat
manufacturer=XY-COMPANY model = "UVW DRIVE" {
scsi2logical=1 # Common definitions for all modes
can-bsr can-partitions auto-lock
# Definition of modes
mode1 blocksize=0 compression=1
mode2 blocksize=1024 compression=1
mode3 blocksize=0 compression=0
mode4 blocksize = 1k compression=0 }
.fi
.RE
.PP
The devices are identified using zero or more of the following
keywords corresponding to the data returned by the tape device as
response to the SCSI INQUIRY command. The matches are case-sensitive
and performed up to the length defined in the configuration file
(permitting use of partial matches).
.IP manufacturer=
This keyword specifies the string that must match the vendor
identification returned by the device.
.IP model=
This keyword defines the string that must match the
.B product identification
returned by the device.
.IP revision=
This keyword matched the string that must match the
.B product revision level
returned by the device.
.PP
All of the matching initializations are collected in the order they
are defined in the file. This means that common parameters can be
defined for all devices using zero keywords for a definition
block. Another consequence is that, for instance, some parameters can
be easily given different values for a specific firmware revision without
repeating the parameters common to all revisions.
.PP
The tape parameters are defined using the following keywords. More
thorough description of the parameters can be found from the
.I st(4)
man page (not up to date when this is written) or from the file
.I drivers/scsi/README.st
in the Linux kernel source tree. The keywords are matched using only
the first characters. The part of the keywords not used in matching is
enclosed by []. The numeric values may be specified either in decimal
notation or hexadecimal notation (using the prefix 0x).
.IP drive-[buffering]=value
The drive's buffering parameter is set to
.I value.
This parameter if common for all modes.
.IP cleaning
The cleaning request notifying parameter is set to
.I value
.IP no-w[ait]
The immediate mode is used with commands like rewind if
.I value
is non-zero (i.e., the driver does not wait for the command to finish).
.IP mode=value
This keyword starts definition of tape mode
.I value.
The number of the mode must be between 1 and 4.
.IP disab[led]=value
This mode is disabled for this device if
.I value
is non-zero. Can be used if some mode defined in a more general
definition should be disabled by a more specific definition for some
device (for example, for a device with buggy firmware level).
.IP block[size]=value
The default tape block size is set to
.I value.
bytes. The block size zero means variable block mode.
.IP dens[ity]=value
The tape density code is set to
.I value.
.IP buff[ering]=value
The buffered writes by the driver in fixed block mode are enabled if
.I value
is non-zero.
.IP async[-writes]=value
Asynchronous writes by the driver are enabled if
.I value
is non-zero.
.IP read[-ahead]=value
Read-ahead by the driver in fixed block mode is allowed if
.I value
is non-zero.
.IP two[-fms]=value
Two filemarks are written when a file being written to is closed if
.I value
is non-zero. By default, one filemark is written.
.IP comp[ression]=value
Compression of the data by the drive is enabled if
.I value
is non-zero. Note that the tape driver can't enable compression for
all drives that can compress data. Note also that some drives define
compression using density codes.
.IP auto[-lock]=value
The tape drive door is locked automatically when the device file is
opened if
.I value
is non-zero.
.IP fast[-eom]=value
The MTEOM command is performed using the SCSI command that spaces
directly to the end of medium if
.I value
is non-zero. The drawback is that the file number in the status
becomes invalid. By default, spacing to end of medium is performed by
spacing over filemarks until end of medium is detected and the file
number remains valid.
.IP can-b[sr]=value
Backspacing over records is used by the driver when repositioning
the tape when read-ahead is enabled if
.I value
is non-zero.
.IP noblk[limits]=value
The tape driver does not use the READ BLOCK LIMITS SCSI command when
the device is being opened if
.I value
is non-zero. This is for the drives that do not support this SCSI
command.
.IP can-p[artitions]=value
The support for tape partitions is enabled if
.I value
is non-zero.
.IP scsi2[logical]=value
Logical block addresses are used in the MTSEEK and MTIOCPOS
commands if
.I value
is non-zero. The default is to use the device-specific addresses.
.IP sili=value
If
.I value
is non-zero, the SILI bit is set when reading in variable block mode. This
may speed up reading blocks shorter than the read byte count. Set this only if
you know that the drive supports SILI and the HBA reliably returns transfer
residual byte counts. Requires kernel version >= 2.6.26.
.IP defs-for-w[rites]=value
The parameters defining the tape format (density, block size, etc.)
are forced when writing starts at the beginning of a tape if
.I value
is non-zero. The default is to change there parameters each time the
device is opened at the beginning of a tape (or the mode is changed in
the middle of a tape).
.IP sysv=value
The System V tape semantics are used if
.I value
is non-zero. Otherwise the BSD semantics are used.
.IP timeout=value
The normal timeout for the device is set to
.I value
seconds.
.IP long-time[out]=value
The long timeout for the device is set to
.I value
seconds.
.SH RETURN VALUE
The program exits with value one if the command line is incorrect, the
definition file is not found, or option -p is given and parsing the
definition file fails. In all other cases the return value is
zero (i.e., failing of initialization is not currently signaled by
the return value).
.SH RESTRICTIONS
With the exception of the -p option, the program can be used only by
the superuser. This is because the program uses ioctls allowed only
for the superuser.
.SH AUTHOR
The program is written by Kai Makisara <Kai.Makisara@kolumbus.fi>, and
is currently maintained by Iustin Pop <iustin@k1024.org>.
.SH COPYRIGHT
The program and the manual page are copyrighted by Kai Makisara, 1998-2008.
They can be distributed according to the GNU Copyleft.
.SH BUGS
Please report bugs to <https://github.com/iustin/mt-st>.
.SH SEE ALSO
st(4) mt(1)