File-local contracts for the hosted POSIX byte-stream operations. More...

#include "fw_if_fs_posix_internal.h"
#include "ra8_attributes.h"

Include dependency graph for fw_if_fs_posix_stream_contracts_internal.h:

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

Functions
static ra8_err_t	internal_open_flags (fw_fs_open_mode_t mode, int *out_flags)
	Map a portable open mode to confined no-follow openat flags.
static ra8_err_t	internal_read (void ctx, void file_state, uint8_t dst, uint32_t cap, uint32_t out_read)
	Retry an interrupted POSIX read and expose a legitimate short read.
static ra8_err_t	internal_tell (void ctx, void file_state, uint64_t *out_offset)
	Report the current POSIX descriptor offset.

Detailed Description

File-local contracts for the hosted POSIX byte-stream operations.

Declares the file-local open-mode mapping, descriptor-read, and offset-query helpers implemented by fw_if_fs_posix_stream.c. Their complete contracts stay readable without pushing that unit past the repository size ceiling; the cross-unit RA8_PRIV operation contracts instead live in fw_if_fs_posix_internal.h, their single declaration authority.

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

Since: Version 0.1.0

Definition in file fw_if_fs_posix_stream_contracts_internal.h.

Function Documentation

◆ internal_open_flags()

ra8_err_t internal_open_flags	(	fw_fs_open_mode_t	mode,
		int *	out_flags )

static

Map a portable open mode to confined no-follow openat flags.

Adds close-on-exec and no-follow to read, truncate, append, and exclusive-create modes; rejects every unrecognized value.

Parameters

[in]	mode	Portable open mode.
[out]	out_flags	Receives POSIX open flags.

Returns: Mode mapping status.

Return values

k_ra8_ok	`out_flags` contains the complete safe host flag set.
k_ra8_err_invalid_arg	`mode` is unsupported or invalid.

Precondition: out_flags addresses one writable integer.; Required fallback macros preserve fail-closed behavior on this host.

Postcondition: Success writes flags corresponding exactly to mode.; Failure leaves out_flags unchanged.

Note: Pure apart from caller output and thread-safe.

Since: Version 0.1.0

◆ internal_read()

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

static

Retry an interrupted POSIX read and expose a legitimate short read.

Repeats only EINTR, maps other host errors, and preserves short-read and zero-byte EOF semantics in the portable count.

Parameters

[in]	ctx	Unused confined-root context.
[in,out]	file_state	Open posix_file_state_t.
[out]	dst	Destination for at most `cap` bytes.
[in]	cap	Writable destination capacity.
[out]	out_read	Accepted byte count.

Returns: Host read status.

Return values

k_ra8_ok	A bounded prefix or EOF was reported.
k_ra8_err_*	Mapped non-interrupt read failure.

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

Postcondition: Success reports no more than cap bytes.; The file offset advances by the reported count.

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

Since: Version 0.1.0

◆ internal_tell()

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

static

Report the current POSIX descriptor offset.

Uses lseek(SEEK_CUR) without moving the offset and maps host errors.

Parameters

[in]	ctx	Unused confined-root context.
[in]	file_state	Open posix_file_state_t.
[out]	out_offset	Receives the absolute byte offset.

Returns: Host position-query status.

Return values

k_ra8_ok	`out_offset` contains the current position.
k_ra8_err_*	Mapped lseek failure.

Precondition: file_state owns an open seekable descriptor.; out_offset addresses one writable uint64_t object.

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

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

Since: Version 0.1.0

Functions

Detailed Description

Function Documentation

◆ internal_open_flags()

◆ internal_read()

◆ internal_tell()