Shared errno/descriptor helpers for the POSIX filesystem port. More...

#include <stddef.h>
#include <stdint.h>
#include <time.h>
#include "fw_if_fs.h"
#include "fw_if_fs_posix.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for fw_if_fs_posix_internal.h:

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

Go to the source code of this file.

Data Structures
struct	posix_directory_record_t
	Validated view over one raw host directory record. More...
struct	posix_directory_reader_t
	Caller-owned cursor and fixed storage for raw directory batches. More...
struct	posix_directory_state_t
	POSIX state placed in caller directory workspace. More...
struct	posix_file_state_t
	POSIX state placed in caller file workspace. More...
struct	posix_transaction_state_t
	POSIX state placed in caller transaction workspace. More...

Enumerations
enum	posix_limits_t : uint16_t { k_posix_stage_leaf_span = 13U , k_posix_max_open_files = 64U , k_posix_component_cap = 256U , k_posix_file_mode = 0600 , k_posix_directory_mode = 0700 , k_posix_stage_attempts = 64U }
	Local component and stage-search bounds. More...
enum	posix_root_alias_t : uint8_t { k_posix_root_alias_none = 0U , k_posix_root_alias_tmp = 1U , k_posix_root_alias_var = 2U }
	Classification of a verified filesystem-root directory alias. More...
enum	posix_hex_limits_t : uint8_t { k_posix_hex_nibble_bits = 4U , k_posix_stage_hex_digits = 6U , k_posix_hex_last_digit = k_posix_stage_hex_digits - 1U , k_posix_hex_nibble_mask = 0x0FU }
	Hexadecimal stage-name encoding constants. More...
enum	posix_numeric_limits_t : uint32_t { k_posix_epoch_year_offset = 1900U , k_posix_nanosecond_max = 999999999U , k_posix_transaction_id_mask = 0x00FFFFFFU }
	POSIX timestamp and transaction arithmetic constants. More...
enum	posix_directory_limits_t : uint16_t { k_posix_directory_buffer_bytes = 4096U , k_posix_directory_read_retries = 16U }
	Raw directory buffer and retry bounds. More...
enum	posix_linux_dirent_layout_t : uint8_t { k_posix_linux_reclen_offset = 16U , k_posix_linux_name_offset = 19U , k_posix_linux_record_align = 8U }
	Linux getdents64 wire-record offsets and alignment. More...
enum	posix_darwin_dirent_layout_t : uint8_t { k_posix_darwin_reclen_offset = 16U , k_posix_darwin_namlen_offset = 18U , k_posix_darwin_name_offset = 21U , k_posix_darwin_record_align = 4U }
	Darwin getdirentries64 wire-record offsets and alignment. More...

Functions
ra8_err_t	priv_fs_posix_errno (int value)
	Map one captured errno value into ra8_err_t.
ra8_err_t	priv_fs_posix_close_fd (int *fd)
	Close exactly once and invalidate the caller's descriptor.
ra8_err_t	priv_fs_posix_close_fd_preserve (int *fd, ra8_err_t primary)
	Close one owned descriptor while preserving a primary status.
ra8_err_t	priv_fs_posix_root_alias_classify (const char component, const char target, size_t target_bytes, posix_root_alias_t *out_alias)
	Classify one exact filesystem-root alias component and target pair.
ra8_err_t	priv_fs_posix_root_alias_open (int root_fd, posix_root_alias_t alias, int *out_fd)
	Open a classified root alias through its canonical components.
ra8_err_t	priv_fs_posix_component_open (int parent_fd, const char component, int out_fd)
	Open one validated directory component without following its pathname.
ra8_err_t	priv_fs_posix_directory_next (int fd, posix_directory_reader_t reader, posix_directory_record_t out, bool *out_end)
	Read and validate the next raw hosted directory record.
fw_fs_timestamp_t	priv_fs_posix_timestamp (time_t seconds, long nanoseconds)
	Convert a POSIX UTC instant into the portable civil representation.
ra8_err_t	priv_fs_posix_copy_path (char out, const char path)
	Copy one bounded portable path.
ra8_err_t	priv_fs_posix_stage_path (const char destination, uint32_t id, char out)
	Build an 8.3-compatible sibling transaction path.
ra8_err_t	priv_fs_posix_dir_open (void ctx, const char path, void *directory_state, uint32_t state_bytes)
	Open a confined raw-directory cursor in caller storage.
ra8_err_t	priv_fs_posix_dir_next (void ctx, void directory_state, fw_fs_dirent_value_t out, bool out_entry)
	Copy the next visible raw-directory entry.
ra8_err_t	priv_fs_posix_dir_close (void ctx, void directory_state)
	Close one owned raw-directory descriptor.
ra8_err_t	priv_fs_posix_listdir (void ctx, const char path, uint32_t max_entries, fw_fs_list_fn_t callback, void callback_ctx, uint32_t out_count, bool *out_complete)
	Enumerate a POSIX directory through bounded raw records.
ra8_err_t	priv_fs_posix_bind_interfaces (fw_fs_t out, fw_fs_posix_state_t state, const fw_fs_caps_t *caps)
	Bind the immutable POSIX operation tables to initialized state.
ra8_err_t	priv_fs_posix_parent_open (fw_fs_posix_state_t state, const char path, int out_parent_fd, char out_leaf)
	Resolve a canonical path's parent without following any symlink.
ra8_err_t	priv_fs_posix_open (void ctx, const char path, fw_fs_open_mode_t mode, void *file_state, uint32_t state_bytes)
	Open one confined regular file into caller workspace.
ra8_err_t	priv_fs_posix_write (void ctx, void file_state, const uint8_t src, uint32_t len, uint32_t out_written)
	Complete POSIX short writes while reporting any accepted prefix.
ra8_err_t	priv_fs_posix_seek (void ctx, void file_state, uint64_t offset)
	Seek a POSIX descriptor to an unsigned absolute offset.
ra8_err_t	priv_fs_posix_size (void ctx, void file_state, uint64_t *out_size)
	Report a POSIX descriptor's current file length.
ra8_err_t	priv_fs_posix_sync (void ctx, void file_state)
	Flush file contents and metadata through POSIX fsync.
ra8_err_t	priv_fs_posix_close (void ctx, void file_state)
	Close and consume one caller-owned POSIX file state.
const fw_fs_stream_iface_t *	priv_fs_posix_stream_iface (void)
	Borrow the immutable POSIX byte-stream operation table.

Detailed Description

Shared errno/descriptor helpers for the POSIX filesystem port.

Defines the fixed caller-workspace layouts and bounded helper contracts used across the POSIX adapter translation units. These declarations keep hosted descriptor, timestamp, path, transaction-name, and Darwin root-alias policy private to the port while avoiding duplicated platform logic.

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

Definition in file fw_if_fs_posix_internal.h.

Enumeration Type Documentation

◆ posix_darwin_dirent_layout_t

enum posix_darwin_dirent_layout_t : uint8_t

Darwin getdirentries64 wire-record offsets and alignment.

Enumerator
k_posix_darwin_reclen_offset	Offset of d_reclen.
k_posix_darwin_namlen_offset	Offset of d_namlen.
k_posix_darwin_name_offset	Offset of d_name.
k_posix_darwin_record_align	Kernel record alignment.

Definition at line 101 of file fw_if_fs_posix_internal.h.

◆ posix_directory_limits_t

enum posix_directory_limits_t : uint16_t

Raw directory buffer and retry bounds.

Enumerator
k_posix_directory_buffer_bytes	Fixed local kernel buffer.
k_posix_directory_read_retries	Maximum interrupted reads.

Definition at line 88 of file fw_if_fs_posix_internal.h.

◆ posix_hex_limits_t

enum posix_hex_limits_t : uint8_t

Hexadecimal stage-name encoding constants.

Enumerator
k_posix_hex_nibble_bits	Bits represented by one hex digit.
k_posix_stage_hex_digits	Hex digits in a stage identifier.
k_posix_hex_last_digit	Highest valid index in a stage identifier.
k_posix_hex_nibble_mask	Low-nibble mask.

Definition at line 72 of file fw_if_fs_posix_internal.h.

◆ posix_limits_t

enum posix_limits_t : uint16_t

Local component and stage-search bounds.

Enumerator
k_posix_stage_leaf_span	Stage leaf plus terminating NUL.
k_posix_max_open_files	Truthful hosted descriptor capacity.
k_posix_component_cap	Component buffer including NUL.
k_posix_file_mode	Owner-only created-file mode.
k_posix_directory_mode	Owner-only created-directory mode.
k_posix_stage_attempts	Collision-search attempt cap.

Definition at line 32 of file fw_if_fs_posix_internal.h.

◆ posix_linux_dirent_layout_t

enum posix_linux_dirent_layout_t : uint8_t

Linux getdents64 wire-record offsets and alignment.

Enumerator
k_posix_linux_reclen_offset	Offset of d_reclen.
k_posix_linux_name_offset	Offset of d_name.
k_posix_linux_record_align	Kernel record alignment.

Definition at line 94 of file fw_if_fs_posix_internal.h.

◆ posix_numeric_limits_t

enum posix_numeric_limits_t : uint32_t

POSIX timestamp and transaction arithmetic constants.

Enumerator
k_posix_epoch_year_offset	struct tm year origin.
k_posix_nanosecond_max	Largest valid subsecond.
k_posix_transaction_id_mask	Six hexadecimal digits.

Definition at line 81 of file fw_if_fs_posix_internal.h.

◆ posix_root_alias_t

enum posix_root_alias_t : uint8_t

Classification of a verified filesystem-root directory alias.

Distinguishes ordinary directory components from the two Darwin filesystem root aliases whose exact relative targets may be opened canonically. The pure classifier produces a non-none value only for an exact component- target tuple; Darwin callers additionally verify the parent descriptor identifies / before treating that classification as permission to open.

Invariant: Only tmp -> private/tmp and var -> private/var can be classified; production use is restricted to Darwin actual root.

Example: posix_root_alias_t alias = k_posix_root_alias_none;

posix_root_alias_t
posix_root_alias_t
Classification of a verified filesystem-root directory alias.
Definition fw_if_fs_posix_internal.h:65

k_posix_root_alias_none
@ k_posix_root_alias_none
Component is not an approved root alias.
Definition fw_if_fs_posix_internal.h:66

See also: priv_fs_posix_root_alias_verify(); priv_fs_posix_root_alias_open(); priv_fs_posix_root_alias_classify()

Since: Version 0.1.0

Enumerator
k_posix_root_alias_none	Component is not an approved root alias.
k_posix_root_alias_tmp	Root tmp resolves to private/tmp.
k_posix_root_alias_var	Root var resolves to private/var.

Definition at line 65 of file fw_if_fs_posix_internal.h.

Function Documentation

◆ priv_fs_posix_bind_interfaces()

ra8_err_t priv_fs_posix_bind_interfaces	(	fw_fs_t *	out,
		fw_fs_posix_state_t *	state,
		const fw_fs_caps_t *	caps )

Bind the immutable POSIX operation tables to initialized state.

Hands fw_fs_bind this port's namespace and transaction vtables, which are translation-unit-scoped, together with the shared table borrowed from priv_fs_posix_stream_iface and state as the single backend context. Routing the bind through one helper is what keeps those two private tables from needing a second copy in the initialization unit. Every consistency rule between the tables and caps is enforced inside the facade rather than here.

Parameters

[out]	out	Facade populated with the bound tables, context, and caps.
[in,out]	state	Initialized adapter state published as backend context.
[in]	caps	Truthful capability and workspace-sizing descriptor.

Returns: Facade bind status.

Return values

k_ra8_ok	`out` is a complete facade over `state`.
k_ra8_err_null_ptr	`out`, `state`, or `caps` is NULL.
k_ra8_err_invalid_arg	An advertised capability, workspace alignment, or root-path rule is not satisfied by the bound tables.

Precondition: state is fully initialized with an open root descriptor, because a successful bind immediately publishes it as the backend context.; caps describes state truthfully, including every workspace size and power-of-two alignment the facade re-validates.

Postcondition: Success installs the namespace, stream, and transaction tables and the same state pointer into all three facade sections.; Failure writes nothing to out and releases nothing from state, so unwinding the adapter state stays the caller's responsibility.

Note: Thread-safe; the bound tables are immutable and statically initialized, and the call itself writes only out.

Since: Version 0.1.0

Definition at line 835 of file fw_if_fs_posix.c.

References fw_fs_bind(), priv_fs_posix_stream_iface(), RA8_PRIV, s_namespace_iface, and s_transaction_iface.

Referenced by fw_fs_posix_init().

◆ priv_fs_posix_close()

ra8_err_t priv_fs_posix_close	(	void *	ctx,
		void *	file_state )

Close and consume one caller-owned POSIX file state.

Delegates to the shared EINTR-safe descriptor close helper, which invalidates the stored descriptor to prevent unsafe retries.

Parameters

[in]	ctx	Unused confined-root context.
[in,out]	file_state	Open posix_file_state_t to consume.

Returns: Host close status.

Return values

k_ra8_ok	The descriptor closed successfully.
k_ra8_err_*	Mapped close failure.

Precondition: file_state owns one open descriptor.; No concurrent I/O or close uses the descriptor.

Postcondition: The stored descriptor is invalidated on every return path.; The state cannot be used for I/O without reopening.

Note: Not thread-safe for concurrent access to one file state.

Since: Version 0.1.0

Definition at line 219 of file fw_if_fs_posix_stream.c.

References priv_fs_posix_close_fd(), and RA8_PRIV.

Referenced by internal_txn_abort(), internal_txn_validate(), and priv_fs_posix_stream_iface().

◆ priv_fs_posix_close_fd()

ra8_err_t priv_fs_posix_close_fd ( int * fd )

Close exactly once and invalidate the caller's descriptor.

Reads *fd, stores -1 back, and only then calls close, so a caller that retries after a failure cannot close a descriptor number the host has already recycled for another object. An already-invalidated slot is reported rather than closed, which is what makes the unconditional cleanup calls on every error path in this port safe.

Parameters

[in,out] fd Owned descriptor slot, invalidated before the close.

Returns: Mapped descriptor-close status.

Return values

k_ra8_ok	The descriptor closed successfully.
k_ra8_err_invalid_state	*fd was already negative; nothing was closed.
k_ra8_err_*	Mapped close failure from priv_fs_posix_errno.

Precondition: fd addresses one writable integer this port owns; the pointer is dereferenced without a null guard.; No other owner closes or reuses *fd concurrently; the invalidation protects only against a repeated call made through fd.

Postcondition: *fd is -1 on every return path, including both failure paths.; close is issued at most once, and never for an already-invalid slot.

Note: Not thread-safe for concurrent access to one descriptor slot.

Since: Version 0.1.0

Definition at line 98 of file fw_if_fs_posix_common.c.

References k_ra8_err_invalid_state, k_ra8_ok, priv_fs_posix_errno(), and RA8_PRIV.

Referenced by fw_fs_posix_deinit(), internal_directory_open(), internal_mkdir(), internal_native_stat(), internal_parent_open_step(), internal_parent_sync(), internal_rename(), internal_rmdir(), internal_root_open(), internal_root_open_step(), internal_unlink(), priv_fs_posix_close(), priv_fs_posix_close_fd_preserve(), priv_fs_posix_dir_close(), priv_fs_posix_open(), and priv_fs_posix_root_alias_open().

◆ priv_fs_posix_close_fd_preserve()

ra8_err_t priv_fs_posix_close_fd_preserve	(	int *	fd,
		ra8_err_t	primary )

Close one owned descriptor while preserving a primary status.

Delegates descriptor consumption to priv_fs_posix_close_fd. When primary already reports a failure, that failure remains the caller-visible result even if cleanup also fails. When the primary operation succeeded, the descriptor-close result is returned so a cleanup failure cannot be hidden.

Parameters

[in,out]	fd	Owned descriptor slot, invalidated by the close attempt.
[in]	primary	Status produced before descriptor cleanup.

Returns: primary when it is not k_ra8_ok; otherwise the close status.

Return values

k_ra8_ok	The primary operation and descriptor close both succeeded.
k_ra8_err_*	The primary operation failed, or cleanup failed after a successful primary operation.

Precondition: fd is non-NULL and addresses one writable descriptor slot.; *fd satisfies the ownership contract of priv_fs_posix_close_fd.

Postcondition: *fd is -1 and the descriptor was closed at most once.; A primary failure is never replaced by a secondary cleanup failure.

Note: Not thread-safe for concurrent access to one descriptor slot.

Since: Version 0.1.0

Definition at line 111 of file fw_if_fs_posix_common.c.

References k_ra8_ok, priv_fs_posix_close_fd(), and RA8_PRIV.

Referenced by internal_directory_open(), internal_parent_open_step(), internal_root_open_step(), priv_fs_posix_open(), priv_fs_posix_parent_open(), and priv_fs_posix_root_alias_open().

◆ priv_fs_posix_component_open()

ra8_err_t priv_fs_posix_component_open	(	int	parent_fd,
		const char *	component,
		int *	out_fd )

Open one validated directory component without following its pathname.

Uses no-follow metadata and openat beneath parent_fd. Linux rejects every symbolic link. Darwin permits only an exact tmp or var alias whose parent descriptor identifies actual /, and opens that alias through canonical no-follow private components instead of its pathname.

Parameters

[in]	parent_fd	Open descriptor for the selected parent directory.
[in]	component	Terminated child component without slash bytes.
[out]	out_fd	Receives the owned directory descriptor.

Returns: Validated component-open status.

Return values

k_ra8_ok	`out_fd` owns the requested directory.
k_ra8_err_access_denied	A symbolic link is not an approved Darwin alias.
k_ra8_err_not_found	The component is absent or is not a directory.
k_ra8_err_*	Mapped metadata, open, or descriptor-close failure.

Precondition: parent_fd is open and component is a validated non-empty name.; out_fd is non-NULL and does not alias either input.

Postcondition: Success publishes exactly one owned descriptor.; Failure publishes no descriptor and retains parent_fd ownership.

Note: Thread-safe subject to host namespace race semantics.

Since: Version 0.1.0

Definition at line 117 of file fw_if_fs_posix.c.

References internal_intermediate_check(), k_posix_root_alias_none, k_ra8_ok, O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW, priv_fs_posix_errno(), priv_fs_posix_root_alias_open(), and RA8_PRIV.

Referenced by internal_directory_open(), internal_parent_open_step(), and internal_root_open_step().

◆ priv_fs_posix_copy_path()

ra8_err_t priv_fs_posix_copy_path	(	char *	out,
		const char *	path )

Copy one bounded portable path.

Copies bytes forward until the terminator is reached or the portable path capacity is exhausted, so an oversized or unterminated source is reported instead of overrunning out. The bound is the portable k_fw_fs_path_cap rather than a host PATH_MAX, which keeps every adapter path the same size as the caller workspace that stores it.

Parameters

[out]	out	Destination holding k_fw_fs_path_cap writable bytes.
[in]	path	Source path to copy, including its terminator.

Returns: Bounded path-copy status.

Return values

k_ra8_ok	`out` holds the terminated copy.
k_ra8_err_invalid_size	No terminator appears within the capacity.

Precondition: out addresses k_fw_fs_path_cap writable bytes and does not overlap path; both pointers are dereferenced without a null guard.; path stays readable through its terminator, or for k_fw_fs_path_cap bytes when it carries none.

Postcondition: Success leaves out NUL-terminated with at most k_fw_fs_path_cap - 1 visible bytes.; Failure leaves out fully overwritten and unterminated, so a rejected copy must never be read back as a string.

Note: Pure apart from the caller's destination, and thread-safe.

Since: Version 0.1.0

Definition at line 607 of file fw_if_fs_posix_common.c.

References k_fw_fs_path_cap, k_ra8_err_invalid_size, k_ra8_ok, and RA8_PRIV.

Referenced by internal_txn_begin().

◆ priv_fs_posix_dir_close()

ra8_err_t priv_fs_posix_dir_close	(	void *	ctx,
		void *	directory_state )

Close one owned raw-directory descriptor.

Invalidates the stored descriptor before mapping the host close result, preventing a retry from closing a reused descriptor number.

Parameters

[in,out]	ctx	Bound POSIX adapter context.
[in,out]	directory_state	Open caller-owned cursor workspace.

Returns: Mapped descriptor-close status.

Return values

k_ra8_ok	The descriptor closed successfully.
k_ra8_err_*	Mapped host close failure.

Precondition: directory_state is non-NULL and owns a directory descriptor.; ctx is the bound adapter context associated with the cursor.

Postcondition: The descriptor field is invalidated even when close reports an error.; Caller workspace ownership remains with the caller.

Note: The generic facade consumes its handle on every return.

Since: Version 0.1.0

Definition at line 373 of file fw_if_fs_posix.c.

References posix_directory_state_t::fd, priv_fs_posix_close_fd(), and RA8_PRIV.

Referenced by priv_fs_posix_listdir().

◆ priv_fs_posix_dir_next()

ra8_err_t priv_fs_posix_dir_next	(	void *	ctx,
		void *	directory_state,
		fw_fs_dirent_value_t *	out,
		bool *	out_entry )

Copy the next visible raw-directory entry.

Decodes bounded native records, skips dot entries, and performs a no-follow metadata lookup before publishing a stable copied value.

Parameters

[in,out]	ctx	Bound POSIX adapter context.
[in,out]	directory_state	Open caller-owned cursor workspace.
[out]	out	Stable copied portable entry value.
[out]	out_entry	True when `out` contains an entry; false at EOF.

Returns: Raw read, metadata, or validation status.

Return values

k_ra8_ok	One entry was copied or native end was observed.
k_ra8_err_*	Raw-read, record, metadata, or retry-bound failure.

Precondition: Output and cursor pointers are non-NULL and the cursor owns its descriptor.; ctx names the same bound root that opened the cursor.

Postcondition: No lock is retained and borrowed kernel-record bytes never escape.; Success with out_entry true fully initializes out.

Note: Namespace mutation may surface as the exact fstatat lookup error.

Since: Version 0.1.0

Definition at line 333 of file fw_if_fs_posix.c.

References AT_SYMLINK_NOFOLLOW, posix_directory_state_t::fd, internal_node_type(), k_posix_directory_budget_overhead, k_ra8_err_invalid_state, k_ra8_ok, memcpy(), fw_fs_dirent_value_t::name, posix_directory_record_t::name, fw_fs_dirent_value_t::name_bytes, posix_directory_record_t::name_bytes, priv_fs_posix_directory_next(), priv_fs_posix_errno(), RA8_PRIV, posix_directory_state_t::reader, fw_fs_dirent_value_t::size_bytes, strcmp(), and fw_fs_dirent_value_t::type.

Referenced by priv_fs_posix_listdir().

◆ priv_fs_posix_dir_open()

ra8_err_t priv_fs_posix_dir_open	(	void *	ctx,
		const char *	path,
		void *	directory_state,
		uint32_t	state_bytes )

Open a confined raw-directory cursor in caller storage.

Opens beneath the bound root without following the final leaf and initializes the fixed raw-record buffer in caller storage.

Parameters

[in,out]	ctx	Bound POSIX adapter context.
[in]	path	Validated canonical directory path.
[out]	directory_state	Caller-owned cursor workspace.
[in]	state_bytes	Accessible workspace extent.

Returns: Confined open or workspace status.

Return values

k_ra8_ok	The workspace owns one directory descriptor.
k_ra8_err_*	Capacity, confinement, open, or platform failure.

Precondition: Required pointers are non-NULL and path passed facade validation.; state_bytes describes the writable extent at directory_state.

Postcondition: Success owns one directory descriptor in directory_state.; Failure closes every descriptor acquired by this operation.

Note: No allocator-backed C runtime directory object is used.

Since: Version 0.1.0

Definition at line 320 of file fw_if_fs_posix.c.

References posix_directory_state_t::fd, internal_directory_open(), k_ra8_err_no_mem, and RA8_PRIV.

Referenced by priv_fs_posix_listdir().

◆ priv_fs_posix_directory_next()

ra8_err_t priv_fs_posix_directory_next	(	int	fd,
		posix_directory_reader_t *	reader,
		posix_directory_record_t *	out,
		bool *	out_end )

Read and validate the next raw hosted directory record.

Serves the next record from reader's fixed buffer and refills that buffer with one bounded raw syscall batch when the cursor reaches the end of the previous batch, so enumeration needs no allocator-backed DIR object. Both the caller-supplied cursor state and every decoded record extent are re-validated on entry, and the published name borrows bytes inside reader instead of being copied. Dot entries are not filtered here; the portable layer above does that.

Parameters

[in]	fd	Open directory descriptor owning the enumeration position.
[in,out]	reader	Caller-owned batch buffer and cursor.
[out]	out	Borrowed name view and exact record extent.
[out]	out_end	True when the host reported end of directory.

Returns: Raw record read, decode, or cursor-validation status.

Return values

k_ra8_ok	`out` describes one record, or `out_end` is true at end.
k_ra8_err_null_ptr	`reader`, `out`, or `out_end` is NULL.
k_ra8_err_invalid_state	`fd` is negative, the cursor and valid extent disagree, or a native record layout is malformed.
k_ra8_err_invalid_size	A record name exceeds k_posix_component_cap.
k_ra8_err_busy	Every bounded refill attempt was interrupted.
k_ra8_err_*	Mapped raw-read failure.

Precondition: fd is the same descriptor that produced reader's current batch; pairing a cursor with another descriptor interleaves two enumerations.; reader was zero-initialized before the first call of an enumeration and is not shared with a second cursor.

Postcondition: Success advances the cursor by exactly the decoded record extent, so no record is delivered twice.; out->name points inside reader and stays valid only until the next call made on the same reader.

Note: Not thread-safe for concurrent use of one descriptor offset or reader.

Since: Version 0.1.0

Definition at line 526 of file fw_if_fs_posix_common.c.

References posix_directory_reader_t::buffer, posix_directory_reader_t::cursor, internal_directory_fill(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, RA8_PRIV, posix_directory_record_t::record_bytes, and posix_directory_reader_t::valid_bytes.

Referenced by priv_fs_posix_dir_next().

◆ priv_fs_posix_errno()

ra8_err_t priv_fs_posix_errno ( int value )

Map one captured errno value into ra8_err_t.

Translates the host failure vocabulary into the portable one with a total switch, so every backend path in this port reports the same code for the same condition. Families collapse deliberately: descriptor and space exhaustion both read as k_ra8_err_no_mem, and ELOOP joins the permission family because an unapproved symbolic link is denied rather than missing. Any value the switch does not name becomes k_ra8_fail, never a success code.

Parameters

[in] value Captured errno value, or zero for an observed success.

Returns: Portable status for value.

Return values

k_ra8_ok	`value` is zero.
k_ra8_err_not_found	ENOENT or ENOTDIR.
k_ra8_err_exists	EEXIST.
k_ra8_err_no_mem	ENOSPC, EDQUOT, EMFILE, or ENFILE.
k_ra8_err_not_empty	ENOTEMPTY.
k_ra8_err_access_denied	EACCES, EPERM, or ELOOP.
k_ra8_err_invalid_arg	EINVAL, EXDEV, ENAMETOOLONG, or EISDIR.
k_ra8_err_invalid_size	EFBIG or EOVERFLOW.
k_ra8_err_invalid_state	EBADF.
k_ra8_err_busy	EBUSY.
k_ra8_err_not_supported	ENOTSUP where the host defines it.
k_ra8_fail	Every other errno value.

Precondition: value was captured immediately after the failing host call; an intervening close or stat may already have overwritten errno.; value is an errno code, never a negated syscall return, because a zero argument is reported as success.

Postcondition: No caller object, errno, or host state is read or written.; An unrecognized value collapses to k_ra8_fail, so no host failure can be mapped onto a success code.

Note: Pure and thread-safe.

Since: Version 0.1.0

Definition at line 56 of file fw_if_fs_posix_common.c.

References k_ra8_err_access_denied, k_ra8_err_busy, k_ra8_err_exists, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_no_mem, k_ra8_err_not_empty, k_ra8_err_not_found, k_ra8_err_not_supported, k_ra8_fail, k_ra8_ok, and RA8_PRIV.

Referenced by internal_directory_fill(), internal_directory_open(), internal_intermediate_check(), internal_mkdir(), internal_native_stat(), internal_parent_sync(), internal_read(), internal_rename_noreplace(), internal_rename_opened(), internal_rmdir(), internal_root_base_open(), internal_space(), internal_tell(), internal_unlink(), priv_fs_posix_close_fd(), priv_fs_posix_component_open(), priv_fs_posix_dir_next(), priv_fs_posix_open(), priv_fs_posix_parent_open(), priv_fs_posix_root_alias_open(), priv_fs_posix_seek(), priv_fs_posix_size(), priv_fs_posix_sync(), and priv_fs_posix_write().

◆ priv_fs_posix_listdir()

ra8_err_t priv_fs_posix_listdir	(	void *	ctx,
		const char *	path,
		uint32_t	max_entries,
		fw_fs_list_fn_t	callback,
		void *	callback_ctx,
		uint32_t *	out_count,
		bool *	out_complete )

Enumerate a POSIX directory through bounded raw records.

Opens without symlink traversal, skips dot entries, bounds native records plus look-ahead, stats each leaf no-follow, and closes always.

Parameters

[in,out]	ctx	Initialized confined-root adapter context.
[in]	path	Validated portable directory path.
[in]	max_entries	Maximum portable callback deliveries.
[in]	callback	Portable directory-entry callback.
[in,out]	callback_ctx	Opaque callback state.
[in,out]	out_count	Running count initialized by public dispatch.
[out]	out_complete	Whether native EOF was observed.

Returns: Enumeration, callback, metadata, or close status.

Return values

k_ra8_ok	Enumeration ended without an error.
k_ra8_err_*	First confined directory, callback, stat, or close failure.

Precondition: Pointer arguments are non-NULL and public bounds were validated.; out_count initially contains zero.

Postcondition: Callback delivery never exceeds max_entries.; The directory descriptor is closed on every return path.

Note: Not thread-safe with concurrent mutation of the enumerated directory.

Since: Version 0.1.0

Definition at line 676 of file fw_if_fs_posix_common.c.

References k_ra8_ok, fw_fs_dirent_value_t::name, fw_fs_dirent_value_t::name_bytes, priv_fs_posix_dir_close(), priv_fs_posix_dir_next(), priv_fs_posix_dir_open(), RA8_PRIV, fw_fs_dirent_value_t::size_bytes, and fw_fs_dirent_value_t::type.

◆ priv_fs_posix_open()

ra8_err_t priv_fs_posix_open	(	void *	ctx,
		const char *	path,
		fw_fs_open_mode_t	mode,
		void *	file_state,
		uint32_t	state_bytes )

Open one confined regular file into caller workspace.

Maps safe flags, resolves the no-follow parent, opens relative to it, closes the parent, then rejects any resulting non-regular object.

Parameters

[in,out]	ctx	Initialized confined-root adapter context.
[in]	path	Validated portable file path.
[in]	mode	Portable open mode.
[out]	file_state	Caller workspace receiving posix_file_state_t.
[in]	state_bytes	Writable workspace size.

Returns: Workspace, mode, resolution, open, or type-check status.

Return values

k_ra8_ok	`file_state` owns one open regular-file descriptor.
k_ra8_err_no_mem	The workspace is undersized.
k_ra8_err_invalid_arg	The mode or opened object type is invalid.
k_ra8_err_*	Mapped resolution, open, stat, or close failure.

Precondition: Pointer arguments and alignment satisfy the bound stream contract.; ctx owns a live confined root descriptor.

Postcondition: Success transfers exactly one descriptor into file_state.; Failure closes every descriptor acquired internally.

Note: Thread-safe for independent file states subject to namespace races.

Since: Version 0.1.0

Definition at line 73 of file fw_if_fs_posix_stream.c.

References internal_open_flags(), k_posix_component_cap, k_posix_file_mode, k_ra8_err_invalid_arg, k_ra8_err_no_mem, k_ra8_ok, priv_fs_posix_close_fd(), priv_fs_posix_close_fd_preserve(), priv_fs_posix_errno(), priv_fs_posix_parent_open(), and RA8_PRIV.

Referenced by internal_stage_open(), internal_txn_validate(), and priv_fs_posix_stream_iface().

◆ priv_fs_posix_parent_open()

ra8_err_t priv_fs_posix_parent_open	(	fw_fs_posix_state_t *	state,
		const char *	path,
		int *	out_parent_fd,
		char *	out_leaf )

Resolve a canonical path's parent without following any symlink.

Duplicates the bound root and walks each intermediate component with no-follow stat/open calls, so normal paths remain confined beneath the owned descriptor as ownership moves. Darwin replaces a verified actual-root alias with its canonical no-follow descriptor; Linux rejects every alias and neither platform follows the alias pathname.

Parameters

[in]	state	Initialized confined-root adapter state.
[in]	path	Validated portable path below the bound root.
[out]	out_parent_fd	Receives the owned parent directory descriptor.
[out]	out_leaf	Receives the terminated final component.

Returns: Resolution status.

Return values

k_ra8_ok	Both parent descriptor and leaf were published.
k_ra8_err_access_denied	An intermediate component is an unapproved symlink.
k_ra8_err_not_found	An intermediate component is absent or not a directory.
k_ra8_err_invalid_size	A component or iteration bound is invalid.
k_ra8_err_*	Mapped descriptor operation failure.

Precondition: Pointer arguments are non-NULL and outputs have advertised capacity.; path passed portable lexical validation and is not root-only.

Postcondition: On success caller owns *out_parent_fd and out_leaf is populated.; On failure every descriptor opened by this resolver is closed.

Note: Thread-safe for independent state; host namespace changes can race resolution.

Since: Version 0.1.0

Definition at line 178 of file fw_if_fs_posix.c.

References internal_next_component(), internal_parent_open_step(), k_fw_fs_path_cap, k_posix_component_cap, k_ra8_err_invalid_size, k_ra8_ok, memcpy(), priv_fs_posix_close_fd_preserve(), priv_fs_posix_errno(), RA8_PRIV, and fw_fs_posix_state_t::root_fd.

Referenced by internal_directory_open(), internal_mkdir(), internal_native_stat(), internal_parent_sync(), internal_rename(), internal_rmdir(), internal_unlink(), and priv_fs_posix_open().

◆ priv_fs_posix_root_alias_classify()

ra8_err_t priv_fs_posix_root_alias_classify	(	const char *	component,
		const char *	target,
		size_t	target_bytes,
		posix_root_alias_t *	out_alias )

Classify one exact filesystem-root alias component and target pair.

Accepts only the byte-exact relative pairs tmp -> private/tmp and var -> private/var. Absolute targets, swapped components, prefixes, suffixes, truncation, and every other pair remain denied.

Parameters

[in]	component	Terminated candidate alias basename.
[in]	target	Raw, not necessarily terminated link-target bytes.
[in]	target_bytes	Number of readable bytes in `target`.
[out]	out_alias	Receives the classified alias selection.

Returns: Root-alias tuple classification status.

Return values

k_ra8_ok	The component and target are one approved pair.
k_ra8_err_access_denied	The pair is not approved.

Precondition: component, target, and out_alias are non-NULL.; target addresses at least target_bytes readable bytes.

Postcondition: Success publishes the pair's non-none alias selection.; Failure leaves out_alias set to k_posix_root_alias_none.

Note: Pure and thread-safe.

Since: Version 0.1.0

Definition at line 149 of file fw_if_fs_posix_common.c.

References internal_bytes_equal(), k_posix_root_alias_none, k_posix_root_alias_tmp, k_posix_root_alias_var, k_ra8_err_access_denied, k_ra8_ok, RA8_PRIV, and strcmp().

◆ priv_fs_posix_root_alias_open()

ra8_err_t priv_fs_posix_root_alias_open	(	int	root_fd,
		posix_root_alias_t	alias,
		int *	out_fd )

Open a classified root alias through its canonical components.

Opens private beneath root_fd, then the selected tmp or var child, applying O_NOFOLLOW to both operations. The original alias path is never opened, closing the validation-to-use replacement window.

Parameters

[in]	root_fd	Open descriptor for a root-like directory.
[in]	alias	Valid non-none alias selection.
[out]	out_fd	Receives the owned canonical directory descriptor.

Returns: Canonical directory-open status.

Return values

k_ra8_ok	`out_fd` owns the selected canonical directory.
k_ra8_err_invalid_arg	`alias` is not a supported selection.
k_ra8_err_*	Mapped canonical open or descriptor-close failure.

Precondition: root_fd remains open and contains real private/tmp or private/var directories corresponding to alias.; alias is k_posix_root_alias_tmp or k_posix_root_alias_var.; out_fd addresses one writable integer descriptor object.

Postcondition: Success publishes exactly one owned descriptor in out_fd.; Failure publishes no descriptor and closes every descriptor opened here.

Warning: Darwin production callers must first prove root_fd identifies actual / through ::priv_fs_posix_root_alias_verify.

Note: Fixture tests may exercise the canonical no-follow mechanics beneath a private root-like directory without weakening the production rule.; Thread-safe for independent descriptors.

Since: Version 0.1.0

Definition at line 211 of file fw_if_fs_posix_common.c.

References k_posix_root_alias_tmp, k_posix_root_alias_var, k_ra8_err_invalid_arg, k_ra8_ok, O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW, priv_fs_posix_close_fd(), priv_fs_posix_close_fd_preserve(), priv_fs_posix_errno(), and RA8_PRIV.

Referenced by priv_fs_posix_component_open().

◆ priv_fs_posix_seek()

ra8_err_t priv_fs_posix_seek	(	void *	ctx,
		void *	file_state,
		uint64_t	offset )

Seek a POSIX descriptor to an unsigned absolute offset.

Rejects values not representable by signed 64-bit host offsets before issuing one lseek(SEEK_SET).

Parameters

[in]	ctx	Unused confined-root context.
[in,out]	file_state	Open posix_file_state_t.
[in]	offset	Absolute byte offset.

Returns: Host seek status.

Return values

k_ra8_ok	The descriptor position is `offset`.
k_ra8_err_invalid_size	`offset` exceeds INT64_MAX.
k_ra8_err_*	Mapped lseek failure.

Precondition: file_state owns an open seekable descriptor.; No concurrent operation changes the same descriptor offset.

Postcondition: Success sets the next I/O position to offset.; File contents and length are unchanged.

Note: Not thread-safe for concurrent use of one descriptor offset.

Since: Version 0.1.0

Definition at line 168 of file fw_if_fs_posix_stream.c.

References k_ra8_err_invalid_size, k_ra8_ok, priv_fs_posix_errno(), and RA8_PRIV.

Referenced by internal_txn_seek(), and priv_fs_posix_stream_iface().

◆ priv_fs_posix_size()

ra8_err_t priv_fs_posix_size	(	void *	ctx,
		void *	file_state,
		uint64_t *	out_size )

Report a POSIX descriptor's current file length.

Queries descriptor metadata with fstat and widens the non-negative regular-file size to the portable uint64_t result.

Parameters

[in]	ctx	Unused confined-root context.
[in]	file_state	Open posix_file_state_t.
[out]	out_size	Receives current file length in bytes.

Returns: Host metadata-query status.

Return values

k_ra8_ok	`out_size` contains the current length.
k_ra8_err_*	Mapped fstat failure.

Precondition: file_state owns an open regular-file descriptor.; out_size addresses one writable uint64_t object.

Postcondition: Success writes the length without changing descriptor position.; File contents are unchanged.

Note: Thread-safe subject to file mutation and descriptor lifecycle synchronization.

Since: Version 0.1.0

Definition at line 195 of file fw_if_fs_posix_stream.c.

References k_ra8_ok, priv_fs_posix_errno(), and RA8_PRIV.

Referenced by internal_txn_seek(), and priv_fs_posix_stream_iface().

◆ priv_fs_posix_stage_path()

ra8_err_t priv_fs_posix_stage_path	(	const char *	destination,
		uint32_t	id,
		char *	out )

Build an 8.3-compatible sibling transaction path.

Retains everything through destination's final / and appends the fixed twelve-byte leaf TX, six lowercase hexadecimal digits of id's low 24 bits, and .TMP. Staging beside the destination rather than in a scratch directory is what lets publication be one rename inside a single directory and filesystem. Uniqueness belongs to the caller, which advances its transaction counter and retries when the constructed leaf already exists.

Parameters

[in]	destination	Validated portable destination path.
[in]	id	Transaction identifier; only its low 24 bits are rendered.
[out]	out	Destination holding k_fw_fs_path_cap writable bytes.

Returns: Stage-name construction status.

Return values

k_ra8_ok	`out` holds the terminated sibling stage path.
k_ra8_err_invalid_size	`destination` has no terminator within k_fw_fs_path_cap, or its parent prefix leaves no room for the leaf.

Precondition: destination is a validated portable path beginning with /, so the retained prefix ends at a real separator.; out addresses k_fw_fs_path_cap writable bytes and does not overlap destination.

Postcondition: Success publishes a path sharing destination's parent directory, so the later publication rename never crosses a filesystem.; Both capacity checks precede every write, so a rejected call leaves out untouched.

Note: Pure apart from the caller's destination, and thread-safe; the helper contributes no uniqueness of its own.

Since: Version 0.1.0

Definition at line 641 of file fw_if_fs_posix_common.c.

References internal_hex6(), k_fw_fs_path_cap, k_posix_stage_hex_digits, k_posix_stage_leaf_span, k_posix_transaction_id_mask, k_ra8_err_invalid_size, k_ra8_ok, and RA8_PRIV.

Referenced by internal_stage_open().

◆ priv_fs_posix_stream_iface()

const fw_fs_stream_iface_t * priv_fs_posix_stream_iface ( void )

Borrow the immutable POSIX byte-stream operation table.

Hands back the single translation-unit-scoped vtable so the adapter's namespace and transaction units can bind or borrow the same stream implementation without a second copy of the table.

Returns: Address of the immutable stream operation table.

Return values

non-NULL The one stream vtable, valid for the program lifetime.

Precondition: The caller only reads through the returned table.; No caller attempts to modify the referenced operations.

Postcondition: The returned table outlives every caller and is never reassigned.; No adapter state is read or written by the call itself.

Note: Thread-safe; the table is immutable and statically initialized.

Since: Version 0.1.0

Immutable POSIX stream vtable.

Definition at line 226 of file fw_if_fs_posix_stream.c.

References internal_read(), internal_tell(), priv_fs_posix_close(), priv_fs_posix_open(), priv_fs_posix_seek(), priv_fs_posix_size(), priv_fs_posix_sync(), priv_fs_posix_write(), and RA8_PRIV.

Referenced by internal_txn_validate(), and priv_fs_posix_bind_interfaces().

◆ priv_fs_posix_sync()

ra8_err_t priv_fs_posix_sync	(	void *	ctx,
		void *	file_state )

Flush file contents and metadata through POSIX fsync.

Delegates durability to the host descriptor and maps any failure.

Parameters

[in]	ctx	Unused confined-root context.
[in,out]	file_state	Open posix_file_state_t.

Returns: Host synchronization status.

Return values

k_ra8_ok	The host accepted the durability request.
k_ra8_err_*	Mapped fsync failure.

Precondition: file_state owns an open descriptor valid for synchronization.; No concurrent close consumes the descriptor.

Postcondition: Success makes prior writes durable according to host filesystem guarantees.; Descriptor ownership and offset are unchanged.

Note: Thread-safe only with external descriptor lifecycle synchronization.

Since: Version 0.1.0

Definition at line 208 of file fw_if_fs_posix_stream.c.

References k_ra8_ok, priv_fs_posix_errno(), and RA8_PRIV.

Referenced by internal_txn_validate(), and priv_fs_posix_stream_iface().

◆ priv_fs_posix_timestamp()

fw_fs_timestamp_t priv_fs_posix_timestamp	(	time_t	seconds,
		long	nanoseconds )

Convert a POSIX UTC instant into the portable civil representation.

Rejects an out-of-range subsecond, converts seconds with the reentrant gmtime_r, and rejects a civil year that does not fit the portable uint16_t field. Rejection is total rather than partial: the zero-initialized value is returned unmodified, so valid is the one flag a caller has to test. No zone conversion is applied.

Parameters

[in]	seconds	POSIX UTC epoch seconds taken from one struct timespec.
[in]	nanoseconds	Subsecond field of that same struct timespec, in 0..k_posix_nanosecond_max.

Returns: Portable civil timestamp value.

Return values

valid==true	Every civil field and the subsecond are populated in UTC.
valid==false	`nanoseconds` is out of range, gmtime_r failed, or the civil year does not fit the portable field; the value stays zeroed.

Precondition: seconds is a UTC epoch instant rather than a local-time value, because the published utc_offset_min is hard-coded to zero.; nanoseconds is the timespec subsecond, not a total nanosecond count, because it is published beside the separately converted seconds.

Postcondition: Success sets both valid and utc_offset_valid with a zero utc_offset_min, so the value always reads as UTC.; Rejection returns a fully zeroed value rather than a partly filled one.

Note: Pure and thread-safe; the conversion uses the reentrant gmtime_r.

Since: Version 0.1.0

Definition at line 574 of file fw_if_fs_posix_common.c.

References fw_fs_datetime_t::day, fw_fs_datetime_t::hour, k_posix_epoch_year_offset, k_posix_nanosecond_max, fw_fs_datetime_t::minute, fw_fs_datetime_t::month, fw_fs_datetime_t::nanosecond, RA8_PRIV, fw_fs_datetime_t::second, fw_fs_datetime_t::utc_offset_min, fw_fs_timestamp_t::utc_offset_valid, fw_fs_timestamp_t::valid, fw_fs_timestamp_t::value, and fw_fs_datetime_t::year.

Referenced by internal_stat().

◆ priv_fs_posix_write()

ra8_err_t priv_fs_posix_write	(	void *	ctx,
		void *	file_state,
		const uint8_t *	src,
		uint32_t	len,
		uint32_t *	out_written )

Complete POSIX short writes while reporting any accepted prefix.

Retries interrupts, advances over positive short writes, maps host errors, and treats a zero-byte write before completion as failure.

Parameters

[in]	ctx	Unused confined-root context.
[in,out]	file_state	Open posix_file_state_t.
[in]	src	Source bytes.
[in]	len	Exact requested byte count.
[in,out]	out_written	Running accepted count initialized by public dispatch.

Returns: Complete-write status.

Return values

k_ra8_ok	Exactly `len` bytes were accepted.
k_ra8_fail	The host returned zero before completion.
k_ra8_err_*	Mapped non-interrupt write failure.

Precondition: file_state owns an open writable descriptor.; src addresses len readable bytes when non-zero.

Postcondition: Success sets out_written to len.; Failure preserves the exact accepted prefix count.

Note: Not thread-safe for concurrent use of one descriptor offset.

Since: Version 0.1.0

Definition at line 139 of file fw_if_fs_posix_stream.c.

References k_ra8_fail, k_ra8_ok, priv_fs_posix_errno(), and RA8_PRIV.

Referenced by internal_txn_write(), and priv_fs_posix_stream_iface().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ posix_darwin_dirent_layout_t

◆ posix_directory_limits_t

◆ posix_hex_limits_t

◆ posix_limits_t

◆ posix_linux_dirent_layout_t

◆ posix_numeric_limits_t

◆ posix_root_alias_t

Function Documentation

◆ priv_fs_posix_bind_interfaces()

◆ priv_fs_posix_close()

◆ priv_fs_posix_close_fd()

◆ priv_fs_posix_close_fd_preserve()

◆ priv_fs_posix_component_open()

◆ priv_fs_posix_copy_path()

◆ priv_fs_posix_dir_close()

◆ priv_fs_posix_dir_next()

◆ priv_fs_posix_dir_open()

◆ priv_fs_posix_directory_next()

◆ priv_fs_posix_errno()

◆ priv_fs_posix_listdir()

◆ priv_fs_posix_open()

◆ priv_fs_posix_parent_open()

◆ priv_fs_posix_root_alias_classify()

◆ priv_fs_posix_root_alias_open()

◆ priv_fs_posix_seek()

◆ priv_fs_posix_size()

◆ priv_fs_posix_stage_path()

◆ priv_fs_posix_stream_iface()

◆ priv_fs_posix_sync()

◆ priv_fs_posix_timestamp()

◆ priv_fs_posix_write()