Hosted POSIX byte-stream operations for the portable filesystem port. More...

#include <errno.h>
#include <fcntl.h>
#include <stdint.h>
#include <sys/stat.h>
#include <unistd.h>
#include "fw_if_fs.h"
#include "fw_if_fs_backend.h"
#include "fw_if_fs_posix_stream_contracts_internal.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for fw_if_fs_posix_stream.c:

Macros
#define	O_CLOEXEC (0)
	Zero fallback when the host lacks close-on-exec open flags.
#define	O_NOFOLLOW (0)
	Zero fallback paired with explicit no-follow metadata validation.

Functions
static ra8_err_t	internal_open_flags (fw_fs_open_mode_t mode, int *out_flags)
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.
static ra8_err_t	internal_read (void ctx, void file_state, uint8_t dst, uint32_t cap, uint32_t out_read)
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.
static ra8_err_t	internal_tell (void ctx, void file_state, uint64_t *out_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

Hosted POSIX byte-stream operations for the portable filesystem port.

Tag: [Ring 4 / Host Port] {World: Host}

Owns the adapter's complete fw_fs_stream_iface_t implementation: portable open-mode to no-follow openat flag mapping, interrupt-safe read and write loops, absolute seek and position queries, length queries, durability, and close. Every operation drives a caller-owned posix_file_state_t, so this unit holds no mutable state and resolves no path beyond the confined parent the shared no-follow resolver hands it. Namespace policy and staged publication live in fw_if_fs_posix.c, which drives these same operations for its transaction stage through the widened RA8_PRIV entry points.

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

Since: 0.1.0

Definition in file fw_if_fs_posix_stream.c.

Macro Definition Documentation

◆ O_CLOEXEC

#define O_CLOEXEC (0)

Zero fallback when the host lacks close-on-exec open flags.

Definition at line 42 of file fw_if_fs_posix_stream.c.

◆ O_NOFOLLOW

#define O_NOFOLLOW (0)

Zero fallback paired with explicit no-follow metadata validation.

Definition at line 47 of file fw_if_fs_posix_stream.c.

Function Documentation

◆ internal_open_flags()

ra8_err_t internal_open_flags	(	fw_fs_open_mode_t	mode,
		int *	out_flags )

static

Definition at line 51 of file fw_if_fs_posix_stream.c.

References k_fw_fs_open_append, k_fw_fs_open_create_new, k_fw_fs_open_read, k_fw_fs_open_write_truncate, k_ra8_err_invalid_arg, k_ra8_ok, O_CLOEXEC, O_NOFOLLOW, and RA8_INTERNAL.

Referenced by priv_fs_posix_open().

◆ internal_read()

ra8_err_t internal_read	(	void *	ctx,
		void *	file_state,
		uint8_t *	dst,
		uint32_t	cap,
		uint32_t *	out_read )

static

Definition at line 119 of file fw_if_fs_posix_stream.c.

References k_ra8_ok, and priv_fs_posix_errno().

◆ internal_tell()

ra8_err_t internal_tell	(	void *	ctx,
		void *	file_state,
		uint64_t *	out_offset )

static

Definition at line 182 of file fw_if_fs_posix_stream.c.

References k_ra8_ok, priv_fs_posix_errno(), and RA8_INTERNAL.

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

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ O_CLOEXEC

◆ O_NOFOLLOW

Function Documentation

◆ internal_open_flags()

◆ internal_read()

◆ internal_tell()

◆ priv_fs_posix_close()

◆ priv_fs_posix_open()

◆ priv_fs_posix_seek()

◆ priv_fs_posix_size()

◆ priv_fs_posix_stream_iface()

◆ priv_fs_posix_sync()

◆ priv_fs_posix_write()