Crate hadris_fat 

hadris-fat

A pure Rust, no_std-compatible library for reading, writing, and formatting FAT12, FAT16, and FAT32 filesystems, plus an opt-in unstable exFAT preview. It is suitable for disk-image tools, bootloaders, kernels, firmware, embedded devices, SD cards, and USB drives.

Quick Start

use std::fs::File;
use hadris_fat::sync::FatVolume;

let file = File::open("disk.img").unwrap();
let fs = FatVolume::open(file).unwrap();
let root = fs.root_dir();
let mut iter = root.entries();
while let Some(Ok(entry)) = iter.next_entry() {
    println!("{}", entry.name());
}

Builder: custom providers and FAT caching

FatVolume::builder configures the clock and OEM-codepage providers — and, with the cache feature, an LRU FAT-sector cache — before mounting:

use hadris_fat::sync::FatVolume;
use std::fs::OpenOptions;

let disk = OpenOptions::new()
    .read(true)
    .write(true)
    .open("disk.img")
    .unwrap();
let fs = FatVolume::builder(disk)
    .fat_cache(16)
    .open()
    .unwrap();

// Normal FatVolume operations use the installed cache transparently.
let _root = fs.root_dir();

// After cached writes, flush before dropping the volume.
fs.flush().unwrap();

Without cache, omit .fat_cache(...). A zero capacity also disables the cache. The cache is sync-only; async operations access the FAT directly. See FatVolumeBuilder.

Feature Flags

Feature	Default	Description
std	Yes	Standard library support (enables alloc and chrono clock)
alloc	No	Heap allocation without full std
sync	No	Synchronous API via hadris-io sync traits
async	No	Asynchronous API via hadris-io async traits
read	Yes	Read operations
write	Yes	Write operations (requires alloc + read)
lfn	Yes	Long filename (VFAT) support
cache	No	FAT sector caching for reduced I/O
tool	No	Analysis and diagnostic utilities
unstable-exfat	No	Unstable, sync-only exFAT preview

Known Limitations

• async + cache: The FAT-sector cache is sync-only; async operations access the FAT directly.
• exFAT: The unstable-exfat preview is outside the V2 API stability promise and is not recommended for irreplaceable data. It is sync-only and does not support fragmented allocation bitmap / upcase metadata, directory growth, general cross-cluster entry-set placement, TexFAT, or repair workflows. Enable the preview and see the exfat module for its qualified scope.

Dual Sync/Async Architecture

This crate provides both synchronous and asynchronous APIs through a compile-time code transformation system. The same implementation source is compiled twice:

• sync module: synchronous API (enabled by sync feature)
• async module: asynchronous API (enabled by async feature)

std does not select an I/O mode. The default feature set enables sync explicitly, and synchronous API types are re-exported at the crate root whenever sync is enabled.

Modules

• error — Error types for FAT operations
• file — Short filename (8.3) types and validation
• raw — On-disk structures: boot sector, BPB, directory entries
• sync::fs — Filesystem handle and metadata
• sync::dir — Directory iteration and entry types
• sync::read — Read extension trait for file content
• sync::write — Write extension trait for file modification
• sync::fat_table — FAT table access (FAT12/16/32)
• sync::cache — Optional FAT sector caching
• sync::format — Filesystem formatting (requires write)
• sync::tool — Analysis and verification (requires tool)

Re-exports

pub use error::Error;

pub use error::Result;

pub use sync::*;

Modules

async

Asynchronous FAT filesystem API.

error

Error types for the hadris-fat crate.

file

FAT filename types, including 8.3 and long-file-name helpers.

oem

OEM code page conversion for short (8.3) filenames.

raw

Raw on-disk FAT structures and attribute flags.

sync

Synchronous FAT filesystem API.

time

Time / date types and the TimeProvider trait.