High–level API wrapping an underlying littlefs-based implementation that can operate either purely in RAM, Flash or backed by a host file (persisted across runs). More...

Collaboration diagram for File System Runtime:

Data Structures
struct	fs_file_t
	File and directory metadata. More...

Typedefs
typedef struct fs_volume_t	fs_volume_t
	Opaque filesystem volume handle.

Volume management
fs_volume_t *	fs_vol_init_memory (size_t size)
	Create a new volatile (RAM) filesystem volume. More...

fs_volume_t *	fs_vol_init_file (const char *path, size_t size)
	Open or create a host file–backed persistent volume. More...

fs_volume_t *	fs_vol_init_flash (size_t size)
	Open or create a non-volatile flash-backed persistent volume. More...

void	fs_vol_finalize (fs_volume_t *volume)
	Unmount and release all resources for a volume. More...

size_t	fs_vol_size (fs_volume_t volume, size_t free)
	Return total addressable size of a mounted volume. More...

bool	fs_vol_readdir (fs_volume_t volume, const char path, fs_file_t *iterator)
	Iterate directory entries. More...

fs_file_t	fs_vol_stat (fs_volume_t volume, const char path)
	Lookup file or directory metadata for a path. More...

bool	fs_vol_mkdir (fs_volume_t volume, const char path)
	Create a directory. More...

bool	fs_vol_remove (fs_volume_t volume, const char path)
	Remove a file or (empty) directory. More...

bool	fs_vol_move (fs_volume_t volume, const char old_path, const char *new_path)
	Move or rename a file/directory. More...

File management
fs_file_t	fs_file_create (fs_volume_t volume, const char path)
	Create a new file or truncate an existing file to zero length. More...

fs_file_t	fs_file_open (fs_volume_t volume, const char path, bool write)
	Open an existing file for read/write. More...

bool	fs_file_close (fs_file_t *file)
	Close an opened file. More...

size_t	fs_file_read (fs_file_t file, void buffer, size_t size)
	Read data from an opened file. More...

size_t	fs_file_write (fs_file_t file, const void buffer, size_t size)
	Write data to an opened file. More...

bool	fs_file_seek (fs_file_t *file, size_t offset)
	Seek to a position within an opened file. More...

Detailed Description

High–level API wrapping an underlying littlefs-based implementation that can operate either purely in RAM, Flash or backed by a host file (persisted across runs).

Thread-safety: Functions are NOT thread-safe; the caller must serialize access to a volume and file. Returned pointers (paths/names) reference caller-managed or internal static memory and must not be freed.

Function Documentation

◆ fs_file_close()

bool fs_file_close ( fs_file_t * file )

Close an opened file.

Parameters

file	File to close.

◆ fs_file_create()

fs_file_t fs_file_create	(	fs_volume_t *	volume,
		const char *	path
	)

Create a new file or truncate an existing file to zero length.

Parameters

volume	Mounted volume.
path	Path to create.

Returns: Opened read/write file, or zeroed struct on failure.

◆ fs_file_open()

fs_file_t fs_file_open	(	fs_volume_t *	volume,
		const char *	path,
		bool	write
	)

Open an existing file for read/write.

Parameters

volume	Mounted volume.
path	File path to open.
write	True to open for writing, false for read-only.

Returns: Opened file, or zeroed struct on failure.

◆ fs_file_read()

size_t fs_file_read	(	fs_file_t *	file,
		void *	buffer,
		size_t	size
	)

Read data from an opened file.

Parameters

file	File to read from.
buffer	Buffer to read data into.
size	Number of bytes to read (cannot be zero).

Returns: Number of bytes read, or 0 on error.

◆ fs_file_seek()

bool fs_file_seek	(	fs_file_t *	file,
		size_t	offset
	)

Seek to a position within an opened file.

Parameters

file	File to seek.
offset	Offset in bytes from the beginning of the file.

Returns: true on success, false on error.

◆ fs_file_write()

size_t fs_file_write	(	fs_file_t *	file,
		const void *	buffer,
		size_t	size
	)

Write data to an opened file.

Parameters

file	File to write to.
buffer	Buffer to write data from.
size	Number of bytes to write (cannot be zero).

Returns: Number of bytes written, or 0 on error.

◆ fs_vol_finalize()

void fs_vol_finalize ( fs_volume_t * volume )

Unmount and release all resources for a volume.

Parameters

volume Volume returned from an init call (may be NULL).

Safe to call with NULL (no effect). After return the pointer is invalid.

◆ fs_vol_init_file()

fs_volume_t* fs_vol_init_file	(	const char *	path,
		size_t	size
	)

Open or create a host file–backed persistent volume.

Attempts to mount the filesystem stored in path. If mounting fails, a format is performed and a fresh filesystem created. If the file is shorter than size it may be expanded (filling new space with erased pattern 0xFF).

Parameters

path	Host path to the image file (created if absent).
size	Minimum size in bytes; ignored if existing file is larger.

Returns: Mounted volume pointer, or NULL on error.

◆ fs_vol_init_flash()

fs_volume_t* fs_vol_init_flash ( size_t size )

Open or create a non-volatile flash-backed persistent volume.

Attempts to mount the filesystem stored in flash memory. The location of the volume in flash memory is implementation-specific. If mounting fails, a format is performed and a fresh filesystem created.

Parameters

size	Minimum size in bytes; ignored if existing file is larger.

Returns: Mounted volume pointer, or NULL on error.

◆ fs_vol_init_memory()

fs_volume_t* fs_vol_init_memory ( size_t size )

Create a new volatile (RAM) filesystem volume.

Parameters

size	Requested minimum size in bytes (rounded up to block geometry).

Returns: Pointer to mounted volume on success, NULL on failure.

Notes:

Contents are lost when fs_vol_finalize() is called or the process exits.
The real capacity may be larger than requested due to block rounding.

◆ fs_vol_mkdir()

bool fs_vol_mkdir	(	fs_volume_t *	volume,
		const char *	path
	)

Create a directory.

Parameters

volume	Mounted volume.
path	New directory path (parents must already exist).

Returns: true on success or if directory already exists; false on error.

◆ fs_vol_move()

bool fs_vol_move	(	fs_volume_t *	volume,
		const char *	old_path,
		const char *	new_path
	)

Move or rename a file/directory.

Parameters

volume	Mounted volume.
old_path	Existing path.
new_path	Destination path (must not already exist).

Returns: true on success, false on error (missing source, conflict, etc.).

◆ fs_vol_readdir()

bool fs_vol_readdir	(	fs_volume_t *	volume,
		const char *	path,
		fs_file_t *	iterator
	)

Iterate directory entries.

Parameters

volume	Mounted volume.
path	Directory path ("/" for root). NULL treated as root.
iterator	In/out. Provide zeroed struct to start; do NOT alter ctx.

Returns: true if an entry was produced (fields populated), false when done.

On first call, iterator must be zeroed to start iteration. Successive calls return the next entry until no more are available, at which point false is returned and iterator->name is set to NULL. The iterator state is allocated internally and freed when iteration ends or an error occurs.

Note: The order of entries is not specified and may vary between calls.; The special entries "." and ".." are not returned.; The iterator must be repeatedly called until it returns false to free internal resources.

◆ fs_vol_remove()

bool fs_vol_remove	(	fs_volume_t *	volume,
		const char *	path
	)

Remove a file or (empty) directory.

Parameters

volume	Mounted volume.
path	Path to remove.

Returns: true on success; false if not found or directory not empty.

◆ fs_vol_size()

size_t fs_vol_size	(	fs_volume_t *	volume,
		size_t *	free
	)

Return total addressable size of a mounted volume.

Parameters

volume	Volume handle.
free	Pointer to size_t to receive approximate free space in bytes (may be NULL).

Returns: Size in bytes, or 0 if volume is NULL/invalid.

◆ fs_vol_stat()

fs_file_t fs_vol_stat	(	fs_volume_t *	volume,
		const char *	path
	)

Lookup file or directory metadata for a path.

Parameters

volume	Mounted volume.
path	Absolute path within volume (NULL/empty -> root).

Returns: Populated fs_file_t. If not found, name == NULL.

objc

Data Structures

Typedefs

Volume management

File management

Detailed Description

Function Documentation

◆ fs_file_close()

◆ fs_file_create()

◆ fs_file_open()

◆ fs_file_read()

◆ fs_file_seek()

◆ fs_file_write()

◆ fs_vol_finalize()

◆ fs_vol_init_file()

◆ fs_vol_init_flash()

◆ fs_vol_init_memory()

◆ fs_vol_mkdir()

◆ fs_vol_move()

◆ fs_vol_readdir()

◆ fs_vol_remove()

◆ fs_vol_size()

◆ fs_vol_stat()