filesystem_exfat

README

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

Feature	Status	Notes
Open / Close	✅	Supports bare images and partitioned disks
Format	✅	Creates exFAT images
ReadFile	✅	Full file reads supported
WriteFile	✅	Full file writes supported
MkDir / Delete / Rename	✅	Directory operations supported
ReadLink / Symlinks	⚠️ No	exFAT does not support POSIX symlinks
Partitioned images	✅	MBR/GPT supported

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

Operation	Status
Open / Close	✅ implemented
Format	✅ implemented
Stat	✅ implemented
ListDir	✅ implemented
ReadFile	✅ implemented
WriteFile	✅ implemented
MkDir	✅ implemented
DeleteFile	✅ implemented
DeleteDir	✅ implemented (recursive)
Rename	✅ implemented
ReadLink	⚠️ stub — exFAT has no symlinks

API

Format

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

func Format(path string, sizeBytes int64, cfg FormatConfig) (*FS, error)

Open

func Open(imagePath string, partIndex int) (*FS, error)
func (fs *FS) Close() error
func (fs *FS) Info() Info
func (fs *FS) PartitionOffset() int64

Read

func (fs *FS) Stat(path string) (filesystem.Stat, error)
func (fs *FS) ListDir(path string) ([]filesystem.DirEntry, error)
func (fs *FS) ReadFile(path string) ([]byte, error)

Write

func (fs *FS) WriteFile(path string, data []byte, perm os.FileMode) error
func (fs *FS) MkDir(path string, perm os.FileMode) error
func (fs *FS) DeleteFile(path string) error
func (fs *FS) DeleteDir(path string) error
func (fs *FS) Rename(oldPath, newPath string) error

Implements

This package implements the filesystem.Filesystem interface defined in github.com/go-filesystems/interface. Callers can treat an opened *FS 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")

Documentation

Index

• Constants
• func Format(path string, sizeBytes int64, cfg FormatConfig) (filesystem.Filesystem, error)
• func Open(imagePath string, partIndex int) (filesystem.Filesystem, error)
• type FormatConfig
• type Info
  • func (info Info) BytesPerSector() uint32
  • func (info Info) ClusterHeapOffsetBytes(partOffset int64) int64
  • func (info Info) ClusterSize() uint64
  • func (info Info) FATOffsetBytes(partOffset int64) int64
  • func (info Info) RootDirOffset(partOffset int64) int64
  • func (info Info) SectorsPerCluster() uint32

Constants

const MaxLabelLen = 11

MaxLabelLen is the maximum number of UTF-16 code units storable in the exFAT Volume Label entry (per the exFAT specification §7.3).

Functions

func Format

func Format(path string, sizeBytes int64, cfg FormatConfig) (filesystem.Filesystem, error)

Format creates a new exFAT filesystem in the file at path. The file is created (or truncated) and formatted. sizeBytes must be a multiple of the cluster size (4096) and large enough to hold the metadata region plus at least one data cluster.

On success the newly formatted filesystem is opened and returned; the caller must Close it when done.

func Open

func Open(imagePath string, partIndex int) (filesystem.Filesystem, error)

Open opens imagePath, optionally selecting a partition, and parses the exFAT boot sector.

Types

type FormatConfig

type FormatConfig struct {
	// Label is the volume label (stored as a volume-label directory entry;
	// not in the boot sector for exFAT). Trimmed to 11 characters.
	Label string
	// VolumeSerialNumber is the 32-bit serial number. A random value is generated when zero.
	VolumeSerialNumber uint32
}

FormatConfig holds optional parameters for Format. All fields are optional; sensible defaults are used when left at their zero value.

type Info

type Info struct {
	PartitionStartSector   uint64
	VolumeLength           uint64
	FATOffset              uint32
	FATLength              uint32
	ClusterHeapOffset      uint32
	ClusterCount           uint32
	RootDirectoryCluster   uint32
	VolumeSerialNumber     uint32
	FileSystemRevision     uint16
	VolumeFlags            uint16
	BytesPerSectorShift    uint8
	SectorsPerClusterShift uint8
	NumberOfFATs           uint8
	DriveSelect            uint8
	PercentInUse           uint8
}

Info holds the fields decoded from the exFAT main boot sector.

func (Info) BytesPerSector

func (info Info) BytesPerSector() uint32

BytesPerSector returns the logical sector size in bytes.

func (Info) ClusterHeapOffsetBytes

func (info Info) ClusterHeapOffsetBytes(partOffset int64) int64

ClusterHeapOffsetBytes returns the absolute byte offset of the cluster heap.

func (Info) ClusterSize

func (info Info) ClusterSize() uint64

ClusterSize returns the allocation cluster size in bytes.

func (Info) FATOffsetBytes

func (info Info) FATOffsetBytes(partOffset int64) int64

FATOffsetBytes returns the absolute byte offset of the first FAT.

func (Info) RootDirOffset

func (info Info) RootDirOffset(partOffset int64) int64

RootDirOffset returns the absolute byte offset of the root directory cluster.

func (Info) SectorsPerCluster

func (info Info) SectorsPerCluster() uint32

SectorsPerCluster returns the cluster size expressed in sectors.