Guarded incremental-directory dispatch for portable filesystem ports. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "fw_if_fs.h"
#include "fw_if_fs_backend.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for fw_if_fs_dir.c:

Functions
static ra8_err_t	internal_cursor_names (const fw_fs_namespace_t *names)
	Validate one namespace facade used for cursor dispatch.
static ra8_err_t	internal_cursor_workspace (void *workspace, uint32_t bytes, uint32_t need, uint8_t align)
	Validate cursor workspace size and alignment.
static ra8_err_t	internal_cursor_handle (const fw_fs_dir_t *directory)
	Validate an open directory cursor before dispatch.
static ra8_err_t	internal_cursor_entry (const fw_fs_caps_t caps, const fw_fs_dirent_value_t entry)
	Validate one backend-produced stable directory value.
ra8_err_t	fw_fs_dir_open (const fw_fs_namespace_t names, const char path, fw_fs_dir_t directory, void workspace, uint32_t workspace_size)
	Open one directory cursor into caller-owned backend workspace.
ra8_err_t	fw_fs_dir_next (fw_fs_dir_t directory, fw_fs_dirent_value_t out, bool *out_entry)
	Copy one stable directory entry from an open cursor.
ra8_err_t	fw_fs_dir_close (fw_fs_dir_t *directory)
	Close and consume an open directory cursor, including on close error.

Detailed Description

Guarded incremental-directory dispatch for portable filesystem ports.

Tag: [Ring 2 / Interface] {World: Any}

Validates caller-owned cursor storage, lifecycle, and stable copied directory values before returning them to domain code.

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

Definition in file fw_if_fs_dir.c.

Function Documentation

◆ fw_fs_dir_close()

ra8_err_t fw_fs_dir_close ( fw_fs_dir_t * directory )

nodiscard

Close and consume an open directory cursor, including on close error.

Definition at line 217 of file fw_if_fs_dir.c.

References fw_fs_dir_t::ctx, fw_fs_namespace_iface::dir_close, fw_fs_dir_t::iface, internal_cursor_handle(), k_ra8_ok, and fw_fs_dir_t::state.

Referenced by internal_library_close(), internal_list_pages(), internal_verify_artifacts(), and internal_verify_library_root().

◆ fw_fs_dir_next()

ra8_err_t fw_fs_dir_next	(	fw_fs_dir_t *	directory,
		fw_fs_dirent_value_t *	out,
		bool *	out_entry )

nodiscard

Copy one stable directory entry from an open cursor.

No backend lock remains held after return. A clean end reports *out_entry == false and a zeroed out value.

Definition at line 190 of file fw_if_fs_dir.c.

References fw_fs_dir_t::caps, fw_fs_dir_t::ctx, fw_fs_namespace_iface::dir_next, fw_fs_dir_t::iface, internal_cursor_entry(), internal_cursor_handle(), k_ra8_err_null_ptr, k_ra8_ok, and fw_fs_dir_t::state.

Referenced by internal_library_enumerate(), internal_library_first_child(), internal_list_pages(), internal_verify_artifacts(), and internal_verify_library_root().

◆ fw_fs_dir_open()

ra8_err_t fw_fs_dir_open	(	const fw_fs_namespace_t *	names,
		const char *	path,
		fw_fs_dir_t *	directory,
		void *	workspace,
		uint32_t	workspace_size )

nodiscard

Open one directory cursor into caller-owned backend workspace.

Definition at line 150 of file fw_if_fs_dir.c.

References fw_fs_namespace_t::caps, fw_fs_namespace_t::ctx, fw_fs_namespace_iface::dir_open, fw_fs_caps_t::directory_workspace_align, fw_fs_caps_t::directory_workspace_bytes, fw_fs_path_validate(), fw_fs_namespace_t::iface, internal_cursor_names(), internal_cursor_workspace(), fw_fs_dir_t::is_open, k_ra8_err_busy, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by internal_library_enumerate(), internal_library_first_child(), internal_list_pages_open_dir(), internal_verify_artifacts(), and internal_verify_library_root().

◆ internal_cursor_entry()

ra8_err_t internal_cursor_entry	(	const fw_fs_caps_t *	caps,
		const fw_fs_dirent_value_t *	entry )

static

Validate one backend-produced stable directory value.

Checks bounded NUL termination, portable leaf-path syntax, node type, and the directory-size invariant at the trust boundary.

Parameters

[in]	caps	Immutable namespace limits.
[in]	entry	Candidate copied directory entry.

Returns: Portable entry-contract status.

Return values

k_ra8_ok	The value is coherent and names one safe leaf.
k_ra8_err_invalid_state	A backend violated the cursor contract.

Precondition: Both pointers are non-NULL and entry is fully initialized.; caps contains the immutable limits of the producing backend.

Postcondition: Inputs are unchanged.; Success proves the copied value is safe for public publication.

Note: Pure and thread-safe.

Since: Version 0.1.0

Definition at line 129 of file fw_if_fs_dir.c.

References fw_fs_path_validate(), k_fw_fs_node_directory, k_fw_fs_node_none, k_fw_fs_node_other, k_fw_fs_path_cap, k_ra8_err_invalid_state, k_ra8_ok, memcpy(), fw_fs_dirent_value_t::name, fw_fs_dirent_value_t::name_bytes, fw_fs_caps_t::name_max_bytes, RA8_INTERNAL, fw_fs_dirent_value_t::size_bytes, strnlen(), and fw_fs_dirent_value_t::type.

Referenced by fw_fs_dir_next().

◆ internal_cursor_handle()

ra8_err_t internal_cursor_handle ( const fw_fs_dir_t * directory )

static

Validate an open directory cursor before dispatch.

Rejects unopened and detached handles before dereferencing their backend callback table.

Parameters

[in] directory Directory cursor to inspect.

Returns: Cursor lifecycle status.

Return values

k_ra8_ok	The cursor is open and dispatchable.
k_ra8_err_null_ptr	`directory` is NULL.
k_ra8_err_invalid_state	The cursor is not open.
k_ra8_err_not_initialized	The cursor lacks a backend interface.

Precondition: The caller does not concurrently close directory.; A non-NULL cursor object remains readable for the call duration.

Postcondition: No state is modified.; Success proves a live backend interface is available.

Note: Thread-safe only with external lifecycle synchronization.

Since: Version 0.1.0

Definition at line 102 of file fw_if_fs_dir.c.

References fw_fs_dir_t::iface, fw_fs_dir_t::is_open, k_ra8_err_invalid_state, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and RA8_INTERNAL.

Referenced by fw_fs_dir_close(), and fw_fs_dir_next().

◆ internal_cursor_names()

ra8_err_t internal_cursor_names ( const fw_fs_namespace_t * names )

static

Validate one namespace facade used for cursor dispatch.

Checks only the binding needed by incremental-directory operations; it does not inspect or mutate backend-owned state.

Parameters

[in] names Namespace facade to inspect.

Returns: Facade lifecycle status.

Return values

k_ra8_ok	The facade is bound.
k_ra8_err_null_ptr	`names` is NULL.
k_ra8_err_not_initialized	No namespace vtable is bound.

Precondition: The caller does not concurrently replace names.; A non-NULL facade object remains readable for the call duration.

Postcondition: No state is modified.; The return value depends only on the observed facade binding.

Note: Pure for a stable binding.

Since: Version 0.1.0

Definition at line 41 of file fw_if_fs_dir.c.

References fw_fs_namespace_t::iface, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and RA8_INTERNAL.

Referenced by fw_fs_dir_open().

◆ internal_cursor_workspace()

ra8_err_t internal_cursor_workspace	(	void *	workspace,
		uint32_t	bytes,
		uint32_t	need,
		uint8_t	align )

static

Validate cursor workspace size and alignment.

Enforces the opaque backend's published extent and power-of-two alignment contract before the backend can see caller storage.

Parameters

[in,out]	workspace	Caller-owned opaque storage.
[in]	bytes	Accessible storage extent.
[in]	need	Backend-required storage extent.
[in]	align	Backend-required power-of-two alignment.

Returns: Workspace contract status.

Return values

k_ra8_ok	The workspace meets the backend contract.
k_ra8_err_null_ptr	`workspace` is NULL.
k_ra8_err_no_mem	`bytes` is less than `need`.
k_ra8_err_invalid_state	Backend alignment metadata is invalid.
k_ra8_err_invalid_arg	The workspace address is misaligned.

Precondition: Size and alignment facts came from a bound filesystem.; bytes describes the accessible extent beginning at workspace.

Postcondition: The workspace is unchanged.; Success proves the full backend extent is suitably aligned.

Note: Pure and thread-safe.

Since: Version 0.1.0

Definition at line 71 of file fw_if_fs_dir.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_no_mem, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by fw_fs_dir_open().

Functions

Detailed Description

Function Documentation

◆ fw_fs_dir_close()

◆ fw_fs_dir_next()

◆ fw_fs_dir_open()

◆ internal_cursor_entry()

◆ internal_cursor_handle()

◆ internal_cursor_names()

◆ internal_cursor_workspace()