filesystem_exfat

exfat

Pure-Go read/write access to exFAT filesystem images — no root privileges, no external tools, no CGO.

Supports bare filesystem images and MBR/GPT partitioned disks, full directory traversal, file mutation and filesystem creation.

Support summary

Untrusted input

An image is attacker-controlled data. Every allocation a value in the image can size is bounded before it happens, and a hostile image gets an error, not an out-of-memory kill:

• a cluster buffer is allocated only after the cluster's last byte has been read: a 512-byte file whose boot sector declares 32 MiB clusters no longer costs 64 MiB to Open;
• a NoFatChain (contiguous) run is bounded by the bytes the image really holds, not by ClusterCount and the entry's DataLength, so two small claims cannot size a multi-gigabyte cluster list;
• a directory is at most 256 MiB (8388608 entries of 32 bytes, Linux MAX_EXFAT_DENTRIES), not 256 clusters of up to 32 MiB;
• an allocation bitmap larger than the image is refused.

When the reader cannot say how long it is, the length is found by probing single bytes (about 2*log2(size) reads).

FuzzOpenAndWalk drives the read surface; the regression tests are in bombs_test.go.

Limitations

• exFAT does not support POSIX symlinks or POSIX permissions/ACLs.
• Metadata is limited compared to POSIX filesystems (no ownership, no Unix permissions).
• No journaling; this implementation is intended for tooling and tests, not production workloads.

Module

github.com/go-filesystems/exfat

Supported operations

API

Open and Format return the plain filesystem.Filesystem interface (there is no richer exported FS type) — exFAT-specific extras (Info, PartitionOffset, volume label, truncate, resize) are reached by type-asserting to the optional interfaces from github.com/go-filesystems/interface, or to the package's own Info getter.

Format / Open

type FormatConfig struct {
    Label              string
    VolumeSerialNumber uint32 // 0 = randomly generated
}

func Format(path string, sizeBytes int64, cfg FormatConfig) (filesystem.Filesystem, error)
func Open(imagePath string, partIndex int) (filesystem.Filesystem, error)

Read / Write

The returned value's Stat / ListDir / ReadFile / WriteFile / MkDir / DeleteFile / DeleteDir / Rename are exactly the filesystem.Filesystem contract — see that package's README for the full signatures.

exFAT-specific extras (type-assert)

// Read part of a file without materialising all of it: OpenFile resolves the
// FAT chain once (cluster numbers, not data) and then serves byte ranges, so a
// 4 KiB read out of a 4 GiB file costs 4 KiB. Required by anything that mounts
// or exports the volume.
if o, ok := fs.(filesystem.Opener); ok {
    f, err := o.OpenFile("/big.bin")
    if err != nil {
        return err
    }
    defer f.Close()
    buf := make([]byte, 4096)
    n, err := f.ReadAt(buf, 1<<30) // io.ReaderAt semantics, exactly
    _, _ = n, err
    _ = f.Size()                   // from metadata; reads nothing

    // ...and write part of one, in place. Without this a positional write can
    // only be ReadFile + splice + WriteFile: the whole file read, reallocated
    // and written back on every request, so writing a file in blocks is
    // quadratic. Measured over a real Linux kernel NFS mount, 8 MiB in 64 KiB
    // blocks took 31 s (269 kB/s) that way, against 1.5 s with this.
    if w, ok := f.(filesystem.WritableFile); ok {
        _, err = w.WriteAt(buf, 1<<30) // io.WriterAt semantics, exactly
        _ = w.Truncate(1 << 20)        // grow zero-fills; shrink frees clusters
        _ = w.Sync()                   // fsync(2) on a file-backed image
    }
}
if l, ok := fs.(filesystem.Labeller); ok {
    _ = l.SetLabel("MYVOL")
}
if t, ok := fs.(filesystem.Truncater); ok {
    _ = t.Truncate("/big.bin", 4096)
}
if r, ok := fs.(interface{ Resize(int64) error }); ok {
    _ = r.Resize(newSizeBytes) // also exposes Grow(int64) error / Shrink(int64) error
}
if i, ok := fs.(interface{ Info() Info }); ok {
    fmt.Println(i.Info().ClusterSize())
}

Implements

This package implements the filesystem.Filesystem interface defined in github.com/go-filesystems/interface. Callers can treat the value returned by Open/Format as a filesystem.Filesystem to write generic tooling that works across the other filesystem modules in this repository.

Example:

import (
    filesystem "github.com/go-filesystems/interface"
    fsex "github.com/go-filesystems/exfat"
)

f, _ := fsex.Open("exfat.img", -1)
defer f.Close()
var fs filesystem.Filesystem = f
_, _ = fs.ReadFile("/hello.txt")