IFS::Host::FileSystem Class Reference

IFS implementation of Host filing system. More...

#include <FileSystem.h>

Inheritance diagram for IFS::Host::FileSystem:
Collaboration diagram for IFS::Host::FileSystem:

Public Member Functions

 FileSystem (const char *rootpath=nullptr)
 
 ~FileSystem () override
 
int mount () override
 Mount file system, performing any required initialisation. More...
 
int getinfo (Info &info) override
 get filing system information More...
 
String getErrorString (int err) override
 get the text for a returned error code More...
 
int opendir (const char *path, DirHandle &dir) override
 open a directory for reading More...
 
int rewinddir (DirHandle dir) override
 Reset directory read position to start. More...
 
int readdir (DirHandle dir, Stat &stat) override
 read a directory entry More...
 
int closedir (DirHandle dir) override
 close a directory object More...
 
int mkdir (const char *path) override
 Create a directory. More...
 
int stat (const char *path, Stat *stat) override
 get file information More...
 
int fstat (FileHandle file, Stat *stat) override
 get file information More...
 
int fsetxattr (FileHandle file, AttributeTag tag, const void *data, size_t size) override
 Set an extended attribute on an open file. More...
 
int fgetxattr (FileHandle file, AttributeTag tag, void *buffer, size_t size) override
 Get an extended attribute from an open file. More...
 
int fenumxattr (FileHandle file, AttributeEnumCallback callback, void *buffer, size_t bufsize) override
 Enumerate attributes. More...
 
int setxattr (const char *path, AttributeTag tag, const void *data, size_t size) override
 Set an extended attribute for a file given its path. More...
 
int getxattr (const char *path, AttributeTag tag, void *buffer, size_t size) override
 Get an attribute from a file given its path. More...
 
FileHandle open (const char *path, OpenFlags flags) override
 open a file (or directory) by path More...
 
int close (FileHandle file) override
 close an open file More...
 
int read (FileHandle file, void *data, size_t size) override
 read content from a file and advance cursor More...
 
int write (FileHandle file, const void *data, size_t size) override
 write content to a file at current position and advance cursor More...
 
file_offset_t lseek (FileHandle file, file_offset_t offset, SeekOrigin origin) override
 change file read/write position More...
 
int eof (FileHandle file) override
 determine if current file position is at end of file More...
 
file_offset_t tell (FileHandle file) override
 get current file position More...
 
int ftruncate (FileHandle file, file_size_t new_size) override
 Truncate (reduce) the size of an open file. More...
 
int flush (FileHandle file) override
 flush any buffered data to physical media More...
 
int rename (const char *oldpath, const char *newpath) override
 rename a file More...
 
int remove (const char *path) override
 remove (delete) a file by path More...
 
int fremove (FileHandle file) override
 remove (delete) a file by handle More...
 
int format () override
 format the filing system More...
 
int check () override
 Perform a file system consistency check. More...
 
- Public Member Functions inherited from IFS::IFileSystem
virtual ~IFileSystem ()
 Filing system implementations should dismount and cleanup here. More...
 
virtual int setProfiler (IProfiler *profiler)
 Set profiler instance to enable debugging and performance assessment. More...
 
virtual int setVolume (uint8_t index, IFileSystem *fileSystem)
 Set volume for mountpoint. More...
 
virtual int fcontrol (FileHandle file, ControlCode code, void *buffer, size_t bufSize)
 Low-level and non-standard file control operations. More...
 
virtual int fgetextents (FileHandle file, Storage::Partition *part, Extent *list, uint16_t extcount)
 Get extents for a file. More...
 

Additional Inherited Members

- Public Types inherited from IFS::IFileSystem
enum  Type { Type::XX, Type::MAX }
 
enum  Attribute { Attribute::XX, Attribute::MAX }
 
using Attributes = BitSet< uint8_t, Attribute, size_t(Attribute::MAX)>
 

Detailed Description

IFS implementation of Host filing system.

Constructor & Destructor Documentation

◆ FileSystem()

IFS::Host::FileSystem::FileSystem ( const char *  rootpath = nullptr)
inline

◆ ~FileSystem()

IFS::Host::FileSystem::~FileSystem ( )
inlineoverride

Member Function Documentation

◆ check()

int IFS::Host::FileSystem::check ( )
inlineoverridevirtual

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 from IFS::IFileSystem.

◆ close()

int IFS::Host::FileSystem::close ( FileHandle  file)
overridevirtual

close an open file

Parameters
filehandle to open file
Return values
interror code

Implements IFS::IFileSystem.

◆ closedir()

int IFS::Host::FileSystem::closedir ( DirHandle  dir)
overridevirtual

close a directory object

Parameters
dirdirectory to close
Return values
interror code

Implements IFS::IFileSystem.

◆ eof()

int IFS::Host::FileSystem::eof ( FileHandle  file)
overridevirtual

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

Implements IFS::IFileSystem.

◆ fenumxattr()

int IFS::Host::FileSystem::fenumxattr ( FileHandle  file,
AttributeEnumCallback  callback,
void *  buffer,
size_t  bufsize 
)
overridevirtual

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

Implements IFS::IFileSystem.

◆ fgetxattr()

int IFS::Host::FileSystem::fgetxattr ( FileHandle  file,
AttributeTag  tag,
void *  buffer,
size_t  size 
)
overridevirtual

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)

Implements IFS::IFileSystem.

◆ flush()

int IFS::Host::FileSystem::flush ( FileHandle  file)
overridevirtual

flush any buffered data to physical media

Parameters
filehandle to open file
Return values
interror code

Implements IFS::IFileSystem.

◆ format()

int IFS::Host::FileSystem::format ( )
inlineoverridevirtual

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.

Implements IFS::IFileSystem.

◆ fremove()

int IFS::Host::FileSystem::fremove ( FileHandle  file)
inlineoverridevirtual

remove (delete) a file by handle

Parameters
filehandle to open file
Return values
interror code

Implements IFS::IFileSystem.

◆ fsetxattr()

int IFS::Host::FileSystem::fsetxattr ( FileHandle  file,
AttributeTag  tag,
const void *  data,
size_t  size 
)
overridevirtual

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

Implements IFS::IFileSystem.

◆ fstat()

int IFS::Host::FileSystem::fstat ( FileHandle  file,
Stat stat 
)
overridevirtual

get file information

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

Implements IFS::IFileSystem.

◆ ftruncate()

int IFS::Host::FileSystem::ftruncate ( FileHandle  file,
file_size_t  new_size 
)
overridevirtual

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

Implements IFS::IFileSystem.

◆ getErrorString()

String IFS::Host::FileSystem::getErrorString ( int  err)
overridevirtual

get the text for a returned error code

Return values
String

Reimplemented from IFS::IFileSystem.

◆ getinfo()

int IFS::Host::FileSystem::getinfo ( Info info)
overridevirtual

get filing system information

Parameters
infostructure to read information into
Return values
interror code

Implements IFS::IFileSystem.

◆ getxattr()

int IFS::Host::FileSystem::getxattr ( const char *  path,
AttributeTag  tag,
void *  buffer,
size_t  size 
)
overridevirtual

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)

Implements IFS::IFileSystem.

◆ lseek()

file_offset_t IFS::Host::FileSystem::lseek ( FileHandle  file,
file_offset_t  offset,
SeekOrigin  origin 
)
overridevirtual

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
file_offset_tcurrent position or error code

Implements IFS::IFileSystem.

◆ mkdir()

int IFS::Host::FileSystem::mkdir ( const char *  path)
overridevirtual

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 IFS::FileSystem::makedirs() for this purpose.

Implements IFS::IFileSystem.

◆ mount()

int IFS::Host::FileSystem::mount ( )
overridevirtual

Mount file system, performing any required initialisation.

Return values
errorcode

Implements IFS::IFileSystem.

◆ open()

FileHandle IFS::Host::FileSystem::open ( const char *  path,
OpenFlags  flags 
)
overridevirtual

open a file (or directory) by path

Parameters
pathfull path to file
flagsDesired access and other options
Return values
FileHandlefile 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.

Implements IFS::IFileSystem.

◆ opendir()

int IFS::Host::FileSystem::opendir ( const char *  path,
DirHandle dir 
)
overridevirtual

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

Implements IFS::IFileSystem.

◆ read()

int IFS::Host::FileSystem::read ( FileHandle  file,
void *  data,
size_t  size 
)
overridevirtual

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

Implements IFS::IFileSystem.

◆ readdir()

int IFS::Host::FileSystem::readdir ( DirHandle  dir,
Stat stat 
)
overridevirtual

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.

Implements IFS::IFileSystem.

◆ remove()

int IFS::Host::FileSystem::remove ( const char *  path)
overridevirtual

remove (delete) a file by path

Parameters
path
Return values
interror code

Implements IFS::IFileSystem.

◆ rename()

int IFS::Host::FileSystem::rename ( const char *  oldpath,
const char *  newpath 
)
overridevirtual

rename a file

Parameters
oldpath
newpath
Return values
interror code

Implements IFS::IFileSystem.

◆ rewinddir()

int IFS::Host::FileSystem::rewinddir ( DirHandle  dir)
overridevirtual

Reset directory read position to start.

Parameters
dir
Return values
interror code

Implements IFS::IFileSystem.

◆ setxattr()

int IFS::Host::FileSystem::setxattr ( const char *  path,
AttributeTag  tag,
const void *  data,
size_t  size 
)
overridevirtual

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

Implements IFS::IFileSystem.

◆ stat()

int IFS::Host::FileSystem::stat ( const char *  path,
Stat stat 
)
overridevirtual

get file information

Parameters
pathname or path of file/directory/mountpoint
sstructure to return information in, may be null to do a simple file existence check
Return values
interror 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:

int handle = fs.open("path-to-mountpoint");
Stat stat;
fs.fstat(handle, &stat);
fs.close(handle);

Implements IFS::IFileSystem.

◆ tell()

file_offset_t IFS::Host::FileSystem::tell ( FileHandle  file)
overridevirtual

get current file position

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

Implements IFS::IFileSystem.

◆ write()

int IFS::Host::FileSystem::write ( FileHandle  file,
const void *  data,
size_t  size 
)
overridevirtual

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

Implements IFS::IFileSystem.


The documentation for this class was generated from the following file:
int stat(const char *path, Stat *stat) override
get file information