Raw-descriptor implementation of the portable byte-stream backend. More...

#include "ra8_io_stream_posix.h"
#include <errno.h>
#include <stdint.h>
#include <unistd.h>
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_io_stream_backend.h"
#include "ra8_io_stream_posix_internal.h"

Include dependency graph for ra8_io_stream_posix.c:

Enumerations
enum	ra8_io_stream_posix_const_t : uint32_t { k_posix_write_interrupt_limit = 16U }
	POSIX descriptor-write retry limits. More...

Functions
static ra8_err_t	internal_map_errno (int error_number)
	Map one descriptor-write errno value to the canonical vocabulary.
static ra8_err_t	internal_write_loop_step (int fd, const uint8_t bytes, uint32_t length, uint32_t done, uint32_t interrupts, ra8_io_stream_posix_write_fn_t writer, void writer_context)
	Perform one write attempt within the bounded retry loop.
ra8_err_t	priv_ra8_io_stream_posix_write_loop (int fd, const uint8_t bytes, uint32_t length, uint32_t out_written, ra8_io_stream_posix_write_fn_t writer, void *writer_context)
	Complete one descriptor write through an injected raw primitive.
static int64_t	internal_native_write (void context, int fd, const uint8_t bytes, uint32_t length, int *out_errno)
	Invoke the native POSIX descriptor-write primitive once.
static ra8_err_t	internal_posix_write (void context, const uint8_t bytes, uint32_t length, uint32_t *out_written)
	Stream-backend callback for one borrowed POSIX descriptor.
ra8_err_t	ra8_io_stream_posix_init (ra8_io_stream_t stream, ra8_io_stream_posix_state_t state, int fd)
	Bind a borrowed writable descriptor as a byte-stream sink.

Variables
static const ra8_io_stream_iface_t	s_posix_stream_iface
	Immutable borrowed-descriptor stream backend.

Detailed Description

Raw-descriptor implementation of the portable byte-stream backend.

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

Performs exact bounded writes through write(2), retries a finite number of interruptions, detects impossible kernel progress, and maps host failures to ra8_err_t. The descriptor is borrowed and no C-runtime stream is created.

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

Definition in file ra8_io_stream_posix.c.

Enumeration Type Documentation

◆ ra8_io_stream_posix_const_t

enum ra8_io_stream_posix_const_t : uint32_t

POSIX descriptor-write retry limits.

Enumerator
k_posix_write_interrupt_limit	Maximum interrupted attempts.

Definition at line 34 of file ra8_io_stream_posix.c.

Function Documentation

◆ internal_map_errno()

ra8_err_t internal_map_errno ( int error_number )

static

Map one descriptor-write errno value to the canonical vocabulary.

Converts only the captured error value supplied by the write loop. It does not inspect or modify the process-global errno object.

Parameters

[in] error_number Captured non-zero errno value.

Returns: Canonical error corresponding to error_number.

Return values

k_ra8_err_protocol_error	`error_number` was zero.
k_ra8_fail	No more specific canonical mapping exists.

Precondition: error_number is the value captured for one failed write attempt.; The caller does not require preservation of host-specific distinctions.

Postcondition: The returned value depends only on error_number.; No global error state or descriptor state is modified.

Note: Multiple host errno values may intentionally map to one portable code.

Since: 0.1.0

Definition at line 60 of file ra8_io_stream_posix.c.

References k_ra8_err_access_denied, k_ra8_err_comm_error, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_no_mem, k_ra8_err_protocol_error, k_ra8_err_would_block, k_ra8_fail, and RA8_INTERNAL.

Referenced by internal_write_loop_step().

◆ internal_native_write()

int64_t internal_native_write	(	void *	context,
		int	fd,
		const uint8_t *	bytes,
		uint32_t	length,
		int *	out_errno )

static

Invoke the native POSIX descriptor-write primitive once.

Calls write(2) exactly once and captures errno immediately when the syscall reports failure. Retry and exact-transfer policy belongs to the surrounding injected write loop.

Parameters

[in]	context	Unused native-writer context.
[in]	fd	Writable descriptor.
[in]	bytes	Source bytes.
[in]	length	Maximum bytes for this attempt.
[out]	out_errno	Captured errno on failure, otherwise zero.

Returns: Native byte count or negative failure result.

Return values

-1	The native descriptor write failed and `out_errno` was set.

Precondition: bytes spans length readable bytes and out_errno is writable.; fd designates a descriptor acceptable to write(2).

Postcondition: A non-negative result never exceeds length.; out_errno is zero on success and the captured errno on failure.

Note: The caller owns bounded interruption retries.

Since: 0.1.0

Definition at line 198 of file ra8_io_stream_posix.c.

◆ internal_posix_write()

ra8_err_t internal_posix_write	(	void *	context,
		const uint8_t *	bytes,
		uint32_t	length,
		uint32_t *	out_written )

static

Stream-backend callback for one borrowed POSIX descriptor.

Resolves the bound descriptor from context and delegates the entire exact transfer to priv_ra8_io_stream_posix_write_loop.

Parameters

[in]	context	Bound ra8_io_stream_posix_state_t.
[in]	bytes	Source bytes.
[in]	length	Requested byte count.
[out]	out_written	Proven accepted byte count.

Returns: Canonical exact-write status.

Return values

k_ra8_ok Every requested byte was accepted.

Precondition: All pointers are non-null and bytes spans length bytes.; context points to an initialized ra8_io_stream_posix_state_t.

Postcondition: Success means every requested byte was accepted.; out_written contains the proven accepted prefix on every return.

Note: A caller that wants EPIPE returned must suppress the host's default SIGPIPE disposition at its composition boundary.

Since: 0.1.0

Definition at line 231 of file ra8_io_stream_posix.c.

References ra8_io_stream_posix_state_t::fd, internal_native_write(), and priv_ra8_io_stream_posix_write_loop().

◆ internal_write_loop_step()

ra8_err_t internal_write_loop_step	(	int	fd,
		const uint8_t *	bytes,
		uint32_t	length,
		uint32_t *	done,
		uint32_t *	interrupts,
		ra8_io_stream_posix_write_fn_t	writer,
		void *	writer_context )

static

Perform one write attempt within the bounded retry loop.

Issues one write, retries in place on EINTR up to the bounded interrupt limit, and maps every other negative result through internal_map_errno. A zero or over-reported result is rejected as a protocol violation.

Parameters

[in]	fd	Open POSIX descriptor.
[in]	bytes	Source buffer.
[in]	length	Total requested byte count.
[in,out]	done	Running written-byte count; unchanged on a retry.
[in,out]	interrupts	Running EINTR retry count.
[in]	writer	Injected native write primitive.
[in,out]	writer_context	Writer-specific context.

Returns: Write status.

Return values

k_ra8_ok	The write advanced `done`, or an in-limit EINTR retry left it unchanged.
k_ra8_err_retry_limit	The bounded EINTR retry count was exceeded.
k_ra8_err_protocol_error	The writer reported zero or excess bytes.
other	The mapped native write error.

Precondition: done is strictly less than length on entry.; bytes holds at least length readable bytes and writer is non-NULL.

Postcondition: On success without a retry, done advances by the bytes written.; On any error return done is unchanged, so the caller cannot skip bytes.

Note: Not thread-safe: mutates caller-owned scratch state.

Since: 0.1.0

Definition at line 119 of file ra8_io_stream_posix.c.

References internal_map_errno(), k_posix_write_interrupt_limit, k_ra8_err_protocol_error, k_ra8_err_retry_limit, k_ra8_ok, and RA8_INTERNAL.

Referenced by priv_ra8_io_stream_posix_write_loop().

◆ priv_ra8_io_stream_posix_write_loop()

ra8_err_t priv_ra8_io_stream_posix_write_loop	(	int	fd,
		const uint8_t *	bytes,
		uint32_t	length,
		uint32_t *	out_written,
		ra8_io_stream_posix_write_fn_t	writer,
		void *	writer_context )

Complete one descriptor write through an injected raw primitive.

Repeats interrupted attempts up to the fixed adapter ceiling, accumulates only proven progress, and rejects zero or over-reported successful writes.

Parameters

[in]	fd	Writable descriptor forwarded to `writer`.
[in]	bytes	Source bytes.
[in]	length	Requested byte count.
[out]	out_written	Bytes accepted before success or failure.
[in]	writer	Raw write primitive.
[in,out]	writer_context	Opaque context forwarded to `writer`.

Returns: Canonical transfer status.

Return values

k_ra8_ok	Exactly `length` bytes were accepted.
k_ra8_err_retry_limit	The bounded interruption ceiling was exceeded.
k_ra8_err_protocol_error	The writer reported impossible progress.

Precondition: bytes spans length readable bytes.; out_written and writer are non-null.

Postcondition: Success publishes exactly length accepted bytes.; Failure publishes only the proven accepted prefix.

Note: Thread-safe across distinct writer contexts.

Since: 0.1.0

Definition at line 146 of file ra8_io_stream_posix.c.

References internal_write_loop_step(), k_ra8_err_null_ptr, k_ra8_ok, RA8_LOOP_BOUND, and RA8_PRIV.

Referenced by internal_posix_write().

◆ ra8_io_stream_posix_init()

ra8_err_t ra8_io_stream_posix_init	(	ra8_io_stream_t *	stream,
		ra8_io_stream_posix_state_t *	state,
		int	fd )

nodiscard

Bind a borrowed writable descriptor as a byte-stream sink.

Parameters

[out]	stream	Stream handle to initialize.
[out]	state	Caller-owned adapter state retained by `stream`.
[in]	fd	Open writable descriptor borrowed for the binding lifetime.

Returns: Canonical binding status.

Return values

k_ra8_ok	The stream is bound to `fd`.
k_ra8_err_null_ptr	A required pointer is null.
k_ra8_err_invalid_arg	`fd` is negative.

Precondition: fd remains open and writable until the last operation through stream has completed.; The caller exclusively owns stream and state while binding.

Postcondition: Success initializes both stream and state.; Failure leaves both objects unchanged.

Note: Thread-safe across distinct descriptors and state objects.

Since: 0.1.0

Definition at line 249 of file ra8_io_stream_posix.c.

References k_ra8_err_invalid_arg, k_ra8_err_null_ptr, k_ra8_ok, ra8_io_stream_bind(), and s_posix_stream_iface.

Referenced by internal_bind_diagnostic(), internal_output_init(), internal_output_init(), and main().

Variable Documentation

◆ s_posix_stream_iface

const ra8_io_stream_iface_t s_posix_stream_iface

static

Initial value:

                                                        = {
  .write = internal_posix_write,
  .flush = nullptr,
}

Immutable borrowed-descriptor stream backend.

Definition at line 243 of file ra8_io_stream_posix.c.

Referenced by ra8_io_stream_posix_init().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_io_stream_posix_const_t

Function Documentation

◆ internal_map_errno()

◆ internal_native_write()

◆ internal_posix_write()

◆ internal_write_loop_step()

◆ priv_ra8_io_stream_posix_write_loop()

◆ ra8_io_stream_posix_init()

Variable Documentation

◆ s_posix_stream_iface