IFS::IFileSystem Class Referenceabstract

Installable File System base class. More...

#include <IFileSystem.h>

Inheritance diagram for IFS::IFileSystem:
[legend]

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 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 int lseek (FileHandle file, int 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 int32_t tell (FileHandle file)=0
 get current file position More...
 
virtual int ftruncate (FileHandle 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 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

Enumerator
XX 
MAX 

◆ Type

Enumerator
XX 
MAX 

Constructor & Destructor Documentation

◆ ~IFileSystem()

virtual IFS::IFileSystem::~IFileSystem ( )
inlinevirtual

Filing system implementations should dismount and cleanup here.

Member Function Documentation

◆ check()

virtual int IFS::IFileSystem::check ( )
inlinevirtual

Perform a file system consistency check.

Return values
interror 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::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ close()

virtual int IFS::IFileSystem::close ( FileHandle  file)
pure virtual

close an open file

Parameters
filehandle to open file
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ closedir()

virtual int IFS::IFileSystem::closedir ( DirHandle  dir)
pure virtual

close a directory object

Parameters
dirdirectory to close
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ eof()

virtual int IFS::IFileSystem::eof ( FileHandle  file)
pure virtual

determine if current file position is at end of file

Parameters
filehandle to open file
Return values
int0 - not EOF, > 0 - at EOF, < 0 - error

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ fcontrol()

virtual int IFS::IFileSystem::fcontrol ( FileHandle  file,
ControlCode  code,
void *  buffer,
size_t  bufSize 
)
inlinevirtual

Low-level and non-standard file control operations.

Parameters
file
codeFCNTL_XXX code
bufferInput/Output buffer
bufSizeSize of buffer
Return values
interror 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()

virtual int IFS::IFileSystem::fenumxattr ( FileHandle  file,
AttributeEnumCallback  callback,
void *  buffer,
size_t  bufsize 
)
pure virtual

Enumerate attributes.

Parameters
filehandle to open file
callbackCallback function to invoke for each attribute found
bufferBuffer to use for reading attribute data. Use nullptr if only tags are required
bufsizeSize of buffer
Return values
interror code, on success returns number of attributes read

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ fgetxattr()

virtual int IFS::IFileSystem::fgetxattr ( FileHandle  file,
AttributeTag  tag,
void *  buffer,
size_t  size 
)
pure virtual

Get an extended attribute from an open file.

Parameters
filehandle to open file
tagThe attribute to read
bufferBuffer to receive attribute content
sizeSize of the buffer
Return values
interror code, on success returns size of attribute (which may be larger than size)

Implemented in IFS::FWFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ flush()

virtual int IFS::IFileSystem::flush ( FileHandle  file)
pure virtual

flush any buffered data to physical media

Parameters
filehandle to open file
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ format()

virtual int IFS::IFileSystem::format ( )
pure virtual

format the filing system

Return values
interror 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::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ fremove()

virtual int IFS::IFileSystem::fremove ( FileHandle  file)
pure virtual

remove (delete) a file by handle

Parameters
filehandle to open file
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ fsetxattr()

virtual int IFS::IFileSystem::fsetxattr ( FileHandle  file,
AttributeTag  tag,
const void *  data,
size_t  size 
)
pure virtual

Set an extended attribute on an open file.

Parameters
filehandle to open file
tagThe attribute to write
dataContent of the attribute. Pass nullptr to remove the attribute (if possible).
sizeSize of the attribute in bytes
Return values
interror code
Note
Attributes may not be written to disk until flush() or close() are called

Implemented in IFS::FWFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ fstat()

virtual int IFS::IFileSystem::fstat ( FileHandle  file,
Stat stat 
)
pure virtual

get file information

Parameters
filehandle to open file
statstructure to return information in, may be null
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ ftruncate()

virtual int IFS::IFileSystem::ftruncate ( FileHandle  file,
size_t  new_size 
)
pure virtual

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

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ getErrorString()

virtual String IFS::IFileSystem::getErrorString ( int  err)
inlinevirtual

get the text for a returned error code

Return values
String

Reimplemented in IFS::FWFS::FileSystem, IFS::HYFS::FileSystem, IFS::Host::FileSystem, and IFS::Gdb::FileSystem.

◆ getinfo()

virtual int IFS::IFileSystem::getinfo ( Info info)
pure virtual

get filing system information

Parameters
infostructure to read information into
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::HYFS::FileSystem, IFS::Host::FileSystem, and IFS::Gdb::FileSystem.

◆ getxattr()

virtual int IFS::IFileSystem::getxattr ( const char *  path,
AttributeTag  tag,
void *  buffer,
size_t  size 
)
pure virtual

Get an attribute from a file given its path.

Parameters
fileFull path to file (or directory)
tagThe attribute to read
bufferBuffer to receive attribute content
sizeSize of the buffer
Return values
interror code, on success returns size of attribute (which may be larger than size)

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ lseek()

virtual int IFS::IFileSystem::lseek ( FileHandle  file,
int  offset,
SeekOrigin  origin 
)
pure virtual

change file read/write position

Parameters
filehandle to open file
offsetposition relative to origin
originwhere to seek from (start/end or current position)
Return values
intcurrent position or error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ mkdir()

virtual int IFS::IFileSystem::mkdir ( const char *  path)
pure virtual

Create a directory.

Parameters
pathPath to directory
Return values
interror 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 makedirs() for this purpose.

Implemented in IFS::FWFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ mount()

virtual int IFS::IFileSystem::mount ( )
pure virtual

Mount file system, performing any required initialisation.

Return values
errorcode

Implemented in IFS::FWFS::FileSystem, IFS::HYFS::FileSystem, IFS::Host::FileSystem, and IFS::Gdb::FileSystem.

◆ open()

virtual FileHandle IFS::IFileSystem::open ( const char *  path,
OpenFlags  flags 
)
pure virtual

open a file by path

Parameters
pathfull path to file
flagsopens for opening file
Return values
FileHandlefile handle or error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ opendir()

virtual int IFS::IFileSystem::opendir ( const char *  path,
DirHandle dir 
)
pure virtual

open a directory for reading

Parameters
pathpath to directory. nullptr is interpreted as root directory
dirreturns a pointer to the directory object
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::HYFS::FileSystem, IFS::Host::FileSystem, and IFS::Gdb::FileSystem.

◆ read()

virtual int IFS::IFileSystem::read ( FileHandle  file,
void *  data,
size_t  size 
)
pure virtual

read content from a file and advance cursor

Parameters
filehandle to open file
databuffer to write into
sizesize of file buffer, maximum number of bytes to read
Return values
intnumber of bytes read or error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ readdir()

virtual int IFS::IFileSystem::readdir ( DirHandle  dir,
Stat stat 
)
pure virtual

read a directory entry

Parameters
dir
stat
Return values
interror 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::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ remove()

virtual int IFS::IFileSystem::remove ( const char *  path)
pure virtual

remove (delete) a file by path

Parameters
path
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ rename()

virtual int IFS::IFileSystem::rename ( const char *  oldpath,
const char *  newpath 
)
pure virtual

rename a file

Parameters
oldpath
newpath
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ rewinddir()

virtual int IFS::IFileSystem::rewinddir ( DirHandle  dir)
pure virtual

Reset directory read position to start.

Parameters
dir
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ setProfiler()

virtual int IFS::IFileSystem::setProfiler ( IProfiler profiler)
inlinevirtual

Set profiler instance to enable debugging and performance assessment.

Parameters
profiler
Return values
interror code - profiling may not be supported on all filesystems

◆ setVolume()

virtual int IFS::IFileSystem::setVolume ( uint8_t  index,
IFileSystem fileSystem 
)
inlinevirtual

Set volume for mountpoint.

Parameters
indexVolume index
fileSystemThe filesystem to root at this mountpoint
Return values
interror code

Reimplemented in IFS::FWFS::FileSystem, and IFS::HYFS::FileSystem.

◆ setxattr()

virtual int IFS::IFileSystem::setxattr ( const char *  path,
AttributeTag  tag,
const void *  data,
size_t  size 
)
pure virtual

Set an extended attribute for a file given its path.

Parameters
pathFull path to file (or directory)
tagThe attribute to write
dataContent of the attribute. Pass nullptr to remove the attribute (if possible).
sizeSize of the attribute in bytes
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ stat()

virtual int IFS::IFileSystem::stat ( const char *  path,
Stat stat 
)
pure virtual

get file information

Parameters
pathname or path of file
sstructure to return information in, may be null to do a simple file existence check
Return values
interror code

Implemented in IFS::FWFS::FileSystem, IFS::HYFS::FileSystem, IFS::Gdb::FileSystem, and IFS::Host::FileSystem.

◆ tell()

virtual int32_t IFS::IFileSystem::tell ( FileHandle  file)
pure virtual

get current file position

Parameters
filehandle to open file
Return values
int32_tcurrent position relative to start of file, or error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.

◆ write()

virtual int IFS::IFileSystem::write ( FileHandle  file,
const void *  data,
size_t  size 
)
pure virtual

write content to a file at current position and advance cursor

Parameters
filehandle to open file
databuffer to read from
sizenumber of bytes to write
Return values
intnumber of bytes written or error code

Implemented in IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::HYFS::FileSystem, and IFS::Host::FileSystem.


The documentation for this class was generated from the following file: