Installable File System base class. More...
#include <IFileSystem.h>
Classes | |
struct | Info |
Basic information about filing system. More... | |
struct | NameInfo |
Filing system information with buffer for name. More... | |
Public Types | |
enum | Type { Type::XX, Type::MAX } |
enum | Attribute { Attribute::XX, Attribute::MAX } |
using | Attributes = BitSet< uint8_t, Attribute, size_t(Attribute::MAX)> |
Public Member Functions | |
virtual | ~IFileSystem () |
Filing system implementations should dismount and cleanup here. More... | |
virtual int | mount ()=0 |
Mount file system, performing any required initialisation. More... | |
virtual int | getinfo (Info &info)=0 |
get filing system information More... | |
virtual int | setProfiler (IProfiler *profiler) |
Set profiler instance to enable debugging and performance assessment. More... | |
virtual String | getErrorString (int err) |
get the text for a returned error code More... | |
virtual int | setVolume (uint8_t index, IFileSystem *fileSystem) |
Set volume for mountpoint. More... | |
virtual int | opendir (const char *path, DirHandle &dir)=0 |
open a directory for reading More... | |
virtual int | readdir (DirHandle dir, Stat &stat)=0 |
read a directory entry More... | |
virtual int | rewinddir (DirHandle dir)=0 |
Reset directory read position to start. More... | |
virtual int | closedir (DirHandle dir)=0 |
close a directory object More... | |
virtual int | mkdir (const char *path)=0 |
Create a directory. More... | |
virtual int | stat (const char *path, Stat *stat)=0 |
get file information More... | |
virtual int | fstat (FileHandle file, Stat *stat)=0 |
get file information More... | |
virtual int | fcontrol (FileHandle file, ControlCode code, void *buffer, size_t bufSize) |
Low-level and non-standard file control operations. More... | |
virtual FileHandle | open (const char *path, OpenFlags flags)=0 |
open a file (or directory) by path More... | |
virtual int | close (FileHandle file)=0 |
close an open file More... | |
virtual int | read (FileHandle file, void *data, size_t size)=0 |
read content from a file and advance cursor More... | |
virtual int | write (FileHandle file, const void *data, size_t size)=0 |
write content to a file at current position and advance cursor More... | |
virtual file_offset_t | lseek (FileHandle file, file_offset_t offset, SeekOrigin origin)=0 |
change file read/write position More... | |
virtual int | eof (FileHandle file)=0 |
determine if current file position is at end of file More... | |
virtual file_offset_t | tell (FileHandle file)=0 |
get current file position More... | |
virtual int | ftruncate (FileHandle file, file_size_t new_size)=0 |
Truncate (reduce) the size of an open file. More... | |
virtual int | flush (FileHandle file)=0 |
flush any buffered data to physical media More... | |
virtual int | fsetxattr (FileHandle file, AttributeTag tag, const void *data, size_t size)=0 |
Set an extended attribute on an open file. More... | |
virtual int | fgetxattr (FileHandle file, AttributeTag tag, void *buffer, size_t size)=0 |
Get an extended attribute from an open file. More... | |
virtual int | fenumxattr (FileHandle file, AttributeEnumCallback callback, void *buffer, size_t bufsize)=0 |
Enumerate attributes. More... | |
virtual int | setxattr (const char *path, AttributeTag tag, const void *data, size_t size)=0 |
Set an extended attribute for a file given its path. More... | |
virtual int | getxattr (const char *path, AttributeTag tag, void *buffer, size_t size)=0 |
Get an attribute from a file given its path. More... | |
virtual int | fgetextents (FileHandle file, Storage::Partition *part, Extent *list, uint16_t extcount) |
Get extents for a file. More... | |
virtual int | rename (const char *oldpath, const char *newpath)=0 |
rename a file More... | |
virtual int | remove (const char *path)=0 |
remove (delete) a file by path More... | |
virtual int | fremove (FileHandle file)=0 |
remove (delete) a file by handle More... | |
virtual int | format ()=0 |
format the filing system More... | |
virtual int | check () |
Perform a file system consistency check. More... | |
Detailed Description
Installable File System base class.
- Note
- The 'I' implies Installable but could be for Interface :-)
Construction and initialisation of a filing system is implementation-dependent so there are no methods here for that.
Methods are defined as virtual abstract unless we actually have a default base implementation. Whilst some methods could just return Error::NotImplemented by default, keeping them abstract forces all file system implementations to consider them so provides an extra check for completeness.
Member Typedef Documentation
◆ Attributes
Member Enumeration Documentation
◆ Attribute
|
strong |
◆ Type
|
strong |
Constructor & Destructor Documentation
◆ ~IFileSystem()
|
inlinevirtual |
Filing system implementations should dismount and cleanup here.
Member Function Documentation
◆ check()
|
inlinevirtual |
Perform a file system consistency check.
- Return values
-
int error code
- Note
- if possible, issues should be resolved. Returns 0 if file system checked out OK. Otherwise there were issues: < 0 for unrecoverable errors,
0 for recoverable errors.
Reimplemented in IFS::Gdb::FileSystem, IFS::FWFS::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ close()
|
pure virtual |
close an open file
- Parameters
-
file handle to open file
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ closedir()
close a directory object
- Parameters
-
dir directory to close
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ eof()
|
pure virtual |
determine if current file position is at end of file
- Parameters
-
file handle to open file
- Return values
-
int 0 - not EOF, > 0 - at EOF, < 0 - error
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ fcontrol()
|
inlinevirtual |
Low-level and non-standard file control operations.
- Parameters
-
file code FCNTL_XXX code buffer Input/Output buffer bufSize Size of buffer
- Return values
-
int error code or, on success, data size
To simplify usage the same buffer is used for both input and output. Only the size of the buffer is provided. If a specific FCNTL code requires more information then it will be contained within the provided data.
Reimplemented in IFS::FWFS::FileSystem, and IFS::HYFS::FileSystem.
◆ fenumxattr()
|
pure virtual |
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
- Return values
-
int error code, on success returns number of attributes read
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ fgetextents()
|
inlinevirtual |
Get extents for a file.
- Parameters
-
file Handle to open file part Partition where the file lives (OUT, OPTIONAL) list Buffer for extents (OPTIONAL) extcount Maximum number of extents to return in list
- Return values
-
int Total number of extents for file (may be larger than 'extcount'), or error code
Reimplemented in IFS::FWFS::FileSystem, and IFS::HYFS::FileSystem.
◆ fgetxattr()
|
pure virtual |
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
- Return values
-
int error code, on success returns size of attribute (which may be larger than size)
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ flush()
|
pure virtual |
flush any buffered data to physical media
- Parameters
-
file handle to open file
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ format()
|
pure virtual |
format the filing system
- Return values
-
int error code
- 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.
Implemented in IFS::Gdb::FileSystem, IFS::FWFS::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ fremove()
|
pure virtual |
remove (delete) a file by handle
- Parameters
-
file handle to open file
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ fsetxattr()
|
pure virtual |
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
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ fstat()
|
pure virtual |
get file information
- Parameters
-
file handle to open file stat structure to return information in, may be null
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ ftruncate()
|
pure virtual |
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
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ getErrorString()
get the text for a returned error code
- Return values
-
String
Reimplemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ getinfo()
get filing system information
- Parameters
-
info structure to read information into
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ getxattr()
|
pure virtual |
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
- Return values
-
int error code, on success returns size of attribute (which may be larger than size)
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ lseek()
|
pure virtual |
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)
- Return values
-
file_offset_t current position or error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ mkdir()
|
pure virtual |
Create a directory.
- Parameters
-
path Path to directory
- Return values
-
int error code
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.
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ mount()
|
pure virtual |
Mount file system, performing any required initialisation.
- Return values
-
error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ open()
|
pure virtual |
open a file (or directory) by path
- Parameters
-
path full path to file flags Desired access and other options
- Return values
-
FileHandle file handle or error code
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.
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ opendir()
open a directory for reading
- Parameters
-
path path to directory. nullptr is interpreted as root directory dir returns a pointer to the directory object
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ read()
|
pure virtual |
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
- Return values
-
int number of bytes read or error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ readdir()
read a directory entry
- Parameters
-
dir stat
- Return values
-
int error code
- Note
- File system allocates entries structure as it usually needs to track other information. It releases memory when closedir() is called.
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ remove()
|
pure virtual |
remove (delete) a file by path
- Parameters
-
path
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ rename()
|
pure virtual |
rename a file
- Parameters
-
oldpath newpath
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ rewinddir()
Reset directory read position to start.
- Parameters
-
dir
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ setProfiler()
Set profiler instance to enable debugging and performance assessment.
- Parameters
-
profiler
- Return values
-
int error code - profiling may not be supported on all filesystems
Reimplemented in IFS::FAT::FileSystem.
◆ setVolume()
|
inlinevirtual |
Set volume for mountpoint.
- Parameters
-
index Volume index fileSystem The filesystem to root at this mountpoint
- Return values
-
int error code
Reimplemented in IFS::FWFS::FileSystem, and IFS::HYFS::FileSystem.
◆ setxattr()
|
pure virtual |
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
- Return values
-
int error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ stat()
get file information
- 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
- Return values
-
int error code
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
:
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ tell()
|
pure virtual |
get current file position
- Parameters
-
file handle to open file
- Return values
-
file_offset_t current position relative to start of file, or error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
◆ write()
|
pure virtual |
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
- Return values
-
int number of bytes written or error code
Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::FAT::FileSystem, and IFS::HYFS::FileSystem.
The documentation for this class was generated from the following file: