ra8_io_vfs.h File Reference

ra8_io virtual filesystem – mount many volumes, address them by name. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_fs.h"
#include "ra8_io_fsfmt.h"

Include dependency graph for ra8_io_vfs.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ra8_io_vfs_dir_t
	Caller-owned format-neutral directory cursor. More...
struct	ra8_io_vfs_stat_t
	Metadata returned by ra8_io_vfs_stat. More...

Typedefs
typedef struct ra8_io_vfs_file	ra8_io_vfs_file_t

Enumerations
enum	ra8_io_vfs_limits_t : uint8_t {   k_ra8_io_vfs_max_mounts = 4 ,   k_ra8_io_vfs_max_files = 4 ,   k_ra8_io_vfs_name_max = 16 }
	Static limits for the VFS mount table. More...

Functions
ra8_err_t	ra8_io_vfs_init (void)
	Reset the VFS mount table to empty.
ra8_err_t	ra8_io_vfs_mount (const char *name, ra8_fs_mount_t *mount)
	Register a mounted volume under a name.
ra8_err_t	ra8_io_vfs_mount_auto (const char *name, const ra8_fs_backend_t *backend)
	Probe and mount a block backend through the registered format ops.
ra8_err_t	ra8_io_vfs_unmount (const char *name)
	Remove a named mount from the table.
ra8_err_t	ra8_io_vfs_open (const char *path, ra8_fs_mode_t mode, ra8_fs_file_t **out_file)
	Open a file by "name:/path".
ra8_err_t	ra8_io_vfs_file_open (const char *path, ra8_fs_mode_t mode, ra8_io_vfs_file_t **out_file)
	Open a format-neutral stream through a mounted format's ops.
ra8_err_t	ra8_io_vfs_file_close (ra8_io_vfs_file_t *file)
	Close and always release one format-neutral stream facade.
ra8_err_t	ra8_io_vfs_file_read (ra8_io_vfs_file_t *file, void *buf, uint32_t bytes, uint32_t *out_read)
	Read bytes through a format-neutral stream.
ra8_err_t	ra8_io_vfs_file_write (ra8_io_vfs_file_t *file, const void *buf, uint32_t bytes)
	Write bytes, or return not-supported when capability-gated.
ra8_err_t	ra8_io_vfs_file_seek (ra8_io_vfs_file_t *file, uint64_t offset_bytes)
	Seek a format-neutral stream.
ra8_err_t	ra8_io_vfs_file_tell (const ra8_io_vfs_file_t *file, uint64_t *out_offset)
	Report a format-neutral stream's current offset.
ra8_err_t	ra8_io_vfs_file_size (const ra8_io_vfs_file_t *file, uint64_t *out_bytes)
	Report a format-neutral stream's size.
ra8_err_t	ra8_io_vfs_file_sync (ra8_io_vfs_file_t *file)
	Explicitly sync a stream, or return not-supported when unavailable.
ra8_err_t	ra8_io_vfs_unlink (const char *path)
	Delete a file by "name:/path".
ra8_err_t	ra8_io_vfs_rename (const char *old_path, const char *new_path)
	Rename a file within one mount.
ra8_err_t	ra8_io_vfs_stat (const char *path, ra8_io_vfs_stat_t *out)
	Query metadata for "name:/path".
ra8_err_t	ra8_io_vfs_get_caps (const char *name, ra8_io_fsfmt_caps_t *out)
	Copy the truthful capabilities of a named mounted format.
ra8_err_t	ra8_io_vfs_free_space (const char *name, ra8_fs_space_t *out)
	Query free and total bytes through a mounted format's ops.
ra8_err_t	ra8_io_vfs_listdir (const char *path, ra8_fs_listdir_cb_t cb, void *ctx)
	Enumerate a directory named "name:/path".
ra8_err_t	ra8_io_vfs_dir_requirements (const char *path, uint32_t *out_bytes, uint8_t *out_align, uint16_t *out_max_open)
	Query cursor workspace requirements for a qualified directory path.
ra8_err_t	ra8_io_vfs_dir_open (const char *path, ra8_io_vfs_dir_t *directory, void *workspace, uint32_t workspace_bytes)
	Open a format-neutral incremental directory cursor.
ra8_err_t	ra8_io_vfs_dir_next (ra8_io_vfs_dir_t *directory, ra8_fs_dirent_t *out, bool *out_entry)
	Copy one stable entry or report clean end-of-directory.
ra8_err_t	ra8_io_vfs_dir_close (ra8_io_vfs_dir_t *directory)
	Close and consume one caller-owned VFS directory cursor.
ra8_err_t	ra8_io_vfs_mkdir (const char *path)
	Create a directory named "name:/path".
ra8_err_t	ra8_io_vfs_rmdir (const char *path)
	Remove the empty directory named "name:/path".

Detailed Description

ra8_io virtual filesystem – mount many volumes, address them by name.

Tag

[Ring 4 / PAL] {World: NS}

The VFS is a small mount table over ra8_fs: register a mounted volume under a short name (e.g. "sd", "ospi", "ram"), then reach files through a "name:/path" string. This is the "address storage by name, not by peripheral" layer – several filesystems on different media coexist and are told apart by their mount name. Each registered mount is an ra8_fs_mount_t the caller obtained by mounting an ra8_fs_backend_t (typically one produced by ra8_io_blockdev_as_fs_backend over any block device).

Path-resolving operations (open / unlink / rename / stat / listdir / mkdir / rmdir) live here; once a file is open the caller drives it with the existing ra8_fs_read / ra8_fs_write / ra8_fs_seek / ra8_fs_close file operations.

ra8_fs_backend_t be = {};
(void)ra8_io_blockdev_as_fs_backend(&sd_bd, &be);
ra8_fs_mount_t* m = nullptr;
(void)ra8_fs_mount(&be, &m);
(void)ra8_io_vfs_mount("sd", m);
ra8_fs_file_t* f = nullptr;
(void)ra8_io_vfs_open("sd:/book.epb", k_ra8_fs_mode_read, &f);

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

0.1.0

Definition in file ra8_io_vfs.h.

Typedef Documentation

ra8_io_vfs_file_t

typedef struct ra8_io_vfs_file ra8_io_vfs_file_t

Definition at line 66 of file ra8_io_vfs.h.

Enumeration Type Documentation

ra8_io_vfs_limits_t

enum ra8_io_vfs_limits_t : uint8_t

Static limits for the VFS mount table.

Since

0.1.0

Enumerator
k_ra8_io_vfs_max_mounts	Concurrent named mounts.
k_ra8_io_vfs_max_files	Concurrent generic streams.
k_ra8_io_vfs_name_max	Mount name length incl NUL.

Definition at line 55 of file ra8_io_vfs.h.

Function Documentation

ra8_io_vfs_dir_close()

ra8_err_t ra8_io_vfs_dir_close ( ra8_io_vfs_dir_t * directory )

nodiscard

Close and consume one caller-owned VFS directory cursor.

Definition at line 234 of file ra8_io_vfs_namespace.c.

References ra8_io_vfs_dir_t::format, ra8_io_vfs_dir_t::is_open, k_ra8_err_invalid_state, k_ra8_err_null_ptr, and ra8_io_vfs_dir_t::state.

Referenced by internal_dir_close().

ra8_io_vfs_dir_next()

ra8_err_t ra8_io_vfs_dir_next ( ra8_io_vfs_dir_t * directory, ra8_fs_dirent_t * out, bool * out_entry )

nodiscard

Copy one stable entry or report clean end-of-directory.

Definition at line 221 of file ra8_io_vfs_namespace.c.

References ra8_io_vfs_dir_t::format, ra8_io_vfs_dir_t::is_open, k_ra8_err_invalid_state, k_ra8_err_null_ptr, and ra8_io_vfs_dir_t::state.

Referenced by internal_dir_next().

ra8_io_vfs_dir_open()

ra8_err_t ra8_io_vfs_dir_open ( const char * path, ra8_io_vfs_dir_t * directory, void * workspace, uint32_t workspace_bytes )

nodiscard

Open a format-neutral incremental directory cursor.

Parameters

[in]	path	Qualified VFS directory path.
[out]	directory	Idle caller-owned cursor facade.
[in,out]	workspace	Format-private caller storage.
[in]	workspace_bytes	Accessible workspace extent.

Returns

Resolution, capability, workspace, or format-open status.

Precondition

Required pointers are non-NULL and workspace meets reported requirements.

Postcondition

Success retains no mount-table lock or borrowed path pointer.

Since

0.1.0

Definition at line 182 of file ra8_io_vfs_namespace.c.

References ra8_io_fsfmt_caps_t::directory_workspace_align, vfs_slot_t::format, ra8_io_vfs_dir_t::is_open, k_ra8_err_busy, k_ra8_err_invalid_arg, k_ra8_err_no_mem, k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_ok, vfs_slot_t::mount_ctx, priv_ra8_io_vfs_resolve(), and ra8_io_fsfmt_caps_t::supports_dir_cursor.

Referenced by internal_dir_open().

ra8_io_vfs_dir_requirements()

ra8_err_t ra8_io_vfs_dir_requirements ( const char * path, uint32_t * out_bytes, uint8_t * out_align, uint16_t * out_max_open )

nodiscard

Query cursor workspace requirements for a qualified directory path.

Parameters

[in]	path	Qualified VFS path whose mount selects the format.
[out]	out_bytes	Required caller workspace bytes.
[out]	out_align	Required power-of-two workspace alignment.
[out]	out_max_open	Maximum concurrently open cursors.

Returns

Resolution or capability status.

Return values

k_ra8_err_not_supported

The mounted format declines cursor support.

Precondition

Output pointers and path are non-NULL.

Postcondition

Success reports immutable registered-format facts.

Since

0.1.0

Definition at line 154 of file ra8_io_vfs_namespace.c.

References vfs_slot_t::format, k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_ok, and priv_ra8_io_vfs_resolve().

Referenced by internal_dir_requirements().

ra8_io_vfs_file_close()

ra8_err_t ra8_io_vfs_file_close ( ra8_io_vfs_file_t * file )

nodiscard

Close and always release one format-neutral stream facade.

Definition at line 625 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_close_writer(), and internal_rabook_close().

ra8_io_vfs_file_open()

ra8_err_t ra8_io_vfs_file_open ( const char * path, ra8_fs_mode_t mode, ra8_io_vfs_file_t ** out_file )

nodiscard

Open a format-neutral stream through a mounted format's ops.

Unlike the legacy ra8_io_vfs_open native-handle adapter, this API works for every registered format. The facade comes from a fixed static pool; no heap allocation occurs.

Parameters

[in]	path	"name:/path" string.
[in]	mode	Read, write, or append.
[out]	out_file	Opaque VFS stream on success.

Return values

k_ra8_ok	Stream opened.
k_ra8_err_not_supported	The format is read-only or lacks the mode.
k_ra8_err_no_mem	The fixed stream table is full.
k_ra8_err_*	Resolution or format error.

Since

0.1.0

Definition at line 598 of file ra8_io_vfs.c.

References vfs_slot_t::format, internal_free_file(), internal_vfs_file_open_resolve(), k_ra8_err_no_mem, k_ra8_ok, vfs_slot_t::mount_ctx, RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_begin(), and internal_rabook_open_reader().

ra8_io_vfs_file_read()

ra8_err_t ra8_io_vfs_file_read ( ra8_io_vfs_file_t * file, void * buf, uint32_t bytes, uint32_t * out_read )

nodiscard

Read bytes through a format-neutral stream.

Definition at line 637 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_rabook_read_exact().

ra8_io_vfs_file_seek()

ra8_err_t ra8_io_vfs_file_seek ( ra8_io_vfs_file_t * file, uint64_t offset_bytes )

nodiscard

Seek a format-neutral stream.

Definition at line 667 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_rabook_read_exact().

ra8_io_vfs_file_size()

ra8_err_t ra8_io_vfs_file_size ( const ra8_io_vfs_file_t * file, uint64_t * out_bytes )

nodiscard

Report a format-neutral stream's size.

Definition at line 686 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_rabook_open_reader().

ra8_io_vfs_file_sync()

ra8_err_t ra8_io_vfs_file_sync ( ra8_io_vfs_file_t * file )

nodiscard

Explicitly sync a stream, or return not-supported when unavailable.

Definition at line 696 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_close_writer().

ra8_io_vfs_file_tell()

ra8_err_t ra8_io_vfs_file_tell ( const ra8_io_vfs_file_t * file, uint64_t * out_offset )

nodiscard

Report a format-neutral stream's current offset.

Definition at line 676 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, RA8_CHECK_NULL_PTR, and s_tag.

ra8_io_vfs_file_write()

ra8_err_t ra8_io_vfs_file_write ( ra8_io_vfs_file_t * file, const void * buf, uint32_t bytes )

nodiscard

Write bytes, or return not-supported when capability-gated.

Definition at line 648 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_write().

ra8_io_vfs_free_space()

ra8_err_t ra8_io_vfs_free_space ( const char * name, ra8_fs_space_t * out )

nodiscard

Query free and total bytes through a mounted format's ops.

Parameters

[in]	name	Mount name without a colon.
[out]	out	Space snapshot.

Return values

k_ra8_err_not_supported

The format lacks a free-space operation.

Since

0.1.0

Definition at line 723 of file ra8_io_vfs.c.

References vfs_slot_t::format, k_ra8_err_not_found, k_ra8_err_not_supported, vfs_slot_t::mount_ctx, priv_ra8_io_vfs_find(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_space().

ra8_io_vfs_get_caps()

ra8_err_t ra8_io_vfs_get_caps ( const char * name, ra8_io_fsfmt_caps_t * out )

nodiscard

Copy the truthful capabilities of a named mounted format.

Parameters

[in]	name	Mount name without a colon.
[out]	out	Capability snapshot.

Return values

k_ra8_ok	Capabilities copied.
k_ra8_err_not_found	No mount has that name.

Since

0.1.0

Definition at line 711 of file ra8_io_vfs.c.

References vfs_slot_t::format, k_ra8_err_not_found, k_ra8_ok, priv_ra8_io_vfs_find(), RA8_CHECK_NULL_PTR, and s_tag.

ra8_io_vfs_init()

ra8_err_t ra8_io_vfs_init ( void )

nodiscard

Reset the VFS mount table to empty.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok

All mount slots released.

Precondition

None.

No file opened through the VFS is still in use.

Postcondition

Every mount slot is free.

Subsequent path operations fail until a volume is mounted.

Note

Not thread-safe.

Since

0.1.0

Definition at line 403 of file ra8_io_vfs.c.

References internal_vfs_init_slot(), k_ra8_io_vfs_max_files, k_ra8_io_vfs_max_mounts, k_ra8_ok, s_files, and s_table.

Referenced by internal_mount_sd(), internal_sd_demo_roundtrip(), and sdhi_demo_mount_via_io().

ra8_io_vfs_listdir()

ra8_err_t ra8_io_vfs_listdir ( const char * path, ra8_fs_listdir_cb_t cb, void * ctx )

nodiscard

Enumerate a directory named "name:/path".

Parameters

[in]	path	"name:/path" directory string ("name:/" for the root).
[in]	cb	Per-entry callback (non-NULL).
[in]	ctx	Cookie forwarded to cb.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Enumeration complete.
k_ra8_err_null_ptr	path or cb was NULL.
k_ra8_err_invalid_arg	path has no name: prefix.
k_ra8_err_not_found	The mount name is absent.
k_ra8_err_*	Propagated from ra8_fs_listdir.

Precondition

The named volume is mounted.

cb is non-NULL.

Postcondition

cb was invoked once per visible entry.

No volume state is mutated.

Note

Not thread-safe.

Since

0.1.0

Definition at line 144 of file ra8_io_vfs_namespace.c.

References vfs_slot_t::format, vfs_slot_t::mount_ctx, priv_ra8_io_vfs_resolve(), RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_listdir().

ra8_io_vfs_mkdir()

ra8_err_t ra8_io_vfs_mkdir ( const char * path )

nodiscard

Create a directory named "name:/path".

Routes to the named mount and delegates to ra8_fs_mkdir, which creates the final path component as a new directory. Nested paths are supported on FAT12/16/32 and exFAT when every intermediate component already exists.

Parameters

[in]

path

"name:/path" directory string.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Directory created.
k_ra8_err_null_ptr	path was NULL.
k_ra8_err_invalid_arg	path has no name: prefix, or a bad leaf.
k_ra8_err_not_found	The mount name or a path component is absent.
k_ra8_err_exists	The directory already exists.

Precondition

The named volume is mounted.

path is non-NULL.

Postcondition

On success the directory resolves.

On any non-ok return the volume is unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 247 of file ra8_io_vfs_namespace.c.

References vfs_slot_t::format, k_ra8_err_not_supported, vfs_slot_t::mount_ctx, priv_ra8_io_vfs_resolve(), RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_mkdir(), internal_mount_sd(), ra8_io_roundtrip_subdir_file(), and sdhi_demo_roundtrip().

ra8_io_vfs_mount()

ra8_err_t ra8_io_vfs_mount ( const char * name, ra8_fs_mount_t * mount )

nodiscard

Register a mounted volume under a name.

Parameters

[in]	name	Mount name (1..15 chars, no : or /).
[in]	mount	Live ra8_fs_mount_t (must out-live the registration).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Volume registered.
k_ra8_err_null_ptr	name or mount was NULL.
k_ra8_err_invalid_arg	Name empty or too long.
k_ra8_err_exists	The name is already mounted.
k_ra8_err_no_mem	The mount table is full.

Precondition

mount was returned by ra8_fs_mount and stays alive while registered.

name contains no : or /.

Postcondition

On success "name:/..." paths resolve to mount.

On any non-ok return the table is unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 418 of file ra8_io_vfs.c.

References internal_free_mount(), internal_name_ok(), internal_store_mount(), k_ra8_err_exists, k_ra8_err_invalid_arg, k_ra8_err_no_mem, k_ra8_ok, priv_ra8_io_vfs_find(), RA8_CHECK_NULL_PTR, ra8_io_fsfmt_get_builtin(), RA8_RETURN_ON_ERROR, s_tag, and ra8_fs_mount_t::type.

Referenced by internal_demo_mount(), internal_demo_mount(), internal_mount_sd(), internal_ra8_io_roundtrip_format_mount(), internal_swap_run_one(), ra8_io_roundtrip_mount(), and sdhi_demo_mount_via_io().

ra8_io_vfs_mount_auto()

ra8_err_t ra8_io_vfs_mount_auto ( const char * name, const ra8_fs_backend_t * backend )

nodiscard

Probe and mount a block backend through the registered format ops.

Parameters

[in]	name	Mount name (1..15 chars, no : or /).
[in]	backend	Device-neutral block backend to probe and mount.

Return values

k_ra8_ok	A registered format claimed and mounted the volume.
k_ra8_err_null_ptr	An argument was NULL.
k_ra8_err_invalid_arg	The mount name was invalid.
k_ra8_err_exists	The name is already mounted.
k_ra8_err_no_mem	The fixed mount table is full.
k_ra8_err_not_found	No registered format claimed the volume.
k_ra8_err_*	The selected format's mount error.

Precondition

ra8_io_fsfmt_init was called and any foreign formats were registered.

Postcondition

On success every VFS operation dispatches through the selected format's ops.

ra8_io_vfs_unmount releases the owned format context.

Since

0.1.0

Definition at line 466 of file ra8_io_vfs.c.

References internal_free_mount(), internal_name_ok(), internal_store_mount(), internal_vfs_probe_and_mount(), k_ra8_err_exists, k_ra8_err_invalid_arg, k_ra8_err_no_mem, k_ra8_ok, priv_ra8_io_vfs_find(), RA8_CHECK_NULL_PTR, and s_tag.

ra8_io_vfs_open()

ra8_err_t ra8_io_vfs_open ( const char * path, ra8_fs_mode_t mode, ra8_fs_file_t ** out_file )

nodiscard

Open a file by "name:/path".

Parameters

[in]	path	"name:/path" string.
[in]	mode	Open mode (read / write / append).
[out]	out_file	Populated file handle on success.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	File opened.
k_ra8_err_null_ptr	path or out_file was NULL.
k_ra8_err_invalid_arg	path has no name: prefix.
k_ra8_err_not_found	The mount name or the file is absent.
k_ra8_err_*	Propagated from ra8_fs_open.

Precondition

The named volume is mounted.

out_file is writable.

Postcondition

On success drive the handle with ra8_fs_read / ra8_fs_write / etc.

On any non-ok return out_file is untouched.

Note

Not thread-safe.

Since

0.1.0

Definition at line 547 of file ra8_io_vfs.c.

References vfs_slot_t::format, internal_vfs_open_resolve(), k_ra8_ok, vfs_slot_t::mount_ctx, RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_demo_read_once(), internal_open(), internal_ra8_io_roundtrip_read_verify(), internal_ra8_io_roundtrip_write_subdir(), internal_ra8_vfs_compress_load_blob(), internal_ra8_vfs_compress_store_blob(), internal_swap_vfs_read_verify(), internal_swap_vfs_write(), ra8_io_roundtrip_read_verify(), ra8_io_roundtrip_subdir_file(), sdhi_demo_read_and_verify(), and sdhi_demo_write_payload().

ra8_io_vfs_rename()

ra8_err_t ra8_io_vfs_rename ( const char * old_path, const char * new_path )

nodiscard

Rename a file within one mount.

Parameters

[in]	old_path	"name:/old" string.
[in]	new_path	"name:/new" string (same mount as old_path).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	File renamed.
k_ra8_err_null_ptr	Either argument was NULL.
k_ra8_err_invalid_arg	Missing prefix, or the two mounts differ.
k_ra8_err_not_found	The mount or old_path is absent.
k_ra8_err_exists	new_path already exists.

Precondition

Both paths name the same mounted volume and the file is closed.

Both arguments are non-NULL.

Postcondition

On success new_path resolves to the prior file data.

On any non-ok return the volume is unchanged.

Note

Not thread-safe. Cross-mount moves are not supported.

Since

0.1.0

Definition at line 92 of file ra8_io_vfs_namespace.c.

References vfs_slot_t::format, internal_vfs_rename_split(), k_ra8_err_not_found, k_ra8_err_not_supported, k_ra8_io_vfs_name_max, k_ra8_ok, vfs_slot_t::mount_ctx, priv_ra8_io_vfs_find(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_commit(), and internal_rename().

ra8_io_vfs_rmdir()

ra8_err_t ra8_io_vfs_rmdir ( const char * path )

nodiscard

Remove the empty directory named "name:/path".

Routes to the named mount and delegates to ra8_fs_rmdir, which removes the final path component when it is an existing directory holding no live entries. FAT's own "." and ".." links are ignored; exFAT has no dot entries. The volume root and plain files are refused.

Parameters

[in]

path

"name:/path" directory string.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Directory removed.
k_ra8_err_null_ptr	path was NULL.
k_ra8_err_invalid_arg	path has no name: prefix, names the root, or names a file.
k_ra8_err_not_found	The mount name or a path component is absent.
k_ra8_err_not_empty	The directory still holds entries.

Precondition

The named volume is mounted.

path is non-NULL.

Postcondition

On success the directory no longer resolves.

On any non-ok return the volume is unchanged.

Note

Not thread-safe.

See also

ra8_io_vfs_mkdir() Creates the directory this removes.

ra8_io_vfs_unlink() Removes a file instead.

Since

0.1.0

Definition at line 265 of file ra8_io_vfs_namespace.c.

References vfs_slot_t::format, k_ra8_err_not_supported, vfs_slot_t::mount_ctx, priv_ra8_io_vfs_resolve(), RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_rmdir().

ra8_io_vfs_stat()

ra8_err_t ra8_io_vfs_stat ( const char * path, ra8_io_vfs_stat_t * out )

nodiscard

Query metadata for "name:/path".

Delegates to ra8_fs_stat(), which reads the directory entry without opening it. A directory therefore reports is_directory == true and size_bytes == 0, and attr is the entry's real attribute byte – read-only, hidden and system all survive the trip. A missing name is k_ra8_ok with exists == false, not an error: absence is an answer.

"name:/" names the volume root, which always exists and is always a directory.

Parameters

[in]	path	"name:/path" string.
[out]	out	Metadata snapshot (exists reflects presence).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Metadata resolved (exists may be false).
k_ra8_err_null_ptr	path or out was NULL.
k_ra8_err_invalid_arg	path has no name: prefix, or a component is not a valid 8.3 name.
k_ra8_err_not_found	The mount name is absent.

Precondition

The named volume is mounted.

out is writable.

Postcondition

On success *out describes the entry (or exists == false).

No volume state is mutated and no file handle is consumed.

Note

Not thread-safe unless a lock is installed (see ra8_fs_set_lock()).

See also

ra8_fs_stat() The primitive this reports.

Since

0.1.0

Definition at line 118 of file ra8_io_vfs_namespace.c.

References ra8_fs_stat_t::accessed, ra8_io_vfs_stat_t::accessed, ra8_fs_stat_t::attr, ra8_io_vfs_stat_t::attr, ra8_fs_stat_t::created, ra8_io_vfs_stat_t::created, ra8_io_vfs_stat_t::exists, vfs_slot_t::format, ra8_fs_stat_t::is_directory, ra8_io_vfs_stat_t::is_directory, k_ra8_err_not_found, k_ra8_ok, ra8_fs_stat_t::modified, ra8_io_vfs_stat_t::modified, vfs_slot_t::mount_ctx, priv_ra8_io_vfs_resolve(), RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, s_tag, ra8_fs_stat_t::size_bytes, and ra8_io_vfs_stat_t::size_bytes.

Referenced by internal_abort_stage(), internal_final_absent(), internal_mount_sd(), internal_parent_check(), internal_remove_stale_stage(), internal_staged_file_check(), and internal_stat().

ra8_io_vfs_unlink()

ra8_err_t ra8_io_vfs_unlink ( const char * path )

nodiscard

Delete a file by "name:/path".

Parameters

[in]

path

"name:/path" string.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	File unlinked.
k_ra8_err_null_ptr	path was NULL.
k_ra8_err_invalid_arg	path has no name: prefix.
k_ra8_err_not_found	The mount name or the file is absent.

Precondition

The named volume is mounted and the file is closed.

path is non-NULL.

Postcondition

On success the file no longer resolves.

On any non-ok return the volume is unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 38 of file ra8_io_vfs_namespace.c.

References vfs_slot_t::format, k_ra8_err_not_supported, vfs_slot_t::mount_ctx, priv_ra8_io_vfs_resolve(), RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_abort_stage(), internal_remove_stale_stage(), and internal_unlink().

ra8_io_vfs_unmount()

ra8_err_t ra8_io_vfs_unmount ( const char * name )

nodiscard

Remove a named mount from the table.

Parameters

[in]

name

Mount name to release.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Mount released.
k_ra8_err_null_ptr	name was NULL.
k_ra8_err_not_found	The name was not mounted.

Precondition

No file opened on this mount is still in use.

name is non-NULL.

Postcondition

"name:/..." paths no longer resolve.

The underlying ra8_fs_mount_t is left untouched (caller owns it).

Note

Not thread-safe.

Since

0.1.0

Definition at line 490 of file ra8_io_vfs.c.

References vfs_slot_t::format, k_ra8_err_busy, k_ra8_err_not_found, k_ra8_io_vfs_max_files, k_ra8_ok, vfs_slot_t::mount_ctx, vfs_slot_t::owned, priv_ra8_io_vfs_find(), RA8_CHECK_NULL_PTR, s_files, and s_tag.

Referenced by internal_swap_run_one().