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::FileSystem * | getFileSystem () |
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::FileSystem * | fileMountArchive (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 | ) |
◆ FILE_SYSTEM_ATTR_MAP
#define FILE_SYSTEM_ATTR_MAP | ( | XX | ) |
Attribute flags for filing system.
◆ FILESYSTEM_TYPE_MAP
#define FILESYSTEM_TYPE_MAP | ( | XX | ) |
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 | ) |
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
using Directory = IFS::Directory |
◆ DirHandle
using DirHandle = IFS::DirHandle |
◆ ErrorCode
using IFS::ErrorCode = typedef int |
◆ File
◆ file_t
using file_t = IFS::FileHandle |
◆ FileAttribute
using FileAttribute = IFS::FileAttribute |
◆ FileAttributes
using FileAttributes = IFS::FileAttributes |
◆ FileHandle
using FileHandle = IFS::FileHandle |
◆ FileNameStat
using FileNameStat = IFS::NameStat |
◆ FileOpenFlag
using FileOpenFlag = IFS::OpenFlag |
◆ FileOpenFlags
using FileOpenFlags = IFS::OpenFlags |
◆ FileStat
Enumeration Type Documentation
◆ Value
|
strong |
Function Documentation
◆ createDirectories()
int createDirectories | ( | const T & | path | ) |
Create a directory and all required parent directories.
- Parameters
-
path Path to directory
- Return values
-
int Error code
◆ createDirectory()
int createDirectory | ( | const T & | path | ) |
Create a directory.
- Parameters
-
path Path to directory
- Return values
-
int Error code
◆ dirExist() [1/2]
|
inline |
Check if a directory exists on file system.
- Parameters
-
dirName Full path to directory to check for
- Return values
-
bool true if directory exists
◆ dirExist() [2/2]
|
inline |
◆ fileClose()
|
inline |
Clode file.
- Parameters
-
file Handle of file to close
- Note
- File Handle is returned from fileOpen function
◆ fileCloseDir()
|
inline |
close a directory object
- Parameters
-
dir directory to close
- Return values
-
int Error code
◆ fileDelete() [1/3]
|
inline |
Delete file.
- Parameters
-
name Name of file to delete
- Return values
-
int Error code
◆ fileDelete() [2/3]
|
inline |
◆ fileDelete() [3/3]
|
inline |
Delete file.
- Parameters
-
file handle of file to delete
- Return values
-
int Error code
◆ fileExist() [1/2]
|
inline |
Check if a file exists on file system.
- Parameters
-
fileName Full path to file to check for
- Return values
-
bool true if file exists
◆ fileExist() [2/2]
|
inline |
◆ fileFlush()
|
inline |
Flush pending writes.
- Parameters
-
file File handle
- Return values
-
int Size of last file written or error code
◆ fileFreeFileSystem()
|
inline |
◆ fileGetContent() [1/3]
String fileGetContent | ( | const TFileName & | fileName | ) |
Read content of a file.
- Parameters
-
fileName Name of file to read from
- 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]
|
inline |
◆ fileGetContent() [3/3]
|
inline |
Read content of a file.
- 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
- 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()
|
inline |
◆ fileGetSize()
|
inline |
Get size of file.
- Parameters
-
fileName Name of file
- Return values
-
file_size_t Size of file in bytes, 0 on error
◆ fileGetSystemInfo()
|
inline |
Get basic file system information.
- Return values
-
int Error code
◆ fileIsEOF()
|
inline |
Check if at end of file.
- Parameters
-
file File handle
- Return values
-
bool true if at end of file
◆ fileMountArchive()
|
inline |
Mount a backup archive.
- Parameters
-
filename Path 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()
|
inline |
Open file by path.
- Parameters
-
path Full path to file flags Mode to open file
- Return values
-
file File handle or negative error code
◆ fileOpenDir() [1/2]
|
inline |
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
◆ fileOpenDir() [2/2]
◆ fileOpenRootDir()
|
inline |
◆ fileRead()
|
inline |
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
◆ fileReadDir()
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
◆ fileRename() [1/2]
|
inline |
Rename file.
- Parameters
-
oldName Original name of file to rename newName New name for file
- Return values
-
int Error code
◆ fileRename() [2/2]
◆ fileRewindDir()
|
inline |
Rewind to start of directory entries.
- Parameters
-
dir The directory object returned by fileOpenDir()
- Return values
-
int Error code
◆ fileSeek()
|
inline |
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
◆ fileSetACL()
|
inline |
Set access control information.
- Parameters
-
file File handle acl
- Return values
-
int Error code
◆ fileSetAttr()
int fileSetAttr | ( | const T & | filename, |
FileAttributes | attr | ||
) |
Set file attributes.
- Parameters
-
filename attr
- Return values
-
int Error code
◆ fileSetContent() [1/2]
|
inline |
Create or replace file with defined content.
- 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
- 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]
|
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()
|
inline |
Set access control information for file.
- Parameters
-
file handle to open file, must have write access
- Return values
-
int Error code
- Note
- any writes to file will reset this to current time
◆ fileStats() [1/3]
|
inline |
Get file statistics.
- Parameters
-
name File name stat Pointer to SPIFFS statistic structure to populate
- Return values
-
int Error code
◆ fileStats() [2/3]
◆ fileStats() [3/3]
|
inline |
brief Get file statistics
- Parameters
-
file File handle stat Pointer to SPIFFS statistic structure to populate
- Return values
-
int Error code
◆ fileSystemCheck()
|
inline |
Perform a consistency check/repair on the active file system.
- Return values
-
int 0 if OK, < 0 unrecoverable errors, > 0 repairs required
◆ fileSystemFormat()
|
inline |
Format the active file system.
- Return values
-
int Error code
◆ fileSystemType()
IFS::FileSystem::Type fileSystemType | ( | ) |
Get the type of file system currently mounted (if any)
- Return values
-
FileSystemType the file system type
◆ fileTell()
|
inline |
Get position in file.
- Parameters
-
file File handle
- Return values
-
file_offset_t Read / write cursor position or error code
◆ fileTouch()
|
inline |
Update file modification time.
- Parameters
-
file File handle
- Return values
-
int Error code
◆ fileTruncate() [1/3]
int fileTruncate | ( | const TFileName & | fileName, |
file_size_t | newSize | ||
) |
Truncate (reduce) the size of a file.
- Parameters
-
fileName newSize
- Return values
-
int Error 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]
|
inline |
Truncate an open file at the current cursor position.
- Parameters
-
file Open file handle, must have Write access
- Return values
-
int Error code
◆ fileTruncate() [3/3]
|
inline |
Truncate (reduce) the size of an open file.
- Parameters
-
file Open file handle, must have Write access newSize
- Return values
-
int Error 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()
|
inline |
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
◆ fromSystem()
|
inline |
Translate system error code into IFS error code.
◆ fwfs_mount() [1/2]
bool fwfs_mount | ( | ) |
Mount the first available FWFS volume.
- Return values
-
bool true on success
◆ fwfs_mount() [2/2]
bool fwfs_mount | ( | Storage::Partition | partition | ) |
Mount SPIFFS volume from a specific partition.
- Return values
-
bool true on success
◆ getFileSystem()
|
inline |
Get the currently active file system, if any.
- Return values
-
IFS::FileSystem*
◆ isSystem()
|
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 | ) |
◆ toSystem()
|
inline |
Translate IFS error code into SYSTEM code.
Variable Documentation
◆ FS_OK [1/2]
|
constexpr |
◆ FS_OK [2/2]
|
constexpr |
◆ SYSTEM
|
constexpr |
◆ USER
|
constexpr |