Crate qcow

A library for working with qcow (version 1, 2, and 3) files.

Example

// open qcow
let qcow = qcow::open(PATH).unwrap();

// print out list of snapshots in the qcow
for snapshot in qcow.snapshots() {
    println!(
        "Snapshot {:?}: {:?} (size = {})",
        snapshot.unique_id,
        snapshot.name,
        snapshot.vm_state_size
    );
}

// create a reader for accessing the virtual hard disk
let mut file = BufReader::new(File::open(PATH)?);
let qcow2 = qcow.unwrap_qcow2();
let mut reader = qcow2.reader(&mut file);

// read the first 10 bytes of the virtual hard disk
let mut buf = [0; 10];
reader.read_exact(&mut buf)?;

Important types/functions

• Retrieving a qcow - open (from path), load (from reader), load_from_memory (from slice)
• Converting to qcow2 - DynamicQcow::unwrap_qcow2
• Reading from a virtual hard disk - Qcow2::reader (returns Reader, which implements Read + Seek)

Features

• Parse qcow files
• Full qcow version 1 support
  • Support for parsing the header and some associated data
• Full qcow version 2-3 support
  • Header parsing, including extra version 3 header data
  • Header extension parsing, allowing you to use addition data they provide
  • Lookup table (L1 and L2) parsing, only loading L2 tables on demand
  • Snapshot parsing, including snapshot L1 lookup tables
  • Support for reading the contents of the virtual disk
    • Includes compression support (for both zlib and zstd)
    • Cluster lookup caching, backtracking on cache miss
    • Allows arbitrary seeking within the guest

Modules

• header_ext
  Module for types pertaining to QCOW header extensions
• levels
  Types used for parsing the 2-level indexing of clusters that allows qcow to sparsely store virtual drive contents.
• v1
  Module containing structs specific to the legacy QCOW v1 format

Structs

• AutoClearFeatures
  Bitmask of auto-clear features. An implementation may only write to an image with unknown auto-clear features if it clears the respective bits from this field first.
• CompatibleFeatures
  Bitmask of compatible features. An implementation can safely ignore any unknown bits that are set.
• IncompatibleFeatures
  Bitmask of incompatible features. An implementation must fail to open an image if an unknown bit is set.
• Qcow1
  Parsed representation of a v1 qcow file (legacy)
• Qcow2
  Parsed representation of a qcow2 file.
• QcowHeader
  Top-level header of Qcow format
• Reader
  A reader for reading from the guest virtual drive. Should be constructed using Qcow2::reader.
• Snapshot
  An entry in the snapshot table representing the system state at a moment in time
• SnapshotExtraData
  Optional extra snapshot data that comes from format updates
• SnapshotTime
  Represents the time a snapshot was taken in the form of seconds, nanoseconds. The nanoseconds represent the sub-second time of the snapshot.
• Version3Header
  Part of header only present in Qcow version 3

Enums

• CompressionType
  Compression type used for compressed clusters.
• DynamicQcow
  An enum representing a qcow of any version
• EncryptionMethod
  Encryption method (if any) to use for image contents.
• Error
  An error encountered by the qcow crate from either a parsing failure or an I/O error.

Functions

• load
  Read a qcow or qcow2 file from a reader
• load_from_memory
  Read a qcow or qcow2 file from a slice
• open
  Open a qcow or qcow2 file from a path