Why apfs?

apfs is a standalone pure-Rust library for reading APFS filesystems with full B-tree traversal and object map resolution.

* Only byteorder and thiserror — no compression, no FFI, no system libs.

Features

Format Support

Quick Start

Open and Browse

use apfs::ApfsVolume;
use std::fs::File;
use std::io::BufReader;

let file = File::open("container.raw")?;
let mut vol = ApfsVolume::open(BufReader::new(file))?;

// Volume info
let info = vol.volume_info();
println!("{}: {} files, {} dirs", info.name, info.num_files, info.num_directories);

// List root directory
for entry in vol.list_directory("/")? {
    println!("{:?} {:>12} {}", entry.kind, entry.size, entry.name);
}

Read a File

// Read into memory
let data = vol.read_file("/Applications/Upscayl.app/Contents/Info.plist")?;

// Or stream to a writer (low memory)
let mut out = File::create("Info.plist")?;
vol.read_file_to("/Applications/Upscayl.app/Contents/Info.plist", &mut out)?;

Walk Entire Filesystem

for entry in vol.walk()? {
    if entry.entry.kind == apfs::EntryKind::File {
        println!("{}: {} bytes", entry.path, entry.entry.size);
    }
}

Streaming File Access

use std::io::Read;

let mut reader = vol.open_file("/large-file.bin")?;
let mut buf = [0u8; 4096];
let n = reader.read(&mut buf)?;

File Metadata

let stat = vol.stat("/.DS_Store")?;
println!("Size: {} bytes", stat.size);
println!("Owner: {}:{}", stat.uid, stat.gid);
println!("Mode: 0o{:o}", stat.mode);

Architecture

Container (NXSB)
  ├── Checkpoint descriptor area → latest valid superblock
  ├── Container OMAP → resolves volume OIDs to physical blocks
  └── Volume (APSB)
        ├── Volume OMAP → resolves catalog OIDs to physical blocks
        └── Catalog B-tree (virtual, keyed by OID then type)
              ├── Inodes (type 3) — file/directory metadata
              ├── Xattrs (type 4) — extended attributes
              ├── File extents (type 8) — physical data locations
              └── Directory records (type 9) — name → inode mapping

Modules

Limitations

• Read-only — no write support
• No encryption — cannot read FileVault or per-file encrypted volumes
• No compression — transparent compression (lzvn, lzfse, zlib) not decompressed
• No snapshots — snapshot browsing not implemented
• Single volume — reads only the first volume in a multi-volume container
• No extended attributes — xattr values not exposed through the public API

Next Steps

• Pipeline integration with dpp for DMG → APFS workflows
• Encryption support (FileVault, per-file)
• Compressed extent decompression (lzvn, lzfse, zlib)
• Snapshot browsing
• Multi-volume support
• Extended attribute access

License

MIT