Crate dwarfs

A library for reading DwarFS archives (aka. images).

Currently, DwarFS filesystem version 2.3..=2.5 is supported, which should be compatible with files generated by upstream mkdwarfs v0.5.0..=v0.12.4 (latest at the time of writing). Other versions may also be readable but are not guaranteed.

use dwarfs::{Archive, ArchiveIndex, AsChunks};
use std::fs::File;

// Open an archive file and load the metadata of it.
let file = File::open("./my.dwarfs")?;
let (index, mut archive) = Archive::new(file)?;

// Hierarchy traversal.
for entry in index.root().entries() {
    let inode = entry.inode();
    println!("/{} mode={}", entry.name(), inode.metadata().file_type_mode());
    if let Some(deep) = inode.as_dir() {
        for entry in deep.entries() {
            // ...
        }
    }
}

// Resolve paths.
let file: dwarfs::File = index.get_path(["src", "Cargo.toml"])
    .expect("does not exist")
    .as_file()
    .expect("not a file");
// The simple way to read content.
let bytes: Vec<u8> = file.read_to_vec(&mut archive)?;

Cargo features

• zstd, lzma, lz4 (Only zstd is enabled by default)

  Enable relevant decompression algorithm support. zstd is the default compression algorithm mkdwarfs uses and it should be enough for most cases.

• log (Enabled by default)

  Enable trace-level logging and time measurement for internal events via log crate. Useful for profiling or debugging. Should not have performance penalty unless trace-level log is enabled.

• serialize (Disabled by default)

  Enable serialization support for various structures. It enables:

  • [metadata::Schema::to_bytes]
  • [metadata::Metadata::to_schema_and_bytes]
  • [fsst::to_bytes]

Re-exports

pub extern crate positioned_io;

pub extern crate zerocopy;

Modules

archive

The high-level interface for accessing a DwarFS archive.

fsst

The Fast Static Symbol Table (FSST) decoder for compressed string tables StringTable::symtab.

metadata

The low-level metadata structures and parsers.

section

The low-level module for accessing sections in a DwarFS archive.

Structs

Archive

A DwarFS archive wrapping reader R.

ArchiveIndex

The index of a DwarFS archive representing the whole hierarchy.

Device

A character or block device inode.

Dir

A directory inode.

DirEntry

An entry in a directory.

Error

An error raised from parsing or accessing Archive.

File

A regular file inode.

Inode

A generic inode.

InodeMetadata

The metadata of an inode.

Ipc

A pipe or socket inode.

Symlink

A symlink inode.

Enums

InodeKind

An inode, classified by its kind.

Constants

SUPPORTED_VERSION_RANGE

The range of filesystem version tuple (major, minor) supported by this library.

Traits

AsChunks

Trait for data-bearing objects, notably Files and Chunks.

Type Aliases

Result

Type alias using Error as the default error type.