Owned anonymous raw-fd spools for bounded verifier composition. More...

#include <errno.h>
#include <fcntl.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
#include "ra8_attributes.h"
#include "ra8_fmt_host_fd_internal.h"
#include "ra8_fmt_host_spool_internal.h"

Include dependency graph for ra8_fmt_host_spool.c:

Macros
#define	_POSIX_C_SOURCE (200809L)

Enumerations
enum	spool_const_t : uint32_t { k_spool_attempts = 16U , k_spool_radix = 10U , k_spool_mode = 0600U , k_spool_digits = 20U }
	Scratch creation and spelling bounds. More...

Functions
static ra8_err_t	internal_parent (const char *path, char parent[k_ra8_fmt_host_path_cap])
	Copy the anchor parent into fixed storage.
static ra8_err_t	internal_decimal (char name[k_ra8_fmt_host_name_cap], size_t *len, uint64_t value)
	Append one unsigned decimal into a bounded scratch name.
static ra8_err_t	internal_name (uint32_t attempt, char name[k_ra8_fmt_host_name_cap])
	Form one collision-bounded private scratch leaf.
static ra8_err_t	internal_append (void ctx, const uint8_t bytes, size_t len)
	Append exactly to one unsealed anonymous descriptor.
static ra8_err_t	internal_seal (void *ctx, uint64_t expected_size)
	Seal an exact spool extent before positioned reads.
static ra8_err_t	internal_read (void ctx, uint64_t offset, uint8_t bytes, size_t len, size_t *got)
	Positioned-read one sealed anonymous spool.
static ra8_err_t	internal_create (int parent_fd, ra8_fmt_host_spool_t *state)
	Create and immediately unlink one exclusive scratch leaf.
ra8_err_t	priv_fmt_host_spool_open (const char anchor_path, ra8_fmt_host_spool_t state, ra8_fmt_spool_t *out)
	Create an anonymous scratch file beside an anchored input path.
void	priv_fmt_host_spool_close (ra8_fmt_host_spool_t *state)
	Close an anonymous scratch artifact.

Detailed Description

Owned anonymous raw-fd spools for bounded verifier composition.

Creates exclusive sibling scratch files, unlinks them immediately, and exposes append, seal, and positioned-read callbacks over owned raw fds.

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

Since: 0.1.0

Definition in file ra8_fmt_host_spool.c.

Macro Definition Documentation

◆ _POSIX_C_SOURCE

#define _POSIX_C_SOURCE (200809L)

Definition at line 11 of file ra8_fmt_host_spool.c.

Enumeration Type Documentation

◆ spool_const_t

enum spool_const_t : uint32_t

Scratch creation and spelling bounds.

Enumerator
k_spool_attempts	Exclusive-create collision ceiling.
k_spool_radix	Decimal filename radix.
k_spool_mode	Owner-only scratch permissions.
k_spool_digits	Digits in one uint64_t spelling.

Definition at line 27 of file ra8_fmt_host_spool.c.

Function Documentation

◆ internal_append()

ra8_err_t internal_append	(	void *	ctx,
		const uint8_t *	bytes,
		size_t	len )

static

Append exactly to one unsealed anonymous descriptor.

Retries interrupted positioned writes without changing descriptor position.

Parameters

[in,out]	ctx	Bound ra8_fmt_host_spool_t.
[in]	bytes	Source bytes.
[in]	len	Exact byte count.

Returns: Raw-fd or state status.

Return values

k_ra8_ok	Every byte was appended.
k_ra8_err_invalid_state	The binding, span, or state is invalid.
k_ra8_fail	A host write failed.

Precondition: Non-empty bytes spans len readable bytes.; The bound spool is open and unsealed.

Postcondition: Success advances logical position by exactly len.; Failure never marks the spool sealed.

Note: Not thread-safe through one spool state.

Since: 0.1.0

Definition at line 152 of file ra8_fmt_host_spool.c.

References ra8_fmt_host_spool_t::fd, k_ra8_err_invalid_state, k_ra8_fail, k_ra8_ok, ra8_fmt_host_spool_t::position, and ra8_fmt_host_spool_t::sealed.

◆ internal_create()

ra8_err_t internal_create	(	int	parent_fd,
		ra8_fmt_host_spool_t *	state )

static

Create and immediately unlink one exclusive scratch leaf.

Tries a bounded private-name sequence and retains only the owned descriptor.

Parameters

[in]	parent_fd	Open parent directory.
[out]	state	Receives the owned descriptor.

Returns: Creation or collision status.

Return values

k_ra8_ok	An exclusive file was opened and unlinked.
k_ra8_fail	Creation or immediate unlink failed.
other	Bounded-name status.

Precondition: state is initialized closed.; parent_fd names an open directory owned by the caller.

Postcondition: Success leaves no directory entry and one open descriptor.; Failure leaves state closed and removes any created entry.

Note: Collision work is bounded by k_spool_attempts.

Since: 0.1.0

Definition at line 274 of file ra8_fmt_host_spool.c.

References ra8_fmt_host_spool_t::fd, internal_name(), k_ra8_err_exists, k_ra8_fail, k_ra8_fmt_host_name_cap, k_ra8_ok, k_spool_attempts, k_spool_mode, O_CLOEXEC, and O_NOFOLLOW.

Referenced by priv_fmt_host_spool_open().

◆ internal_decimal()

ra8_err_t internal_decimal	(	char	name[k_ra8_fmt_host_name_cap],
		size_t *	len,
		uint64_t	value )

static

Append one unsigned decimal into a bounded scratch name.

Reverses base-ten digits locally, then appends them in display order.

Parameters

[in,out]	name	NUL-terminated partial name.
[in,out]	len	Current and resulting payload length.
[in]	value	Value to append.

Returns: Capacity status.

Return values

k_ra8_ok	The complete decimal was appended.
k_ra8_err_invalid_size	The fixed spelling buffer is insufficient.

Precondition: name spans k_ra8_fmt_host_name_cap bytes.; len names the current in-bounds NUL offset.

Postcondition: Success appends the complete decimal and NUL.; Failure leaves filesystem state untouched.

Note: Pure apart from caller state.

Since: 0.1.0

Definition at line 85 of file ra8_fmt_host_spool.c.

References k_ra8_err_invalid_size, k_ra8_fmt_host_name_cap, k_ra8_ok, k_spool_digits, and k_spool_radix.

Referenced by internal_name().

◆ internal_name()

ra8_err_t internal_name	(	uint32_t	attempt,
		char	name[k_ra8_fmt_host_name_cap] )

static

Form one collision-bounded private scratch leaf.

Combines the fixed prefix, process identifier, and attempt index.

Parameters

[in]	attempt	Attempt index.
[out]	name	Receives the complete leaf.

Returns: Capacity status.

Return values

k_ra8_ok	The complete private leaf fits.
k_ra8_err_invalid_size	Decimal spelling exceeded fixed storage.

Precondition: name spans k_ra8_fmt_host_name_cap bytes.; attempt is below k_spool_attempts.

Postcondition: Success emits a private process-and-attempt leaf.; No filesystem state is inspected or modified.

Note: Thread safety inherits process-identifier stability.

Since: 0.1.0

Definition at line 119 of file ra8_fmt_host_spool.c.

References internal_decimal(), k_ra8_fmt_host_name_cap, k_ra8_ok, and memcpy().

Referenced by internal_create().

◆ internal_parent()

ra8_err_t internal_parent	(	const char *	path,
		char	parent[k_ra8_fmt_host_path_cap] )

static

Copy the anchor parent into fixed storage.

Resolves an explicit parent, root slash, or current-directory dot.

Parameters

[in]	path	NUL-terminated anchor spelling.
[out]	parent	Receives a NUL-terminated parent path.

Returns: Bounded path status.

Return values

k_ra8_ok	The complete parent fits.
k_ra8_err_invalid_size	The spelling is empty or too long.

Precondition: parent spans k_ra8_fmt_host_path_cap bytes.; path is null or points to a NUL-terminated spelling.

Postcondition: Success writes either the explicit parent, slash, or dot.; Failure does not create or open any filesystem object.

Note: Pure apart from caller output.

Since: 0.1.0

Definition at line 50 of file ra8_fmt_host_spool.c.

References k_ra8_err_invalid_size, k_ra8_fmt_host_path_cap, k_ra8_ok, memcpy(), strlen(), and strrchr().

Referenced by priv_fmt_host_spool_open().

◆ internal_read()

ra8_err_t internal_read	(	void *	ctx,
		uint64_t	offset,
		uint8_t *	bytes,
		size_t	len,
		size_t *	got )

static

Positioned-read one sealed anonymous spool.

Retries interrupted host reads and preserves descriptor position.

Parameters

[in,out]	ctx	Bound ra8_fmt_host_spool_t.
[in]	offset	Absolute byte offset.
[out]	bytes	Destination bytes.
[in]	len	Requested bytes.
[out]	got	Receives actual bytes, including short EOF.

Returns: Raw-fd or state status.

Return values

k_ra8_ok	The request completed, possibly at EOF.
k_ra8_err_invalid_state	The binding, span, or state is invalid.
k_ra8_fail	A host read failed.

Precondition: Non-empty bytes spans len writable bytes.; The bound spool was successfully sealed.

Postcondition: Success initializes got and never changes descriptor position.; No spool byte or logical extent is modified.

Note: Thread-safe for independent destinations after sealing.

Since: 0.1.0

Definition at line 229 of file ra8_fmt_host_spool.c.

References ra8_fmt_host_spool_t::fd, k_ra8_err_invalid_state, k_ra8_fail, k_ra8_ok, ra8_fmt_host_spool_t::position, and ra8_fmt_host_spool_t::sealed.

◆ internal_seal()

ra8_err_t internal_seal	(	void *	ctx,
		uint64_t	expected_size )

static

Seal an exact spool extent before positioned reads.

Cross-checks logical and host extents, then synchronizes deferred writes.

Parameters

[in,out]	ctx	Bound ra8_fmt_host_spool_t.
[in]	expected_size	Producer-reported complete byte count.

Returns: Exact-size, sync, or state status.

Return values

k_ra8_ok	The complete exact extent is durable and readable.
k_ra8_err_validation_failed	Logical or host size differs.
other	Invalid-state or host-sync status.

Precondition: The spool is open and unsealed.; No append callback is running concurrently.

Postcondition: Success permits reads over exactly expected_size bytes.; Failure never exposes the spool as sealed.

Note: Scratch syncing catches deferred host write errors before trust.

Since: 0.1.0

Definition at line 191 of file ra8_fmt_host_spool.c.

References ra8_fmt_host_spool_t::fd, k_ra8_err_invalid_state, k_ra8_err_validation_failed, k_ra8_fail, k_ra8_ok, ra8_fmt_host_spool_t::position, and ra8_fmt_host_spool_t::sealed.

Referenced by priv_fmt_host_spool_open().

◆ priv_fmt_host_spool_close()

void priv_fmt_host_spool_close ( ra8_fmt_host_spool_t * state )

Close an anonymous scratch artifact.

Releases the only owner of an already-unlinked raw descriptor.

Parameters

[in,out] state Possibly open spool state.

Precondition: state is null or was initialized by the spool-open operation.; No callback is executing through state.

Postcondition: Any owned descriptor is closed and marked -1.; Repeated cleanup leaves the state closed.

Note: Idempotent for sequential cleanup.

Since: 0.1.0

Definition at line 333 of file ra8_fmt_host_spool.c.

References ra8_fmt_host_spool_t::fd, and RA8_PRIV.

Referenced by internal_cleanup().

◆ priv_fmt_host_spool_open()

ra8_err_t priv_fmt_host_spool_open	(	const char *	anchor_path,
		ra8_fmt_host_spool_t *	state,
		ra8_fmt_spool_t *	out )

nodiscard

Create an anonymous scratch file beside an anchored input path.

Parameters

[in]	anchor_path	Existing input spelling used only to select its parent.
[out]	state	Receives owned raw-fd state.
[out]	out	Receives portable append, seal, and positioned-read callbacks.

Returns: Host creation or bounded-path status.

Precondition: Output pointers are writable and anchor_path is NUL-terminated.

Postcondition: Success leaves no directory entry; only state owns the descriptor.; Failure owns no descriptor and creates no persistent filesystem object.

Note: Host composition edge only; the portable verifier sees callbacks.

Since: 0.1.0

Definition at line 302 of file ra8_fmt_host_spool.c.

References internal_append(), internal_create(), internal_parent(), internal_read(), internal_seal(), k_ra8_err_null_ptr, k_ra8_fail, k_ra8_fmt_host_path_cap, k_ra8_ok, O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW, and RA8_PRIV.

Referenced by internal_execute().

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ _POSIX_C_SOURCE

Enumeration Type Documentation

◆ spool_const_t

Function Documentation

◆ internal_append()

◆ internal_create()

◆ internal_decimal()

◆ internal_name()

◆ internal_parent()

◆ internal_read()

◆ internal_seal()

◆ priv_fmt_host_spool_close()

◆ priv_fmt_host_spool_open()