NAME¶
stinit - initialize SCSI magnetic tape drives
SYNOPSIS¶
stinit [-f conf-file] [-h] [-p] [-r] [-v] [devices...]
DESCRIPTION¶
This manual page documents the tape control program
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.
OPTIONS¶
- -f conf-file
- Specifies the name of the text file containing the
definitions for different tape drive types. By default stinit tries
to find the definition file stinit.def or /etc/stinit.def
(in this order).
- -h
- Print the usage information.
- -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.
- -r
- Rewind every device being initialized.
- -v
- The more -v options (currently up to two), the more verbose
output.
- --version
- Print the program version.
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
/dev/tapes is found, the devfs filesystem is assumed to
be mounted on /dev. Otherwise, the directories
/dev/scsi and
/dev are scanned for device files.
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
/dev/scsi and
/dev. Only full path names are supported with
devfs.
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
{}. Specification of the drive
description is restarted after each parameter definition block.
The drive descriptions and the parameter definitions consist of pairs
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
k or
M can be used to give the value in units of 1024 or 1024 *
1024, respectively. If the
=value -part is omitted, the value
"1" is used. If the character
# 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:
# 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 }
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).
- manufacturer=
- This keyword specifies the string that must match the
vendor identification returned by the device.
- model=
- This keyword defines the string that must match the
product identification returned by the device.
- revision=
- This keyword matched the string that must match the
product revision level returned by the device.
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.
The tape parameters are defined using the following keywords. More thorough
description of the parameters can be found from the
st(4) man page (not
up to date when this is written) or from the file
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).
- drive-[buffering]=value
- The drive's buffering parameter is set to value.
This parameter if common for all modes.
- cleaning
- The cleaning request notifying parameter is set to
value
- no-w[ait]
- The immediate mode is used with commands like rewind if
value is non-zero (i.e., the driver does not wait for the command
to finish).
- mode=value
- This keyword starts definition of tape mode value.
The number of the mode must be between 1 and 4.
- disab[led]=value
- This mode is disabled for this device if 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).
- block[size]=value
- The default tape block size is set to value. bytes.
The block size zero means variable block mode.
- dens[ity]=value
- The tape density code is set to value.
- buff[ering]=value
- The buffered writes by the driver in fixed block mode are
enabled if value is non-zero.
- async[-writes]=value
- Asynchronous writes by the driver are enabled if
value is non-zero.
- read[-ahead]=value
- Read-ahead by the driver in fixed block mode is allowed if
value is non-zero.
- two[-fms]=value
- Two filemarks are written when a file being written to is
closed if value is non-zero. By default, one filemark is
written.
- comp[ression]=value
- Compression of the data by the drive is enabled if
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.
- auto[-lock]=value
- The tape drive door is locked automatically when the device
file is opened if value is non-zero.
- fast[-eom]=value
- The MTEOM command is performed using the SCSI command that
spaces directly to the end of medium if 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.
- can-b[sr]=value
- Backspacing over records is used by the driver when
repositioning the tape when read-ahead is enabled if value is
non-zero.
- noblk[limits]=value
- The tape driver does not use the READ BLOCK LIMITS SCSI
command when the device is being opened if value is non-zero. This
is for the drives that do not support this SCSI command.
- can-p[artitions]=value
- The support for tape partitions is enabled if value
is non-zero.
- scsi2[logical]=value
- Logical block addresses are used in the MTSEEK and MTIOCPOS
commands if value is non-zero. The default is to use the
device-specific addresses.
- sili=value
- If 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.
- 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
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).
- sysv=value
- The System V tape semantics are used if value is
non-zero. Otherwise the BSD semantics are used.
- timeout=value
- The normal timeout for the device is set to value
seconds.
- long-time[out]=value
- The long timeout for the device is set to value
seconds.
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).
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.
AUTHOR¶
The program is written by Kai Makisara <Kai.Makisara@kolumbus.fi>.
COPYRIGHT¶
The program and the manual page are copyrighted by Kai Makisara, 1998-2008. They
can be distributed according to the GNU Copyleft.
SEE ALSO¶
st(4) mt(1)