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.
- 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 IFS::FAT
Functions
-
int translateFatfsResult(uint8_t result, bool diskio_write)
-
String fatfsErrorToStr(uint8_t err)
-
ErrorCode calculateFatParam(Partition partition, const FormatOptions &opt, FatParam ¶m)
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
- Returns
ErrorCode – When partitioning using MBR format, this method can be used to determine the
Sys indicator
value setting.
-
ErrorCode formatVolume(Partition partition, const FatParam ¶m)
Format partition using pre-calculated FAT parameters.
- Parameters
partition – The partition to format
param – Detailed FAT parameters (returned from
calculateFatParam
)
- Returns
ErrorCode – This function allows fine control over exactly how a FAT partition is constructed. Generally the
calculateFatParam
function should be used to populate theparam
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
- Returns
ErrorCode –
-
struct FatParam
- #include <Format.h>
Public Members
-
uint32_t sectorsPerBlock
Flash erase block size.
-
uint16_t sectorsPerCluster
Set to 0 for auto-calculation.
-
uint32_t sectorsPerBlock
-
class FileSystem : public IFS::IFileSystem
- #include <FileSystem.h>
Wraps fatfs
Public Functions
-
virtual int mount() override
Mount file system, performing any required initialisation.
- Returns
error – code
-
virtual int getinfo(Info &info) override
get filing system information
- Parameters
info – structure to read information into
- Returns
int – error code
-
virtual int setProfiler(IProfiler *profiler) override
Set profiler instance to enable debugging and performance assessment.
- Parameters
profiler –
- Returns
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
- Returns
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
- Returns
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 –
- Returns
int – error code
-
virtual int rewinddir(DirHandle dir) override
Reset directory read position to start.
- Parameters
dir –
- Returns
int – error code
-
virtual int closedir(DirHandle dir) override
close a directory object
- Parameters
dir – directory to close
- Returns
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
- Returns
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
- Returns
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
- Returns
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.
- 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
- Returns
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
- Returns
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
- Returns
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
- Returns
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
- Returns
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
- Returns
FileHandle – file handle or error code
-
virtual int close(FileHandle file) override
close an open file
- Parameters
file – handle to open file
- Returns
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
- Returns
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
- Returns
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)
- Returns
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
- Returns
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
- Returns
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 –
- Returns
int – Error code
-
virtual int flush(FileHandle file) override
flush any buffered data to physical media
- Parameters
file – handle to open file
- Returns
int – error code
-
virtual int rename(const char *oldpath, const char *newpath) override
rename a file
- Parameters
oldpath –
newpath –
- Returns
int – error code
-
virtual int remove(const char *path) override
remove (delete) a file by path
- Parameters
path –
- Returns
int – error code
-
virtual int fremove(FileHandle file) override
remove (delete) a file by handle
- Parameters
file – handle to open file
- Returns
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.
- Returns
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,
- Returns
int – error code
-
virtual int mount() override
-
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)
-
SysTypes types = {0}
-
int translateFatfsResult(uint8_t result, bool diskio_write)
References
Environment Variables
SoC support
esp32
esp32c2
esp32c3
esp32s2
esp32s3
esp8266
host
rp2040