FatIFS

IFS library for Sming supporting FAT filesystems.

Formatting

Use IFS::FAT::formatVolume() to format a partition:

part = ... // Storage::Partition
int err = IFS::FAT::formatVolume(part);
Serial << "formatVolume: " << IFS::Error::toString(err) << endl;

An optional IFS::FAT::FormatOptions parameter can be used to provide additional settings:

IFS::FAT::FormatOptions opt{
   .volumeLabel = "My FAT volume", // Volume label (distinct from partition name)
   .types = Storage::Disk::SysType::fat32, // Only use FAT32 for this volume
};
int err = IFS::FAT::formatVolume(part, opt);

For more detailed low-control over the formatting:

IFS::FAT::FatParam param;
int err = IFS::FAT::calculateFatParam(part, opt, param);
if(err == FS_OK) {
   // .. adjust settings in `param` before formatting
   int err = IFS::FAT::formatVolume(part, param);
}

Mounting FAT volumes

Unlike SPIFFS or LittleFS, failure to mount a filing system does not auto-format the volume. Instead, this is left to the application to handle. For example:

auto fs = IFS::createFatFilesystem(part);
if(fs != nullptr) {
   int err = fs->mount();
   if(err == Error::BadFileSystem) {
      // Filesystem layout is invalid...
      fs->format();
      err = fs->mount();
   }
   if(err != FS_OK) {
      // Handle error
   }
}

Configuration options

ENABLE_EXFAT

default: 0 (disabled)

Set to 1 to enable support for EXFAT volumes. Requires ENABLE_STORAGE_SIZE64 option.

ENABLE_FAT_TRIM

default: disabled

When using devices with TRIM support this setting should be enabled.: See https://en.wikipedia.org/wiki/Trim_(computing).

FAT_CODEPAGE: default: 437 (US English)

Acknowledgements

ChanN’s fatfs library <http://elm-chan.org/fsw/ff/00index_e.html>`
Linux Kernel <https://github.com/torvalds/linux/>
Linux utilities https://github.com/util-linux/util-linux
Linux FUSE exFAT filing system implementation https://github.com/relan/exfat

API Documentation

namespace FAT

Functions

int translateFatfsResult(uint8_t result, bool diskio_write)

String fatfsErrorToStr(uint8_t err)

ErrorCode calculateFatParam(Partition partition, const FormatOptions &opt, FatParam &param)

Deduce FAT volume parameters for given space.

Parameters:

partition – The partition to format
opt – Formatting options
param – On success, contains calculated parameters for FAT volume

Return values:

ErrorCode – When partitioning using MBR format, this method can be used to determine the Sys indicator value setting.

ErrorCode formatVolume(Partition partition, const FatParam &param)

Format partition using pre-calculated FAT parameters.

Parameters:

partition – The partition to format
param – Detailed FAT parameters (returned from calculateFatParam)

Return values:

ErrorCode – This function allows fine control over exactly how a FAT partition is constructed. Generally the calculateFatParam function should be used to populate the param structure, then any modifications can be made as required before actually formatting the volume.

inline ErrorCode formatVolume(Partition partition, const FormatOptions &opt = {})

Format partition with a blank FAT volume.

Parameters:

partition – The partition to format
opt – Formatting options

Return values:

ErrorCode –

class FileSystem : public IFS::IFileSystem

#include <FileSystem.h>

Wraps fatfs

Public Functions

virtual int mount() override

Mount file system, performing any required initialisation.

Return values:: error – code

virtual int getinfo(Info &info) override

get filing system information

Parameters:: info – structure to read information into
Return values:: int – error code

virtual int setProfiler(IProfiler *profiler) override

Set profiler instance to enable debugging and performance assessment.

Parameters:: profiler –
Return values:: int – error code - profiling may not be supported on all filesystems

virtual String getErrorString(int err) override

get the text for a returned error code

Return values:: String –

virtual int opendir(const char *path, DirHandle &dir) override

open a directory for reading

Parameters:

path – path to directory. nullptr is interpreted as root directory
dir – returns a pointer to the directory object

Return values:

int – error code

virtual int readdir(DirHandle dir, Stat &stat) override

read a directory entry

Note

File system allocates entries structure as it usually needs to track other information. It releases memory when closedir() is called.

Parameters:

dir –
stat –

Return values:

int – error code

virtual int rewinddir(DirHandle dir) override

Reset directory read position to start.

Parameters:: dir –
Return values:: int – error code

virtual int closedir(DirHandle dir) override

close a directory object

Parameters:: dir – directory to close
Return values:: int – error code

virtual int mkdir(const char *path) override

Create a directory.

Only the final directory in the path is guaranteed to be created. Usually, this call will fail if intermediate directories are not present. Use IFS::FileSystem::makedirs() for this purpose.

Parameters:: path – Path to directory
Return values:: int – error code

virtual int stat(const char *path, Stat *stat) override

get file information

Returned stat will indicate whether the path is a mountpoint or directory. For a mount point, stats for the root directory of the mounted filesystem must be obtained by opening a handle then using fstat:

int handle = fs.open("path-to-mountpoint");
Stat stat;
fs.fstat(handle, &stat);
fs.close(handle);

Parameters:

path – name or path of file/directory/mountpoint
s – structure to return information in, may be null to do a simple file existence check

Return values:

int – error code

virtual int fstat(FileHandle file, Stat *stat) override

get file information

Parameters:

file – handle to open file
stat – structure to return information in, may be null

Return values:

int – error code

virtual int fcontrol(FileHandle file, ControlCode code, void *buffer, size_t bufSize) override

Low-level and non-standard file control operations.

To simplify usage the same buffer is used for both input and output. Only the size of the buffer is provided. If a specific FCNTL code requires more information then it will be contained within the provided data.

Parameters:

file –
code – FCNTL_XXX code
buffer – Input/Output buffer
bufSize – Size of buffer

Return values:

int – error code or, on success, data size

virtual int fsetxattr(FileHandle file, AttributeTag tag, const void *data, size_t size) override

Set an extended attribute on an open file.

Note

Attributes may not be written to disk until flush() or close() are called

Parameters:

file – handle to open file
tag – The attribute to write
data – Content of the attribute. Pass nullptr to remove the attribute (if possible).
size – Size of the attribute in bytes

Return values:

int – error code

virtual int fgetxattr(FileHandle file, AttributeTag tag, void *buffer, size_t size) override

Get an extended attribute from an open file.

Parameters:

file – handle to open file
tag – The attribute to read
buffer – Buffer to receive attribute content
size – Size of the buffer

Return values:

int – error code, on success returns size of attribute (which may be larger than size)

virtual int fenumxattr(FileHandle file, AttributeEnumCallback callback, void *buffer, size_t bufsize) override

Enumerate attributes.

Parameters:

file – handle to open file
callback – Callback function to invoke for each attribute found
buffer – Buffer to use for reading attribute data. Use nullptr if only tags are required
bufsize – Size of buffer

Return values:

int – error code, on success returns number of attributes read

virtual int setxattr(const char *path, AttributeTag tag, const void *data, size_t size) override

Set an extended attribute for a file given its path.

Parameters:

path – Full path to file (or directory)
tag – The attribute to write
data – Content of the attribute. Pass nullptr to remove the attribute (if possible).
size – Size of the attribute in bytes

Return values:

int – error code

virtual int getxattr(const char *path, AttributeTag tag, void *buffer, size_t size) override

Get an attribute from a file given its path.

Parameters:

file – Full path to file (or directory)
tag – The attribute to read
buffer – Buffer to receive attribute content
size – Size of the buffer

Return values:

int – error code, on success returns size of attribute (which may be larger than size)

virtual FileHandle open(const char *path, OpenFlags flags) override

open a file (or directory) by path

This function may also be used to obtain a directory handle to perform various operations such as enumerating attributes. Calls to read or write on such handles will typically fail.

Parameters:

path – full path to file
flags – Desired access and other options

Return values:

FileHandle – file handle or error code

virtual int close(FileHandle file) override

close an open file

Parameters:: file – handle to open file
Return values:: int – error code

virtual int read(FileHandle file, void *data, size_t size) override

read content from a file and advance cursor

Parameters:

file – handle to open file
data – buffer to write into
size – size of file buffer, maximum number of bytes to read

Return values:

int – number of bytes read or error code

virtual int write(FileHandle file, const void *data, size_t size) override

write content to a file at current position and advance cursor

Parameters:

file – handle to open file
data – buffer to read from
size – number of bytes to write

Return values:

int – number of bytes written or error code

virtual file_offset_t lseek(FileHandle file, file_offset_t offset, SeekOrigin origin) override

change file read/write position

Parameters:

file – handle to open file
offset – position relative to origin
origin – where to seek from (start/end or current position)

Return values:

file_offset_t – current position or error code

virtual int eof(FileHandle file) override

determine if current file position is at end of file

Parameters:: file – handle to open file
Return values:: int – 0 - not EOF, > 0 - at EOF, < 0 - error

virtual file_offset_t tell(FileHandle file) override

get current file position

Parameters:: file – handle to open file
Return values:: file_offset_t – current position relative to start of file, or error code

virtual int ftruncate(FileHandle file, file_size_t new_size) override

Truncate (reduce) the size of an open file.

Note

In POSIX ftruncate() can also make the file bigger, however SPIFFS can only reduce the file size and will return an error if newSize > fileSize

Parameters:

file – Open file handle, must have Write access
newSize –

Return values:

int – Error code

virtual int flush(FileHandle file) override

flush any buffered data to physical media

Parameters:: file – handle to open file
Return values:: int – error code

virtual int rename(const char *oldpath, const char *newpath) override

rename a file

Parameters:

oldpath –
newpath –

Return values:

int – error code

virtual int remove(const char *path) override

remove (delete) a file by path

Parameters:: path –
Return values:: int – error code

virtual int fremove(FileHandle file) override

remove (delete) a file by handle

Parameters:: file – handle to open file
Return values:: int – error code

virtual int format() override

format the filing system

Note

this does a default format, returning file system to a fresh state The filing system implementation may define more specialised methods which can be called directly.

Return values:: int – error code

virtual int check() override

Perform a file system consistency check.

Note

if possible, issues should be resolved. Returns 0 if file system checked out OK. Otherwise there were issues: < 0 for unrecoverable errors,

0 for recoverable errors.

Return values:: int – error code

struct FormatOptions

#include <Format.h>

Formatting options.

Public Members

SysTypes types = {0}: Valid partition format types.

uint8_t numFats = {1}: Number of FATs (1 or 2)

unsigned align = {0}: Data area alignment (sector)

unsigned numRootEntries = {512}: Number of root directory entries.

uint32_t clusterSize = {4096}: Cluster size (byte)

struct FatParam

#include <Format.h>

Public Members

uint32_t sectorsPerBlock: Flash erase block size.

uint16_t sectorsPerCluster: Set to 0 for auto-calculation.

References

Environment Variables

ENABLE_EXFAT
ENABLE_FAT_TRIM
ENABLE_STORAGE_SIZE64
FAT_CODEPAGE

SoC support

esp32
esp32c2
esp32c3
esp32s2
esp32s3
esp8266
host
rp2040