POSIX raw-descriptor composition bindings for cache_bench. More...

#include <stdint.h>
#include "cache_bench_io.h"

Include dependency graph for cache_bench_host.h:

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

Data Structures
struct	cb_host_source_t
	Borrowed raw descriptor source binding. More...
struct	cb_host_output_t
	Output transaction or borrowed standard descriptor. More...
struct	cb_host_scratch_t
	Unlinked raw-descriptor scratch binding. More...

Enumerations
enum	cb_host_limit_t : uint16_t { k_cb_host_path_capacity = 4096U }

Functions
void	cb_host_standard_sinks (cb_sink_t output, cb_sink_t error)
	Bind the process standard-output and standard-error descriptor sinks.
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.
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.
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

POSIX raw-descriptor composition bindings for cache_bench.

Publishes the host-only adapters that bind portable benchmark I/O seams to borrowed or explicitly owned POSIX descriptors.

[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.h.

Enumeration Type Documentation

◆ cb_host_limit_t

enum cb_host_limit_t : uint16_t

Enumerator
k_cb_host_path_capacity	Bounded host path copy.

Definition at line 19 of file cache_bench_host.h.

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().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ cb_host_limit_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()