File System

Defines

CHECK_FS(_method)

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 

Functions

inline IFS::FileSystem *getFileSystem()

Get the currently active file system, if any.

Return values:: IFS::FileSystem* –

void fileSetFileSystem(IFS::IFileSystem *fileSystem)

Sets the currently active file system.

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.

Parameters:: fileSystem –

inline void fileFreeFileSystem()

bool fileMountFileSystem(IFS::IFileSystem *fs): Mount a constructed filesystem with debug messages.

bool fwfs_mount()

Mount the first available FWFS volume.

Return values:: bool – true on success

bool fwfs_mount(Storage::Partition partition)

Mount SPIFFS volume from a specific partition.

Return values:: bool – true on success

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

Mount a backup archive.

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

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

Open file by path.

Parameters:

path – Full path to file
flags – Mode to open file

Return values:

file – File handle or negative error code

inline int fileClose(FileHandle file)

Clode file.

Note

File Handle is returned from fileOpen function

Parameters:: file – Handle of file to close

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

Write to file.

Parameters:

file – File handle
data – Pointer to data to write to file
size – Quantity of data elements to write to file

Return values:

int – Quantity of data elements actually written to file or negative error code

inline int fileTouch(FileHandle file)

Update file modification time.

Parameters:: file – File handle
Return values:: int – Error code

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

Read from file.

Parameters:

file – File handle
data – Pointer to data buffer in to which to read data
size – Quantity of data elements to read from file

Return values:

int – Quantity of data elements actually read from file or negative error code

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

Position file cursor.

Parameters:

file – File handle
offset – Quantity of bytes to move cursor
origin – Position from where to move cursor

Return values:

file_offset_t – Offset within file or negative error code

inline bool fileIsEOF(FileHandle file)

Check if at end of file.

Parameters:: file – File handle
Return values:: bool – true if at end of file

inline file_offset_t fileTell(FileHandle file)

Get position in file.

Parameters:: file – File handle
Return values:: file_offset_t – Read / write cursor position or error code

inline int fileFlush(FileHandle file)

Flush pending writes.

Parameters:: file – File handle
Return values:: int – Size of last file written or error code

inline String fileGetErrorString(int err)

get the text for a returned error code

Parameters:: err –
Return values:: String –

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

Create or replace file with defined content.

Note

This function creates a new file or replaces an existing file and populates the file with the content of a c-string buffer.

Parameters:

fileName – Name of file to create or replace
content – Pointer to c-string containing content to populate file with
length – Number of characters to write

Return values:

int – Number of bytes transferred or error code

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

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

Get size of file.

Parameters:: fileName – Name of file
Return values:: file_size_t – Size of file in bytes, 0 on error

inline int fileTruncate(FileHandle file, file_size_t newSize)

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

inline int fileTruncate(FileHandle file)

Truncate an open file at the current cursor position.

Parameters:: file – Open file handle, must have Write access
Return values:: int – Error code

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

Truncate (reduce) the size of a file.

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

Parameters:

fileName –
newSize –

Return values:

int – Error code

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

Rename file.

Parameters:

oldName – Original name of file to rename
newName – New name for file

Return values:

int – Error code

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

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

Read content of a file.

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

Parameters:: fileName – Name of file to read from
Return values:: String – String variable in to which to read the file content

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

Read content of a file.

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!

Note

Returns 0 if the file could not be read

Parameters:

fileName – Name of file to read from
buffer – Pointer to a character buffer in to which to read the file content
bufSize – Quantity of bytes to read from file

Return values:

size_t – Quantity of bytes read from file or zero on failure

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

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

Get file statistics.

Parameters:

name – File name
stat – Pointer to SPIFFS statistic structure to populate

Return values:

int – Error code

inline int fileStats(const String &fileName, FileStat &stat)

inline int fileStats(FileHandle file, FileStat &stat)

brief Get file statistics

Parameters:

file – File handle
stat – Pointer to SPIFFS statistic structure to populate

Return values:

int – Error code

inline int fileDelete(const char *fileName)

Delete file.

Parameters:: name – Name of file to delete
Return values:: int – Error code

inline int fileDelete(const String &fileName)

inline int fileDelete(FileHandle file)

Delete file.

Parameters:: file – handle of file to delete
Return values:: int – Error code

inline bool fileExist(const char *fileName)

Check if a file exists on file system.

Parameters:: fileName – Full path to file to check for
Return values:: bool – true if file exists

inline bool fileExist(const String &fileName)

inline bool dirExist(const char *dirName)

Check if a directory exists on file system.

Parameters:: dirName – Full path to directory to check for
Return values:: bool – true if directory exists

inline bool dirExist(const String &dirName)

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

Open a named directory for reading.

Parameters:

name – Name of directory to open, empty or “/” for root
dir – Directory object

Return values:

int – Error code

inline int fileOpenDir(const String &dirName, DirHandle &dir)

inline int fileOpenRootDir(DirHandle &dir)

inline int fileCloseDir(DirHandle dir)

close a directory object

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

inline int fileReadDir(DirHandle dir, FileStat &stat)

Read a directory entry.

Parameters:

dir – The directory object returned by fileOpenDir()
stat – The returned information, owned by DirHandle object

Return values:

int – Error code

inline int fileRewindDir(DirHandle dir)

Rewind to start of directory entries.

Parameters:: dir – The directory object returned by fileOpenDir()
Return values:: int – Error code

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

Get basic file system information.

Return values:: int – Error code

IFS::FileSystem::Type fileSystemType()

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

Return values:: FileSystemType – the file system type

inline int fileSystemFormat()

Format the active file system.

Return values:: int – Error code

inline int fileSystemCheck()

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

Return values:: int – 0 if OK, < 0 unrecoverable errors, > 0 repairs required

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

Set access control information.

Parameters:

file – File handle
acl –

Return values:

int – Error code

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

Set file attributes.

Parameters:

filename –
attr –

Return values:

int – Error code

inline int fileSetTime(FileHandle file, time_t mtime)

Set access control information for file.

Note

any writes to file will reset this to current time

Parameters:: file – handle to open file, must have write access
Return values:: int – Error code

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

Create a directory.

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

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

Create a directory and all required parent directories.

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

Variables

constexpr int FS_OK = IFS::FS_OK 

namespace SmingInternal

Variables

IFS::FileSystem *activeFileSystem

Global file system instance.

Filing system implementations should use helper functions to setup and initialise a filing system. If successful, call fileSetFileSystem() to make it active. This ensures that any active filing system is dismounted destroyed first.