ra8_fmt_host_fd_internal.h File Reference

Raw file-descriptor adapters for the portable format-tool contracts. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_fmt_stream.h"

Include dependency graph for ra8_fmt_host_fd_internal.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_fmt_host_snapshot_t
	Captured regular-file identity and mutation evidence. More...
struct	ra8_fmt_host_source_t
	Open raw-fd source and its portable view. More...
struct	ra8_fmt_host_fd_sink_t
	Append sink backed by a caller-owned descriptor. More...
struct	ra8_fmt_host_transaction_t
	Caller-owned state for one sibling-file transaction. More...

Enumerations
enum	ra8_fmt_host_limit_t : uint32_t {   k_ra8_fmt_host_path_cap = 1024U ,   k_ra8_fmt_host_name_cap = 256U }
	Bounded host path and transaction-name capacities. More...

Functions
ra8_err_t	priv_fmt_host_source_open (const char *path, uint64_t max_size, ra8_fmt_host_source_t *out)
	Open a bounded, regular, non-symlink input object.
bool	priv_fmt_host_sources_same (const ra8_fmt_host_source_t *first, const ra8_fmt_host_source_t *second)
	Confirm two opens captured the same unchanged regular-file object.
ra8_err_t	priv_fmt_host_source_unchanged (const ra8_fmt_host_source_t *source)
	Revalidate one open descriptor against its captured snapshot.
void	priv_fmt_host_source_close (ra8_fmt_host_source_t *source)
	Close an open host source; safe after failed open.
ra8_fmt_sink_t	priv_fmt_host_fd_sink (ra8_fmt_host_fd_sink_t *state)
	Obtain the exact-write portable sink for a raw descriptor.
void	priv_fmt_host_log_byte (void *ctx, uint8_t byte)
	Adapt a logging byte to an injected raw-fd sink.
ra8_err_t	priv_fmt_host_transaction_begin (const char *path, ra8_fmt_host_transaction_t *state, ra8_fmt_transaction_t *out)
	Begin a sibling-temp durable replacement transaction.

Detailed Description

Raw file-descriptor adapters for the portable format-tool contracts.

Defines caller-owned source, sink, and transaction state; raw host descriptors remain confined to this composition boundary.

Copyright

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

Since

0.1.0

Definition in file ra8_fmt_host_fd_internal.h.

Enumeration Type Documentation

ra8_fmt_host_limit_t

enum ra8_fmt_host_limit_t : uint32_t

Bounded host path and transaction-name capacities.

Enumerator
k_ra8_fmt_host_path_cap	Parent-path storage including NUL.
k_ra8_fmt_host_name_cap	One leaf name including NUL.

Definition at line 19 of file ra8_fmt_host_fd_internal.h.

Function Documentation

priv_fmt_host_fd_sink()

ra8_fmt_sink_t priv_fmt_host_fd_sink ( ra8_fmt_host_fd_sink_t * state )

nodiscard

Obtain the exact-write portable sink for a raw descriptor.

Definition at line 576 of file ra8_fmt_host_fd.c.

References internal_fd_write(), and RA8_PRIV.

Referenced by internal_open(), main(), priv_fmt_try_portable_convert(), priv_fmt_try_portable_inspect(), and priv_fmt_try_portable_verify().

priv_fmt_host_log_byte()

void priv_fmt_host_log_byte	(	void *	ctx,
		uint8_t	byte )

Adapt a logging byte to an injected raw-fd sink.

Bridges the core logger's no-status byte callback to the same exact-write descriptor adapter used by portable reports.

Parameters

[in,out]	ctx	Bound ra8_fmt_host_fd_sink_t.
[in]	byte	One log byte.

Precondition

ctx points at a writable raw-fd sink for the callback lifetime.

The bound descriptor remains open during this call.

Postcondition

The byte was offered exactly once; host write failure is intentionally dropped.

No descriptor ownership or caller state changed.

Note

Matches the no-status byte-sink contract of ra8_log_set_byte_sink().

Since

0.1.0

Definition at line 581 of file ra8_fmt_host_fd.c.

References internal_fd_write(), and RA8_PRIV.

Referenced by main().

priv_fmt_host_source_close()

void priv_fmt_host_source_close

(

ra8_fmt_host_source_t *

source

)

Close an open host source; safe after failed open.

Releases only the raw descriptor and marks the host wrapper closed.

Parameters

[in,out]

source

Host source state, nullable for cleanup convenience.

Precondition

source is null or was initialized by the source-open operation.

No positioned read uses the same source concurrently.

Postcondition

Any owned descriptor is closed and set to -1.

A null or already-closed source is unchanged.

Note

Idempotent for sequential cleanup calls.

Since

0.1.0

Definition at line 568 of file ra8_fmt_host_fd.c.

References ra8_fmt_host_source_t::fd, and RA8_PRIV.

Referenced by internal_cleanup(), internal_open(), and priv_fmt_try_portable_convert().

priv_fmt_host_source_open()

ra8_err_t priv_fmt_host_source_open ( const char * path, uint64_t max_size, ra8_fmt_host_source_t * out )

nodiscard

Open a bounded, regular, non-symlink input object.

Definition at line 513 of file ra8_fmt_host_fd.c.

References ra8_fmt_source_t::ctx, ra8_fmt_host_source_t::fd, internal_pread(), internal_snapshot(), internal_source_validate(), k_ra8_err_access_denied, k_ra8_err_invalid_size, k_ra8_err_null_ptr, k_ra8_fail, k_ra8_ok, O_CLOEXEC, O_NOFOLLOW, RA8_PRIV, ra8_fmt_source_t::read_at, ra8_fmt_source_t::size, ra8_fmt_host_source_t::snapshot, ra8_fmt_host_source_t::source, and ra8_fmt_source_t::validate.

Referenced by internal_open(), internal_open_and_size(), and priv_fmt_try_portable_convert().

priv_fmt_host_source_unchanged()

ra8_err_t priv_fmt_host_source_unchanged ( const ra8_fmt_host_source_t * source )

nodiscard

Revalidate one open descriptor against its captured snapshot.

Parameters

[in]

source

Open source wrapper.

Returns

Canonical stability status.

Return values

k_ra8_ok	Descriptor still names the captured regular file.
k_ra8_err_validation_failed	Identity, size, or timestamps changed.
k_ra8_fail	Host metadata query failed.

Precondition

source came from a successful source-open call.

Postcondition

No descriptor position or captured field changes.

Note

Detects in-place concurrent mutation between verifier phase boundaries.

Since

0.1.0

Definition at line 550 of file ra8_fmt_host_fd.c.

References ra8_fmt_host_source_t::fd, internal_snapshot(), internal_snapshot_same(), k_ra8_err_invalid_state, k_ra8_err_validation_failed, k_ra8_fail, k_ra8_ok, RA8_PRIV, and ra8_fmt_host_source_t::snapshot.

Referenced by internal_open_and_size(), and internal_source_validate().

priv_fmt_host_sources_same()

bool priv_fmt_host_sources_same ( const ra8_fmt_host_source_t * first, const ra8_fmt_host_source_t * second )

nodiscard

Confirm two opens captured the same unchanged regular-file object.

Parameters

[in]	first	First open source context.
[in]	second	Independent second open source context.

Returns

Whether identity, extent, and mutation timestamps match.

Precondition

Both sources came from successful host source-open calls.

Postcondition

Neither descriptor nor snapshot is changed.

Note

Pure over captured evidence.

Since

0.1.0

Definition at line 540 of file ra8_fmt_host_fd.c.

References ra8_fmt_host_source_t::fd, internal_snapshot_same(), RA8_PRIV, and ra8_fmt_host_source_t::snapshot.

Referenced by internal_open_and_size().

priv_fmt_host_transaction_begin()

ra8_err_t priv_fmt_host_transaction_begin ( const char * path, ra8_fmt_host_transaction_t * state, ra8_fmt_transaction_t * out )

nodiscard

Begin a sibling-temp durable replacement transaction.

Definition at line 586 of file ra8_fmt_host_fd.c.

References ra8_fmt_host_transaction_t::active, ra8_fmt_transaction_t::ctx, ra8_fmt_host_transaction_t::final_name, internal_split_path(), internal_stage_name(), internal_transaction_abort(), internal_validate_destination(), k_host_create_attempts, k_host_mode_private, k_ra8_err_exists, k_ra8_err_null_ptr, k_ra8_fail, k_ra8_fmt_host_path_cap, k_ra8_ok, O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW, ra8_fmt_transaction_t::ops, ra8_fmt_host_transaction_t::parent_fd, RA8_PRIV, s_transaction_ops, ra8_fmt_host_transaction_t::stage_exists, ra8_fmt_host_transaction_t::stage_fd, and ra8_fmt_host_transaction_t::stage_name.

Referenced by internal_execute(), and internal_run().