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