add exported API to fat

Author: soypat

Diff for: example_test.go

@@ -0,0 +1,46 @@
+package fat_test
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/soypat/fat"
+)
+
+func ExampleFS_basic_usage() {
+	// device could be an SD card, RAM, or anything that implements the BlockDevice interface.
+	device := fat.DefaultFATByteBlocks(32000)
+	var fs fat.FS
+	err := fs.Mount(device, device.BlockSize(), fat.ModeRW)
+	if err != nil {
+		panic(err)
+	}
+	var file fat.File
+	err = fs.OpenFile(&file, "newfile.txt", fat.ModeCreateAlways|fat.ModeWrite)
+	if err != nil {
+		panic(err)
+	}
+
+	_, err = file.Write([]byte("Hello, World!"))
+	if err != nil {
+		panic(err)
+	}
+	err = file.Close()
+	if err != nil {
+		panic(err)
+	}
+
+	// Read back the file:
+	err = fs.OpenFile(&file, "newfile.txt", fat.ModeRead)
+	if err != nil {
+		panic(err)
+	}
+	data, err := io.ReadAll(&file)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(string(data))
+	file.Close()
+	// Output:
+	// Hello, World!
+}

Diff for: exported.go

@@ -0,0 +1,187 @@
+package fat
+
+import (
+	"errors"
+	"io"
+	"math"
+	"time"
+)
+
+// Mode represents the file access mode used in Open.
+type Mode uint8
+
+// File access modes for calling Open.
+const (
+	ModeRead  Mode = Mode(faRead)
+	ModeWrite Mode = Mode(faWrite)
+	ModeRW    Mode = ModeRead | ModeWrite
+
+	ModeCreateNew    Mode = Mode(faCreateNew)
+	ModeCreateAlways Mode = Mode(faCreateAlways)
+	ModeOpenExisting Mode = Mode(faOpenExisting)
+	ModeOpenAppend   Mode = Mode(faOpenAppend)
+
+	allowedModes = ModeRead | ModeWrite | ModeCreateNew | ModeCreateAlways | ModeOpenExisting | ModeOpenAppend
+)
+
+var (
+	errInvalidMode   = errors.New("invalid fat access mode")
+	errForbiddenMode = errors.New("forbidden fat access mode")
+)
+
+// Dir represents an open FAT directory.
+type Dir struct {
+	dir
+	inlineInfo FileInfo
+}
+
+// Mount mounts the FAT file system on the given block device and sector size.
+// It immediately invalidates previously open files and directories pointing to the same FS.
+// Mode should be ModeRead, ModeWrite, or both.
+func (fsys *FS) Mount(bd BlockDevice, blockSize int, mode Mode) error {
+	if mode&^(ModeRead|ModeWrite) != 0 {
+		return errInvalidMode
+	} else if blockSize > math.MaxUint16 {
+		return errors.New("sector size too large")
+	}
+	fr := fsys.mount_volume(bd, uint16(blockSize), uint8(mode))
+	if fr != frOK {
+		return fr
+	}
+	return nil
+}
+
+// OpenFile opens the named file for reading or writing, depending on the mode.
+// The path must be absolute (starting with a slash) and must not contain
+// any elements that are "." or "..".
+func (fsys *FS) OpenFile(fp *File, path string, mode Mode) error {
+	prohibited := (mode & ModeRW) &^ fsys.perm
+	if mode&^allowedModes != 0 {
+		return errInvalidMode
+	} else if prohibited != 0 {
+		return errForbiddenMode
+	}
+	fr := fsys.f_open(fp, path, uint8(mode))
+	if fr != frOK {
+		return fr
+	}
+	return nil
+}
+
+// Read reads up to len(buf) bytes from the File. It implements the [io.Reader] interface.
+func (fp *File) Read(buf []byte) (int, error) {
+	fr := fp.obj.validate()
+	if fr != frOK {
+		return 0, fr
+	}
+	br, fr := fp.f_read(buf)
+	if fr != frOK {
+		return br, fr
+	} else if br == 0 && fr == frOK {
+		return br, io.EOF
+	}
+	return br, nil
+}
+
+// Write writes len(buf) bytes to the File. It implements the [io.Writer] interface.
+func (fp *File) Write(buf []byte) (int, error) {
+	fr := fp.obj.validate()
+	if fr != frOK {
+		return 0, fr
+	}
+	bw, fr := fp.f_write(buf)
+	if fr != frOK {
+		return bw, fr
+	}
+	return bw, nil
+}
+
+// Close closes the file and syncs any unwritten data to the underlying device.
+func (fp *File) Close() error {
+	fr := fp.f_close()
+	if fr != frOK {
+		return fr
+	}
+	return nil
+}
+
+// Sync syncs any unwritten data to the underlying device.
+func (fp *File) Sync() error {
+	fr := fp.obj.validate()
+	if fr != frOK {
+		return fr
+	}
+	fr = fp.obj.fs.sync()
+	if fr != frOK {
+		return fr
+	}
+	return nil
+}
+
+// OpenDir opens the named directory for reading.
+func (fsys *FS) OpenDir(dp *Dir, path string) error {
+	fr := fsys.f_opendir(&dp.dir, path)
+	if fr != frOK {
+		return fr
+	}
+	return nil
+}
+
+// ForEachFile calls the callback function for each file in the directory.
+func (dp *Dir) ForEachFile(callback func(*FileInfo) error) error {
+	fr := dp.obj.validate()
+	if fr != frOK {
+		return fr
+	} else if dp.obj.fs.perm&ModeRead == 0 {
+		return errForbiddenMode
+	}
+
+	fr = dp.sdi(0) // Rewind directory.
+	if fr != frOK {
+		return fr
+	}
+	for {
+		fr := dp.f_readdir(&dp.inlineInfo)
+		if fr != frOK {
+			return fr
+		} else if dp.inlineInfo.fname[0] == 0 {
+			return nil // End of directory.
+		}
+		err := callback(&dp.inlineInfo)
+		if err != nil {
+			return err
+		}
+	}
+}
+
+// AlternateName returns the alternate name of the file.
+func (finfo *FileInfo) AlternateName() string {
+	return str(finfo.altname[:])
+}
+
+// Name returns the name of the file.
+func (finfo *FileInfo) Name() string {
+	return str(finfo.fname[:])
+}
+
+// Size returns the size of the file in bytes.
+func (finfo *FileInfo) Size() int64 {
+	return finfo.fsize
+}
+
+// ModTime returns the modification time of the file.
+func (finfo *FileInfo) ModTime() time.Time {
+	// https://www.win.tue.nl/~aeb/linux/fs/fat/fat-1.html
+	hour := int(finfo.ftime >> 11)
+	min := int((finfo.ftime >> 5) & 0x3f)
+	doubleSeconds := int(finfo.ftime & 0x1f)
+	yearSince1980 := int(finfo.fdate >> 9)
+	month := int((finfo.fdate >> 5) & 0xf)
+	day := int(finfo.fdate & 0x1f)
+	return time.Date(yearSince1980+1980, time.Month(month), day, hour, min, 2*doubleSeconds, 0, time.UTC)
+}
+
+// IsDir returns true if the file is a directory.
+func (finfo *FileInfo) IsDir() bool {
+	return finfo.fattrib&amDIR != 0
+}

Diff for: fat.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"encoding/binary"
 	"errors"
-	"io/fs"
 	"log/slog"
 	"math/bits"
 	"runtime"
@@ -18,9 +17,9 @@ import (
 type BlockDevice interface {
 	ReadBlocks(dst []byte, startBlock int64) (int, error)
 	WriteBlocks(data []byte, startBlock int64) (int, error)
-	EraseSectors(startBlock, numBlocks int64) error
+	EraseBlocks(startBlock, numBlocks int64) error
 	// Mode returns 0 for no connection/prohibited access, 1 for read-only, 3 for read-write.
-	Mode() accessmode
+	// Mode() accessmode
 }
 
 // sector index type.
@@ -60,7 +59,7 @@ type FS struct {
 	ffCodePage int
 	dbcTbl     [10]byte
 	id         uint16 // Filesystem mount ID. Serves to invalidate open files after mount.
-	perm       fs.FileMode
+	perm       Mode
 	codepage   []byte // unicode conversion table.
 	exCvt      []byte //  points to _tblCT* corresponding to codepage table.
 	log        *slog.Logger
@@ -108,7 +107,7 @@ const (
 	sfnBufSize = 12
 )
 
-type fileinfo struct {
+type FileInfo struct {
 	fsize   int64 // File Size.
 	fdate   uint16
 	ftime   uint16
@@ -208,6 +207,8 @@ func (fp *File) f_read(buff []byte) (br int, res fileResult) {
 	rbuff := buff
 	if fp.flag&faRead == 0 {
 		return 0, frDenied
+	} else if fsys.perm&ModeRead == 0 {
+		return 0, frDenied
 	}
 	remain := fp.obj.objsize - fp.fptr
 	btr := len(buff)
@@ -356,6 +357,8 @@ func (fp *File) f_write(buf []byte) (bw int, fr fileResult) {
 		return 0, frWriteProtected
 	} else if fp.obj.fs.fstype == fstypeExFAT {
 		return 0, frUnsupported
+	} else if fp.obj.fs.perm&ModeWrite == 0 {
+		return 0, frWriteProtected
 	}
 	fs := fp.obj.fs
 	btw := len(buf)
@@ -500,6 +503,8 @@ func (fsys *FS) f_open(fp *File, name string, mode accessmode) fileResult {
 		return frInvalidObject
 	} else if fsys.fstype == fstypeExFAT {
 		return frUnsupported
+	} else if fsys.perm == 0 {
+		return frDenied
 	}
 
 	var dj dir
@@ -619,7 +624,7 @@ func (fsys *FS) f_open(fp *File, name string, mode accessmode) fileResult {
 	return res
 }
 
-func (dp *dir) f_readdir(fno *fileinfo) fileResult {
+func (dp *dir) f_readdir(fno *FileInfo) fileResult {
 	fsys := dp.obj.fs
 	fsys.trace("dir:f_readdir")
 	if fsys.fstype == fstypeExFAT {
@@ -764,12 +769,7 @@ func (fsys *FS) mount_volume(bd BlockDevice, ssize uint16, mode uint8) (fr fileR
 	// mutexes or file path handling. File path handling is left to
 	// the Go standard library which does a much better job than us.
 	// See `filepath` and `fs` standard library packages.
-	devMode := bd.Mode()
-	if devMode == 0 {
-		return frNotReady
-	} else if mode&devMode != mode {
-		return frDenied
-	}
+
 	blk, err := makeBlockIndexer(int(ssize))
 	if err != nil {
 		return frInvalidParameter
@@ -778,6 +778,7 @@ func (fsys *FS) mount_volume(bd BlockDevice, ssize uint16, mode uint8) (fr fileR
 	fsys.id++ // Invalidate open files.
 	fsys.blk = blk
 	fsys.ssize = ssize
+	fsys.perm = Mode(mode)
 	fmt := fsys.find_volume(0)
 
 	if fmt == bootsectorstatusDiskError {
@@ -1167,6 +1168,9 @@ func (fsys *FS) st_clust(dir []byte, cl uint32) {
 }
 
 func (fsys *FS) disk_write(buf []byte, sector lba, numsectors int) diskresult {
+	if fsys.perm&ModeWrite == 0 {
+		return drWriteProtected
+	}
 	fsys.trace("fs:disk_write", slog.Uint64("start", uint64(sector)), slog.Int("numsectors", numsectors))
 	if fsys.blk.off(int64(len(buf))) != 0 || fsys.blk._divideBlockSize(int64(len(buf))) != int64(numsectors) {
 		fsys.logerror("disk_write:unaligned")
@@ -1196,7 +1200,7 @@ func (fsys *FS) disk_read(dst []byte, sector lba, numsectors int) diskresult {
 }
 func (fsys *FS) disk_erase(startSector lba, numSectors int) diskresult {
 	fsys.trace("fs:disk_erase", slog.Uint64("start", uint64(startSector)), slog.Int("numsectors", numSectors))
-	err := fsys.device.EraseSectors(int64(startSector), int64(numSectors))
+	err := fsys.device.EraseBlocks(int64(startSector), int64(numSectors))
 	if err != nil {
 		fsys.logerror("disk_erase", slog.String("err", err.Error()))
 		return drError
@@ -1871,7 +1875,7 @@ func (dp *dir) sdi(ofs uint32) fileResult {
 	return frOK
 }
 
-func (dp *dir) get_fileinfo(fno *fileinfo) {
+func (dp *dir) get_fileinfo(fno *FileInfo) {
 	fsys := dp.obj.fs
 
 	fno.fname[0] = 0 // Invalidate.
@@ -2348,13 +2352,6 @@ func (fsys *FS) gen_numname(dst, src []byte, lfn []uint16, seq uint32) {
 	}
 }
 
-func (finfo *fileinfo) AlternateName() string {
-	return str(finfo.altname[:])
-}
-func (finfo *fileinfo) Name() string {
-	return str(finfo.fname[:])
-}
-
 func str(s []byte) string {
 	if len(s) == 0 {
 		return ""