Struct Formatter 

pub struct Formatter { /* private fields */ }

Single-pass ext4 image builder.

Implementations

impl Formatter

pub fn with_options(path: &Path, opts: FormatOptions) -> FormatResult<Self>

Create a new formatter that writes an ext4 image to path.

The file is truncated and re-created as a sparse file of opts.size bytes. The root directory (inode 2) and the /lost+found directory (required by e2fsck) are created automatically.

Only opts.block_size == 4096 is currently accepted; other values return FormatError::UnsupportedBlockSize. Labels are validated eagerly — an oversize or NUL-containing label returns FormatError::InvalidLabel before any file work happens.

pub fn new( path: &Path, block_size: u32, min_disk_size: u64, ) -> FormatResult<Self>

Create a new formatter with defaults for UUID (random) and label (empty).

Thin shim over Formatter::with_options for the common case where only the image size matters. Callers that need a specific UUID or volume label should use with_options directly.

pub fn create( &mut self, path: &str, mode: u16, link: Option<&str>, ts: Option<FileTimestamps>, data: Option<&mut dyn Read>, uid: Option<u32>, gid: Option<u32>, xattrs: Option<&HashMap<String, Vec<u8>>>, ) -> FormatResult<()>

Create a file, directory, or symlink at path.

Parent directories are created recursively with mode 0755, inheriting uid/gid from the nearest existing parent (like mkdir -p).

pub fn exists(&self, path: &str) -> bool

Check whether path exists in the in-memory file tree.

pub fn is_dir(&self, path: &str) -> bool

Check whether path exists and is a directory.

pub fn list_dir(&self, path: &str) -> Vec<String>

List the names of immediate children of a directory (excluding . and ..). Returns an empty vec if path is not a directory.

pub fn set_permissions(&mut self, path: &str, mode: u16) -> FormatResult<()>

Update the permission bits of an existing entry.

pub fn set_owner(&mut self, path: &str, uid: u32, gid: u32) -> FormatResult<()>

Update the owner uid/gid of an existing entry.

pub fn link(&mut self, link_path: &str, target_path: &str) -> FormatResult<()>

Create a hard link at link_path pointing to target_path.

pub fn unlink( &mut self, path: &str, directory_whiteout: bool, ) -> FormatResult<()>

Remove the entry at path.

When directory_whiteout is true, only children are removed and the directory entry itself is kept (used for overlay whiteouts).

pub fn close(self) -> FormatResult<()>

Finalize the ext4 image.

Writes directory entries (BFS order), the inode table, block/inode bitmaps, group descriptors, and the superblock. Consumes self.

impl Formatter

pub fn unpack_tar<R: Read>(&mut self, reader: R) -> FormatResult<()>

Unpack a tar archive onto this ext4 filesystem.

Handles:

• Regular files, directories, and symbolic links
• OCI whiteout files (.wh.<name> deletes <name>, .wh..wh..opq deletes all children of the containing directory)
• Hard links with cycle detection
• Preservation of uid/gid, permissions, and timestamps