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

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 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.

union FatTime
#include <FatTime.h>

FAT timestamp support.

Public Functions

inline FatTime(uint32_t fdatetime = 0)
inline FatTime(uint16_t fdate, uint16_t ftime)
inline FatTime(IFS::TimeStamp ts)
inline FatTime(DateTime dt)
inline operator DateTime() const
inline explicit operator time_t() const

Public Members

uint16_t time
uint16_t date
struct FatTime::[anonymous] [anonymous]
uint32_t second
uint32_t minute
uint32_t hour
uint32_t day
uint32_t month
uint32_t year
struct FatTime::[anonymous] [anonymous]
uint32_t value

Public Static Attributes

static constexpr unsigned BaseYear = {1980}

References

Environment Variables

SoC support

  • esp32

  • esp32c2

  • esp32c3

  • esp32s2

  • esp32s3

  • esp8266

  • host

  • rp2040

  • rp2350