st01(7) st01(7)
NAME
st01 - Portable Device Interface (PDI) tape target driver
DESCRIPTION
The st01 tape driver receives command requests from the kernel
through the read(2), write(2), and ioctl(2) system calls. The
st01 driver generates the appropriate commands and passes them
through the host adapter driver to the tape device. When
command execution is complete, the host adapter driver
notifies st01 through an interrupt. After this notification,
st01 performs any required error recovery, and indicates to
the kernel that the Input/Output (I/O) request is complete.
The st01 driver operates independently of the hardware used to
communicate with the HBA bus.
I/O requests must be in length a multiple of the tape block
length. The default value is 512 bytes.
Only raw character interface files are provided. When opened,
the tape is assumed to be positioned as desired. If a
retension-on-open special file is opened, the tape is
retensioned before any I/O is performed. When a T_RWD,
T_RETENSION, T_LOAD, or T_UNLOAD ioctl is requested and the
tape has been written, two file marks are written before the
ioctl is executed.
The open(2) on a tape device can fail is a tape is not
inserted, resulting in the error report EIO. An open(2) can
also fail if the tape controller associated with the special
file is not detected by the driver. In this case, the error
reported is ENXIO.
The following table lists the actions that occur on close.
depending on whether the file is designated as rewind or no-
rewind, and if the tape was written or read:
Rewind | Tape | Tape | Action
on Close?| Read?| Written?| on Close
_________|_______|__________|___________________________
Yes | Yes | N/A | Rewind tape.
Yes | N/A | Yes | Write two file marks and
| | | rewind tape.
Yes | No | No | Rewind tape
No | No | No |
Copyright 1994 Novell, Inc. Page 1
st01(7) st01(7)
| | | No tape movement
No | Yes | N/A | Position tape after next
| | | file mark
No | N/A | Yes | Write one file mark and
| | | position tape after this
| | | file mark
Some media may be ejected from the drive, if this
functionality is supported (not all drives are supported).
A read occurring when the tape is positioned immediately
before a file mark returns zero(0) bytes, and the tape is
positioned after the file mark. As with other raw devices,
seeks are ignored. Some tape devices allow both reads and
writes to occur between rewinds; the st01 driver supports
these devices.
st01 Device Nodes
/dev/rmt:
Nodes in this directory provide access to the attached tape
devices found by the system.
cCbBtTlL C - Controller Number
B - SCSI Bus Number
T - SCSI Target ID
L - SCSI Logical Unit Number
- Rewinds the media on device close.
cCbBtTlLn C - Controller Number
B - SCSI Bus Number
T - SCSI Target ID
L - SCSI Logical Unit Number
- Does not rewind the media on device close.
cCbBtTlLnr C - Controller Number
B - SCSI Bus Number
T - SCSI Target ID
L - SCSI Logical Unit Number
- Retensions the media on device open.
- Does not rewind the media on device close.
cCbBtTlLr C - Controller Number
Copyright 1994 Novell, Inc. Page 2
st01(7) st01(7)
B - SCSI Bus Number
T - SCSI Target ID
L - SCSI Logical Unit Number
- Retensions the media on device open.
- Rewinds the media on device close.
cCbBtTlLu C - Controller Number
B - SCSI Bus Number
T - SCSI Target ID
L - SCSI Logical Unit Number
- Rewinds the media on device close.
- Issues an UNLOAD request on device close, on
drives supporting this command the media will
be ejected from the drive.
ctapeN N - The drive number. The drives are numbered
sequentially starting at 1 as they are
found by the system.
- Rewinds the media on device close.
ntapeN N - The drive number. The drives are numbered
sequentially starting at 1 as they are
found by the system.
- Does not rewind the media on device close.
rtapeN N - The drive number. The drives are numbered
sequentially starting at 1 as they are
found by the system.
- Retensions the media on device open.
- Rewinds the media on device close.
utapeN N - The drive number. The drives are numbered
sequentially starting at 1 as they are
found by the system.
- Rewinds the media on device close.
- Issues an UNLOAD request on device close, on
drives supporting this command the media will
be ejected from the drive.
Copyright 1994 Novell, Inc. Page 3
st01(7) st01(7)
ioctl Calls
The following ioctl calls are used by the st01 driver to
control tape positioning:
T_SFF/T_SFB Positions the tape forward or backward arg [see
ioctl(2)] number of file marks from the current
tape head position toward the End-of-Tape (EOT)
or Beginning-of-Tape (BOT). Forward movement
of the tape leaves the tape positioned on the
EOT side of a file mark or at EOT, and
backwards movement leaves the tape positioned
on the BOT side of a file mark or at BOT. A
backward positioning operation causes the next
read to return 0 bytes unless arg is greater
than the number of file marks between the
current position and BOT. The value of arg
must be a positive integer. A value of 0 is
not considered an error, but does not result in
any tape movement.
T_SBF/T_SBB Positions the tape forward or backward arg
number of blocks from the current tape head
position toward the EOT or BOT. Upon command
completion, the tape head is positioned in the
gap between tape blocks. Thus, skipping a
block forward advances to the next block, and
skipping a block backward retreats to the last
block. The value of arg must be a positive
integer. Upon any attempt to skip over a file
mark, the tape is positioned on the EOT/BOT
side of the file mark for forward/backward
movement, and the positioning operation ceases.
A value of 0 is not considered an error, but
does not result in any tape movement.
T_RWD Rewinds the tape from the current tape position
to the BOT. Two file marks are written before
the rewind if the tape has been written. This
command does not unload the tape.
T_WRFILEM Writes file marks to the tape. The value of
arg defines the number of consecutive file
marks to be written. If an error occurs while
writing file marks, the number of file marks
that have been successfully written is
indeterminate.
Copyright 1994 Novell, Inc. Page 4
st01(7) st01(7)
T_EOD Positions the tape just beyond the last file
mark.
T_STD Defines the recording density of the tape media
being used. The numeric density code used is
as defined in the SCSI-2 draft specification.
T_PREVMV Locks the tape in the drive. This prevention
may be in the form of a mechanical lock or an
LED to indicate the device is in use. T_PREVMV
is supported only on devices that implement
this feature. For example, ICT devices are
among those which do not support this ioctl.
T_ALLOMV Unlocks the tape in the drive. This command is
used to undo the lock created by T_PREVMV.
T_ALLOMV is supported only on devices that
implement this feature. For example, ICT
devices are among those which do not support
this ioctl.
T_LOAD Loads the tape media and position the tape BOT.
T_UNLOAD Unloads the tape. Most devices rewind the tape
before unloading. Devices capable of ejecting
the tape will do so in response to this
command.
T_ERASE Erases the tape, from BOT to EOT. If the tape
is not positioned at BOT, the tape is
positioned at BOT before performing the erase
function.
T_RDBLKLEN Returns the minimum and maximum block lengths
supported by the tape device. The value of arg
must be a struct blklen. See the file
/usr/include/sys/st01.h for more information.
T_WRBLKLEN Sets the current block length for the tape
device. The value of arg must be a struct
blklen with both max_blen and min_blen set to
the desired block length. See the file
/usr/include/sys/st01.h for more information.
Copyright 1994 Novell, Inc. Page 5
st01(7) st01(7)
T_RETENSION Retensions the tape in the drive, running the
tape at high speed from BOT to EOT, and then
back again. The retension operation leaves the
tape positioned at BOT.
The following ioctl commands identify a target driver and get
a pass-through major and minor number for a target device.
B_GETTYPE Gets the bus name (for example, scsi) and
device driver name (for example, st01) of a
specific device
B_GETDEV Gets the pass-through major and minor number to
the calling utility, allowing creation of a
pass-through special device file.
Files
/usr/include/sys/st01_ioctl.h
/usr/include/sys/st01.h
/usr/include/sys/sdi_edt.h
USAGE
Once any drive error is encountered, the driver will not
perform any other functions until the file is closed.
The st01 tape driver does not always require block sizes that
are in multiples of 512 bytes, but block size is device
dependent. You should set the tape driver to use the block
size supported by the tape device. Failure to set the block
size correctly will result in an error when the driver
attempts to write a block of the unsupported size. The
default mode for I/O for any magnetic tape (QIC tape, 9-track,
DAT) is for fixed-length blocks of 512 bytes. To change this
default, you should use the tapecntl(1) command.
The tape driver does not support the use of the sar command.
REFERENCES
adsc(7), close(2), dpt(7), ioctl(2), mcis(7), read(2),
sc01(7), sd01(7), sw01(7), tapecntl(1) wd7000(7), write(2)
NOTICES
Using variable-length block mode when writing magnetic tapes
is discouraged because it may not work correctly in releases
before SVR4.2 MP. Magnetic tape should always be written in
fixed-length block mode, even though you are free to change
Copyright 1994 Novell, Inc. Page 6
st01(7) st01(7)
the default fixed-block length from 512 bytes to any other
fixed-block mode the tape drive supports.
If users request a read or write greater than MAXBIOSIZE, the
read or write will fail.
Copyright 1994 Novell, Inc. Page 7