Installable File System

Created for Sming Framework Project August 2018 by mikee47

I struggled to find anything like this for embedded systems. Probably didn’t look hard enough, but it seemed like a fun thing to do so here we are.

The term ‘IFS’ came about because of the ‘I’ naming convention for virtual ‘Interface’ classes, hence IFileSystem. The term ‘installable’ is entirely appropriate because IFS allows file systems to be loaded and unloaded dynamically. Or maybe I just nicked the term from Microsoft :-)

Overview

IFS is written in C++ and has these core components:

FileSystem API

File systems are implemented using the IFS::IFileSystem virtual class. This is, in essence, a single large ‘function table’ you will see in regular filesystem implementations.

Class methods are similar to SPIFFS (which is POSIX-like).

Note

A single Stat structure is used both for reading directory entries and for regular fileStat() operations.

This differs from regular file APIs but is intended to simplify operation.

Applications will typically use IFS::FileSystem instead, which adds additional methods and overloads such as String parameter support. This used to implement the standard ‘flat’ Sming filesystem API, with a few minor changes and a number of additions.

Two wrapper clases (IFS::File and IFS::Directory) are provided for applications to manage access to files and folders.

Firmware FileSystem (FWFS)

Files, directories and metadata are all stored as objects in an Object Store, which can be SPIFFS or on a FWRO (Firmware, Read-Only) image. FWRO images are compact, fast and use less RAM than SPIFFS. To support read/write data SPIFFS can be mounted in a sub-directory.

A python tool fsbuild is used to build an FWFS image from user files. See Filesystem builder.

This is integrated into the build system using the fwfs-build target for the partition. Example Hardware configuration fragment:

"partitions": {
   "fwfs1": {
      "address": "0x280000",
      "size": "0x60000",
      "type": "data",
      "subtype": "fwfs",
      "filename": "out/fwfs1.bin",
      "build": {
          "target": "fwfs-build",   // To build a FWFS image
          "config": "fsimage.fwfs"  // Configuration for the image
      }
   }
}

Sming provides the Basic IFS sample application which gives a worked example of this.

Various IFS implementations are provided:

IFS::FWFS::FileSystem

Firmware Filesystem. It is designed to support all features of IFS, whereas other filesystems may only use a subset.

IFS::SPIFFS::FileSystem

SPIFFS filesystem. The metadata feature is used to store extended file attributes.

IFS::HYFS::FileSystem

Hybrid filesystem. Uses FWFS as the root filesystem, with SPIFFS ‘layered’ on top. When a file is opened for writing it is transparently copied to the SPIFFS partition so it can be updated. Wiping the SPIFFS partition reverts the filesystem to its original state.

Note that files marked as ‘read-only’ on the FWFS system are blocked from this behaviour.

IFS::Host::FileSystem

For Host architecture this allows access to the Linux/Windows host filesystem.

IFS::Gdb::FileSystem

When running under a debugger this allows access to the Host filesystem. (Currently only works for ESP8266.)

IFS (and FWFS) has the following features:

Attributes

Files have a standard set of attribute flags plus modification time and simple role-based access control list (ACL)

Directories

Fully supported, and can be enumerated with associated file information using a standard opendir/readdir/closedir function set.

User metadata

Supported for application use

Filesystem API

The Sming FileSystem functions are now wrappers around a single IFileSystem instance, which is provided by the application.

Streaming classes

Sming provides IFS implementations for these so they can be constructed on any filesystem, not just the main (global) one.

Dynamic loading

File systems may be loaded/created and unloaded/destroyed at runtime

Multiple filesystems

Applications may use any supported filesystem, or write their own, or use any combination of existing filesystems to meet requirements. The API is the same.

FWFS

Many applications require a default, often fixed set of files. The easiest way is just to use SPIFFS. The problem is that power outages can corrupt a filesystem. For an embedded device that’s bad news. SPIFFS is also a bit overkill if you’re just storing configuration data, or it’s just for read-only use.

So what do you do if your filesystem gets wiped? Resetting a system back to a functional, default state can be tricky if the core user interface web files are gone. You could reformat and pull a standard set of files off a server somewhere. If your storage requirements are minimal, you could link the file data into your firmware as constant data blocks.

That’s kind of what FWFS does, but in a more structured and user-friendly way.

FWFS offers a more convenient solution by providing all your default files in a compact, fast, read-only format. Images can be mounted in separate partitions, linked into the program image itself or stored as files within another filesystem.

Note

This behaviour is supported by partitions (see Storage Management) using custom Storage::Device objects.

Objects

FWFS goes further than a simple read-write system. All files, directories and associated information elements are stored as ‘objects’. Files and directories are ‘named’ objects, which may contain other objects either directly or as references. Small objects (255 bytes or less) are stored directly, larger ones get their own file. Maximum object size is 16Mbytes.

File content is stored in un-named data objects. A named object can have any number of these and will be treated as a single entity for read/write operations. File ‘fragments’ do not need to be contiguous, and are reassembled during read operations.

Named objects can be enumerated using IFS::IFileSystem::readdir(). Internally, FWFS uses handles to access any named object. Handles are allocated from a static pool to avoid excessive dynamic (heap) allocation. Users can attach their own data to any named object using custom object types.

Object stores

FWFS uses a mid-level layer to deal with reading and writing objects. It is at a slightly higher level than media, which allows efficient use of flash storage for direct read-only access, or SPIFFS as a read/write layer. Each object store provides access to a single volume.

When implemented on SPIFFS, a named object is stored as a file. So a directory is just another file. If the directory contains large files, then the corresponding data objects will be stored separately as other SPIFFS files. Names are not required on the SPIFFS volume as Object IDs are used exclusively.

Be aware, therefore, that any change to an object will involve rewriting the underlying file. The SPIFFS object store can probably be improved. For example, as FWFS doesn’t require file content to be in a single object, appending to a file can be done by creating new data objects and appending them to the file object. SPIFFS will do this sort of thing anyway, so there should be a way to combine the two.

Redirection

FWFS incorporates a redirector. This works by creating a mount point (a named object), which looks like a directory. When accessed, this get redirected to the root of another object store. The maximum number of mount points is fixed at compile time, but stores can be mounted and dismounted at any time.

Archival

One possible application for FWFS images is for archiving. Multiple filesystem images could be stored on a web server and pulled into memory as required.

Images can be generated ‘on the fly’ as a backup archive using a archive object store; this would support writing only.

Access Control

This came about because I wanted to secure down my ESP8266 web server applications so that only the basic index.html, stylesheets and accompanying javascript would be publicly accessibly. Everything else would require user authentication.

I also wanted to prevent certain users from accessing restricted files. Other users would also be able to edit files. So a simple role-based access control mechanism seemed appropriate.

Access control typically encapsulates two areas:

Authentication

Is the user who they say they are? Usually performed by validating a username/password combination.

Authorisation

What is the user permitted to do?

I’ll step aside for a brief word on security. Authentication is the weakest link because it’s exposed to public scrutiny. To avoid compromise authentication must only be done over a secured link. That means SSL.

If you have the option it’s usually best to put all your smart devices behind a secure proxy. The raspberry Pi is great for stuff like this. The Pi deals with keeping the public connection secure, and translates it into a regular HTTP connection for the ESP8266.

If you don’t have this option, but you need to connect your ESP8266 to the internet, use the SSL build for Sming.

Having done this, we don’t need to worry about encrypting passwords as the SSL layer will do that. We just need to make sure they’re good passwords.

In my applications authentication is done by matching username/password against the user database, stored in a JSON file. If successful, the session gets a token which appears in every subsequent request. The user database indicates a User Role, one of public, guest, user, manager or admin. IFS keeps an ‘Access Control List’ (ACL) for each file containing two entries (ACE), one for read access and another for write access. The ACE specifies the minimum assigned IFS::UserRole required for access.

This is probably as much as the filesystem needs to do. I can’t see that file ownership, inherited permissions or more finely-grained access permissions would be required, but having said that extending this system would probably be fairly straightforward.

Configuration filesystem

@todo

If an application only requires write access for configuration files, SPIFFS is overkill. These files would be updated very infrequently, so wear-levelling would be un-necessary. The names and number of files would probably also be known at build time, and an individual file could be limited to a fixed size, for example one or two flash sectors. A ConfigFileSystem implementation would not need to support file creation or deletion.

Such a system would require almost no static RAM allocation and code size would be tiny.

Note

The ESP-IDF has a mechanism for flash-based configuration space via the NVS component. It is robust and flexible but uses a signficant amount of RAM for buffering which may preclude its use with the ESP8266.

Code dependencies

Written initially for Sming, the library is portable to other systems.

No definitions from SPIFFS or other modules should be used in the public interface; such dependencies should be managed internally.

Applications should avoid using filesystem-dependent calls, structures or error codes. Such code, if necessary, should be placed into a separate module.

Implementation details

The traditional way to implement installable filing systems is using function tables, such as you’ll see in Linux. One reason is because the Linux kernel is written in C, not C++. For Sming, a virtual class seems the obvious choice, however there are some pros and cons.

VMT

Advantages

• Compiler ensures correct ordering of methods, parameter type checking

• Simpler coding

• Extending and overriding is natural

Function table

Advantages

• Portable to C applications (although with some fudging so are VMTs).

Disadvantages

• Care required to keep function order and parameters correct. Very likely we’d use a bunch of macros to deal with this.

Macros

We could #define the active filing system name which the FileSystem functions would map to the appropriate call. For example, fileOpen would get mapped to SPIFlashFileSystem_open(). We need to provide macros for defining file system functions.

Advantages

• Fast

Disadvantages

• Complicated

• Prone to bugs

• Not C++

API

namespace IFS

Access.h Access control definitions

Created on: 6 Jun 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Compression.h

Created on: 31 Aug 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Control.h

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Directory.h

Created: May 2019

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

File.h

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

FileAttributes.h

Created on: 31 Aug 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

FsBase.h Common base for file system classes

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

FileSystem.h FWFS - Firmware File System

Created on: 19 Jul 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

ObjectStore.h

Created on: 1 Sep 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

ObjRefCache.h

Created on: 1 Sep 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

FileSystem.h IFS wrapper for GDB syscall file access

Created on: 1 December 2020

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Helpers.h Helper functions to assist with standard filesystem creation

Created on: 27 Jan 2019

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

NameBuffer.h

Created on: 31 Aug 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Object.h Basic definitions for FW file system structure.

Created on: 7 Aug 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

A filesystem image is basically:

uint32_t START_MARKER;
Object Objects[];
Object EndObject;
uint32_t END_MARKER;

An FWFS Object is a variable-length structure which can be read as either 1 or 2 words, depending on the type. Objects always start on a word boundary. File and directory objects are both emitted as ‘named’ objects which contain a list of zero or more child objects. When the image is built the child objects are emitted first, followed by the parent. This puts the root directory at the end of the image. This arrangement means an image can be generated without having to back-track and rewrite headers.

Child objects can be of any type. A directory object will mostly contain other file and directory objects. File data is stored in a data object, not in the file object itself. This is usually found following the file object, but it doesn’t have to be. Any object may be referenced by zero or more named object(s). For example, file links/aliases can contain references to the same file data. A file object may contain multiple data objects. These are treated as a contiguous block for file operations. This would potentially allow a file system builder to place common file blocks into shared data objects.

Object names are from 0 to 255 characters, inclusive. The root directory has a zero-length name. Paths lengths are unlimited. ‘/’ is used as the path separator. It informs the filesystem of the parent/child relationship between one directory object and a sub-ordinate. ‘:’ is used as the file stream separator. It performs the equivalent of the path separator for non-directory named objects. For exaample, file object may contain named objects accessible thus: index.html:info opens a handle to a named object called ‘info’ belonging to index.html.

OK, I admit it; this is pinched from NTFS; but it’s such a cool idea. Applications can use it to attach custom data to their files without limitation.

As a side note, of course FWFS is read-only. More precisely, it only supports random reading of files, not random writing. Serial writing is supported in the form of image creation.

For SPIFFS, IFS is a wrapper. The metadata features are supported using SPIFFS metadata. An alternative approach is to implement every named object as a SPIFFS file. We’d then get all the features of FWFS in a rewritable system, with all the benefits of SPIFFS wear-levelling.

Objects are identified by their index, but it’s not stored in the image. Instead, it’s tracked via internal object descriptor.

To optimise lookups, an object table can be stored at the end of the image. This is just an array of 32-bit image offsets so that an object can be located instantly on large volumes. This will be optional as it can consume significant space.

OpenFlags.h

Created on: 31 Aug 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Error.h SPIFFS error codes

Created on: 31 Aug 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

FileMeta.h

Created on: 21 Jul 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Stat.h

Created: August 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

TimeStamp.h

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

UserRole.h

Created on: 6 Jun 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Util.h Various bits for file system implementations to use

Created on: 10 Sep 2018

Copyright 2019 mikee47 mike@sillyhouse.net

This file is part of the IFS Library

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this library. If not, see https://www.gnu.org/licenses/.

Return compression corresponding to given string

Parameters

• str:

Return Value

• Compression::Type:

Compression::Type getCompressionType(const char *str, Compression::Type defaultValue = Compression::Type::None)

Compression::Type getCompressionType(const String &str, Compression::Type defaultValue = Compression::Type::None)

Return the access type value for the given string.

Parameters

• str:

• defaultRole: Returned if string isn’t recognsed

Return Value

• UserRole:

UserRole getUserRole(const char *str, UserRole defaultRole)

UserRole getUserRole(const String &str, UserRole defaultRole)

Typedefs

using ErrorCode = int

using FileAttributes = BitSet<uint8_t, FileAttribute, size_t(FileAttribute::MAX)>

File attributes are stored as a bitmask.

using DirHandle = struct FileDir *

using OpenFlags = BitSet<uint8_t, OpenFlag, size_t(OpenFlag::MAX)>

using FileHandle = int16_t

File handle.

References an open file

using FileID = uint32_t

File identifier.

Contained within Stat, uniquely identifies any file on the file system.

Enums

enum ControlCode

See IFS::IFileSystem::fcontrol

These are weakly typed as values may be defined elsewhere.

Values:

FCNTL_GET_MD5_HASH = 1

Get stored MD5 hash for file.

FWFS calculates this when the filesystem image is built and can be used by applications to verify file integrity.

On success, returns size of the hash itself (16) If the file is zero-length then Error::NotFound will be returned as the hash is not stored for empty files.

FCNTL_USER_BASE = 0x8000

Start of user-defined codes.

Codes before this are reserved for system use

enum FileAttribute

Values:

XX

MAX

enum OpenFlag

Values:

XX

MAX

enum UserRole

Values:

XX

MAX

Actually maxmimum value + 1…

Functions

String getAclString(const IFS::ACL &acl)

Return a brief textual representation for an ACL Suitable for inclusion in a file listing.

Parameters

• acl:

Return Value

• String:

String getFileAttributeString(FileAttributes attr)

Get the string representation for the given set of file attributes suitable for inclusion in a file listing.

Parameters

• attr:

Return Value

• String:

IFileSystem *createSpiffsFilesystem(Storage::Partition partition)

Create a SPIFFS filesystem.

Parameters

• partition:

Return Value

• IFileSystem*: constructed filesystem object

IFileSystem *createFirmwareFilesystem(Storage::Partition partition)

Create a firmware filesystem.

Parameters

• partition:

Return Value

• IFileSystem*: constructed filesystem object

IFileSystem *createHybridFilesystem(Storage::Partition fwfsPartition, Storage::Partition spiffsPartition)

Create a hybrid filesystem.

Parameters

• fwfsPartition:

• spiffsPartition:

Return Value

• IFileSystem*: constructed filesystem object

time_t fsGetTimeUTC()

Get current timestamp in UTC.

Note

Filing systems must store timestamps in UTC Use this function; makes porting easier.

Return Value

• time_t:

template<typename T>
static T at_offset(const void *current, int offset)

template<typename T>
static T at_offset(void *current, int offset)

constexpr OpenFlags operator|(OpenFlag a, OpenFlag b)

char getChar(UserRole role)

UserRole getUserRole(char code, UserRole defaultRole)

Variables

constexpr ErrorCode FS_OK = Error::Success

struct Compression

#include <Compression.h>

A compression descriptor.

class Directory : public IFS::FsBase

#include <Directory.h>

Wrapper class for enumerating a directory.

Subclassed by Directory

Public Functions

bool open(const String &dirName = nullptr)

Open a directory and attach this stream object to it.

Note

call getLastError() to determine cause of failure

Parameters

• dirName: Default is root directory

Return Value

• bool: true on success, false on error

void close()

Close directory.

bool rewind()

Rewind directory stream to start so it can be re-enumerated.

Note

call getLastError() to determine cause of failure

Return Value

• bool: true on success, false on error

const String &getDirName() const

Name of directory stream is attached to.

Return Value

• String: invalid if stream isn’t open

bool dirExist() const

Determine if directory exists.

Return Value

• bool: true if stream is attached to a directory

String getPath() const

Get path with leading separator /path/to/dir.

String getParent() const

Get parent directory.

Return Value

• String: invalid if there is no parent directory

class DirectoryTemplate : public SectionTemplate

#include <DirectoryTemplate.h>

Directory stream class.

Subclassed by IFS::HtmlDirectoryTemplate, IFS::JsonDirectoryTemplate

Public Functions

bool nextRecord()

Move to next record.

Return Value

• bool: true to emit section, false to skip

class File : public IFS::FsBase

#include <File.h>

Wraps up all file access methods.

Subclassed by File

Public Functions

bool stat(Stat &stat)

get file information

Parameters

• stat: structure to return information in, may be null

Return Value

• bool: true on success

int control(ControlCode code, void *buffer, size_t bufSize)

Low-level and non-standard file control operations.

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.

Parameters

• code: FCNTL_XXX code

• buffer: Input/Output buffer

• bufSize: Size of buffer

Return Value

• int: error code or, on success, data size

bool open(const String &path, OpenFlags flags = OpenFlag::Read)

open a file by name/path

Parameters

• path: full path to file

• flags: opens for opening file

Return Value

• bool: true on success

bool open(const Stat &stat, OpenFlags flags = OpenFlag::Read)

open a file from it’s stat structure

Parameters

• stat: obtained from readdir()

• flags: opens for opening file

Return Value

• bool: true on success

bool close()

close an open file

Return Value

• bool: true on success

int read(void *data, size_t size)

read content from a file and advance cursor

Parameters

• data: buffer to write into

• size: size of file buffer, maximum number of bytes to read

Return Value

• int: number of bytes read or error code

int write(const void *data, size_t size)

write content to a file at current position and advance cursor

Parameters

• data: buffer to read from

• size: number of bytes to write

Return Value

• int: number of bytes written or error code

int seek(int offset, SeekOrigin origin)

change file read/write position

Parameters

• offset: position relative to origin

• origin: where to seek from (start/end or current position)

Return Value

• int: current position or error code

bool eof()

determine if current file position is at end of file

Return Value

• bool: true if at EOF or file is invalid

int32_t tell()

get current file position

Return Value

• int32_t: current position relative to start of file, or error code

bool truncate(size_t new_size)

Truncate (reduce) the size of an open file.

Parameters

• newSize:

Return Value

• bool: true on success

bool truncate()

Truncate an open file at the current cursor position.

Return Value

• bool: true on success

bool flush()

flush any buffered data to physical media

Return Value

• bool: true on success

bool setacl(const ACL &acl)

Set access control information for file.

Parameters

• acl:

Return Value

• bool: true on success

bool settime(time_t mtime)

Set modification time for file.

Note

any subsequent writes to file will reset this to current time

Return Value

• bool: true on success

bool setcompression(const Compression &compression)

Set file compression information.

Parameters

• compression:

Return Value

• bool: true on success

bool remove()

remove (delete) an open file (and close it)

Return Value

• bool: true on success

uint32_t getSize()

Get size of file.

Return Value

• uint32_t: Size of file in bytes, 0 on error

int readContent(size_t size, ReadContentCallback callback)

Read from current file position and invoke callback for each block read.

Parameters

• size: Maximum number of bytes to read

• callback:

Return Value

• int: Number of bytes processed, or error code

int readContent(ReadContentCallback callback)

Read from current file position to end of file and invoke callback for each block read.

Parameters

• callback:

Return Value

• int: Number of bytes processed, or error code

String getContent()

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

Return Value

• String: String variable in to which to read the file content

struct FileNameBuffer : public IFS::NameBuffer

#include <NameBuffer.h>

a quick’n’dirty name buffer with maximum path allocation

class FileStream : public IFS::FsBase, public ReadWriteStream

#include <FileStream.h>

File stream class.

Subclassed by FileStream, GdbFileStream, HostFileStream

Public Functions

void attach(FileHandle file, size_t size)

Attach this stream object to an open file handle.

Parameters

• file:

• size:

bool open(const String &fileName, IFS::OpenFlags openFlags = OpenFlag::Read)

Open a file and attach this stream object to it.

Note

call getLastError() to determine cause of failure

Parameters

• fileName:

• openFlags:

Return Value

• bool: true on success, false on error

void close()

Close file.

StreamType getStreamType() const

Get the stream type.

Return Value

• StreamType: The stream type.

size_t write(const uint8_t *buffer, size_t size)

Write chars to stream.

Note

Although this is defined in the Print class, ReadWriteStream uses this as the core output method so descendants are required to implement it

Parameters

• buffer: Pointer to buffer to write to the stream

• size: Quantity of chars to write

Return Value

• size_t: Quantity of chars written to stream

int read()

Read one character and moves the stream pointer.

Return Value

• The: character that was read or -1 if none is available

size_t readBytes(char *buffer, size_t length)

Read chars from stream into buffer.

Terminates if length characters have been read or timeout (see setTimeout). Returns the number of characters placed in the buffer (0 means no valid data found).

Note

Inherited classes may provide more efficient implementations without timeout.

uint16_t readMemoryBlock(char *data, int bufSize)

Read a block of memory.

Parameters

• data: Pointer to the data to be read

• bufSize: Quantity of chars to read

Return Value

• uint16_t: Quantity of chars read

int seekFrom(int offset, SeekOrigin origin)

Change position in stream.

Note

This method is implemented by streams which support random seeking, such as files and memory streams.

Parameters

• offset:

• origin:

Return Value

• New: position, < 0 on error

bool isFinished()

Check if all data has been read.

Return Value

• bool: True on success.

String fileName() const

Filename of file stream is attached to.

Return Value

• String: invalid if stream isn’t open

bool fileExist() const

Determine if file exists.

Return Value

• bool: true if stream contains valid file

String getName() const

Returns name of the resource.

Note

Commonly used to obtain name of file

Return Value

• String:

MimeType getMimeType() const

Get MIME type for stream content.

Return Value

• MimeType:

bool isValid() const

Determine if the stream object contains valid data.

Note

Where inherited classes are initialised by constructor this method indicates whether that was successful or not (e.g. FileStream)

Return Value

• bool: true if valid, false if invalid

size_t getPos() const

Get the offset of cursor from beginning of data.

Return Value

• size_t: Cursor offset

size_t getSize() const

Get the total file size.

Return Value

• size_t: File size

int available()

Return the maximum bytes available to read, from current position.

Return Value

• int: -1 is returned when the size cannot be determined

String id() const

Returns unique id of the resource.

Return Value

• String: the unique id of the stream.

bool truncate(size_t newSize)

Reduce the file size.

Parameters

• newSize:

Return Value

• bool: true on success

bool truncate()

Truncate file at current position.

Return Value

• bool: true on success

class FileSystem : public IFS::IFileSystem

#include <FileSystem.h>

Installable File System base class.

Adds additional methods to ease use over base IFileSystem.

Unnamed Group

FileHandle open(const String &path, OpenFlags flags)

open a file by name/path

Parameters

• path: full path to file

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

int ftruncate(FileHandle file)

Truncate an open file at the current cursor position.

int truncate(const char *fileName, size_t newSize)

Truncate a file to a specific size.

Parameters

• fileName: File to truncate

Return Value

• int: new file size, or error code

rename a file

Parameters

• oldpath:

• newpath:

Return Value

• int: error code

using ReadContentCallback = Delegate<int(const char *buffer, size_t size)>

Callback for readContent method.

Parameters

• buffer:

• size:

Return Value

• int: Return number of bytes consumed, < size to stop If < 0 then this is returned as error code to readContent call.

int remove(const String &path)

remove (delete) a file by path

Parameters

• path:

Return Value

• int: error code

uint32_t getSize(FileHandle file)

Get size of file.

Parameters

• file: File handle

Return Value

• uint32_t: Size of file in bytes, 0 on error

uint32_t getSize(const char *fileName)

Get size of file.

Parameters

• fileName: Name of file

Return Value

• uint32_t: Size of file in bytes, 0 on error

int readContent(FileHandle file, size_t size, ReadContentCallback callback)

Read from current file position and invoke callback for each block read.

Parameters

• file:

• size: Maximum number of bytes to read

• callback:

Return Value

• int: Number of bytes processed, or error code

int readContent(FileHandle file, ReadContentCallback callback)

Read from current file position to end of file and invoke callback for each block read.

Parameters

• file:

• callback:

Return Value

• int: Number of bytes processed, or error code

int readContent(const String &filename, ReadContentCallback callback)

Read entire file content in blocks, invoking callback after every read.

Parameters

• filename:

• callback:

Return Value

• int: Number of bytes processed, or error code

Read content of a file

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!

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 Value

• size_t: Quantity of bytes read from file or zero on failure

Returns 0 if the file could not be read

Create or replace file with defined content

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

Return Value

• int: Number of bytes transferred or error code

Parameters

• length: (optional) number of characters to write

Public Functions

int opendir(const String &path, DirHandle &dir)

open a directory for reading

int makedirs(const char *path)

Create a directory and any intermediate directories if they do not already exist.

Parameters

• path: Path to directory. If no trailing ‘/’ is present the final element is considered a filename.

Return Value

• int: error code

int stat(const String &path, Stat *s)

get file information

int fstat(FileHandle file, Stat &stat)

get file information

String getContent(const String &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

Return Value

• String: String variable in to which to read the file content

class FsBase

#include <FsBase.h>

Subclassed by IFS::Directory, IFS::File, IFS::FileStream

Public Functions

int getLastError()

determine if an error occurred during operation

Return Value

• int: filesystem error code

struct FWObjDesc

#include <ObjectStore.h>

FWFS Object Descriptor.

Public Members

Object obj

The object structure.

ObjRef ref

location

class HtmlDirectoryTemplate : public IFS::DirectoryTemplate

#include <HtmlDirectoryTemplate.h>

Read-only stream access to directory listing with HTML output.

class IFileSystem

#include <IFileSystem.h>

Installable File System base class.

Construction and initialisation of a filing system is implementation-dependent so there are no methods here for that.

Note

The ‘I’ implies Installable but could be for Interface :-)

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.

Subclassed by IFS::FileSystem, IFS::FWFS::FileSystem, IFS::Gdb::FileSystem, IFS::Host::FileSystem, IFS::HYFS::FileSystem, IFS::SPIFFS::FileSystem

Public Functions

virtual ~IFileSystem()

Filing system implementations should dismount and cleanup here.

virtual int mount() = 0

Mount file system, performing any required initialisation.

Return Value

• error: code

virtual int getinfo(Info &info) = 0

get filing system information

Parameters

• info: structure to read information into

Return Value

• int: error code

virtual String getErrorString(int err)

get the text for a returned error code

Return Value

• String:

virtual int opendir(const char *path, DirHandle &dir) = 0

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 Value

• int: error code

virtual int fopendir(const Stat *stat, DirHandle &dir)

open a directory for reading

Parameters

• stat: identifies directory to open. nullptr is interpreted as root directory

• dir: returns a pointer to the directory object

Return Value

• int: error code

virtual int readdir(DirHandle dir, Stat &stat) = 0

read a directory entry

Note

File system allocates entries structure as it usually needs to track other information. It releases memory when closedir() is called.

Parameters

• dir:

• stat:

Return Value

• int: error code

virtual int rewinddir(DirHandle dir) = 0

Reset directory read position to start.

Parameters

• dir:

Return Value

• int: error code

virtual int closedir(DirHandle dir) = 0

close a directory object

Parameters

• dir: directory to close

Return Value

• int: error code

virtual int mkdir(const char *path) = 0

Create a directory.

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.

Parameters

• path: Path to directory

Return Value

• int: error code

virtual int stat(const char *path, Stat *stat) = 0

get file information

Parameters

• path: name or path of file

• s: structure to return information in, may be null to do a simple file existence check

Return Value

• int: error code

virtual int fstat(FileHandle file, Stat *stat) = 0

get file information

Parameters

• file: handle to open file

• stat: structure to return information in, may be null

Return Value

• int: error code

virtual int fcontrol(FileHandle file, ControlCode code, void *buffer, size_t bufSize)

Low-level and non-standard file control operations.

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.

Parameters

• file:

• code: FCNTL_XXX code

• buffer: Input/Output buffer

• bufSize: Size of buffer

Return Value

• int: error code or, on success, data size

virtual FileHandle open(const char *path, OpenFlags flags) = 0

open a file by name/path

Parameters

• path: full path to file

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

virtual FileHandle fopen(const Stat &stat, OpenFlags flags) = 0

open a file from it’s stat structure

Parameters

• stat: obtained from readdir()

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

virtual int close(FileHandle file) = 0

close an open file

Parameters

• file: handle to open file

Return Value

• int: error code

virtual int read(FileHandle file, void *data, size_t size) = 0

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 Value

• int: number of bytes read or error code

virtual int write(FileHandle file, const void *data, size_t size) = 0

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 Value

• int: number of bytes written or error code

virtual int lseek(FileHandle file, int offset, SeekOrigin origin) = 0

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 Value

• int: current position or error code

virtual int eof(FileHandle file) = 0

determine if current file position is at end of file

Parameters

• file: handle to open file

Return Value

• int: 0 - not EOF, > 0 - at EOF, < 0 - error

virtual int32_t tell(FileHandle file) = 0

get current file position

Parameters

• file: handle to open file

Return Value

• int32_t: current position relative to start of file, or error code

virtual int ftruncate(FileHandle file, size_t new_size) = 0

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:

Return Value

• int: Error code

virtual int flush(FileHandle file) = 0

flush any buffered data to physical media

Parameters

• file: handle to open file

Return Value

• int: error code

virtual int setacl(FileHandle file, const ACL &acl) = 0

Set access control information for file.

Parameters

• file: handle to open file

• acl:

Return Value

• int: error code

virtual int setattr(const char *path, FileAttributes attr) = 0

Set file attributes.

Parameters

• path: Full path to file

• attr:

Return Value

• int: error code

virtual int settime(FileHandle file, time_t mtime) = 0

Set modificatino tiem for file.

Note

any subsequent writes to file will reset this to current time

Parameters

• file: handle to open file, must have write access

Return Value

• int: error code

virtual int setcompression(FileHandle file, const Compression &compression) = 0

Set file compression information.

Parameters

• file:

• compression:

Return Value

• int: error code

virtual int rename(const char *oldpath, const char *newpath) = 0

rename a file

Parameters

• oldpath:

• newpath:

Return Value

• int: error code

virtual int remove(const char *path) = 0

remove (delete) a file by path

Parameters

• path:

Return Value

• int: error code

virtual int fremove(FileHandle file) = 0

remove (delete) a file by handle

Parameters

• file: handle to open file

Return Value

• int: error code

virtual int format() = 0

format the filing system

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.

Return Value

• int: error code

virtual int check()

Perform a file system consistency check.

Note

if possible, issues should be resolved. Returns 0 if file system checked out OK. Otherwise there were issues: < 0 for unrecoverable errors,

Return Value

• int: error code

struct Info

#include <IFileSystem.h>

Basic information about filing system.

Public Members

Type type = {}

The filing system type identifier.

Attributes attr = {}

Attribute flags.

size_t maxNameLength

Maximum length of a single file name.

size_t maxPathLength

Maximum length of a full file path.

uint32_t volumeID = {0}

Unique identifier for volume.

NameBuffer name

Buffer for name.

uint32_t volumeSize = {0}

Size of volume, in bytes.

uint32_t freeSpace = {0}

Available space, in bytes.

class IObjectStore

#include <ObjectStore.h>

Subclassed by IFS::FWFS::ObjectStore

Public Functions

virtual int initialise() = 0

called by FWFS

Return Value

• error: code

virtual int mounted(const FWObjDesc &od) = 0

called by FWFS to confirm successful mount

Parameters

• od: last object (the end marker)

Return Value

• int: error code

virtual bool isMounted() = 0

determine if store is mounted

Return Value

• true: if mounted

virtual int open(FWObjDesc &od) = 0

find an object and return a descriptor for it

Note

od.ref must be initialised

Parameters

• od: IN/OUT: resolved object

Return Value

• int: error code

virtual int openChild(const FWObjDesc &parent, const FWObjDesc &child, FWObjDesc &od) = 0

open a descriptor for a child object

Parameters

• parent:

• child: reference to child, relative to parent

• od: OUT: resolved object

Return Value

• int: error code

virtual int readHeader(FWObjDesc &od) = 0

read a root object header

Note

this method deals with top-level objects only

Parameters

• od: object descriptor, with offset and ID fields initialised

Return Value

• error: code

virtual int readChildHeader(const FWObjDesc &parent, FWObjDesc &child) = 0

fetch child object header

Note

references are not pursued; the caller must handle that child.ref refers to position relative to parent Implementations must set child.storenum = parent.storenum; other values will be meaningless as object stores are unaware of other stores.

Parameters

• parent:

• child: uninitialised child, returns result

Return Value

• error: code

virtual int readContent(const FWObjDesc &od, uint32_t offset, uint32_t size, void *buffer) = 0

read object content

Note

must fail if cannot read all requested bytes

Parameters

• offset: location to start reading, from start of object content

• size: bytes to read

• buffer: to store data

Return Value

• number: of bytes read, or error code

virtual int close(FWObjDesc &od) = 0

close an object descriptor

Note

the implementation should free any allocated resources

Parameters

• od:

Return Value

• int: error code

class JsonDirectoryTemplate : public IFS::DirectoryTemplate

#include <JsonDirectoryTemplate.h>

Read-only stream providing directory listing in JSON format.

struct NameBuffer

#include <NameBuffer.h>

defines a ‘safe’ name buffer

There are fancier ways to do this but a structure is transparent and requires no heap allocation.

Note

Instead of including a fixed name array in Stat (and IFileSystem::Info) structures, we use a NameBuffer to identify a separate buffer. This has several advantages:

- Maximum size is not fixed
- Finding and copying the name is optional
- Actual name length is returned in the 'length' field, regardless of size
- A NameBuffer structure (or one containing it) only requires initialising once before
a loop operation as buffer/size are preserved.

Note

length always reflects the required name/path length, and may be longer than size.

Subclassed by IFS::FileNameBuffer

Public Functions

NameBuffer(String &s)

Make a NameBuffer point to contents of a String.

int copy(const char *src, uint16_t srclen)

copies text from a source buffer into a name buffer

Note

length field is always set to srclen, regardless of number of characters copied.

Parameters

• src: source name

• srclen: number of characters in name

int addSep()

When building file paths this method simplified appending separators.

Note

if the path is not empty, a separator character is appended

Return Value

• int: error code

char *endptr()

get a pointer to the next write position

Note

use space() to ensure buffer doesn’t overrun When writing text be sure to call terminate() when complete

Return Value

• char*:

uint16_t space()

get the number of free characters available

Note

returns 0 if buffer has overrun

Return Value

• uint16_t:

void terminate()

ensure the buffer has a nul terminator, even if it means overwriting content

bool overflow() const

determine if name buffer overflowed

Note

Compares returned length with buffer size; A nul terminator is always appended, so size should be >= (length + 1)

Public Members

char *buffer = {nullptr}

Buffer to store name.

uint16_t size = {0}

IN: Size of buffer.

uint16_t length = {0}

OUT: length of name.

struct NameStat : public IFS::Stat

#include <Stat.h>

version of Stat with integrated name buffer

Note

provide for convenience

struct Object

#include <Object.h>

Object structure.

Note

all objects conform to this structure. Only the first word (4 bytes) are required to nagivate the file system. All objects have an 8, 16 or 24-bit size field. Content is always immediately after this field. Reference objects are always 8-bit sized.

Public Types

enum Attribute

Object attributes.

Note

these are bit values

Values:

ReadOnly

Object should not be modified or deleted.

Archive

Object modified flag.

Note

Object has been changed on disk. Typically used by backup applications

MAX

using ID = uint16_t

Object identifier.

Public Functions

size_t contentOffset() const

return offset to start of object content

uint32_t contentSize() const

return size of object content, excluding header and size fields

Note

must check return error code

Return Value

• size: or error code

uint32_t size() const

total size this object occupies in the image

Note

objects are word-aligned but this method returns only the used size

Return Value

• size: or error code

Public Members

uint8_t typeData

Stored type plus flag.

uint32_t value

32-bit identifier, e.g. volume ID

uint16_t _contentSize

Object size (excluding this header)

uint8_t namelen

Length of object name.

uint8_t _contentSizeHigh

Allows data up to 16MByte.

struct ObjRef

#include <ObjectStore.h>

gives the identity and location of an FWFS object

Public Members

uint32_t offset = {0}

Offset from start of image.

uint8_t handle = {0}

SPIFFS object store requires handles.

uint8_t storenum = {0}

Object store number.

uint8_t readCount = {0}

For profiling.

uint8_t refCount = {0}

For testing open/close correctness.

struct Stat

#include <Stat.h>

File Status structure.

Subclassed by IFS::NameStat

Public Functions

Stat &operator=(const Stat &rhs)

assign content from another Stat structure

Note

All fields are copied as for a normal assignment, except for ‘name’, where rhs.name contents are copied into our name buffer.

Public Members

IFileSystem *fs = {nullptr}

The filing system owning this file.

NameBuffer name

Name of file.

uint32_t size = {0}

Size of file in bytes.

FileID id = {0}

Internal file identifier.

ACL acl = {UserRole::None, UserRole::None}

Access Control.

TimeStamp mtime = {}

File modification time.

struct TimeStamp

#include <TimeStamp.h>

Manage IFS timestamps stored as an unsigned 32-bit value.

A signed 32-bit value containing seconds will overflow in about 136 years. time_t starts at 1970.

namespace Error

Enums

enum Value

Values:

XX

MAX

Functions

String toString(int err)

get text for an error code

Parameters

• err:

Return Value

• String:

bool isSystem(int err)

Determine if the given IFS error code is system-specific.

int fromSystem(int syscode)

Translate system error code into IFS error code.

int toSystem(int err)

Translate IFS error code into SYSTEM code.

Variables

constexpr ErrorCode USER = {-100}

constexpr ErrorCode SYSTEM = {-1000}

namespace FWFS

Typedefs

using FWFileDescAttributes = BitSet<uint8_t, FWFileDescAttr, 1>

Enums

enum FWFileDescAttr

file descriptor attributes

Note

these are bit values, combine using _BV()

Values:

allocated

Descriptor in use.

class FileSystem : public IFS::IFileSystem

#include <FileSystem.h>

Implementation of firmware filing system using IFS.

Public Functions

int setVolume(uint8_t num, IObjectStore *store)

Set object stores.

Parameters

• num: which store to set

• store: the object store object

Return Value

• int: error code

int mount()

Mount file system, performing any required initialisation.

Return Value

• error: code

int getinfo(Info &info)

get filing system information

Parameters

• info: structure to read information into

Return Value

• int: error code

int opendir(const char *path, DirHandle &dir)

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 Value

• int: error code

int fopendir(const Stat *stat, DirHandle &dir)

open a directory for reading

Parameters

• stat: identifies directory to open. nullptr is interpreted as root directory

• dir: returns a pointer to the directory object

Return Value

• int: error code

int readdir(DirHandle dir, Stat &stat)

read a directory entry

Note

File system allocates entries structure as it usually needs to track other information. It releases memory when closedir() is called.

Parameters

• dir:

• stat:

Return Value

• int: error code

int rewinddir(DirHandle dir)

Reset directory read position to start.

Parameters

• dir:

Return Value

• int: error code

int closedir(DirHandle dir)

close a directory object

Parameters

• dir: directory to close

Return Value

• int: error code

int mkdir(const char *path)

Create a directory.

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.

Parameters

• path: Path to directory

Return Value

• int: error code

int stat(const char *path, Stat *stat)

get file information

Parameters

• path: name or path of file

• s: structure to return information in, may be null to do a simple file existence check

Return Value

• int: error code

int fstat(FileHandle file, Stat *stat)

get file information

Parameters

• file: handle to open file

• stat: structure to return information in, may be null

Return Value

• int: error code

int fcontrol(FileHandle file, ControlCode code, void *buffer, size_t bufSize)

Low-level and non-standard file control operations.

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.

Parameters

• file:

• code: FCNTL_XXX code

• buffer: Input/Output buffer

• bufSize: Size of buffer

Return Value

• int: error code or, on success, data size

int setacl(FileHandle file, const ACL &acl)

Set access control information for file.

Parameters

• file: handle to open file

• acl:

Return Value

• int: error code

int setattr(const char *path, FileAttributes attr)

Set file attributes.

Parameters

• path: Full path to file

• attr:

Return Value

• int: error code

int settime(FileHandle file, time_t mtime)

Set modificatino tiem for file.

Note

any subsequent writes to file will reset this to current time

Parameters

• file: handle to open file, must have write access

Return Value

• int: error code

int setcompression(FileHandle file, const Compression &compression)

Set file compression information.

Parameters

• file:

• compression:

Return Value

• int: error code

FileHandle open(const char *path, OpenFlags flags)

open a file by name/path

Parameters

• path: full path to file

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

FileHandle fopen(const Stat &stat, OpenFlags flags)

open a file from it’s stat structure

Parameters

• stat: obtained from readdir()

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

int close(FileHandle file)

close an open file

Parameters

• file: handle to open file

Return Value

• int: error code

int read(FileHandle file, void *data, size_t size)

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 Value

• int: number of bytes read or error code

int write(FileHandle file, const void *data, size_t size)

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 Value

• int: number of bytes written or error code

int lseek(FileHandle file, int offset, SeekOrigin origin)

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 Value

• int: current position or error code

int eof(FileHandle file)

determine if current file position is at end of file

Parameters

• file: handle to open file

Return Value

• int: 0 - not EOF, > 0 - at EOF, < 0 - error

int32_t tell(FileHandle file)

get current file position

Parameters

• file: handle to open file

Return Value

• int32_t: current position relative to start of file, or error code

int ftruncate(FileHandle file, size_t new_size)

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:

Return Value

• int: Error code

int flush(FileHandle file)

flush any buffered data to physical media

Parameters

• file: handle to open file

Return Value

• int: error code

int rename(const char *oldpath, const char *newpath)

rename a file

Parameters

• oldpath:

• newpath:

Return Value

• int: error code

int remove(const char *path)

remove (delete) a file by path

Parameters

• path:

Return Value

• int: error code

int fremove(FileHandle file)

remove (delete) a file by handle

Parameters

• file: handle to open file

Return Value

• int: error code

int format()

format the filing system

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.

Return Value

• int: error code

int check()

Perform a file system consistency check.

Note

if possible, issues should be resolved. Returns 0 if file system checked out OK. Otherwise there were issues: < 0 for unrecoverable errors,

Return Value

• int: error code

int getFilePath(FileID fileid, NameBuffer &path)

get the full path of a file from its ID

Parameters

• fileid:

• path:

Return Value

• int: error code

struct FWFileDesc

#include <FileSystem.h>

FWFS File Descriptor.

Public Members

FWObjDesc odFile

File object.

uint32_t dataSize = {0}

Total size of data.

uint32_t cursor = {0}

Current read/write offset within file data.

struct FWVolume

#include <FileSystem.h>

FWFS Volume definition - identifies object store and volume object after mounting.

Public Members

ObjRef ref

Volume reference.

class ObjectStore : public IFS::IObjectStore

#include <ObjectStore.h>

object store for read-only filesystem

Public Functions

int initialise()

called by FWFS

Return Value

• error: code

int mounted(const FWObjDesc &od)

called by FWFS to confirm successful mount

Parameters

• od: last object (the end marker)

Return Value

• int: error code

bool isMounted()

determine if store is mounted

Return Value

• true: if mounted

int open(FWObjDesc &od)

find an object and return a descriptor for it

Note

od.ref must be initialised

Parameters

• od: IN/OUT: resolved object

Return Value

• int: error code

int openChild(const FWObjDesc &parent, const FWObjDesc &child, FWObjDesc &od)

open a descriptor for a child object

Parameters

• parent:

• child: reference to child, relative to parent

• od: OUT: resolved object

Return Value

• int: error code

int readHeader(FWObjDesc &od)

read a root object header

Note

this method deals with top-level objects only

Parameters

• od: object descriptor, with offset and ID fields initialised

Return Value

• error: code

int readChildHeader(const FWObjDesc &parent, FWObjDesc &child)

fetch child object header

Note

references are not pursued; the caller must handle that child.ref refers to position relative to parent Implementations must set child.storenum = parent.storenum; other values will be meaningless as object stores are unaware of other stores.

Parameters

• parent:

• child: uninitialised child, returns result

Return Value

• error: code

int readContent(const FWObjDesc &od, uint32_t offset, uint32_t size, void *buffer)

read object content

Note

must fail if cannot read all requested bytes

Parameters

• offset: location to start reading, from start of object content

• size: bytes to read

• buffer: to store data

Return Value

• number: of bytes read, or error code

int close(FWObjDesc &od)

close an object descriptor

Note

the implementation should free any allocated resources

Parameters

• od:

Return Value

• int: error code

class ObjRefCache

#include <ObjRefCache.h>

Cache the locations of several objects to improve search speed.

Public Functions

void improve(ObjRef &ref, FWFS::Object::ID objID)

see if the cache can get a better search position to find an object

Note

FWRO object IDs are sequential indices, so we’ll try to get the start offset as close as possible

Parameters

• ref: current object reference, must be valid

• objID: object we’re looking for

namespace Gdb

class FileSystem : public IFS::IFileSystem

#include <FileSystem.h>

IFS implementation of Host filing system.

Public Functions

int mount()

Mount file system, performing any required initialisation.

Return Value

• error: code

int getinfo(Info &info)

get filing system information

Parameters

• info: structure to read information into

Return Value

• int: error code

String getErrorString(int err)

get the text for a returned error code

Return Value

• String:

int opendir(const char *path, DirHandle &dir)

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 Value

• int: error code

int rewinddir(DirHandle dir)

Reset directory read position to start.

Parameters

• dir:

Return Value

• int: error code

int readdir(DirHandle dir, Stat &stat)

read a directory entry

Note

File system allocates entries structure as it usually needs to track other information. It releases memory when closedir() is called.

Parameters

• dir:

• stat:

Return Value

• int: error code

int closedir(DirHandle dir)

close a directory object

Parameters

• dir: directory to close

Return Value

• int: error code

int mkdir(const char *path)

Create a directory.

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.

Parameters

• path: Path to directory

Return Value

• int: error code

int stat(const char *path, Stat *stat)

get file information

Parameters

• path: name or path of file

• s: structure to return information in, may be null to do a simple file existence check

Return Value

• int: error code

int fstat(FileHandle file, Stat *stat)

get file information

Parameters

• file: handle to open file

• stat: structure to return information in, may be null

Return Value

• int: error code

int setacl(FileHandle file, const ACL &acl)

Set access control information for file.

Parameters

• file: handle to open file

• acl:

Return Value

• int: error code

int setattr(const char *path, FileAttributes attr)

Set file attributes.

Parameters

• path: Full path to file

• attr:

Return Value

• int: error code

int settime(FileHandle file, time_t mtime)

Set modificatino tiem for file.

Note

any subsequent writes to file will reset this to current time

Parameters

• file: handle to open file, must have write access

Return Value

• int: error code

int setcompression(FileHandle file, const Compression &compression)

Set file compression information.

Parameters

• file:

• compression:

Return Value

• int: error code

FileHandle open(const char *path, OpenFlags flags)

open a file by name/path

Parameters

• path: full path to file

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

FileHandle fopen(const Stat &stat, OpenFlags flags)

open a file from it’s stat structure

Parameters

• stat: obtained from readdir()

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

int close(FileHandle file)

close an open file

Parameters

• file: handle to open file

Return Value

• int: error code

int read(FileHandle file, void *data, size_t size)

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 Value

• int: number of bytes read or error code

int write(FileHandle file, const void *data, size_t size)

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 Value

• int: number of bytes written or error code

int lseek(FileHandle file, int offset, SeekOrigin origin)

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 Value

• int: current position or error code

int eof(FileHandle file)

determine if current file position is at end of file

Parameters

• file: handle to open file

Return Value

• int: 0 - not EOF, > 0 - at EOF, < 0 - error

int32_t tell(FileHandle file)

get current file position

Parameters

• file: handle to open file

Return Value

• int32_t: current position relative to start of file, or error code

int ftruncate(FileHandle file, size_t new_size)

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:

Return Value

• int: Error code

int flush(FileHandle file)

flush any buffered data to physical media

Parameters

• file: handle to open file

Return Value

• int: error code

int rename(const char *oldpath, const char *newpath)

rename a file

Parameters

• oldpath:

• newpath:

Return Value

• int: error code

int remove(const char *path)

remove (delete) a file by path

Parameters

• path:

Return Value

• int: error code

int fremove(FileHandle file)

remove (delete) a file by handle

Parameters

• file: handle to open file

Return Value

• int: error code

int format()

format the filing system

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.

Return Value

• int: error code

int check()

Perform a file system consistency check.

Note

if possible, issues should be resolved. Returns 0 if file system checked out OK. Otherwise there were issues: < 0 for unrecoverable errors,

Return Value

• int: error code

namespace Host

Functions

FileSystem &getFileSystem()

Get the currently active file system, if any.

Return Value

• IFS::IFileSystem*:

int syserr()

Get IFS error code for the current system errno.

int mapFlags(OpenFlags flags)

Get corresponding host flags for given IFS flags.

String getErrorString(int err)

class FileSystem : public IFS::IFileSystem

#include <FileSystem.h>

IFS implementation of Host filing system.

Public Functions

int mount()

Mount file system, performing any required initialisation.

Return Value

• error: code

int getinfo(Info &info)

get filing system information

Parameters

• info: structure to read information into

Return Value

• int: error code

String getErrorString(int err)

get the text for a returned error code

Return Value

• String:

int opendir(const char *path, DirHandle &dir)

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 Value

• int: error code

int rewinddir(DirHandle dir)

Reset directory read position to start.

Parameters

• dir:

Return Value

• int: error code

int readdir(DirHandle dir, Stat &stat)

read a directory entry

Note

File system allocates entries structure as it usually needs to track other information. It releases memory when closedir() is called.

Parameters

• dir:

• stat:

Return Value

• int: error code

int closedir(DirHandle dir)

close a directory object

Parameters

• dir: directory to close

Return Value

• int: error code

int mkdir(const char *path)

Create a directory.

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.

Parameters

• path: Path to directory

Return Value

• int: error code

int stat(const char *path, Stat *stat)

get file information

Parameters

• path: name or path of file

• s: structure to return information in, may be null to do a simple file existence check

Return Value

• int: error code

int fstat(FileHandle file, Stat *stat)

get file information

Parameters

• file: handle to open file

• stat: structure to return information in, may be null

Return Value

• int: error code

int setacl(FileHandle file, const ACL &acl)

Set access control information for file.

Parameters

• file: handle to open file

• acl:

Return Value

• int: error code

int setattr(const char *path, FileAttributes attr)

Set file attributes.

Parameters

• path: Full path to file

• attr:

Return Value

• int: error code

int settime(FileHandle file, time_t mtime)

Set modificatino tiem for file.

Note

any subsequent writes to file will reset this to current time

Parameters

• file: handle to open file, must have write access

Return Value

• int: error code

int setcompression(FileHandle file, const Compression &compression)

Set file compression information.

Parameters

• file:

• compression:

Return Value

• int: error code

FileHandle open(const char *path, OpenFlags flags)

open a file by name/path

Parameters

• path: full path to file

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

FileHandle fopen(const Stat &stat, OpenFlags flags)

open a file from it’s stat structure

Parameters

• stat: obtained from readdir()

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

int close(FileHandle file)

close an open file

Parameters

• file: handle to open file

Return Value

• int: error code

int read(FileHandle file, void *data, size_t size)

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 Value

• int: number of bytes read or error code

int write(FileHandle file, const void *data, size_t size)

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 Value

• int: number of bytes written or error code

int lseek(FileHandle file, int offset, SeekOrigin origin)

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 Value

• int: current position or error code

int eof(FileHandle file)

determine if current file position is at end of file

Parameters

• file: handle to open file

Return Value

• int: 0 - not EOF, > 0 - at EOF, < 0 - error

int32_t tell(FileHandle file)

get current file position

Parameters

• file: handle to open file

Return Value

• int32_t: current position relative to start of file, or error code

int ftruncate(FileHandle file, size_t new_size)

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:

Return Value

• int: Error code

int flush(FileHandle file)

flush any buffered data to physical media

Parameters

• file: handle to open file

Return Value

• int: error code

int rename(const char *oldpath, const char *newpath)

rename a file

Parameters

• oldpath:

• newpath:

Return Value

• int: error code

int remove(const char *path)

remove (delete) a file by path

Parameters

• path:

Return Value

• int: error code

int fremove(FileHandle file)

remove (delete) a file by handle

Parameters

• file: handle to open file

Return Value

• int: error code

int format()

format the filing system

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.

Return Value

• int: error code

int check()

Perform a file system consistency check.

Note

if possible, issues should be resolved. Returns 0 if file system checked out OK. Otherwise there were issues: < 0 for unrecoverable errors,

Return Value

• int: error code

namespace HYFS

class FileSystem : public IFS::IFileSystem

#include <FileSystem.h>

Public Functions

int mount()

Mount file system, performing any required initialisation.

Return Value

• error: code

int getinfo(Info &info)

get filing system information

Parameters

• info: structure to read information into

Return Value

• int: error code

String getErrorString(int err)

get the text for a returned error code

Return Value

• String:

int opendir(const char *path, DirHandle &dir)

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 Value

• int: error code

int readdir(DirHandle dir, Stat &stat)

read a directory entry

Note

File system allocates entries structure as it usually needs to track other information. It releases memory when closedir() is called.

Parameters

• dir:

• stat:

Return Value

• int: error code

int rewinddir(DirHandle dir)

Reset directory read position to start.

Parameters

• dir:

Return Value

• int: error code

int closedir(DirHandle dir)

close a directory object

Parameters

• dir: directory to close

Return Value

• int: error code

int mkdir(const char *path)

Create a directory.

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.

Parameters

• path: Path to directory

Return Value

• int: error code

int stat(const char *path, Stat *stat)

get file information

Parameters

• path: name or path of file

• s: structure to return information in, may be null to do a simple file existence check

Return Value

• int: error code

int fstat(FileHandle file, Stat *stat)

get file information

Parameters

• file: handle to open file

• stat: structure to return information in, may be null

Return Value

• int: error code

int fcontrol(FileHandle file, ControlCode code, void *buffer, size_t bufSize)

Low-level and non-standard file control operations.

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.

Parameters

• file:

• code: FCNTL_XXX code

• buffer: Input/Output buffer

• bufSize: Size of buffer

Return Value

• int: error code or, on success, data size

int setacl(FileHandle file, const ACL &acl)

Set access control information for file.

Parameters

• file: handle to open file

• acl:

Return Value

• int: error code

int setattr(const char *path, FileAttributes attr)

Set file attributes.

Parameters

• path: Full path to file

• attr:

Return Value

• int: error code

int settime(FileHandle file, time_t mtime)

Set modificatino tiem for file.

Note

any subsequent writes to file will reset this to current time

Parameters

• file: handle to open file, must have write access

Return Value

• int: error code

int setcompression(FileHandle file, const Compression &compression)

Set file compression information.

Parameters

• file:

• compression:

Return Value

• int: error code

FileHandle open(const char *path, OpenFlags flags)

open a file by name/path

Parameters

• path: full path to file

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

FileHandle fopen(const Stat &stat, OpenFlags flags)

open a file from it’s stat structure

Parameters

• stat: obtained from readdir()

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

int close(FileHandle file)

close an open file

Parameters

• file: handle to open file

Return Value

• int: error code

int read(FileHandle file, void *data, size_t size)

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 Value

• int: number of bytes read or error code

int write(FileHandle file, const void *data, size_t size)

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 Value

• int: number of bytes written or error code

int lseek(FileHandle file, int offset, SeekOrigin origin)

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 Value

• int: current position or error code

int eof(FileHandle file)

determine if current file position is at end of file

Parameters

• file: handle to open file

Return Value

• int: 0 - not EOF, > 0 - at EOF, < 0 - error

int32_t tell(FileHandle file)

get current file position

Parameters

• file: handle to open file

Return Value

• int32_t: current position relative to start of file, or error code

int ftruncate(FileHandle file, size_t new_size)

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:

Return Value

• int: Error code

int flush(FileHandle file)

flush any buffered data to physical media

Parameters

• file: handle to open file

Return Value

• int: error code

int rename(const char *oldpath, const char *newpath)

rename a file

Parameters

• oldpath:

• newpath:

Return Value

• int: error code

int remove(const char *path)

remove (delete) a file by path

Parameters

• path:

Return Value

• int: error code

int fremove(FileHandle file)

remove (delete) a file by handle

Parameters

• file: handle to open file

Return Value

• int: error code

int format()

format the filing system

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.

Return Value

• int: error code

int check()

Perform a file system consistency check.

Note

if possible, issues should be resolved. Returns 0 if file system checked out OK. Otherwise there were issues: < 0 for unrecoverable errors,

Return Value

• int: error code

namespace SPIFFS

Functions

bool isSpiffsError(int err)

String spiffsErrorToStr(int err)

struct FileMeta

#include <FileMeta.h>

Content of SPIFFS metadata area.

Public Static Attributes

constexpr uint32_t Magic = {0xE3457A77}

This number is made up, but serves to identify that metadata is valid.

class FileSystem : public IFS::IFileSystem

#include <FileSystem.h>

Public Functions

int mount()

Mount file system, performing any required initialisation.

Return Value

• error: code

int getinfo(Info &info)

get filing system information

Parameters

• info: structure to read information into

Return Value

• int: error code

String getErrorString(int err)

get the text for a returned error code

Return Value

• String:

int opendir(const char *path, DirHandle &dir)

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 Value

• int: error code

int readdir(DirHandle dir, Stat &stat)

read a directory entry

Note

File system allocates entries structure as it usually needs to track other information. It releases memory when closedir() is called.

Parameters

• dir:

• stat:

Return Value

• int: error code

int rewinddir(DirHandle dir)

Reset directory read position to start.

Parameters

• dir:

Return Value

• int: error code

int closedir(DirHandle dir)

close a directory object

Parameters

• dir: directory to close

Return Value

• int: error code

int mkdir(const char *path)

Create a directory.

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.

Parameters

• path: Path to directory

Return Value

• int: error code

int stat(const char *path, Stat *stat)

get file information

Parameters

• path: name or path of file

• s: structure to return information in, may be null to do a simple file existence check

Return Value

• int: error code

int fstat(FileHandle file, Stat *stat)

get file information

Parameters

• file: handle to open file

• stat: structure to return information in, may be null

Return Value

• int: error code

int setacl(FileHandle file, const ACL &acl)

Set access control information for file.

Parameters

• file: handle to open file

• acl:

Return Value

• int: error code

int setattr(const char *path, FileAttributes attr)

Set file attributes.

Parameters

• path: Full path to file

• attr:

Return Value

• int: error code

int settime(FileHandle file, time_t mtime)

Set modificatino tiem for file.

Note

any subsequent writes to file will reset this to current time

Parameters

• file: handle to open file, must have write access

Return Value

• int: error code

int setcompression(FileHandle file, const Compression &compression)

Set file compression information.

Parameters

• file:

• compression:

Return Value

• int: error code

FileHandle open(const char *path, OpenFlags flags)

open a file by name/path

Parameters

• path: full path to file

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

FileHandle fopen(const Stat &stat, OpenFlags flags)

open a file from it’s stat structure

Parameters

• stat: obtained from readdir()

• flags: opens for opening file

Return Value

• FileHandle: file handle or error code

int close(FileHandle file)

close an open file

Parameters

• file: handle to open file

Return Value

• int: error code

int read(FileHandle file, void *data, size_t size)

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 Value

• int: number of bytes read or error code

int write(FileHandle file, const void *data, size_t size)

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 Value

• int: number of bytes written or error code

int lseek(FileHandle file, int offset, SeekOrigin origin)

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 Value

• int: current position or error code

int eof(FileHandle file)

determine if current file position is at end of file

Parameters

• file: handle to open file

Return Value

• int: 0 - not EOF, > 0 - at EOF, < 0 - error

int32_t tell(FileHandle file)

get current file position

Parameters

• file: handle to open file

Return Value

• int32_t: current position relative to start of file, or error code

int ftruncate(FileHandle file, size_t new_size)

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:

Return Value

• int: Error code

int flush(FileHandle file)

flush any buffered data to physical media

Parameters

• file: handle to open file

Return Value

• int: error code

int rename(const char *oldpath, const char *newpath)

rename a file

Parameters

• oldpath:

• newpath:

Return Value

• int: error code

int remove(const char *path)

remove (delete) a file by path

Parameters

• path:

Return Value

• int: error code

int fremove(FileHandle file)

remove (delete) a file by handle

Parameters

• file: handle to open file

Return Value

• int: error code

int format()

format the filing system

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.

Return Value

• int: error code

int check()

Perform a file system consistency check.

Note

if possible, issues should be resolved. Returns 0 if file system checked out OK. Otherwise there were issues: < 0 for unrecoverable errors,

Return Value

• int: error code

int getFilePath(FileID fileid, NameBuffer &buffer)

get the full path of a file from its ID

Parameters

• fileid:

• buffer:

Return Value

• int: error code

References

• Source Code (submodule, may be patched).

• FlashString Component

• SPIFFS for Sming Component

Used by

• Sming (main) ,Component

Environment Variables

• FSBUILD