filesystem_ntfs

README

ntfs package

This package provides a minimal NTFS driver that implements the filesystem.Filesystem interface.

Implementation details:

• The driver stores a small header region at the start of the image and places file blobs after that header. All operations (read/write/mkdir/rename) operate inside the image file rather than on the host filesystem.
• This is a lightweight, test-oriented implementation and does not attempt to implement the full NTFS on-disk format. Use a real NTFS implementation for full compatibility or integration tests.

Support summary

Feature	Status	Notes
Open / Close	✅	Minimal in-image implementation
ReadFile / WriteFile	✅	Blob storage model inside image
MkDir / Delete / Rename	✅	Implemented (recursive delete supported)
ReadLink / Symlinks	⚠️ No	No NTFS alternate data streams or full symlink support
Free-list reuse	✅	In-image free-list and reuse implemented
Volume label	✅	Label / SetLabel (filesystem.Labeller)

Notes on current capabilities:

• Path normalization: paths are normalized and stored with a leading /.
• Parent directories: WriteFile will create any missing parent directories.
• Directory rename: renaming a directory updates all nested entries.
• Deletion: DeleteDir removes a directory and its contents recursively.

Limitations

• The driver does not implement NTFS metadata (ACLs, alternate data streams, journaling, or real on-disk structures).
• Storage compaction / reuse is not implemented; deleted blobs leave gaps in the image file.

Free-list and reuse

• The driver now maintains an in-image free-list of blob extents freed by delete operations and reuses those extents for subsequent writes when a suitably-sized extent is available. Contiguous free extents are coalesced to reduce fragmentation.

Future improvements

• Implement compaction to defragment storage and reduce image growth.
• Add more NTFS metadata (timestamps, inodes, ACLs) for better compatibility.

Implements

This package implements the filesystem.Filesystem interface from the github.com/go-filesystems/interface module. Tools that accept the filesystem.Filesystem abstraction can operate on NTFS images created or opened by this package.

Example:

import (
	filesystem "github.com/go-filesystems/interface"
	fsnt "github.com/go-filesystems/ntfs"
)

f, _ := fsnt.Open("ntfs.img", -1)
defer f.Close()
var fs filesystem.Filesystem = f
_, _ = fs.Stat("/")

Documentation

Index

• Constants
• Variables
• func Format(path string, sizeBytes int64, cfg FormatConfig) (filesystem.Filesystem, error)
• type FS
  • func Open(imagePath string, partIndex int) (FS, error)
• type FileLayout
• type FormatConfig

Constants

const MaxLabelLen = 128

MaxLabelLen is the cap we enforce on the volume label. The real NTFS limit is 32 UTF-16 code units (~64 on-disk bytes); we use a slightly generous byte cap here since this mock driver stores raw bytes — that gives users headroom while still rejecting absurdly long input.

Variables

var ErrShrinkTooSmall = errors.New("ntfs: shrink target smaller than highest used offset")

ErrShrinkTooSmall is returned by Shrink and Resize when the requested new size is smaller than the highest byte currently occupied by a live file blob. Callers must Compact or delete files before retrying.

Functions

func Format

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

Types

type FS

type FS interface {
	filesystem.Filesystem
	FragmentationStats() (files int, used uint64, freeExtents int, totalFree uint64, largestFree uint64)
	Layout() []FileLayout
	Compact() error
	Symlink(target, linkPath string) error
	Label() string
	SetLabel(label string) error
	Grow(newSizeBytes int64) error
	Shrink(newSizeBytes int64) error
	Resize(newSizeBytes int64) error
}

FS is the public interface returned by Open. It extends filesystem.Filesystem with NTFS-specific operations (fragmentation analysis, compaction and NTFSIMG1 image resize). Callers that only need the generic interface can use it directly; callers that want the extras type-assert (or accept *FS via Open's return type).

NOTE: Grow / Shrink / Resize operate on the NTFSIMG1 image format this driver implements, NOT on real NTFS. Resizing a real NTFS volume would require manipulating the MFT, $Bitmap and runlists and is a separate, much larger project.

func Open

func Open(imagePath string, partIndex int) (FS, error)

Open opens the image file and loads the in-image index. The driver stores a fixed-size header at the start of the partition and places file blobs after that header. partIndex is currently ignored (assumed single-image usage).

type FileLayout

type FileLayout struct {
	Path   string
	Offset uint64
	Size   uint64
}

FileLayout describes a stored file blob location inside the image.

type FormatConfig

type FormatConfig struct{ Label string }

Format creates a fresh NTFS-like image at path with the given size.