Trait Filesystem 

pub trait Filesystem {
    // Required methods
    fn create_file(
        &mut self,
        dev: &mut dyn BlockDevice,
        path: &Path,
        src: FileSource,
        meta: FileMeta,
    ) -> Result<()>;
    fn create_dir(
        &mut self,
        dev: &mut dyn BlockDevice,
        path: &Path,
        meta: FileMeta,
    ) -> Result<()>;
    fn create_symlink(
        &mut self,
        dev: &mut dyn BlockDevice,
        path: &Path,
        target: &Path,
        meta: FileMeta,
    ) -> Result<()>;
    fn create_device(
        &mut self,
        dev: &mut dyn BlockDevice,
        path: &Path,
        kind: DeviceKind,
        major: u32,
        minor: u32,
        meta: FileMeta,
    ) -> Result<()>;
    fn remove(&mut self, dev: &mut dyn BlockDevice, path: &Path) -> Result<()>;
    fn list(
        &mut self,
        dev: &mut dyn BlockDevice,
        path: &Path,
    ) -> Result<Vec<DirEntry>>;
    fn read_file<'a>(
        &'a mut self,
        dev: &'a mut dyn BlockDevice,
        path: &Path,
    ) -> Result<Box<dyn Read + 'a>>;
    fn flush(&mut self, dev: &mut dyn BlockDevice) -> Result<()>;

    // Provided methods
    fn open_file_ro<'a>(
        &'a mut self,
        _dev: &'a mut dyn BlockDevice,
        _path: &Path,
    ) -> Result<Box<dyn FileReadHandle + 'a>> { ... }
    fn open_file_rw<'a>(
        &'a mut self,
        _dev: &'a mut dyn BlockDevice,
        _path: &Path,
        _flags: OpenFlags,
        _meta: Option<FileMeta>,
    ) -> Result<Box<dyn FileHandle + 'a>> { ... }
    fn mutation_capability(&self) -> MutationCapability { ... }
    fn supports_mutation(&self) -> bool { ... }
    fn read_symlink(
        &mut self,
        _dev: &mut dyn BlockDevice,
        _path: &Path,
    ) -> Result<PathBuf> { ... }
    fn total_file_bytes(&mut self, dev: &mut dyn BlockDevice) -> Result<u64> { ... }
}

Top-level dyn-compatible API every filesystem implements. The format / open factory methods live on the sibling FilesystemFactory trait so this one stays object-safe — the generic walker in crate::repack can hold a &mut dyn Filesystem and drive any of Ext / Fat32 / HfsPlus / Ntfs / F2fs / Squashfs / Xfs through the same create_* / remove / list / read_file / flush entry points.

Required Methods

fn create_file( &mut self, dev: &mut dyn BlockDevice, path: &Path, src: FileSource, meta: FileMeta, ) -> Result<()>

Create a regular file at path populated from src with metadata meta.

fn create_dir( &mut self, dev: &mut dyn BlockDevice, path: &Path, meta: FileMeta, ) -> Result<()>

Create a directory at path.

fn create_symlink( &mut self, dev: &mut dyn BlockDevice, path: &Path, target: &Path, meta: FileMeta, ) -> Result<()>

Create a symbolic link at path pointing at target.

fn create_device( &mut self, dev: &mut dyn BlockDevice, path: &Path, kind: DeviceKind, major: u32, minor: u32, meta: FileMeta, ) -> Result<()>

Create a device node / FIFO / socket.

fn remove(&mut self, dev: &mut dyn BlockDevice, path: &Path) -> Result<()>

Remove a file, directory, or special entry. Returns Error::InvalidArgument for a non-empty directory.

fn list( &mut self, dev: &mut dyn BlockDevice, path: &Path, ) -> Result<Vec<DirEntry>>

List the entries of a directory.

fn read_file<'a>( &'a mut self, dev: &'a mut dyn BlockDevice, path: &Path, ) -> Result<Box<dyn Read + 'a>>

Open a regular file for reading. Returns a boxed streaming reader that borrows both self (for filesystem metadata) and dev (for actual block reads), so it must outlive both.

fn flush(&mut self, dev: &mut dyn BlockDevice) -> Result<()>

Persist outstanding dirty state to the device.

Provided Methods

fn open_file_ro<'a>( &'a mut self, _dev: &'a mut dyn BlockDevice, _path: &Path, ) -> Result<Box<dyn FileReadHandle + 'a>>

Open a regular file for random-access reads with no writes. The returned handle is Read + Seek and reports the file’s total length via len(). Every backend that can surface file contents should implement this — including the immutable formats (ISO 9660 / SquashFS / tar / GRF) where open_file_rw is unsupported but seeking inside a file is still meaningful.

Default: returns Unsupported. Implementations override — most can do so by reusing the same extent / runlist walker that powers Self::read_file.

fn open_file_rw<'a>( &'a mut self, _dev: &'a mut dyn BlockDevice, _path: &Path, _flags: OpenFlags, _meta: Option<FileMeta>, ) -> Result<Box<dyn FileHandle + 'a>>

Open a regular file for in-place reads + writes at byte granularity. The returned handle is Read + Write + Seek; dropping it persists any pending bytes (each implementation chooses whether Write::write is eager or buffered).

Filesystems whose on-disk format requires journaling to be safe across crash boundaries should refuse this method until their journal is wired — partial writes that bypass a journal leave the FS in a “needs fsck” state on next mount, which is a worse default than a clear Unsupported error.

Default: returns Unsupported. Implementations override only when they can produce a result that survives a clean unmount without external repair.

fn mutation_capability(&self) -> MutationCapability

Capability of this filesystem with respect to mutating an already-flushed image. Three cases:

• MutationCapability::Mutable: full in-place edits via create_* / remove (ext, FAT32, F2FS).
• MutationCapability::Streaming: writer is sequential only — adding to an existing image means producing a new one from scratch (tar).
• MutationCapability::Immutable: writer can seek but the on-disk format has no in-place mutation hooks (ISO 9660, SquashFS). repack rebuilds.

Default: Mutable. Override on backends that aren’t.

fn supports_mutation(&self) -> bool

Convenience shortcut: can this filesystem satisfy create_file / remove? Equivalent to mutation_capability().supports_add_remove(). Returns true for both MutationCapability::Mutable and MutationCapability::WholeFileOnly — callers that need finer detail (e.g. “can I patch byte N?”) should query Self::mutation_capability directly.

fn read_symlink( &mut self, _dev: &mut dyn BlockDevice, _path: &Path, ) -> Result<PathBuf>

Read a symbolic link’s target. Default returns Unsupported — filesystems that have symlinks (ext, tar, xfs, hfs+, ntfs, squashfs, iso 9660 via Rock Ridge) override.

fn total_file_bytes(&mut self, dev: &mut dyn BlockDevice) -> Result<u64>

Recursive sum of all regular-file sizes in the filesystem. Uses the size field on DirEntry returned by Self::list — filesystems that don’t surface size from a listing return 0 for those entries, in which case the total is best-effort.

Skips the special names ".", "..", and "lost+found" so the walk doesn’t loop / double-count ext’s reserved tree.

Implementors

impl Filesystem for Apfs

Filesystem adapter for APFS. An Apfs opened via Apfs::open is read-only — mutation calls return Unsupported. An Apfs returned by Apfs::format is in pending-write mode: create_file / create_dir / create_symlink buffer operations in memory and flush drains them into a fresh image through write::ApfsWriter. After flush the Apfs is in read mode and behaves like a freshly-opened image.

impl Filesystem for Exfat

Filesystem adapter so inspect::open(dev) can return a Box<dyn Filesystem> that walks and mutates an exFAT image. Symlinks and device nodes have no representation in exFAT and return Unsupported. The caller must call flush to persist FAT + bitmap changes before dropping the volume.

impl Filesystem for Ext

impl Filesystem for F2fs

impl Filesystem for Fat32

impl Filesystem for Grf

impl Filesystem for HfsPlus

impl Filesystem for Iso9660

impl Filesystem for Ntfs

impl Filesystem for Squashfs

impl Filesystem for Tar

Read-only Filesystem adapter so inspect::open(dev) can return a Box<dyn Filesystem> that walks a tar archive. Writes return Unsupported — tar archives are sequential and repack is the only way to produce a new one.

impl Filesystem for Xfs