Crate hadris_cpio 

Hadris CPIO

A Rust implementation of the CPIO archive format (newc/SVR4) with support for no-std environments, streaming reads, and archive creation from in-memory trees or the host filesystem.

CPIO archives are commonly used for Linux initramfs images, RPM packages, and general-purpose file archiving. This crate supports the “new” (newc) ASCII format (070701) and its CRC variant (070702), which are the formats used by modern Linux tools.

Quick Start

Reading an Archive

use std::fs::File;
use std::io::BufReader;
use hadris_cpio::CpioArchiveReader;

let file = File::open("archive.cpio").unwrap();
let mut reader = CpioArchiveReader::new(BufReader::new(file));

while let Some(entry) = reader.next_entry_alloc().unwrap() {
    let name = entry.name_str().unwrap();
    println!("{} ({} bytes)", name, entry.file_size());
    reader.skip_entry_data_owned(&entry).unwrap();
}

Creating an Archive

use std::fs::File;
use std::io::BufWriter;
use hadris_cpio::{CpioArchiveWriter, CpioWriteOptions, FileTree};

let tree = FileTree::from_fs(std::path::Path::new("./my-directory")).unwrap();
let out = BufWriter::new(File::create("archive.cpio").unwrap());
let _out = CpioArchiveWriter::new(out, CpioWriteOptions::default())
    .finish(&tree)
    .unwrap();

Feature Flags

Feature	Description	Dependencies
read	Streaming archive reader	None
alloc	Heap allocation without full std	alloc crate
std	Full standard library support	std, alloc
sync	Synchronous archive API	hadris-io/sync
async	Asynchronous archive API	hadris-io/async
write	Archive creation	alloc, read

Default features: std, sync, read, write

std does not select an I/O mode. Custom configurations should enable sync, async, or both explicitly.

For Bootloaders / Kernels (minimal footprint)

[dependencies]
hadris-cpio = { version = "2.1.0", default-features = false, features = ["read", "sync"] }

For Kernels with Heap (no-std + alloc)

[dependencies]
hadris-cpio = { version = "2.1.0", default-features = false, features = ["read", "alloc", "sync"] }

For Desktop Applications (full features)

[dependencies]
hadris-cpio = "2.1.0"

Archive Format

The newc format stores entries sequentially. Each entry consists of:

1. A 110-byte ASCII header (all numeric fields in uppercase hex)
2. The filename (NUL-terminated, padded to 4-byte boundary)
3. The file data (padded to 4-byte boundary)

The archive ends with a special TRAILER!!! sentinel entry.

Two magic numbers are supported:

• 070701 — Standard newc format
• 070702 — newc with per-file CRC checksums

Architecture

• error — Error types and result alias
• header — Raw 110-byte header parsing and construction
• entry — Decoded entry header with typed fields
• mode — Unix file type extraction from mode bits
• read — Streaming archive reader (CpioArchiveReader)
• write — Archive writer and in-memory file tree

Specification References

• cpio(5) man page — newc format definition
• Linux kernel usr/gen_init_cpio.c — Reference implementation
• RPM file format specification — CPIO payload format

Re-exports

pub use error::Error;

pub use error::Result;

pub use mode::FileType;

pub use sync::*;sync

Modules

asyncasync

Asynchronous CPIO archive API.

error

Error types for CPIO operations.

mode

Unix file type constants and mode bit manipulation.

syncsync

Synchronous CPIO archive API.