Ubuntu Manpage: stinit - initialize SCSI magnetic tape drives

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.