Struct FatVolume 

pub struct FatVolume<DATA: Seek> { /* private fields */ }

A mounted FAT filesystem backed by a seekable data source.

Implementations

impl<DATA: Seek> FatVolume<DATA>

pub fn into_inner(self) -> DATA

Consumes the filesystem handle and returns its underlying data source.

impl<DATA> FatVolume<DATA>

where DATA: Read + Seek,

Implementations for Read APIs

pub fn open(data: DATA) -> Result<Self>

Open a FAT filesystem from a data source with default providers.

Automatically detects FAT12, FAT16, or FAT32 based on the BPB fields. Uses crate::time::DEFAULT_TIME_PROVIDER and crate::oem::DEFAULT_OEM_CONVERTER; for custom providers use FatVolume::builder.

pub fn builder(data: DATA) -> FatVolumeBuilder<DATA>

Start a FatVolumeBuilder for advanced configuration (custom clock, codepage, etc.).

pub fn time_provider(&self) -> &dyn TimeProvider

Borrow the configured clock used for new directory-entry timestamps.

pub fn oem_converter(&self) -> &dyn OemCpConverter

Borrow the configured OEM codepage converter for short (8.3) names.

pub fn fat(&self) -> &Fat

Borrow the FAT table descriptor.

Required when constructing a CachedFat (with the cache feature) via CachedFat::new, which needs the FAT type and max-cluster bound. Otherwise rarely needed by callers — most FAT operations go through FatVolume methods directly.

pub fn root_dir(&self) -> FatDir<'_, DATA>

Returns the filesystem’s root directory.

pub fn fat_type(&self) -> FatType

Get the FAT type of this filesystem

pub fn volume_info(&self) -> &VolumeInfo

Get volume metadata from the boot sector.

This includes the OEM name, volume serial number, volume label, and filesystem type string.

pub fn read_status_flags(&self) -> Result<FsStatusFlags>

Read the FAT-resident volume status flags from FAT[1].

dirty means the volume was not unmounted cleanly; io_errors means the previous host saw I/O failures. FAT12 has no status bits, so the returned flags are always false for FAT12 — check Self::fat_type if that distinction matters to your caller.

pub fn read_root_label(&self) -> Result<Option<[u8; 11]>>

Read the volume label from the root directory entry, if present.

Two volume labels live on a FAT volume: one in the BPB (boot sector, always present, available via Self::volume_info) and an optional directory entry in the root with the VOLUME_ID attribute. Windows updates the latter when a user renames the volume; the BPB copy can drift. Use this method to read the authoritative on-disk name.

Returns Ok(None) if no label entry exists.

pub fn open_path(&self, path: &str) -> Result<FileEntry>

Open a file or directory by path (e.g., “/dir/subdir/file.txt”).

Paths can use forward slashes as separators. Leading slashes are optional. Empty path components are ignored.

pub fn open_file_path(&self, path: &str) -> Result<FileReader<'_, DATA>>

Open a file by path for reading.

This is a convenience method that combines open_path with opening a file reader.

pub fn open_dir_path(&self, path: &str) -> Result<FatDir<'_, DATA>>

Open a directory by path.

This is a convenience method that combines open_path with validating the entry is a directory.

pub fn open_dir_entry(&self, entry: &FileEntry) -> Result<FatDir<'_, DATA>>

Open a directory from a file entry.

The entry must be a directory.

impl<DATA> FatVolume<DATA>

where DATA: Read + Seek,

pub fn fat_cache(&self) -> Option<&Mutex<FatSectorCache>>

Borrow the optional FAT-sector cache configured via FatVolumeBuilder::fat_cache.

Returns None if no cache was installed. Pair with Self::fat and crate::cache::CachedFat::new to perform cached FAT operations, or use the higher-level Self::with_cached_fat helper which holds the cache and disk locks for you.

pub fn with_cached_fat<R>( &self, f: impl FnOnce(&mut CachedFat<'_>, &mut SectorCursor<DATA>) -> R, ) -> Option<R>

Run a closure with a crate::cache::CachedFat view backed by this filesystem’s installed FAT cache and underlying disk handle.

Returns None if no cache was installed via FatVolumeBuilder::fat_cache. Otherwise locks the cache mutex and the data mutex for the duration of the closure and returns Some(value) where value is the closure’s return.

FatVolume’s built-in methods consult the cache automatically; this helper remains useful for bulk FAT walks (free-cluster scans, multi-chain traversal) where holding the cache+disk locks across many entries is cheaper than re-acquiring them per call.

Example

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

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

// Walk the cluster chain of the file at first_cluster=42, using the cache.
let chain = fs
    .with_cached_fat(|cached, disk| cached.read_chain(disk, 42))
    .expect("cache installed")
    .expect("read_chain ok");

pub fn with_fat_cache_locked<R>( &self, f: impl FnOnce(&mut FatSectorCache, &mut SectorCursor<DATA>) -> R, ) -> Option<R>

Run a closure with both the crate::cache::FatSectorCache and underlying disk locked for direct, FAT-type-specific access.

Lower-level than Self::with_cached_fat — gives the closure &mut FatSectorCache so it can call the per-type entry-point methods (crate::cache::FatSectorCache::read_fat32_entry, crate::cache::FatSectorCache::write_fat32_entry, etc.). Most callers want Self::with_cached_fat instead, which wraps the cache in a CachedFat and hides the FAT-type dispatch.

Note: do NOT call Self::fat_cache.lock() inside this closure — the cache mutex is already locked, so a second lock attempt will deadlock (this is a spin::Mutex, not a re-entrant lock).

Returns None if no cache was installed.

impl<DATA> FatVolume<DATA>

where DATA: Read + Write + Seek,

pub fn flush(&self) -> Result<()>

Flush all dirty FAT cache sectors back to every FAT copy on disk.

No-op when no cache was installed. Without an explicit flush(), dirty sectors are written through to disk on LRU eviction (see FatSectorCache::evict_lru_flush) or are still in memory when the FatVolume is dropped. Call this before tearing down the filesystem to guarantee the on-disk FAT is consistent.

impl<DATA: Read + Write + Seek> FatVolume<DATA>

Directory write operations

pub fn create_file( &self, parent: &FatDir<'_, DATA>, name: &str, ) -> Result<FileEntry>

Create a new file in the given directory.

Returns the FileEntry for the newly created file.

pub fn create_dir<'a>( &'a self, parent: &FatDir<'a, DATA>, name: &str, ) -> Result<FatDir<'a, DATA>>

Create a new directory.

Returns a FatDir handle for the newly created directory.

pub fn delete(&self, entry: &FileEntry) -> Result<()>

Delete a file or empty directory.

pub fn rename( &self, entry: &FileEntry, dest_dir: &FatDir<'_, DATA>, new_name: &str, ) -> Result<FileEntry>

Rename or move a file or directory.

Creates a new directory entry with new_name in dest_dir, copying the cluster chain, size, and attributes from the source entry, then marks the old entry as deleted. Data is NOT copied — only the directory entry metadata changes.

If moving a directory to a different parent, the .. entry is updated to point to the new parent.

impl<DATA: Read + Write + Seek> FatVolume<DATA>

Volume label modification (root directory entry).

pub fn set_root_label(&self, name: &[u8; 11]) -> Result<()>

Overwrite the volume label stored in the root-directory entry.

Returns Error::EntryNotFound if no label entry exists today — callers should format the volume with a label, or extend the API later to allocate a new entry. The 11-byte name is written verbatim (FAT spec: space-padded, conventionally uppercase ASCII).

This does not update the BPB volume label; reformatting is the only way to change that one without rewriting the boot sector.

impl<DATA: Read + Write + Seek> FatVolume<DATA>

File attribute modification

pub fn set_attributes( &self, entry: &FileEntry, attrs: DirEntryAttrFlags, ) -> Result<()>

Set the attributes of a file or directory entry.

Only the user-mutable bits (READ_ONLY, HIDDEN, SYSTEM, ARCHIVE) may be changed in place. Attempting to flip DIRECTORY or VOLUME_ID returns Error::InvalidAttributeChange — those bits identify the kind of entry on disk and changing them would orphan a cluster chain or break the root volume label.

impl<DATA: Read + Write + Seek> FatVolume<DATA>

FSInfo update operations

pub fn sync(&self) -> Result<()>

Synchronize the FSInfo sector to disk.

For FAT32 filesystems, this updates the FSInfo sector with the current free cluster count and next free cluster hint. For FAT12/16 filesystems, this only flushes pending writes.

pub fn free_cluster_count(&self) -> Option<u32>

Get the current free cluster count (FAT32 only).

Returns None for FAT12/16 filesystems or if the count is unknown (0xFFFFFFFF).

pub fn next_free_cluster_hint(&self) -> Option<u32>

Get the next free cluster hint (FAT32 only).

Returns None for FAT12/16 filesystems or if the hint is unknown.

Trait Implementations

impl<DATA: Seek> Debug for FatVolume<DATA>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<DATA: Read + Seek> FatAnalysisExt<DATA> for FatVolume<DATA>

fn statistics(&self) -> Result<FatStatistics>

Gather statistics about the filesystem.

fn fragmentation_report(&self, max_files: usize) -> Result<FragmentationReport>

Analyze filesystem fragmentation.

fn scan_fat(&self) -> Result<Vec<ClusterState>>

Scan the FAT table and return the state of each cluster.

fn get_cluster_chain(&self, first_cluster: u32) -> Result<Vec<u32>>

Get the cluster chain for a file.

impl<DATA: Read + Seek> FatVerifyExt<DATA> for FatVolume<DATA>

fn verify(&self) -> Result<VerificationReport>

Verify filesystem integrity.

impl<DATA: Read + Seek> FatVolumeReadExt<DATA> for FatVolume<DATA>

fn read_file<'a>(&'a self, entry: &FileEntry) -> Result<FileReader<'a, DATA>>

Create a reader for a file entry.

impl<DATA: Read + Write + Seek> FatVolumeWriteExt<DATA> for FatVolume<DATA>

Available on crate feature write only.

fn write_file<'a>(&'a self, entry: &FileEntry) -> Result<FileWriter<'a, DATA>>

Create a writer for a file entry.

fn truncate(&self, entry: &FileEntry, new_size: usize) -> Result<()>

Truncate a file to the specified size.

fn set_times( &self, entry: &FileEntry, modified: Option<FatDateTime>, accessed_date: Option<u16>, created: Option<FatDateTime>, ) -> Result<()>

Patch the timestamps on an existing entry without rewriting its data.