rustar 0.1.4 - Docs.rs

What is rustar?

RUSTAR (Rust + USTAR) is a minimal, safe (hopefully), and #![no_std]-friendly library for parsing USTAR archives.
It is designed primarily for Rust-Based OS development, in the case one might bundle their kernel modules, init programs, or resources in a .tar and extract them at runtime (for an initramfs kinda thing)

Why use rustar for an OS?

Using RUSTAR as your filesystem format handler has some big advantages:

Zero external deps: Works in #![no_std], requires only alloc if you need owned Vec<u8>.
Cross-tested: Same code works on bare metal (e.g your OS kernel) and on Linux/Win with cargo test.

Features

purely rust based
#![no_std] compatible
iterator function (TarIter) to walk over headers
zero-mem-copy file lookup (tar_lookup)
(optional) owned extraction (extract_file)
Tested with standard tar --format=ustar archives

Example in OS kernel

This is an example implementation for it in an OS kernel, so same rules apply to a basic no_std environment:

for header in rustar::TarIter::new(archive) {
    println!("file: {} ({} bytes)", header.name, header.size);
}

if let Some(init_bin) = rustar::extract_file(archive, "init.bin") {
    // load and run init program…
}

Example (testing on Linux)

You can include a tar file directly in your unit tests (this is the included unit test):

#[test]
fn test_extract_file() {
    let archive: &[u8] = include_bytes!("../tests/sample.tar");
    let file = rustar::extract_file(archive, "hello.txt")
        .expect("file not found");

    assert_eq!(file, b"Hello World!\n");
}

Create an (already provided) test tar with:

echo "Hello World!" > hello.txt

tar --format=ustar -cf tests/sample.tar hello.txt

Run tests:

cargo test

Roadmap

Add write support (create tar archives in no_std) , although i may already switch over my OS to fat12 or something by then
Expose a safe TarHeader::contents(&self, archive: &[u8]) helper
Support reading from block devices instead of memory slices (this would make life much easier but im lazy)

License

this project uses the MIT License, in full effect. give me credit via name/username :3 (if you want)

Brought to you by your favourite puppygirl Liz 🐾