File System
Defines
-
CHECK_FS(_method)
Typedefs
-
using file_t = IFS::FileHandle
-
using FileHandle = IFS::FileHandle
-
using FileAttribute = IFS::FileAttribute
-
using FileAttributes = IFS::FileAttributes
Functions
-
inline IFS::FileSystem *getFileSystem()
Get the currently active file system, if any.
- Returns
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.
- Returns
bool – true on success
-
bool fwfs_mount(Storage::Partition partition)
Mount SPIFFS volume from a specific partition.
- Returns
bool – true on success
-
inline IFS::FileSystem *fileMountArchive(const String &filename)
Mount a backup archive.
- Parameters
filename – Path to archive file
- Returns
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
- Returns
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
- Returns
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
- Returns
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
- Returns
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
- Returns
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
- Returns
bool – true if at end of file
-
inline file_offset_t fileTell(FileHandle file)
Get position in file.
- Parameters
file – File handle
- Returns
file_offset_t – Read / write cursor position or error code
-
inline int fileFlush(FileHandle file)
Flush pending writes.
- Parameters
file – File handle
- Returns
int – Size of last file written or error code
-
inline String fileGetErrorString(int err)
get the text for a returned error code
- Parameters
err –
- Returns
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
- Returns
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
- Returns
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 –
- Returns
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
- Returns
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 –
- Returns
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
- Returns
int – Error code
-
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
- Returns
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
- Returns
size_t – Quantity of bytes read from file or zero on failure
-
inline int fileStats(const char *fileName, FileStat &stat)
Get file statistics.
- Parameters
name – File name
stat – Pointer to SPIFFS statistic structure to populate
- Returns
int – Error code
-
inline int fileStats(FileHandle file, FileStat &stat)
brief Get file statistics
- Parameters
file – File handle
stat – Pointer to SPIFFS statistic structure to populate
- Returns
int – Error code
-
inline int fileDelete(const char *fileName)
Delete file.
- Parameters
name – Name of file to delete
- Returns
int – Error code
-
inline int fileDelete(FileHandle file)
Delete file.
- Parameters
file – handle of file to delete
- Returns
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
- Returns
bool – true if file exists
-
inline bool dirExist(const char *dirName)
Check if a directory exists on file system.
- Parameters
dirName – Full path to directory to check for
- Returns
bool – true if directory exists
-
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
- Returns
int – Error code
-
inline int fileCloseDir(DirHandle dir)
close a directory object
- Parameters
dir – directory to close
- Returns
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
- Returns
int – Error code
-
inline int fileRewindDir(DirHandle dir)
Rewind to start of directory entries.
- Parameters
dir – The directory object returned by fileOpenDir()
- Returns
int – Error code
-
inline int fileGetSystemInfo(IFS::FileSystem::Info &info)
Get basic file system information.
- Returns
int – Error code
-
IFS::FileSystem::Type fileSystemType()
Get the type of file system currently mounted (if any)
- Returns
FileSystemType – the file system type
-
inline int fileSystemCheck()
Perform a consistency check/repair on the active file system.
- Returns
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 –
- Returns
int – Error code
-
template<typename T>
int fileSetAttr(const T &filename, FileAttributes attr) Set file attributes.
- Parameters
filename –
attr –
- Returns
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
- Returns
int – Error code
-
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.
-
IFS::FileSystem *activeFileSystem