Crate mtio 

Safe Rust bindings for the Linux SCSI tape driver (/dev/st*, /dev/nst*).

Background: how tape differs from disk

Magnetic tape is a sequential-access medium. Unlike a disk, you cannot seek to an arbitrary byte position in O(1); you can only move forward or backward by whole records or filemarks. Writing at any position implicitly discards everything recorded after that point.

Records and tape files

Data is written in records (sometimes called blocks). Each write(2) call to a tape device produces exactly one record on tape; each read(2) call reads at most one record. Records are grouped into tape files separated by filemarks (also called end-of-file marks, or EOF marks). A filemark is a special magnetic pattern that acts as a delimiter; it is written by Tape::write_filemarks and signals read(2) to return zero bytes (just like a regular file EOF).

Positioning

The tape driver tracks position as a (file_number, block_number) pair. You can jump by filemarks with Tape::space_filemarks or by records with Tape::space_records. For coarse positioning, Tape::rewind goes to the absolute beginning (BOT — beginning of tape) and Tape::seek_to_eod goes to the end of all recorded data (EOD).

Logical end of archive

The POSIX and GNU tar convention is to write two consecutive filemarks to signal the logical end of an archive. A reader that encounters two consecutive filemarks knows there is no more archive data. This crate does not enforce this convention but exposes Tape::write_filemarks with a count parameter so callers can write the double filemark easily.

Non-rewinding device nodes

Linux exposes each tape drive as a group of device nodes, most notably:

• /dev/st0, /dev/st1, … — rewinding: the drive rewinds to BOT when the file descriptor is closed.
• /dev/nst0, /dev/nst1, … — non-rewinding: the drive stays at its current position when the file descriptor is closed.

Prefer using the non-rewinding node in multi-file sessions. Using the rewinding node in a multi-file session causes the drive to rewind on the first close(2), silently destroying everything written after the first tape file.

Structure

• Tape — trait implemented by both TapeDevice and MockTape, allowing all higher-level logic to be tested without hardware.
• TapeDevice — wraps a real tape device file; Linux only.
• MockTape — in-memory tape simulation for unit tests; available under the mock feature or in #[cfg(test)] contexts.

Non-rewinding devices

TapeDevice does not implicitly rewind on open or drop; positioning is entirely caller-controlled.

Re-exports

pub use error::TapeError;

pub use status::DriveType;

pub use status::StatusFlags;

pub use status::TapeStatus;

pub use device::TapeDevice;

pub use mock::MockTape;

Modules

device

TapeDevice — a safe wrapper around a Linux tape device file.

error

Error type returned by all tape operations.

mock

MockTape — an in-memory tape simulation for unit testing.

status

Drive status and flag types returned by Tape::status.

Enums

EraseMode

Selects between a short and a long physical erase for Tape::erase.

Constants

MTBSF

Backward space over mt_count filemarks (positions before the FM).

MTBSFM

Backward space mt_count filemarks, leave tape positioned at the FM itself (not after it, unlike MTBSF).

MTBSR

Backward space over mt_count records.

MTBSS

Backward space over mt_count setmarks.

MTCOMPRESSION

Enable or disable hardware data compression. mt_count = 1 enables, mt_count = 0 disables.

MTEOM

Seek to the end of recorded data (EOD). mt_count is ignored.

MTERASE

Erase the tape from the current position to EOT.

MTFSF

Forward space over mt_count filemarks (positions after the FM).

MTFSFM

Forward space mt_count filemarks, leave tape positioned at the FM itself.

MTFSR

Forward space over mt_count records.

MTFSS

Forward space over mt_count setmarks.

MTLOAD

Issue a SCSI LOAD command (instruct the drive to load the cartridge).

MTLOCK

Lock the drive door to prevent accidental ejection.

MTMKPART

Format the tape with partitions. mt_count encodes the partition sizes; see the drive manual and linux/mtio.h for the encoding. Destructive.

MTNOP

No-op: update the status registers only. Useful to refresh MTIOCGET without moving the tape.

MTOFFL

Rewind and take the drive offline (eject). mt_count is ignored.

MTRETEN

Re-tension the tape (wind to EOT and back to BOT to reduce wear).

MTREW

Rewind to beginning of tape. mt_count is ignored.

MTSEEK

Seek to the logical block number given in mt_count.

MTSETBLK

Set the fixed block (record) size. mt_count is the size in bytes; pass 0 for variable-length mode.

MTSETDENSITY

Set the tape density code. Consult the drive manual for valid values.

MTSETDRVBUFFER

Configure st driver options and SCSI mode parameters. Requires root. mt_count must be composed from the MT_ST_* bitmask constants below.

MTSETPART

Select the active tape partition. mt_count is the partition number. Requires the drive to have been formatted with partitions via MTMKPART.

MTUNLOAD

Issue a SCSI UNLOAD command (rewind and eject the cartridge).

MTUNLOCK

Unlock the drive door.

MTWEOF

Write mt_count end-of-file marks (filemarks) at the current position.

MTWEOFI

Write mt_count filemarks immediately (without waiting for drive confirmation). Faster than MTWEOF but the filemark may not be committed if the system crashes before the drive finishes. Requires drive support.

MTWSM

Write mt_count setmarks at the current position.

MT_ST_ASYNC_WRITES

Use asynchronous writes (driver returns immediately; errors reported later).

MT_ST_AUTO_LOCK

Automatically lock the drive door when the device is opened.

MT_ST_BOOLEANS

Set all boolean flags to the values specified in the lower bits (flags not included in the mask are cleared).

MT_ST_BUFFER_WRITES

Buffer write operations in the driver (write returns before data reaches tape).

MT_ST_CAN_BSR

Drive can backspace over records (enables MTBSR).

MT_ST_CAN_PARTITIONS

Drive supports tape partitions (required before using MTSETPART/MTMKPART).

MT_ST_CLEARBOOLEANS

Clear only the boolean flags included in the lower bits (others unchanged).

MT_ST_DEBUGGING

Enable driver debug output (kernel must be compiled with ST_DEBUGGING).

MT_ST_DEF_BLKSIZE

Set the default fixed block size (lower bits = size in bytes; 0 = variable).

MT_ST_DEF_OPTIONS

Set miscellaneous default options (density, compression, block size together).

MT_ST_DEF_WRITES

Interpret O_WRONLY opens as a request to write from the current position (default writes mode for the device).

MT_ST_FAST_MTEOM

Use the fast seek-to-EOD path (MTEOM ioctl) rather than spacing filemarks.

MT_ST_NOWAIT

Return immediately (rather than waiting) when the drive is not ready.

MT_ST_NOWAIT_EOF

Do not wait for the drive to report EOF; return immediately at filemark.

MT_ST_NO_BLKLIMS

Drive does not report block size limits (skip READ BLOCK LIMITS command).

MT_ST_OPTIONS

Mask covering the option group bits.

MT_ST_READ_AHEAD

Enable read-ahead buffering.

MT_ST_SCSI2LOGICAL

Use SCSI-2 logical block addressing for seek/tell operations.

MT_ST_SETBOOLEANS

Set only the boolean flags included in the lower bits (others unchanged).

MT_ST_SET_CLN

Configure the cleaning request threshold reported via status flags.

MT_ST_SET_LONG_TIMEOUT

Set the long SCSI command timeout used for rewind/erase (lower bits = seconds).

MT_ST_SET_TIMEOUT

Set the normal SCSI command timeout (lower bits = seconds).

MT_ST_SILI

Suppress the Incorrect Length Indicator (SILI) for variable-block reads.

MT_ST_SYSV

Use System V semantics: rewind on the last close of a non-rewinding node.

MT_ST_TWO_FM

Write two filemarks when the device is closed after a write, rather than one.

MT_ST_WRITE_THRESHOLD

Set the write-buffer threshold (lower bits = threshold in kB).

Traits

Tape

Operations common to all tape devices.