EINTR-safe raw-descriptor I/O and sibling publication. More...

#include "cache_bench_host.h"
#include <errno.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
#include "ra8_attributes.h"

Include dependency graph for cache_bench_host.c:

Enumerations
enum	cb_host_retry_t : uint8_t { k_cb_host_retry_limit = 32U }
enum	cb_host_mode_t : uint16_t { k_cb_host_create_mode = 0600U }

Functions
static cb_io_status_t	internal_sink_write (void ctx, const uint8_t data, size_t length, size_t *out_written)
	Write one bounded fragment to a borrowed host descriptor.
void	cb_host_standard_sinks (cb_sink_t output, cb_sink_t error)
	Bind the process standard-output and standard-error descriptor sinks.
static cb_io_status_t	internal_source_read (void ctx, uint64_t offset, uint8_t dst, size_t capacity, size_t *out_read)
	Read a bounded fragment from a snapshotted host source.
cb_io_status_t	cb_host_source_open (const char path, cb_host_source_t binding, cb_source_t *source)
	Open a captured-trace path and publish its source seam.
cb_io_status_t	cb_host_source_close (cb_host_source_t *binding)
	Close a source binding.
static cb_io_status_t	internal_split_path (const char path, char parent, size_t parent_capacity, const char **base)
	Split an output path into parent bytes and a borrowed leaf pointer.
static cb_io_status_t	internal_create_temp_exclusive (cb_host_output_t binding, const char parent, const char *base)
	Create a uniquely-named exclusive temp file beside the destination.
cb_io_status_t	cb_host_output_open (const char path, cb_host_output_t binding, cb_sink_t *sink)
	Open a sibling output transaction, or bind descriptor one for NULL.
cb_io_status_t	cb_host_output_commit (cb_host_output_t *binding)
	Flush and atomically publish a transactional output.
void	cb_host_output_abort (cb_host_output_t *binding)
	Abandon a temporary sibling while preserving the destination.
static cb_io_status_t	internal_scratch_transfer (int fd, bool write_mode, uint64_t offset, void *data, size_t length)
	Complete one positional scratch transfer with bounded interruption retries.
static cb_io_status_t	internal_scratch_read (void ctx, uint64_t offset, void data, size_t length)
	Read an exact region through a bound host scratch transaction.
static cb_io_status_t	internal_scratch_write (void ctx, uint64_t offset, void data, size_t length)
	Write an exact region through a bound host scratch transaction.
cb_io_status_t	cb_host_scratch_open (cb_host_scratch_t binding, cb_scratch_t scratch)
	Create an unlinked raw-descriptor scratch transaction.
cb_io_status_t	cb_host_scratch_close (cb_host_scratch_t *binding)
	Close the scratch transaction.

Detailed Description

EINTR-safe raw-descriptor I/O and sibling publication.

Implements the host-only descriptor adapters behind the injected source, sink, scratch, and validated output-transaction seams.

[Ring 7 / Tooling] {World: NS}

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

Since: 0.1.0

Definition in file cache_bench_host.c.

Enumeration Type Documentation

◆ cb_host_mode_t

enum cb_host_mode_t : uint16_t

Enumerator
k_cb_host_create_mode	Owner-only scratch/output permissions.

Definition at line 30 of file cache_bench_host.c.

◆ cb_host_retry_t

enum cb_host_retry_t : uint8_t

Enumerator
k_cb_host_retry_limit	Bounded EINTR/temp-name retry count.

Definition at line 26 of file cache_bench_host.c.

Function Documentation

◆ cb_host_output_abort()

void cb_host_output_abort ( cb_host_output_t * binding )

Abandon a temporary sibling while preserving the destination.

Closes owned descriptors, unlinks a live sibling, and clears the transaction marker; NULL and repeated calls are safe.

Parameters

[in,out] binding Transaction to abandon; NULL is accepted.

Precondition: binding is NULL or initialized output state.; No sink write is in flight through binding.

Postcondition: No owned descriptor or live temporary sibling remains in the binding.; The destination pathname is not replaced by this function.

Note: Host cleanup failures are intentionally best-effort in the void API.

Since: 0.1.0

Definition at line 315 of file cache_bench_host.c.

References cb_host_output_t::dir_fd, cb_host_output_t::fd, cb_host_output_t::temporary, and cb_host_output_t::transactional.

Referenced by cb_host_output_open(), and main().

◆ cb_host_output_commit()

cb_io_status_t cb_host_output_commit ( cb_host_output_t * binding )

Flush and atomically publish a transactional output.

Syncs and closes the temporary file, renames it over the destination, then syncs the parent directory.

Parameters

[in,out] binding Open output transaction or borrowed standard output.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	Publication completed or no transaction was required.
k_cb_io_fault	The binding or a durability operation failed.

Precondition: binding is non-NULL and initialized by cb_host_output_open.; No sink write is in flight through binding.

Postcondition: A successful transaction has no live temporary sibling.; On failure after open, the temporary sibling is unlinked when possible.

Note: Standard output is neither closed nor synchronized by this function.

Since: 0.1.0

Definition at line 289 of file cache_bench_host.c.

References cb_host_output_t::destination, cb_host_output_t::dir_fd, cb_host_output_t::fd, k_cb_io_fault, k_cb_io_ok, cb_host_output_t::temporary, and cb_host_output_t::transactional.

Referenced by main().

◆ cb_host_output_open()

cb_io_status_t cb_host_output_open	(	const char *	path,
		cb_host_output_t *	binding,
		cb_sink_t *	sink )

Open a sibling output transaction, or bind descriptor one for NULL.

Creates a bounded exclusive temporary sibling for pathname output; standard output remains a borrowed non-transactional binding.

Parameters

[in]	path	Destination path, or NULL for standard output.
[out]	binding	Receives transaction state.
[out]	sink	Receives the writable sink seam.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	The sink is ready for publication.
k_cb_io_capacity	A path component exceeds fixed storage.
k_cb_io_fault	An argument or host operation failed.

Precondition: binding and sink are non-NULL.; A non-NULL path is NUL-terminated.

Postcondition: On success, commit or abort must finish a transactional binding.; The destination is unchanged until commit.

Note: Temporary-name retries are bounded by k_cb_host_retry_limit.

Since: 0.1.0

Definition at line 254 of file cache_bench_host.c.

References cb_host_output_abort(), cb_host_output_t::destination, cb_host_output_t::dir_fd, cb_host_output_t::fd, internal_create_temp_exclusive(), internal_sink_write(), internal_split_path(), k_cb_host_path_capacity, k_cb_io_capacity, k_cb_io_fault, k_cb_io_ok, memcpy(), O_CLOEXEC, O_DIRECTORY, and strlen().

Referenced by main().

◆ cb_host_scratch_close()

cb_io_status_t cb_host_scratch_close ( cb_host_scratch_t * binding )

Close the scratch transaction.

Releases the sole descriptor backing the already-unlinked file.

Parameters

[in,out] binding Open scratch descriptor binding.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	The descriptor closed successfully.
k_cb_io_fault	The binding was invalid/closed or close failed.

Precondition: binding is non-NULL and initialized by cb_host_scratch_open.; No scratch callback is in flight.

Postcondition: binding->fd is negative after the close attempt.; The host reclaims the unlinked file when the descriptor closes.

Note: No pathname cleanup is required.

Since: 0.1.0

Definition at line 447 of file cache_bench_host.c.

References cb_host_scratch_t::fd, k_cb_io_fault, and k_cb_io_ok.

Referenced by internal_run_sweep().

◆ cb_host_scratch_open()

cb_io_status_t cb_host_scratch_open	(	cb_host_scratch_t *	binding,
		cb_scratch_t *	scratch )

Create an unlinked raw-descriptor scratch transaction.

Creates a host temporary file, immediately unlinks its pathname, and publishes exact positional read/write callbacks.

Parameters

[out]	binding	Receives the owned scratch descriptor.
[out]	scratch	Receives the injected scratch seam.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	The unlinked transaction is open and bound.
k_cb_io_fault	An argument, create, or unlink operation failed.

Precondition: binding and scratch are non-NULL and writable.; The host temporary directory permits secure file creation.

Postcondition: On success, no pathname refers to the open scratch file.; On failure, no descriptor remains owned by binding.

Note: Scratch bytes live until cb_host_scratch_close.

Since: 0.1.0

Definition at line 427 of file cache_bench_host.c.

References cb_host_scratch_t::fd, internal_scratch_read(), internal_scratch_write(), k_cb_io_fault, and k_cb_io_ok.

Referenced by internal_run_sweep().

◆ cb_host_source_close()

cb_io_status_t cb_host_source_close ( cb_host_source_t * binding )

Close a source binding.

Releases the owned descriptor and marks the binding closed.

Parameters

[in,out] binding Open host source binding.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	The descriptor closed successfully.
k_cb_io_fault	The binding was invalid/closed or close failed.

Precondition: binding is non-NULL and was initialized by cb_host_source_open.; No source read is in flight through binding.

Postcondition: binding->fd is negative after the close attempt.; No descriptor ownership remains with binding.

Note: A host close error is preserved in the return status.

Since: 0.1.0

Definition at line 153 of file cache_bench_host.c.

References cb_host_source_t::fd, k_cb_io_fault, and k_cb_io_ok.

Referenced by internal_close_sources(), and internal_load_argv_traces().

◆ cb_host_source_open()

cb_io_status_t cb_host_source_open	(	const char *	path,
		cb_host_source_t *	binding,
		cb_source_t *	source )

Open a captured-trace path and publish its source seam.

Opens a non-symlink regular file read-only and snapshots its size for mutation checks on every injected read.

Parameters

[in]	path	NUL-terminated host path.
[out]	binding	Receives the owned descriptor binding.
[out]	source	Receives the borrowed source seam.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	The source is open and bound.
k_cb_io_fault	An argument, open, type, or metadata check failed.

Precondition: All pointers are non-NULL.; path names a regular file directly, not a final symlink.

Postcondition: On success, binding owns one descriptor until close.; On failure, no descriptor remains owned by binding.

Note: The source callback borrows binding and must not outlive it.

Since: 0.1.0

Definition at line 133 of file cache_bench_host.c.

References internal_source_read(), k_cb_io_fault, k_cb_io_ok, O_CLOEXEC, O_NOFOLLOW, and cb_host_source_t::size.

Referenced by internal_load_argv_traces().

◆ cb_host_standard_sinks()

void cb_host_standard_sinks	(	cb_sink_t *	output,
		cb_sink_t *	error )

Bind the process standard-output and standard-error descriptor sinks.

Publishes non-owning sink callbacks over descriptors one and two.

Parameters

[out]	output	Standard-output sink; NULL is accepted.
[out]	error	Standard-error sink; NULL is accepted.

Precondition: Each non-NULL output pointer is writable.; The process standard descriptors have their conventional integer values.

Postcondition: Each non-NULL output receives a complete sink binding.; Descriptor ownership remains with the process runtime.

Note: The bindings share file-local descriptor integers but distinct values.

Since: 0.1.0

Definition at line 74 of file cache_bench_host.c.

References internal_sink_write().

Referenced by main().

◆ internal_create_temp_exclusive()

cb_io_status_t internal_create_temp_exclusive	(	cb_host_output_t *	binding,
		const char *	parent,
		const char *	base )

static

Create a uniquely-named exclusive temp file beside the destination.

Retries EEXIST collisions up to k_cb_host_retry_limit, each time formatting a new PID- and attempt-qualified temporary name into binding's temporary-name buffer before an O_EXCL create.

Parameters

[in,out]	binding	Output binding; receives the created descriptor and the accepted temporary-name bytes on success.
[in]	parent	NUL-terminated parent directory path.
[in]	base	Borrowed leaf-name pointer within the original path.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	A new exclusive temp file was created and bound.
k_cb_io_capacity	The formatted temporary name did not fit.
k_cb_io_fault	Every retry was exhausted or a non-EEXIST error hit.

Precondition: binding, parent, and base are non-NULL.; binding's temporary-name buffer has capacity for a candidate name.

Postcondition: On success, binding->fd is open and binding->transactional is true.; On failure, binding->fd is left as this helper set it; the caller still owns cleanup of binding->dir_fd.

Note: Not thread-safe against a concurrent creator of the same destination.

Since: 0.1.0

Definition at line 227 of file cache_bench_host.c.

References cb_host_output_t::fd, k_cb_host_create_mode, k_cb_host_retry_limit, k_cb_io_capacity, k_cb_io_fault, k_cb_io_ok, O_CLOEXEC, cb_host_output_t::temporary, and cb_host_output_t::transactional.

Referenced by cb_host_output_open().

◆ internal_scratch_read()

cb_io_status_t internal_scratch_read	(	void *	ctx,
		uint64_t	offset,
		void *	data,
		size_t	length )

static

Read an exact region through a bound host scratch transaction.

Adapts the injected scratch callback to internal_scratch_transfer.

Parameters

[in]	ctx	Bound cb_host_scratch_t.
[in]	offset	Scratch byte offset.
[out]	data	Destination buffer.
[in]	length	Exact byte count.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	The full region was read.
k_cb_io_fault	The transfer failed.

Precondition: ctx identifies an open scratch descriptor.; data is writable for length bytes.

Postcondition: On success, data holds exactly the requested region.; The scratch binding remains open.

Note: Distinct descriptor bindings may be read independently.

Since: 0.1.0

Definition at line 399 of file cache_bench_host.c.

References internal_scratch_transfer().

Referenced by cb_host_scratch_open().

◆ internal_scratch_transfer()

cb_io_status_t internal_scratch_transfer	(	int	fd,
		bool	write_mode,
		uint64_t	offset,
		void *	data,
		size_t	length )

static

Complete one positional scratch transfer with bounded interruption retries.

Loops over short pread or pwrite results until length bytes complete, resetting the interruption counter after progress.

Parameters

[in]	fd	Open scratch descriptor.
[in]	write_mode	Selects write when true and read when false.
[in]	offset	Initial scratch offset.
[in,out]	data	Transfer buffer.
[in]	length	Exact transfer length.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	The full transfer completed.
k_cb_io_fault	Progress stopped or the retry bound was exhausted.

Precondition: fd is open for the selected operation.; data is valid for length readable or writable bytes.

Postcondition: On success, exactly length bytes were transferred.; The descriptor's sequential offset is unchanged.

Note: The scratch transaction remains open and caller-owned.

Since: 0.1.0

Definition at line 355 of file cache_bench_host.c.

References k_cb_host_retry_limit, k_cb_io_fault, and k_cb_io_ok.

Referenced by internal_scratch_read(), and internal_scratch_write().

◆ internal_scratch_write()

cb_io_status_t internal_scratch_write	(	void *	ctx,
		uint64_t	offset,
		void *	data,
		size_t	length )

static

Write an exact region through a bound host scratch transaction.

Adapts the injected scratch callback to internal_scratch_transfer.

Parameters

[in]	ctx	Bound cb_host_scratch_t.
[in]	offset	Scratch byte offset.
[in]	data	Source buffer.
[in]	length	Exact byte count.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	The full region was written.
k_cb_io_fault	The transfer failed.

Precondition: ctx identifies an open scratch descriptor.; data is readable for length bytes.

Postcondition: On success, the requested scratch region contains data.; The scratch binding remains open.

Note: Distinct descriptor bindings may be written independently.

Since: 0.1.0

Definition at line 422 of file cache_bench_host.c.

References internal_scratch_transfer().

Referenced by cb_host_scratch_open().

◆ internal_sink_write()

cb_io_status_t internal_sink_write	(	void *	ctx,
		const uint8_t *	data,
		size_t	length,
		size_t *	out_written )

static

Write one bounded fragment to a borrowed host descriptor.

Retries interrupted writes up to k_cb_host_retry_limit and reports the exact accepted prefix for cb_sink_write_all.

Parameters

[in]	ctx	Pointer to the borrowed descriptor integer.
[in]	data	Bytes to write.
[in]	length	Requested byte count.
[out]	out_written	Receives the completed prefix length.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	The host accepted a possibly short prefix.
k_cb_io_fault	A binding check or host write failed.

Precondition: data is readable for length bytes when length is non-zero.; ctx and out_written are non-NULL for a valid operation.

Postcondition: On success, out_written does not exceed length.; On failure, out_written is zero when it is writable.

Note: The descriptor remains borrowed and open.

Since: 0.1.0

Definition at line 54 of file cache_bench_host.c.

References k_cb_host_retry_limit, k_cb_io_fault, and k_cb_io_ok.

Referenced by cb_host_output_open(), and cb_host_standard_sinks().

◆ internal_source_read()

cb_io_status_t internal_source_read	(	void *	ctx,
		uint64_t	offset,
		uint8_t *	dst,
		size_t	capacity,
		size_t *	out_read )

static

Read a bounded fragment from a snapshotted host source.

Revalidates file size before each positional read and retries interrupted host calls without changing the descriptor offset.

Parameters

[in]	ctx	Bound cb_host_source_t.
[in]	offset	Byte offset in the source snapshot.
[out]	dst	Destination buffer.
[in]	capacity	Maximum bytes to read.
[out]	out_read	Receives the completed prefix length.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	A possibly short read completed.
k_cb_io_mutated	The source size changed after binding.
k_cb_io_fault	A binding, metadata, or host read failed.

Precondition: dst is writable for capacity bytes.; ctx and out_read are non-NULL and offset is in range.

Postcondition: On success, out_read does not exceed capacity.; The borrowed descriptor's sequential offset is unchanged.

Note: File content mutation without a size change is detected by trace fingerprints.

Since: 0.1.0

Definition at line 108 of file cache_bench_host.c.

References cb_host_source_t::fd, k_cb_host_retry_limit, k_cb_io_fault, k_cb_io_mutated, k_cb_io_ok, and cb_host_source_t::size.

Referenced by cb_host_source_open(), and internal_cache_bind().

◆ internal_split_path()

cb_io_status_t internal_split_path	(	const char *	path,
		char *	parent,
		size_t	parent_capacity,
		const char **	base )

static

Split an output path into parent bytes and a borrowed leaf pointer.

Handles a relative leaf, an absolute root child, and an ordinary parent path without allocating or normalizing either component.

Parameters

[in]	path	NUL-terminated destination path.
[out]	parent	Buffer receiving the NUL-terminated parent.
[in]	parent_capacity	Capacity of `parent`.
[out]	base	Receives a pointer to the leaf within `path`.

Returns: Tool-local I/O status.

Return values

k_cb_io_ok	Both components were published.
k_cb_io_capacity	The parent does not fit or the leaf is empty.

Precondition: path, parent, and base are non-NULL.; path is NUL-terminated and parent_capacity is non-zero.

Postcondition: On success, parent is NUL-terminated and base is non-empty.; path is not modified and ownership does not change.

Note: Symlink and file-type validation is performed by the caller's opens.

Since: 0.1.0

Definition at line 183 of file cache_bench_host.c.

References k_cb_io_capacity, k_cb_io_ok, memcpy(), and strrchr().

Referenced by cb_host_output_open().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ cb_host_mode_t

◆ cb_host_retry_t

Function Documentation

◆ cb_host_output_abort()

◆ cb_host_output_commit()

◆ cb_host_output_open()

◆ cb_host_scratch_close()

◆ cb_host_scratch_open()

◆ cb_host_source_close()

◆ cb_host_source_open()

◆ cb_host_standard_sinks()

◆ internal_create_temp_exclusive()

◆ internal_scratch_read()

◆ internal_scratch_transfer()

◆ internal_scratch_write()

◆ internal_sink_write()

◆ internal_source_read()

◆ internal_split_path()