Architecture-neutral filesystem namespace, stream, and transaction ports. More...

#include <stddef.h>
#include <stdint.h>
#include "fw_if_fs_types.h"
#include "ra8_err.h"

Include dependency graph for fw_if_fs.h:

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

Functions
ra8_err_t	fw_fs_path_validate (const fw_fs_caps_t caps, const char path)
	Validate a canonical portable path against a binding's limits.
ra8_err_t	fw_fs_get_caps (const fw_fs_t fs, fw_fs_caps_t out)
	Copy the immutable capability snapshot from a complete binding.
ra8_err_t	fw_fs_stat (const fw_fs_namespace_t names, const char path, fw_fs_stat_t *out)
	Query a path; a miss is success with out->exists == false.
ra8_err_t	fw_fs_listdir (const fw_fs_namespace_t names, const char path, uint32_t max_entries, fw_fs_list_fn_t callback, void callback_ctx, uint32_t out_count, bool *out_complete)
	Enumerate at most max_entries callback entries.
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.
ra8_err_t	fw_fs_mkdir (const fw_fs_namespace_t names, const char path)
	Create exactly one directory; parents must already exist.
ra8_err_t	fw_fs_unlink (const fw_fs_namespace_t names, const char path)
	Remove one regular file; directories require fw_fs_rmdir.
ra8_err_t	fw_fs_rmdir (const fw_fs_namespace_t names, const char path)
	Remove one empty directory; recursive deletion is deliberately absent.
ra8_err_t	fw_fs_rename (const fw_fs_namespace_t names, const char old_path, const char *new_path, bool replace)
	Rename inside one bound root/volume with optional atomic replacement.
ra8_err_t	fw_fs_space (const fw_fs_namespace_t names, fw_fs_space_t out)
	Report total/free/used bytes when space-query capability is present.
ra8_err_t	fw_fs_open (const fw_fs_stream_port_t streams, const char path, fw_fs_open_mode_t mode, fw_fs_file_t file, void workspace, uint32_t workspace_size)
	Open a file into a caller-owned handle and backend workspace.
ra8_err_t	fw_fs_read (fw_fs_file_t file, uint8_t dst, uint32_t cap, uint32_t *out_read)
	Read up to cap bytes; zero bytes is EOF.
ra8_err_t	fw_fs_write (fw_fs_file_t file, const uint8_t source, uint32_t length, uint32_t *out_written)
	Attempt to write all bytes, reporting any accepted prefix.
ra8_err_t	fw_fs_seek (fw_fs_file_t *file, uint64_t absolute_offset)
	Seek to an absolute byte offset from the beginning.
ra8_err_t	fw_fs_tell (fw_fs_file_t file, uint64_t out_offset)
	Report the current absolute offset.
ra8_err_t	fw_fs_file_size (fw_fs_file_t file, uint64_t out_size)
	Report the open file's current length.
ra8_err_t	fw_fs_sync (fw_fs_file_t *file)
	Request file synchronization or return k_ra8_err_not_supported.
ra8_err_t	fw_fs_close (fw_fs_file_t *file)
	Close and consume an open handle.
ra8_err_t	fw_fs_transaction_begin (const fw_fs_transaction_port_t port, const char destination, fw_fs_transaction_policy_t policy, fw_fs_transaction_t transaction, void workspace, uint32_t workspace_size)
	Create a hidden sibling staging file for one destination.
ra8_err_t	fw_fs_transaction_write (fw_fs_transaction_t transaction, const uint8_t source, uint32_t length, uint32_t *out_written)
	Append bytes to the private staging artifact.
ra8_err_t	fw_fs_transaction_seek (fw_fs_transaction_t *transaction, uint64_t absolute_offset)
	Seek the staging writer to an absolute byte offset for bounded backfill.
ra8_err_t	fw_fs_transaction_validate (fw_fs_transaction_t transaction, fw_fs_validate_fn_t validator, void validator_ctx)
	Flush/reopen the stage and ask validator to inspect it read-only.
ra8_err_t	fw_fs_transaction_commit (fw_fs_transaction_t transaction, bool out_published)
	Publish a validated stage.
ra8_err_t	fw_fs_transaction_abort (fw_fs_transaction_t *transaction)
	Close and remove an unpublished staging artifact.

Detailed Description

Architecture-neutral filesystem namespace, stream, and transaction ports.

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

Portable libraries consume only the smallest facade they need. Paths are rooted in the binding selected by the composition root: /book/a.cbz can be a POSIX sandbox, an SD-card VFS mount, a RAM disk, or a future filesystem. It is never a host absolute path and never contains a device name.

All paths are canonical, NUL-terminated UTF-8 byte strings beginning with /. / is the bound root. Empty components, trailing separators, backslashes, colons, control bytes, . and .. are rejected before a backend runs. This lexical rule plus each adapter's symlink policy prevents a portable caller from escaping the bound root.

Handles and backend workspaces are caller-owned. This interface performs no allocation and contains no operating-system or device header.

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

Since: 0.1.0

Definition in file fw_if_fs.h.

Function Documentation

◆ fw_fs_close()

ra8_err_t fw_fs_close ( fw_fs_file_t * file )

nodiscard

Close and consume an open handle.

The handle is invalidated even when close reports an error, because retrying close is unsafe on some backends.

Definition at line 783 of file fw_if_fs.c.

References internal_file(), and k_ra8_ok.

Referenced by internal_begin_copy(), internal_cache_decode(), internal_cache_read_body_exact(), internal_io_close(), internal_io_open(), internal_mdl_state_load_slot(), internal_mdl_state_scan_slot(), internal_txn_validate(), internal_txn_validate(), mdl_config_load(), mdl_hash_file(), mdl_storage_copy_atomic(), mdl_urlname_sniff_file(), priv_alphabet_soup_load_file_contents(), priv_mdl_export_source_close(), priv_mdl_export_source_open(), priv_mdl_export_source_verify_close(), priv_mdl_rabook_epub_close(), and priv_mdl_rabook_epub_open().

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

◆ fw_fs_file_size()

ra8_err_t fw_fs_file_size	(	fw_fs_file_t *	file,
		uint64_t *	out_size )

nodiscard

Report the open file's current length.

Definition at line 758 of file fw_if_fs.c.

References internal_file(), k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by internal_io_open(), internal_mdl_state_validate_open(), internal_validate_stage(), mdl_config_load(), priv_mdl_export_source_open(), and priv_mdl_rabook_epub_open().

◆ fw_fs_get_caps()

ra8_err_t fw_fs_get_caps	(	const fw_fs_t *	fs,
		fw_fs_caps_t *	out )

nodiscard

Copy the immutable capability snapshot from a complete binding.

Definition at line 468 of file fw_if_fs.c.

References fw_fs_t::caps, fw_fs_namespace_t::iface, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and fw_fs_t::names.

Referenced by internal_list_pages_open_dir(), and mdl_storage_init().

◆ fw_fs_listdir()

ra8_err_t fw_fs_listdir	(	const fw_fs_namespace_t *	names,
		const char *	path,
		uint32_t	max_entries,
		fw_fs_list_fn_t	callback,
		void *	callback_ctx,
		uint32_t *	out_count,
		bool *	out_complete )

nodiscard

Enumerate at most max_entries callback entries.

A backend-reported count above the bound is rejected as k_ra8_err_invalid_state and resets both outputs.

Definition at line 509 of file fw_if_fs.c.

References fw_fs_namespace_t::caps, fw_fs_namespace_t::ctx, fw_fs_path_validate(), fw_fs_namespace_t::iface, internal_names(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, and fw_fs_namespace_iface::listdir.

◆ fw_fs_mkdir()

ra8_err_t fw_fs_mkdir	(	const fw_fs_namespace_t *	names,
		const char *	path )

nodiscard

Create exactly one directory; parents must already exist.

Definition at line 566 of file fw_if_fs.c.

References fw_fs_namespace_t::iface, internal_name_op(), internal_names(), k_ra8_ok, and fw_fs_namespace_iface::mkdir.

Referenced by internal_cache_ensure_directory(), mdl_join_dir_under(), and priv_mdl_app_storage_ensure_directory().

◆ fw_fs_open()

ra8_err_t fw_fs_open	(	const fw_fs_stream_port_t *	streams,
		const char *	path,
		fw_fs_open_mode_t	mode,
		fw_fs_file_t *	file,
		void *	workspace,
		uint32_t	workspace_size )

nodiscard

Open a file into a caller-owned handle and backend workspace.

Definition at line 648 of file fw_if_fs.c.

References fw_fs_stream_port_t::caps, fw_fs_stream_port_t::ctx, fw_fs_caps_t::file_workspace_align, fw_fs_caps_t::file_workspace_bytes, fw_fs_caps_t::flags, fw_fs_path_validate(), fw_fs_stream_port_t::iface, internal_workspace(), k_fw_fs_cap_create_exclusive, k_fw_fs_open_create_new, k_ra8_err_busy, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_ok, and fw_fs_stream_iface::open.

Referenced by internal_begin_copy(), internal_cache_decode(), internal_cache_read_body_exact(), internal_io_open(), internal_mdl_state_load_slot(), internal_mdl_state_scan_slot(), mdl_config_load(), mdl_hash_file(), mdl_urlname_sniff_file(), priv_alphabet_soup_load_file_contents(), priv_mdl_export_source_open(), and priv_mdl_rabook_epub_open().

◆ fw_fs_path_validate()

ra8_err_t fw_fs_path_validate	(	const fw_fs_caps_t *	caps,
		const char *	path )

nodiscard

Validate a canonical portable path against a binding's limits.

Definition at line 286 of file fw_if_fs.c.

References internal_fw_fs_scan_components(), k_fw_fs_path_cap, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, fw_fs_caps_t::name_max_bytes, and fw_fs_caps_t::path_max_bytes.

Referenced by fw_fs_bind(), fw_fs_dir_open(), fw_fs_listdir(), fw_fs_open(), fw_fs_rename(), fw_fs_stat(), fw_fs_transaction_begin(), internal_cursor_entry(), internal_mdl_state_paths(), and internal_name_op().

◆ fw_fs_read()

ra8_err_t fw_fs_read	(	fw_fs_file_t *	file,
		uint8_t *	dst,
		uint32_t	cap,
		uint32_t *	out_read )

nodiscard

Read up to cap bytes; zero bytes is EOF.

A backend count above cap is rejected as k_ra8_err_invalid_state and reset to zero.

Definition at line 699 of file fw_if_fs.c.

References internal_file(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by internal_cache_read_all(), internal_cache_read_body_exact(), internal_config_next(), internal_copy_payload(), internal_mdl_state_hash_payload(), internal_mdl_state_read_all(), internal_mdl_state_reader_refill(), internal_rabook_read(), mdl_hash_stream(), mdl_urlname_sniff_file(), priv_alphabet_soup_read_all(), priv_mdl_export_zip_read(), priv_mdl_rabook_epub_read(), and priv_mdl_verify_io_read_up_to().

◆ fw_fs_rename()

ra8_err_t fw_fs_rename	(	const fw_fs_namespace_t *	names,
		const char *	old_path,
		const char *	new_path,
		bool	replace )

nodiscard

Rename inside one bound root/volume with optional atomic replacement.

Definition at line 593 of file fw_if_fs.c.

References fw_fs_namespace_t::caps, fw_fs_namespace_t::ctx, fw_fs_caps_t::flags, fw_fs_path_validate(), fw_fs_namespace_t::iface, internal_names(), k_fw_fs_cap_atomic_noreplace, k_fw_fs_cap_atomic_replace, k_ra8_err_access_denied, k_ra8_err_not_supported, k_ra8_ok, and fw_fs_namespace_iface::rename.

◆ fw_fs_rmdir()

ra8_err_t fw_fs_rmdir	(	const fw_fs_namespace_t *	names,
		const char *	path )

nodiscard

Remove one empty directory; recursive deletion is deliberately absent.

Definition at line 584 of file fw_if_fs.c.

References fw_fs_namespace_t::iface, internal_name_op(), internal_names(), k_ra8_ok, and fw_fs_namespace_iface::rmdir.

Referenced by internal_library_remove_walk().

◆ fw_fs_seek()

ra8_err_t fw_fs_seek	(	fw_fs_file_t *	file,
		uint64_t	absolute_offset )

nodiscard

Seek to an absolute byte offset from the beginning.

Definition at line 736 of file fw_if_fs.c.

References internal_file(), and k_ra8_ok.

Referenced by internal_jof_pread(), internal_mdl_state_validate_open(), internal_rabook_read(), internal_zip_read(), mdl_verify_open_file(), priv_mdl_export_source_verify_close(), priv_mdl_rabook_epub_read(), and priv_mdl_state_parse_file().

◆ fw_fs_space()

ra8_err_t fw_fs_space	(	const fw_fs_namespace_t *	names,
		fw_fs_space_t *	out )

nodiscard

Report total/free/used bytes when space-query capability is present.

Impossible successful values are rejected as k_ra8_err_invalid_state and leave out zeroed.

Definition at line 623 of file fw_if_fs.c.

References fw_fs_namespace_t::caps, fw_fs_namespace_t::ctx, fw_fs_caps_t::flags, fw_fs_space_t::free_bytes, fw_fs_namespace_t::iface, internal_names(), k_fw_fs_cap_space_query, k_ra8_err_invalid_state, k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_ok, memset(), fw_fs_namespace_iface::space, fw_fs_space_t::total_bytes, and fw_fs_space_t::used_bytes.

◆ fw_fs_stat()

ra8_err_t fw_fs_stat	(	const fw_fs_namespace_t *	names,
		const char *	path,
		fw_fs_stat_t *	out )

nodiscard

Query a path; a miss is success with out->exists == false.

Backend contract violations are rejected as k_ra8_err_invalid_state and leave out zeroed.

Definition at line 480 of file fw_if_fs.c.

References fw_fs_namespace_t::caps, fw_fs_namespace_t::ctx, fw_fs_stat_t::exists, fw_fs_path_validate(), fw_fs_namespace_t::iface, internal_names(), k_fw_fs_node_directory, k_fw_fs_node_none, k_fw_fs_node_other, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, memset(), fw_fs_stat_t::size_bytes, fw_fs_namespace_iface::stat, and fw_fs_stat_t::type.

Referenced by internal_cache_discard_index(), internal_cache_ensure_directory(), internal_jof_load_source(), internal_library_remove_child(), internal_library_remove_root(), internal_library_root(), internal_library_visit(), internal_mdl_fetch_discard_stale_page(), internal_mdl_state_scan_slot(), internal_meta_load_candidate(), internal_metadata_set_page_timestamp(), internal_policy(), internal_resolve_removal_target(), internal_source_size(), internal_verify_artifact_entry(), internal_verify_library_root(), internal_verify_page_rec(), mdl_app_run_pack(), mdl_app_run_verify(), mdl_hash_file(), mdl_join_dir_under(), mdl_state_probe(), priv_mdl_app_storage_ensure_directory(), priv_mdl_app_storage_unlink_regular(), priv_mdl_cache_load(), priv_mdl_cache_read_body(), priv_mdl_export_prepare_cover(), priv_mdl_export_source_open(), and priv_mdl_rabook_epub_open().

◆ fw_fs_sync()

ra8_err_t fw_fs_sync ( fw_fs_file_t * file )

nodiscard

Request file synchronization or return k_ra8_err_not_supported.

Definition at line 771 of file fw_if_fs.c.

References internal_file(), k_ra8_err_not_supported, and k_ra8_ok.

◆ fw_fs_tell()

ra8_err_t fw_fs_tell	(	fw_fs_file_t *	file,
		uint64_t *	out_offset )

nodiscard

Report the current absolute offset.

Definition at line 745 of file fw_if_fs.c.

References internal_file(), k_ra8_err_null_ptr, and k_ra8_ok.

◆ fw_fs_transaction_abort()

ra8_err_t fw_fs_transaction_abort ( fw_fs_transaction_t * transaction )

nodiscard

Close and remove an unpublished staging artifact.

Definition at line 976 of file fw_if_fs.c.

References fw_fs_transaction_iface::abort, fw_fs_transaction_t::active, fw_fs_transaction_t::ctx, fw_fs_transaction_t::iface, internal_transaction(), k_ra8_ok, fw_fs_transaction_t::state, and fw_fs_transaction_t::validated.

Referenced by internal_abort(), internal_mdl_state_abort(), mdl_storage_txn_abort(), and priv_mdl_export_output_commit().

◆ fw_fs_transaction_begin()

ra8_err_t fw_fs_transaction_begin	(	const fw_fs_transaction_port_t *	port,
		const char *	destination,
		fw_fs_transaction_policy_t	policy,
		fw_fs_transaction_t *	transaction,
		void *	workspace,
		uint32_t	workspace_size )

nodiscard

Create a hidden sibling staging file for one destination.

Returns k_ra8_err_not_supported when the bound port does not advertise k_fw_fs_cap_transactions.

Definition at line 850 of file fw_if_fs.c.

Referenced by internal_begin_copy(), internal_mdl_state_build_stage(), and internal_txn_begin().

◆ fw_fs_transaction_commit()

ra8_err_t fw_fs_transaction_commit	(	fw_fs_transaction_t *	transaction,
		bool *	out_published )

nodiscard

Publish a validated stage.

Parameters

[in,out]	transaction	Active, successfully validated transaction.
[out]	out_published	True when the destination changed, even if a later durability operation failed.

A backend returning success without publication violates the contract and is reported as k_ra8_err_invalid_state; the transaction remains active so it can be aborted.

Definition at line 951 of file fw_if_fs.c.

References fw_fs_transaction_t::active, fw_fs_transaction_iface::commit, fw_fs_transaction_t::ctx, fw_fs_transaction_t::iface, internal_transaction(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, fw_fs_transaction_t::state, and fw_fs_transaction_t::validated.

Referenced by mdl_state_save(), mdl_storage_copy_atomic(), mdl_storage_txn_commit(), and priv_mdl_export_output_commit().