Access file system. More...

Macros

#define CHECK_FS(_method)
 
#define IFS_ERROR_MAP(XX)
 IFS return codes. More...
 
#define XX(tag, text)   tag,
 
#define XX(tag, text)   constexpr int tag{-int(Value::tag)};
 
#define FILESYSTEM_TYPE_MAP(XX)
 Four-character tag to identify type of filing system. More...
 
#define FILE_SYSTEM_ATTR_MAP(XX)
 Attribute flags for filing system. More...
 

Typedefs

using file_t = IFS::FileHandle
 
using FileHandle = IFS::FileHandle
 
using DirHandle = IFS::DirHandle
 
using FileOpenFlag = IFS::OpenFlag
 
using FileOpenFlags = IFS::OpenFlags
 
using FileAttribute = IFS::FileAttribute
 
using FileAttributes = IFS::FileAttributes
 
using FileStat = IFS::Stat
 
using FileNameStat = IFS::NameStat
 
using File = IFS::File
 
using Directory = IFS::Directory
 
using IFS::ErrorCode = int
 

Enumerations

enum class  IFS::Error::Value { IFS::Error::XX , IFS::Error::MAX }
 

Functions

IFS::FileSystemgetFileSystem ()
 Get the currently active file system, if any. More...
 
void fileSetFileSystem (IFS::IFileSystem *fileSystem)
 Sets the currently active file system. More...
 
void fileFreeFileSystem ()
 
bool fileMountFileSystem (IFS::IFileSystem *fs)
 Mount a constructed filesystem with debug messages. More...
 
bool fwfs_mount ()
 Mount the first available FWFS volume. More...
 
bool fwfs_mount (Storage::Partition partition)
 Mount SPIFFS volume from a specific partition. More...
 
IFS::FileSystemfileMountArchive (const String &filename)
 Mount a backup archive. More...
 
template<typename T >
FileHandle fileOpen (const T &path, FileOpenFlags flags=File::ReadOnly)
 Open file by path. More...
 
int fileClose (FileHandle file)
 Clode file. More...
 
int fileWrite (FileHandle file, const void *data, size_t size)
 Write to file. More...
 
int fileTouch (FileHandle file)
 Update file modification time. More...
 
int fileRead (FileHandle file, void *data, size_t size)
 Read from file. More...
 
file_offset_t fileSeek (FileHandle file, file_offset_t offset, SeekOrigin origin)
 Position file cursor. More...
 
bool fileIsEOF (FileHandle file)
 Check if at end of file. More...
 
file_offset_t fileTell (FileHandle file)
 Get position in file. More...
 
int fileFlush (FileHandle file)
 Flush pending writes. More...
 
String fileGetErrorString (int err)
 get the text for a returned error code More...
 
template<typename TFileName >
int fileSetContent (const TFileName &fileName, const char *content, size_t length)
 Create or replace file with defined content. More...
 
template<typename TFileName , typename TContent >
int fileSetContent (const TFileName &fileName, TContent content)
 
template<typename TFileName >
file_size_t fileGetSize (const TFileName &fileName)
 Get size of file. More...
 
int fileTruncate (FileHandle file, file_size_t newSize)
 Truncate (reduce) the size of an open file. More...
 
int fileTruncate (FileHandle file)
 Truncate an open file at the current cursor position. More...
 
template<typename TFileName >
int fileTruncate (const TFileName &fileName, file_size_t newSize)
 Truncate (reduce) the size of a file. More...
 
int fileRename (const char *oldName, const char *newName)
 Rename file. More...
 
int fileRename (const String &oldName, const String &newName)
 
template<typename TFileName >
String fileGetContent (const TFileName &fileName)
 Read content of a file. More...
 
template<typename TFileName >
size_t fileGetContent (const TFileName &fileName, char *buffer, size_t bufSize)
 Read content of a file. More...
 
template<typename TFileName >
size_t fileGetContent (const TFileName &fileName, char *buffer)
 
int fileStats (const char *fileName, FileStat &stat)
 Get file statistics. More...
 
int fileStats (const String &fileName, FileStat &stat)
 
int fileStats (FileHandle file, FileStat &stat)
 
int fileDelete (const char *fileName)
 Delete file. More...
 
int fileDelete (const String &fileName)
 
int fileDelete (FileHandle file)
 Delete file. More...
 
bool fileExist (const char *fileName)
 Check if a file exists on file system. More...
 
bool fileExist (const String &fileName)
 
bool dirExist (const char *dirName)
 Check if a directory exists on file system. More...
 
bool dirExist (const String &dirName)
 
int fileOpenDir (const char *dirName, DirHandle &dir)
 Open a named directory for reading. More...
 
int fileOpenDir (const String &dirName, DirHandle &dir)
 
int fileOpenRootDir (DirHandle &dir)
 
int fileCloseDir (DirHandle dir)
 close a directory object More...
 
int fileReadDir (DirHandle dir, FileStat &stat)
 Read a directory entry. More...
 
int fileRewindDir (DirHandle dir)
 Rewind to start of directory entries. More...
 
int fileGetSystemInfo (IFS::FileSystem::Info &info)
 Get basic file system information. More...
 
IFS::FileSystem::Type fileSystemType ()
 Get the type of file system currently mounted (if any) More...
 
int fileSystemFormat ()
 Format the active file system. More...
 
int fileSystemCheck ()
 Perform a consistency check/repair on the active file system. More...
 
int fileSetACL (FileHandle file, const IFS::ACL &acl)
 Set access control information. More...
 
template<typename T >
int fileSetAttr (const T &filename, FileAttributes attr)
 Set file attributes. More...
 
int fileSetTime (FileHandle file, time_t mtime)
 Set access control information for file. More...
 
template<typename T >
int createDirectory (const T &path)
 Create a directory. More...
 
template<typename T >
int createDirectories (const T &path)
 Create a directory and all required parent directories. More...
 
String IFS::Error::toString (int err)
 get text for an error code More...
 
bool IFS::Error::isSystem (int err)
 Determine if the given IFS error code is system-specific. More...
 
int IFS::Error::fromSystem (int syscode)
 Translate system error code into IFS error code. More...
 
int IFS::Error::toSystem (int err)
 Translate IFS error code into SYSTEM code. More...
 
String toString (IFS::IFileSystem::Type type)
 Get String for filesystem type. More...
 
String toString (IFS::IFileSystem::Attribute attr)
 Get String for a filesystem attribute. More...
 

Variables

constexpr int FS_OK = IFS::FS_OK
 
constexpr ErrorCode IFS::Error::USER {-100}
 
constexpr ErrorCode IFS::Error::SYSTEM {-1000}
 
constexpr ErrorCode IFS::FS_OK = Error::Success
 

Detailed Description

Access file system.

Installable file system.

Macro Definition Documentation

◆ CHECK_FS

#define CHECK_FS (   _method)
Value:
auto fileSystem = static_cast<IFS::FileSystem*>(SmingInternal::activeFileSystem); \
if(fileSystem == nullptr) { \
debug_e("ERROR in %s(): No active file system", __FUNCTION__); \
return FileHandle(IFS::Error::NoFileSystem); \
}
Installable File System base class.
Definition: Components/IFS/src/include/IFS/FileSystem.h:40
IFS::FileHandle FileHandle
Definition: Core/FileSystem.h:24
IFS::FileSystem * activeFileSystem
Global file system instance.

◆ FILE_SYSTEM_ATTR_MAP

#define FILE_SYSTEM_ATTR_MAP (   XX)
Value:
XX(Mounted, "Filing system is mounted and in use") \
XX(ReadOnly, "Writing not permitted to this volume") \
XX(Virtual, "Virtual filesystem, doesn't host files directly") \
XX(Check, "Volume check recommended") \
XX(NoMeta, "Metadata unsupported")
#define XX(_name, _tag, _desc)
Definition: IFileSystem.h:110

Attribute flags for filing system.

◆ FILESYSTEM_TYPE_MAP

#define FILESYSTEM_TYPE_MAP (   XX)
Value:
XX(Unknown, NULL, "Unknown") \
XX(FWFS, FWFS, "Firmware File System") \
XX(SPIFFS, SPIF, "SPI Flash File System (SPIFFS)") \
XX(LittleFS, LFS, "Little FS") \
XX(Hybrid, HYFS, "Hybrid File System") \
XX(Host, HOST, "Host File System") \
XX(Fat, FAT, "FAT File System") \
XX(Fat32, FAT32, "FAT32 File System") \
XX(ExFat, exFAT, "EXFAT File System")
Definition: Streams.h:25

Four-character tag to identify type of filing system.

Note
As new filing systems are incorporated into IFS, update this enumeration

◆ IFS_ERROR_MAP

#define IFS_ERROR_MAP (   XX)
Value:
XX(Success, "Success") \
XX(NoFileSystem, "File system has not been set") \
XX(NoPartition, "Partition not found / undefined") \
XX(BadPartition, "Partition is not valid for this filesystem") \
XX(BadVolumeIndex, "Volume index is invalid") \
XX(NotMounted, "File system is not mounted") \
XX(BadObject, "Malformed filesystem object") \
XX(BadFileSystem, "File system corruption detected") \
XX(BadParam, "Invalid parameter(s)") \
XX(NotImplemented, "File system or method not yet implemented") \
XX(NotSupported, "Parameter value not supported") \
XX(NoMem, "Memory allocation failed") \
XX(NameTooLong, "File name or path is too long for buffer") \
XX(BufferTooSmall, "Data is too long for buffer") \
XX(NotFound, "Object not found") \
XX(Exists, "File/directory exists") \
XX(ReadOnly, "Media is read-only") \
XX(ReadFailure, "Media read failed") \
XX(WriteFailure, "Media write failed") \
XX(EraseFailure, "Media erase failed") \
XX(InvalidHandle, "File handle is outside valid range") \
XX(EndOfObjects, "Last object in filing system has been read") \
XX(FileNotOpen, "File handle is valid but the file is not open") \
XX(SeekBounds, "seek would give an invalid file offset") \
XX(NoMoreFiles, "readdir has no more files to return") \
XX(OutOfFileDescs, "Cannot open another file until one is closed") \
XX(Denied, "Operation denied") \
XX(NoSpace, "No free space") \
XX(TooBig, "File size too big")
#define XX(tag, text)
Definition: Components/IFS/src/include/IFS/Error.h:90

IFS return codes.

An IFS implementation must return negative values for errors. Wrappers may use these IFS codes instead of their own. If returning an internal error code it may need to be translated. Methods returning ONLY an error code (i.e. not FileHandle) may return positive 'error' codes for information purposes. See IFileSystem::check() as an example. Return value usage is consistent with SPIFFS.

These codes are allocated using an enum since they are purely for internal purposes.

◆ XX [1/2]

#define XX (   tag,
  text 
)    tag,

◆ XX [2/2]

#define XX (   tag,
  text 
)    constexpr int tag{-int(Value::tag)};

Typedef Documentation

◆ Directory

◆ DirHandle

◆ ErrorCode

using IFS::ErrorCode = typedef int

◆ File

using File = IFS::File

◆ file_t

◆ FileAttribute

◆ FileAttributes

◆ FileHandle

◆ FileNameStat

◆ FileOpenFlag

◆ FileOpenFlags

◆ FileStat

Enumeration Type Documentation

◆ Value

enum IFS::Error::Value
strong
Enumerator
XX 
MAX 

Function Documentation

◆ createDirectories()

template<typename T >
int createDirectories ( const T &  path)

Create a directory and all required parent directories.

Parameters
pathPath to directory
Return values
intError code

◆ createDirectory()

template<typename T >
int createDirectory ( const T &  path)

Create a directory.

Parameters
pathPath to directory
Return values
intError code

◆ dirExist() [1/2]

bool dirExist ( const char *  dirName)
inline

Check if a directory exists on file system.

Parameters
dirNameFull path to directory to check for
Return values
booltrue if directory exists

◆ dirExist() [2/2]

bool dirExist ( const String dirName)
inline

◆ fileClose()

int fileClose ( FileHandle  file)
inline

Clode file.

Parameters
fileHandle of file to close
Note
File Handle is returned from fileOpen function

◆ fileCloseDir()

int fileCloseDir ( DirHandle  dir)
inline

close a directory object

Parameters
dirdirectory to close
Return values
intError code

◆ fileDelete() [1/3]

int fileDelete ( const char *  fileName)
inline

Delete file.

Parameters
nameName of file to delete
Return values
intError code

◆ fileDelete() [2/3]

int fileDelete ( const String fileName)
inline

◆ fileDelete() [3/3]

int fileDelete ( FileHandle  file)
inline

Delete file.

Parameters
filehandle of file to delete
Return values
intError code

◆ fileExist() [1/2]

bool fileExist ( const char *  fileName)
inline

Check if a file exists on file system.

Parameters
fileNameFull path to file to check for
Return values
booltrue if file exists

◆ fileExist() [2/2]

bool fileExist ( const String fileName)
inline

◆ fileFlush()

int fileFlush ( FileHandle  file)
inline

Flush pending writes.

Parameters
fileFile handle
Return values
intSize of last file written or error code

◆ fileFreeFileSystem()

void fileFreeFileSystem ( )
inline

◆ fileGetContent() [1/3]

template<typename TFileName >
String fileGetContent ( const TFileName &  fileName)

Read content of a file.

Parameters
fileNameName of file to read from
Return values
StringString variable in to which to read the file content
Note
After calling this function the content of the file is placed in to a string. The result will be an invalid String (equates to false) if the file could not be read. If the file exists, but is empty, the result will be an empty string "".

◆ fileGetContent() [2/3]

template<typename TFileName >
size_t fileGetContent ( const TFileName &  fileName,
char *  buffer 
)
inline

◆ fileGetContent() [3/3]

template<typename TFileName >
size_t fileGetContent ( const TFileName &  fileName,
char *  buffer,
size_t  bufSize 
)
inline

Read content of a file.

Parameters
fileNameName of file to read from
bufferPointer to a character buffer in to which to read the file content
bufSizeQuantity of bytes to read from file
Return values
size_tQuantity of bytes read from file or zero on failure
Note
After calling this function the content of the file is placed in to a c-string Ensure there is sufficient space in the buffer for file content plus extra trailing null, i.e. at least bufSize + 1 Always check the return value!
Returns 0 if the file could not be read

◆ fileGetErrorString()

String fileGetErrorString ( int  err)
inline

get the text for a returned error code

Parameters
err
Return values
String

◆ fileGetSize()

template<typename TFileName >
file_size_t fileGetSize ( const TFileName &  fileName)
inline

Get size of file.

Parameters
fileNameName of file
Return values
file_size_tSize of file in bytes, 0 on error

◆ fileGetSystemInfo()

int fileGetSystemInfo ( IFS::FileSystem::Info info)
inline

Get basic file system information.

Return values
intError code

◆ fileIsEOF()

bool fileIsEOF ( FileHandle  file)
inline

Check if at end of file.

Parameters
fileFile handle
Return values
booltrue if at end of file

◆ fileMountArchive()

IFS::FileSystem* fileMountArchive ( const String filename)
inline

Mount a backup archive.

Parameters
filenamePath to archive file
Return values
IFS::FileSystem*Mounted filesystem. Caller must delete when finished.

◆ fileMountFileSystem()

bool fileMountFileSystem ( IFS::IFileSystem fs)

Mount a constructed filesystem with debug messages.

◆ fileOpen()

template<typename T >
FileHandle fileOpen ( const T &  path,
FileOpenFlags  flags = File::ReadOnly 
)
inline

Open file by path.

Parameters
pathFull path to file
flagsMode to open file
Return values
fileFile handle or negative error code

◆ fileOpenDir() [1/2]

int fileOpenDir ( const char *  dirName,
DirHandle dir 
)
inline

Open a named directory for reading.

Parameters
nameName of directory to open, empty or "/" for root
dirDirectory object
Return values
intError code

◆ fileOpenDir() [2/2]

int fileOpenDir ( const String dirName,
DirHandle dir 
)
inline

◆ fileOpenRootDir()

int fileOpenRootDir ( DirHandle dir)
inline

◆ fileRead()

int fileRead ( FileHandle  file,
void *  data,
size_t  size 
)
inline

Read from file.

Parameters
fileFile handle
dataPointer to data buffer in to which to read data
sizeQuantity of data elements to read from file
Return values
intQuantity of data elements actually read from file or negative error code

◆ fileReadDir()

int fileReadDir ( DirHandle  dir,
FileStat stat 
)
inline

Read a directory entry.

Parameters
dirThe directory object returned by fileOpenDir()
statThe returned information, owned by DirHandle object
Return values
intError code

◆ fileRename() [1/2]

int fileRename ( const char *  oldName,
const char *  newName 
)
inline

Rename file.

Parameters
oldNameOriginal name of file to rename
newNameNew name for file
Return values
intError code

◆ fileRename() [2/2]

int fileRename ( const String oldName,
const String newName 
)
inline

◆ fileRewindDir()

int fileRewindDir ( DirHandle  dir)
inline

Rewind to start of directory entries.

Parameters
dirThe directory object returned by fileOpenDir()
Return values
intError code

◆ fileSeek()

file_offset_t fileSeek ( FileHandle  file,
file_offset_t  offset,
SeekOrigin  origin 
)
inline

Position file cursor.

Parameters
fileFile handle
offsetQuantity of bytes to move cursor
originPosition from where to move cursor
Return values
file_offset_tOffset within file or negative error code

◆ fileSetACL()

int fileSetACL ( FileHandle  file,
const IFS::ACL acl 
)
inline

Set access control information.

Parameters
fileFile handle
acl
Return values
intError code

◆ fileSetAttr()

template<typename T >
int fileSetAttr ( const T &  filename,
FileAttributes  attr 
)

Set file attributes.

Parameters
filename
attr
Return values
intError code

◆ fileSetContent() [1/2]

template<typename TFileName >
int fileSetContent ( const TFileName &  fileName,
const char *  content,
size_t  length 
)
inline

Create or replace file with defined content.

Parameters
fileNameName of file to create or replace
contentPointer to c-string containing content to populate file with
lengthNumber of characters to write
Return values
intNumber of bytes transferred or error code
Note
This function creates a new file or replaces an existing file and populates the file with the content of a c-string buffer.

◆ fileSetContent() [2/2]

template<typename TFileName , typename TContent >
int fileSetContent ( const TFileName &  fileName,
TContent  content 
)
inline

◆ fileSetFileSystem()

void fileSetFileSystem ( IFS::IFileSystem fileSystem)

Sets the currently active file system.

Parameters
fileSystem
Note
Any existing filing system is destroyed. Typically the filing system implementation has helper functions which create and initialise the file system to a valid state. The last step is to call this function to make it active. Call this function with nullptr to deactivate the filing system.

◆ fileSetTime()

int fileSetTime ( FileHandle  file,
time_t  mtime 
)
inline

Set access control information for file.

Parameters
filehandle to open file, must have write access
Return values
intError code
Note
any writes to file will reset this to current time

◆ fileStats() [1/3]

int fileStats ( const char *  fileName,
FileStat stat 
)
inline

Get file statistics.

Parameters
nameFile name
statPointer to SPIFFS statistic structure to populate
Return values
intError code

◆ fileStats() [2/3]

int fileStats ( const String fileName,
FileStat stat 
)
inline

◆ fileStats() [3/3]

int fileStats ( FileHandle  file,
FileStat stat 
)
inline

brief Get file statistics

Parameters
fileFile handle
statPointer to SPIFFS statistic structure to populate
Return values
intError code

◆ fileSystemCheck()

int fileSystemCheck ( )
inline

Perform a consistency check/repair on the active file system.

Return values
int0 if OK, < 0 unrecoverable errors, > 0 repairs required

◆ fileSystemFormat()

int fileSystemFormat ( )
inline

Format the active file system.

Return values
intError code

◆ fileSystemType()

IFS::FileSystem::Type fileSystemType ( )

Get the type of file system currently mounted (if any)

Return values
FileSystemTypethe file system type

◆ fileTell()

file_offset_t fileTell ( FileHandle  file)
inline

Get position in file.

Parameters
fileFile handle
Return values
file_offset_tRead / write cursor position or error code

◆ fileTouch()

int fileTouch ( FileHandle  file)
inline

Update file modification time.

Parameters
fileFile handle
Return values
intError code

◆ fileTruncate() [1/3]

template<typename TFileName >
int fileTruncate ( const TFileName &  fileName,
file_size_t  newSize 
)

Truncate (reduce) the size of a file.

Parameters
fileName
newSize
Return values
intError code
Note
In POSIX truncate() can also make the file bigger, however SPIFFS can only reduce the file size and will return an error if newSize > fileSize

◆ fileTruncate() [2/3]

int fileTruncate ( FileHandle  file)
inline

Truncate an open file at the current cursor position.

Parameters
fileOpen file handle, must have Write access
Return values
intError code

◆ fileTruncate() [3/3]

int fileTruncate ( FileHandle  file,
file_size_t  newSize 
)
inline

Truncate (reduce) the size of an open file.

Parameters
fileOpen file handle, must have Write access
newSize
Return values
intError code
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

◆ fileWrite()

int fileWrite ( FileHandle  file,
const void *  data,
size_t  size 
)
inline

Write to file.

Parameters
fileFile handle
dataPointer to data to write to file
sizeQuantity of data elements to write to file
Return values
intQuantity of data elements actually written to file or negative error code

◆ fromSystem()

int IFS::Error::fromSystem ( int  syscode)
inline

Translate system error code into IFS error code.

◆ fwfs_mount() [1/2]

bool fwfs_mount ( )

Mount the first available FWFS volume.

Return values
booltrue on success

◆ fwfs_mount() [2/2]

bool fwfs_mount ( Storage::Partition  partition)

Mount SPIFFS volume from a specific partition.

Return values
booltrue on success

◆ getFileSystem()

IFS::FileSystem* getFileSystem ( )
inline

Get the currently active file system, if any.

Return values
IFS::FileSystem*

◆ isSystem()

bool IFS::Error::isSystem ( int  err)
inline

Determine if the given IFS error code is system-specific.

◆ toString() [1/3]

String toString ( IFS::IFileSystem::Attribute  attr)

Get String for a filesystem attribute.

◆ toString() [2/3]

String toString ( IFS::IFileSystem::Type  type)

Get String for filesystem type.

◆ toString() [3/3]

String IFS::Error::toString ( int  err)

get text for an error code

Parameters
err
Return values
String

◆ toSystem()

int IFS::Error::toSystem ( int  err)
inline

Translate IFS error code into SYSTEM code.

Variable Documentation

◆ FS_OK [1/2]

constexpr ErrorCode IFS::FS_OK = Error::Success
constexpr

◆ FS_OK [2/2]

constexpr int FS_OK = IFS::FS_OK
constexpr

◆ SYSTEM

constexpr ErrorCode IFS::Error::SYSTEM {-1000}
constexpr

◆ USER

constexpr ErrorCode IFS::Error::USER {-100}
constexpr