Path-namespace operations over the ra8_io VFS named-mount table. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_fs.h"
#include "ra8_io_fsfmt.h"
#include "ra8_io_vfs.h"
#include "ra8_io_vfs_internal.h"

Include dependency graph for ra8_io_vfs_namespace.c:

Functions
ra8_err_t	ra8_io_vfs_unlink (const char *path)
	Delete a file by "name:/path".
static ra8_err_t	internal_vfs_rename_split (const char old_path, const char new_path, char old_name, char new_name, const char out_old_sub, const char out_new_sub)
	Split both rename paths and require them to name the same mount.
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_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".

Variables
static const char *const	s_tag = "ra8_io_vfs_namespace"
	Module log tag.

Detailed Description

Path-namespace operations over the ra8_io VFS named-mount table.

Tag: [Ring 4 / PAL] {World: NS}

Owns every request that names an entry rather than holds one open: removal, same-mount rename, metadata, directory listing, bounded directory cursors, and directory creation and removal. Each call resolves "name:sub" to a mount slot through priv_ra8_io_vfs_resolve, checks the mount format's advertised capability explicitly, then dispatches to that format's ra8_io_fsfmt_ops_t entry. A rename whose two paths name different mounts is refused rather than emulated, because this facade performs no cross-format copy. All storage is caller-owned or lives in the mount table this unit never touches directly.

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

Since: 0.1.0

Definition in file ra8_io_vfs_namespace.c.

Function Documentation

◆ internal_vfs_rename_split()

ra8_err_t internal_vfs_rename_split	(	const char *	old_path,
		const char *	new_path,
		char *	old_name,
		char *	new_name,
		const char **	out_old_sub,
		const char **	out_new_sub )

static

Split both rename paths and require them to name the same mount.

Renaming across mounts is not a rename this facade supports (it would need a cross-format copy), so both paths must resolve to the identical mount name.

Parameters

[in]	old_path	Full VFS path of the existing entry.
[in]	new_path	Full VFS path of the desired name.
[out]	old_name	Mount-name buffer for `old_path`, at least k_ra8_io_vfs_name_max bytes.
[out]	new_name	Mount-name buffer for `new_path`, at least k_ra8_io_vfs_name_max bytes.
[out]	out_old_sub	Sub-path within the mount for `old_path`.
[out]	out_new_sub	Sub-path within the mount for `new_path`.

Returns: Split-and-match status.

Return values

k_ra8_ok	Both paths split cleanly and name the same mount.
k_ra8_err_invalid_arg	The two paths name different mounts.
other	Either path failed to split.

Precondition: All six parameters are non-NULL.; Both name buffers hold k_ra8_io_vfs_name_max writable bytes.

Postcondition: No mount table entry is modified.; On success both sub-path outputs alias the caller's input strings.

Note: Not thread-safe; caller serializes VFS-table access.

Since: Version 0.1.0

Definition at line 77 of file ra8_io_vfs_namespace.c.

References k_ra8_err_invalid_arg, k_ra8_ok, priv_ra8_io_vfs_split(), priv_ra8_io_vfs_streq(), RA8_INTERNAL, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ra8_io_vfs_rename().

◆ 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_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_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().

Variable Documentation

◆ s_tag

const char* const s_tag = "ra8_io_vfs_namespace"

static

Module log tag.

Definition at line 36 of file ra8_io_vfs_namespace.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_vfs_rename_split()

◆ ra8_io_vfs_dir_close()

◆ ra8_io_vfs_dir_next()

◆ ra8_io_vfs_dir_open()

◆ ra8_io_vfs_dir_requirements()

◆ ra8_io_vfs_listdir()

◆ ra8_io_vfs_mkdir()

◆ ra8_io_vfs_rename()

◆ ra8_io_vfs_rmdir()

◆ ra8_io_vfs_stat()

◆ ra8_io_vfs_unlink()

Variable Documentation

◆ s_tag