fat Namespace Reference

The FAT16/FAT32 reader (CHSd). More...

Classes
struct	File
	A file or folder found in a directory: where it starts and how long it is. More...
struct	Run
	A run of consecutive card blocks holding part of a file (see runs()). More...

Typedefs
typedef bool(*	ListFn) (const char *name, const File &f, bool isDir, void *ctx)
	What list() calls for each entry of a directory.

Enumerations
enum	Err : int8_t {   OK = 0 ,   E_READ = -1 ,   E_NOFS = -10 ,   E_EXFAT = -11 ,   E_NOTFOUND = -12 ,   E_FRAG = -13 ,   E_CHAIN = -14 }
	What the functions that return an int8_t report: OK (0) or a negative error. More...

Functions
int8_t	mount (uint8_t *buf)
	Finds the FAT volume on the card and remembers where its parts are.
int8_t	find (const char *name, File &f, uint8_t *buf)
	Finds a file in the root directory.
int8_t	folder (const char *name, File &dir, uint8_t *buf)
	Finds a folder in the root directory, for match() and list().
int8_t	match (const File &dir, const char *pattern, uint8_t skip, File &f, char *nameOut, uint8_t *buf)
	Finds the (skip + 1)th file in a folder whose name fits a pattern.
int8_t	root (File &dir)
	The root directory as a folder, for match() and list().
int8_t	list (const File &dir, ListFn fn, void *ctx, uint8_t *buf)
	Walks a directory, handing every file and folder in it to fn, in directory order.
int8_t	runs (const File &f, Run *out, uint8_t maxRuns, uint8_t *buf)
	Walks a file's cluster chain once and returns its extents: the runs of consecutive card blocks that hold it.
uint8_t	open (const char *name, Run *out, uint8_t maxRuns, uint8_t *buf)
	The usual way in: sd::init(), mount(), find() and runs() in one go.
bool	read (const Run *run, uint32_t nRuns, uint32_t k, uint8_t *dst)
	Reads block k of a file through its runs.

Detailed Description

The FAT16/FAT32 reader (CHSd).

Typedef Documentation

ListFn

typedef bool(* fat::ListFn) (const char *name, const File &f, bool isDir, void *ctx)

What list() calls for each entry of a directory.

Parameters

name	the entry's 11-character 8.3 name (no NUL), valid only during the call.
f	its first cluster and size.
isDir	true for a folder, false for a file.
ctx	the ctx given to list().

Returns

true to go on to the next entry, false to stop the walk.

Enumeration Type Documentation

Err

enum fat::Err : int8_t

What the functions that return an int8_t report: OK (0) or a negative error.

Enumerator
OK	success
E_READ	the card did not deliver a block
E_NOFS	no FAT16/FAT32 volume: no partition, bad BPB, FAT12
E_EXFAT	exFAT (or NTFS) volume: reformat the card as FAT32
E_NOTFOUND	no such file or directory (or not mounted)
E_FRAG	more runs than the caller has room for
E_CHAIN	cluster chain broken, looped, or not the file's length

Function Documentation

mount()

int8_t fat::mount

(

uint8_t *

buf

)

Finds the FAT volume on the card and remembers where its parts are.

Looks for a superfloppy boot sector at LBA 0, else the first MBR partition of type 01/04/06/0B/0C/0E. An exFAT boot sector at LBA 0, or an MBR with a type 07 partition and no FAT one, is E_EXFAT. Call sd::init() first; everything else here needs a mounted volume.

Parameters

buf	a 512-byte, 4-byte-aligned buffer; clobbered.

Returns

OK, E_READ, E_NOFS (also FAT12, and a blank card) or E_EXFAT.

find()

int8_t fat::find	(	const char *	name,
		File &	f,
		uint8_t *	buf
	)

Finds a file in the root directory.

Parameters

name	its 11-character 8.3 name ("WORDS DIC"); ? matches any character.
f	receives the file's first cluster and size.
buf	a 512-byte, 4-byte-aligned buffer; clobbered.

Returns

OK, E_NOTFOUND (also when not mounted) or E_READ.

folder()

int8_t fat::folder	(	const char *	name,
		File &	dir,
		uint8_t *	buf
	)

Finds a folder in the root directory, for match() and list().

Parameters

name	its 11-character 8.3 name, padded with spaces ("CHCW "); ? matches any character.
dir	receives the folder.
buf	a 512-byte, 4-byte-aligned buffer; clobbered.

Returns

OK, E_NOTFOUND (also when not mounted) or E_READ.

match()

int8_t fat::match	(	const File &	dir,
		const char *	pattern,
		uint8_t	skip,
		File &	f,
		char *	nameOut,
		uint8_t *	buf
	)

Finds the (skip + 1)th file in a folder whose name fits a pattern.

Call it with skip = 0, 1, 2 ... to go through every match, in directory order.

Parameters

dir	the folder, from folder() or root().
pattern	an 11-character 8.3 name in which ? matches any character ("????????CWD": every .CWD file).
skip	how many matching files to pass over first.
f	receives the file's first cluster and size.
nameOut	receives its 11-character name (no NUL); nullptr if not wanted.
buf	a 512-byte, 4-byte-aligned buffer; clobbered.

Returns

OK; E_NOTFOUND: there are no more (or not mounted); E_READ.

root()

int8_t fat::root

(

File &

dir

)

The root directory as a folder, for match() and list().

Parameters

dir	receives the root directory.

Returns

OK; E_NOTFOUND: not mounted.

list()

int8_t fat::list	(	const File &	dir,
		ListFn	fn,
		void *	ctx,
		uint8_t *	buf
	)

Walks a directory, handing every file and folder in it to fn, in directory order.

fn gets each one's 11-character short name (no NUL), its first cluster and size, and whether it is a folder; returning false stops the walk. ., .., deleted entries, volume labels, long-name parts and hidden entries are left out. (For a browser: CHStlView.)

Parameters

dir	the directory, from root() or folder().
fn	called once per entry (see ListFn); it must not touch buf (the directory sector is in it) nor read the card.
ctx	passed to fn unchanged; may be nullptr.
buf	a 512-byte, 4-byte-aligned buffer; clobbered.

Returns

OK (also when fn stopped the walk), E_NOTFOUND (not mounted) or E_READ.

runs()

int8_t fat::runs	(	const File &	f,
		Run *	out,
		uint8_t	maxRuns,
		uint8_t *	buf
	)

Walks a file's cluster chain once and returns its extents: the runs of consecutive card blocks that hold it.

The last run is trimmed to the file's size, and a file of 0 bytes has 0 runs. The walk is bounded by the file's size and the chain must end right there, so a looped or truncated FAT gives E_CHAIN instead of a hang.

Parameters

f	the file, from find() or match().
out	receives the runs.
maxRuns	how many runs out has room for (at most 127 are used).
buf	a 512-byte, 4-byte-aligned buffer; clobbered.

Returns

the number of runs (0 or more), or E_FRAG (more runs than maxRuns: copying the file to a freshly formatted card always helps), E_CHAIN or E_READ.

open()

uint8_t fat::open	(	const char *	name,
		Run *	out,
		uint8_t	maxRuns,
		uint8_t *	buf
	)

The usual way in: sd::init(), mount(), find() and runs() in one go.

A game that tells the player why there is no file (no card, exFAT ...) calls the steps itself: passing the reason on would cost every game some 40 B of flash.

Parameters

name	the file's 11-character 8.3 name in the root directory ("WORDS DIC").
out	receives the file's runs.
maxRuns	how many runs out has room for.
buf	a 512-byte, 4-byte-aligned buffer; clobbered.

Returns

the number of runs; 0 if any step failed or the file is empty.

read()

bool fat::read	(	const Run *	run,
		uint32_t	nRuns,
		uint32_t	k,
		uint8_t *	dst
	)

Reads block k of a file through its runs.

Parameters

run	the file's runs, from open() or runs().
nRuns	how many there are.
k	the block of the file (0 = its first 512 bytes).
dst	where the 512 bytes go (any buffer of 512 bytes).

Returns

true if the block was read; false: past the end of the file, or the card did not deliver it (then sd::init(), or open(), before the next read).