path: root/static/netbsd/man4/st.4 3.html

<table class="head">
  <tr>
    <td class="head-ltitle">ST(4)</td>
    <td class="head-vol">Device Drivers Manual</td>
    <td class="head-rtitle">ST(4)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">st</code> &#x2014; <span class="Nd">SCSI/ATAPI
    tape driver</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Cd">st* at scsibus? target ? lun ?</code>
  <br/>
  <code class="Cd">st1 at scsibus0 target 4 lun 0</code>
  <br/>
  <code class="Cd">st* at atapibus? drive ? flags 0x0000</code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">st</code> driver provides support for SCSI
    and Advanced Technology Attachment Packet Interface (ATAPI) tape drives. It
    allows a tape drive to be run in several different modes depending on minor
    numbers and supports several different &#x2018;sub-modes&#x2019;. The device
    can have both a
    <a class="permalink" href="#raw"><i class="Em" id="raw">raw</i></a>
    interface and a
    <a class="permalink" href="#block"><i class="Em" id="block">block</i></a>
    interface; however, only the raw interface is usually used (or
  recommended).</p>
<p class="Pp">SCSI and ATAPI devices have a relatively high level interface and
    talk to the system via a SCSI or ATAPI adapter and a SCSI or ATAPI adapter
    driver (e.g. <a class="Xr">ahc(4)</a>, <a class="Xr">pciide(4)</a>). A SCSI
    or ATAPI adapter must also be separately configured into the system before a
    SCSI or ATAPI tape can be configured.</p>
<p class="Pp" id="Sequential">As the SCSI or ATAPI adapter is probed during
    boot, the SCSI or ATAPI bus is scanned for devices. Any devices found which
    answer as
    &#x2018;<a class="permalink" href="#Sequential"><i class="Em">Sequential</i></a>&#x2019;
    type devices will be attached to the <code class="Nm">st</code> driver.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="MOUNT_SESSIONS"><a class="permalink" href="#MOUNT_SESSIONS">MOUNT
  SESSIONS</a></h1>
<p class="Pp">The <code class="Nm">st</code> driver is based around the concept
    of a
    &#x201C;<a class="permalink" href="#mount"><i class="Em" id="mount">mount
    session</i></a>&#x201D;, 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 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:</p>
<ol class="Bl-enum">
  <li>Closing an &#x2018;unmount device&#x2019;, referred to as sub-mode 00
      below. An example is <span class="Pa">/dev/rst0</span>.</li>
  <li>Using the <code class="Dv">MTOFFL</code> <a class="Xr">ioctl(2)</a>
      command, reachable through the
      &#x2018;<code class="Cm">offline</code>&#x2019; command of
      <a class="Xr">mt(1)</a>.</li>
  <li>Opening 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).</li>
</ol>
</section>
<section class="Sh">
<h1 class="Sh" id="MODES_AND_SUB-MODES"><a class="permalink" href="#MODES_AND_SUB-MODES">MODES
  AND SUB-MODES</a></h1>
<p class="Pp">There are several different &#x2018;operation&#x2019; modes. These
    are controlled by bits 2 and 3 of the minor number and are designed to allow
    users 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 <a class="Xr">mt(1)</a> command. When a device
    corresponding to a particular mode is first mounted, The operating
    parameters for that 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 operation mode. To change the parameters
    for an operation mode, one must compile them into the
    &#x201C;<i class="Em">quirk</i>&#x201D; table in the driver's source
  code.</p>
<p class="Pp">In addition to the operating modes mentioned above, bits 0 and 1
    of the minor number are interpreted as &#x2018;sub-modes&#x2019;. The
    sub-modes differ in the action taken when the device is closed:</p>
<dl class="Bl-tag">
  <dt>00</dt>
  <dd>A close will rewind the device; if the tape has been written, then a file
      mark will be written before the rewind is requested. The device is
      unmounted.</dd>
  <dt>01</dt>
  <dd>A close will leave the tape mounted. If the tape was written to, a file
      mark will be written. No other head positioning takes place. Any further
      reads or writes will occur directly after the last read, or the written
      file mark.</dd>
  <dt>10</dt>
  <dd>A close will rewind the device. If the tape has been written, then a file
      mark will be written before the rewind is requested. On completion of the
      rewind an unload command will be issued. The device is unmounted.</dd>
  <dt>11</dt>
  <dd>This is Control mode, which allows the tape driver to be opened without a
      tape inserted to allow various ioctls (e.g. MTIOCGET or MTIOCTOP to set
      density or blocksize) and raw SCSI command on through. I/O can be done in
      this mode, if desired, with the same rewind/eject behaviour as mode 01.
      This isn't really an 'action taken on close' type of distinction, but this
      seems to be the place to put this mode.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="BLOCKING_MODES"><a class="permalink" href="#BLOCKING_MODES">BLOCKING
  MODES</a></h1>
<p class="Pp">SCSI tapes may run in either
    &#x2018;<a class="permalink" href="#variable"><i class="Em" id="variable">variable</i></a>&#x2019;
    or
    &#x2018;<a class="permalink" href="#fixed"><i class="Em" id="fixed">fixed</i></a>&#x2019;
    block-size modes. Most QIC-type devices run in fixed block-size mode, where
    most nine-track tapes and many new cartridge formats allow variable
    block-size. The difference between the two is as follows:</p>
<dl class="Bl-inset">
  <dt id="part">Variable block-size</dt>
  <dd>Each write made to the device results in a single logical record written
      to the tape. One can never read or write
      <a class="permalink" href="#part"><i class="Em">part</i></a> of a record
      from tape (though you may request a larger block and read a smaller
      record); nor can one read multiple blocks. 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 (usually between
      1 byte and 64 Kbytes, sometimes more).
    <p class="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 file mark, but it
        was never read, then the next process to read will immediately hit the
        file mark and receive an end-of-file notification.</p>
  </dd>
  <dt>Fixed block-size</dt>
  <dd>Data written by the user is passed to the tape as a succession of fixed
      size blocks. It may be contiguous in memory, but it is considered to be a
      series of independent blocks. One may never write an amount of data that
      is not an exact multiple of the blocksize. One may read and write the same
      data as a different set of records, In other words, blocks that were
      written together may be read separately, and vice-versa.
    <p class="Pp">If one requests more blocks than remain in the file, the drive
        will encounter the file mark. Because there is some data to return
        (unless there were no records before the file mark), the read will
        succeed, returning that data. The next read will return immediately with
        an EOF (as above, if the file mark is never read, it remains for the
        next process to read if in no-rewind mode).</p>
  </dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="FILE_MARK_HANDLING"><a class="permalink" href="#FILE_MARK_HANDLING">FILE
  MARK HANDLING</a></h1>
<p class="Pp">The handling of file marks on write is automatic. If the user has
    written to the tape, and has not done a read since the last write, then a
    file mark will be written to the tape when the device is closed. If a rewind
    is requested after a write, then the driver assumes that the last file on
    the tape has been written, and ensures that there are two file marks written
    to the tape. 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 file marks to tape, but when read, report a
    &#x2018;phantom&#x2019; file mark 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 determined
    yet, and they are treated as separate behaviors by the driver at this
  time).</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EOM_HANDLING"><a class="permalink" href="#EOM_HANDLING">EOM
  HANDLING</a></h1>
<p class="Pp">Attempts to write past EOM and how EOM is reported are handled
    slightly differently based upon whether EARLY WARNING recognition is enabled
    in the driver.</p>
<p class="Pp">If EARLY WARNING recognitions is <i class="Em">not</i> enabled,
    then detection of EOM (as reported in SCSI Sense Data with an EOM indicator)
    causes the write operation to be flagged with I/O error (EIO). This has the
    effect for the user application of not knowing actually how many bytes were
    read (since the return of the <a class="Xr">read(2)</a> system call is set
    to &#x2212;1).</p>
<p class="Pp" id="is">If EARLY WARNING recognition
    <a class="permalink" href="#is"><i class="Em">is</i></a> enabled, then
    detection of EOM (as reported in SCSI Sense Data with an EOM indicator) has
    no immediate effect except that the driver notes that EOM has been detected.
    If the write completing didn't transfer all data that was requested, then
    the residual count (counting bytes <i class="Em">not</i> written) is
    returned to the user application. In any event, the next attempt to write
    (if that is the next action the user application takes) is immediately
    completed with no data transferred, and a residual returned to the user
    application indicating that no data was transferred. This is the traditional
    UNIX EOF indication. The state that EOM had been seen is then cleared.</p>
<p class="Pp">In either mode of operation, the driver does not prohibit the user
    application from writing more data, if it chooses to do so. This will
    continue up until the physical end of media, which is usually signalled
    internally to the driver as a CHECK CONDITION with the Sense Key set to
    VOLUME OVERFLOW. When this or any otherwise unhandled error occurs, an error
    return of EIO will be transmitted to the user application. This does indeed
    mean that if EARLY WARNING is enables and the device continues to set EOM
    indicators prior to hitting physical end of media, that an indeterminate
    number of 'short write returns' as described in the previous paragraph will
    occur. However, the expected user application behaviour (in common with
    other systems) is to close the tape and rewind and request another tape upon
    the receipt of the first EOM indicator, possibly after writing one trailer
    record.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="KERNEL_CONFIGURATION"><a class="permalink" href="#KERNEL_CONFIGURATION">KERNEL
  CONFIGURATION</a></h1>
<p class="Pp">Because different tape drives behave differently, there is a
    mechanism within the source to <code class="Nm">st</code> to quickly and
    conveniently recognize and deal with brands and models of drive that have
    special requirements.</p>
<p class="Pp">There is a table (called the &#x201C;<i class="Em">quirk
    table</i>&#x201D;) in which the identification strings of known errant
    drives can be stored. Alongside each is a set of flags that allows the
    setting of densities and blocksizes for each of the 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 recognized.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="IOCTLS"><a class="permalink" href="#IOCTLS">IOCTLS</a></h1>
<p class="Pp">The following <a class="Xr">ioctl(2)</a> calls apply to SCSI
    tapes. Some also apply to other tapes. They are defined in the header file
    <code class="In">&lt;<a class="In">sys/mtio.h</a>&gt;</code>.</p>
<dl class="Bl-tag">
  <dt id="MTIOCGET"><a class="permalink" href="#MTIOCGET"><code class="Dv">MTIOCGET</code></a></dt>
  <dd>(<code class="Li">struct mtget</code>) Retrieve the status and parameters
      of the tape. Error status and residual is unlatched and cleared by the
      driver when it receives this ioctl.</dd>
  <dt id="MTIOCTOP"><a class="permalink" href="#MTIOCTOP"><code class="Dv">MTIOCTOP</code></a></dt>
  <dd>(<code class="Li">struct mtop</code>) Perform a multiplexed operation. The
      argument structure is as follows:
    <div class="Bd Pp Bd-indent Li">
    <pre>struct mtop {
	short	mt_op;
	daddr_t	mt_count;
};</pre>
    </div>
    <p class="Pp">The following operation values are defined for
        <var class="Va">mt_op</var>:</p>
    <dl class="Bl-tag">
      <dt id="MTWEOF"><a class="permalink" href="#MTWEOF"><code class="Dv">MTWEOF</code></a></dt>
      <dd>Write <var class="Va">mt_count</var> end of file marks at the present
          head position.</dd>
      <dt id="MTFSF"><a class="permalink" href="#MTFSF"><code class="Dv">MTFSF</code></a></dt>
      <dd>Skip over <var class="Va">mt_count</var> file marks. Leave the head on
          the EOM side of the last skipped file mark.</dd>
      <dt id="MTBSF"><a class="permalink" href="#MTBSF"><code class="Dv">MTBSF</code></a></dt>
      <dd>Skip
          <a class="permalink" href="#backwards"><i class="Em" id="backwards">backwards</i></a>
          over <var class="Va">mt_count</var> file marks. Leave the head on the
          BOM (beginning of media) side of the last skipped file mark.</dd>
      <dt id="MTFSR"><a class="permalink" href="#MTFSR"><code class="Dv">MTFSR</code></a></dt>
      <dd>Skip forwards over <var class="Va">mt_count</var> records.</dd>
      <dt id="MTBSR"><a class="permalink" href="#MTBSR"><code class="Dv">MTBSR</code></a></dt>
      <dd>Skip backwards over <var class="Va">mt_count</var> records.</dd>
      <dt id="MTREW"><a class="permalink" href="#MTREW"><code class="Dv">MTREW</code></a></dt>
      <dd>Rewind the device to the beginning of the media.</dd>
      <dt id="MTOFFL"><a class="permalink" href="#MTOFFL"><code class="Dv">MTOFFL</code></a></dt>
      <dd>Rewind the media (and, if possible, eject). Even if the device cannot
          eject the media it will often no longer respond to normal
        requests.</dd>
      <dt id="MTNOP"><a class="permalink" href="#MTNOP"><code class="Dv">MTNOP</code></a></dt>
      <dd>No-op; set status only.</dd>
      <dt id="MTERASE"><a class="permalink" href="#MTERASE"><code class="Dv">MTERASE</code></a></dt>
      <dd>Erase the media from current position. If the field
          <var class="Va">mt_count</var> is nonzero, a full erase is done (from
          current position to end of media). If <var class="Va">mt_count</var>
          is zero, only an erase gap is written. It is hard to say which drives
          support only one but not the other option</dd>
      <dt id="MTCACHE"><a class="permalink" href="#MTCACHE"><code class="Dv">MTCACHE</code></a></dt>
      <dd>Enable controller buffering.</dd>
      <dt id="MTNOCACHE"><a class="permalink" href="#MTNOCACHE"><code class="Dv">MTNOCACHE</code></a></dt>
      <dd>Disable controller buffering.</dd>
      <dt id="MTSETBSIZ"><a class="permalink" href="#MTSETBSIZ"><code class="Dv">MTSETBSIZ</code></a></dt>
      <dd>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 the device was opened in
          Control Mode (in which case this set value persists until a
        reboot).</dd>
      <dt id="MTSETDNSTY"><a class="permalink" href="#MTSETDNSTY"><code class="Dv">MTSETDNSTY</code></a></dt>
      <dd>Set the density value (see <a class="Xr">mt(1)</a>) to use when
          running in the mode opened (minor bits 2 and 3). This parameter is in
          effect for the present mount session only, unless the device was
          opened in Control Mode (in which case this set value persists until a
          reboot). Any byte sized value may be specified. Note that only a very
          small number of them will actually usefully work. The rest will cause
          the tape drive to spit up.</dd>
      <dt id="MTCMPRESS"><a class="permalink" href="#MTCMPRESS"><code class="Dv">MTCMPRESS</code></a></dt>
      <dd>Enable or disable tape drive data compression. Typically tape drives
          will quite contentedly ignore settings on reads, and will probably
          keep you from changing density for writing anywhere but BOT.</dd>
      <dt id="MTEWARN"><a class="permalink" href="#MTEWARN"><code class="Dv">MTEWARN</code></a></dt>
      <dd>Enable or disable EARLY WARNING at EOM behaviour (using the count as a
          boolean value).</dd>
    </dl>
  </dd>
  <dt id="MTIOCRDSPOS"><a class="permalink" href="#MTIOCRDSPOS"><code class="Dv">MTIOCRDSPOS</code></a></dt>
  <dd>(<code class="Li">uint32_t</code>) Read device logical block position. Not
      all drives support this option.</dd>
  <dt id="MTIOCRDHPOS"><a class="permalink" href="#MTIOCRDHPOS"><code class="Dv">MTIOCRDHPOS</code></a></dt>
  <dd>(<code class="Li">uint32_t</code>) Read device hardware block position.
      Not all drives support this option.</dd>
  <dt id="MTIOCSLOCATE"><a class="permalink" href="#MTIOCSLOCATE"><code class="Dv">MTIOCSLOCATE</code></a></dt>
  <dd>(<code class="Li">uint32_t</code>) Position the tape to the specified
      device logical block position.</dd>
  <dt id="MTIOCHLOCATE"><a class="permalink" href="#MTIOCHLOCATE"><code class="Dv">MTIOCHLOCATE</code></a></dt>
  <dd>(<code class="Li">uint32_t</code>) Position the tape to the specified
      hardware block position. Not all drives support this option.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<dl class="Bl-tag Bl-compact">
  <dt><span class="Pa">/dev/[n][e]rst[0-9]</span></dt>
  <dd>general form:</dd>
  <dt><span class="Pa">/dev/rst0</span></dt>
  <dd>Mode 0, Rewind on close</dd>
  <dt><span class="Pa">/dev/nrst0</span></dt>
  <dd>Mode 1, No rewind on close</dd>
  <dt><span class="Pa">/dev/erst0</span></dt>
  <dd>Mode 2, Eject on close (if capable)</dd>
  <dt><span class="Pa">/dev/enrst0</span></dt>
  <dd>Mode 3, Control Mode (elsewise like mode 0)</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<p class="Pp"><a class="Xr">mt(1)</a>, <a class="Xr">intro(4)</a>,
    <a class="Xr">mtio(4)</a>, <a class="Xr">scsi(4)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">This <code class="Nm">st</code> driver was originally written for
    Mach 2.5 by Julian Elischer, and was ported to
    <span class="Ux">NetBSD</span> by Charles Hannum. This man page was edited
    for <span class="Ux">NetBSD</span> by Jon Buller.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">The selection of compression could possibly also be usefully done
    as with a minor device bit.</p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">August 23, 1996</td>
    <td class="foot-os">NetBSD 10.1</td>
  </tr>
</table>