Raw-descriptor CLI composition for JOF and RBKC inspection. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <unistd.h>
#include "ra8_attributes.h"
#include "ra8_fmt_host_fd_internal.h"
#include "ra8_fmt_portable_main_internal.h"
#include "ra8_fmt_stream.h"

Include dependency graph for ra8_fmt_portable_main.c:

Enumerations
enum	cli_const_t : uint32_t { k_cli_exit_ok = 0U , k_cli_exit_fail = 1U , k_cli_exit_usage = 2U , k_cli_input_cap = 268435456U , k_cli_decimal_radix = 10U , k_cli_decimal_chars = 20U }
	Exit values and explicit composition workspace budgets. More...
enum	cli_format_t : uint8_t { k_cli_format_none = 0U , k_cli_format_jof = 1U , k_cli_format_rabook = 2U }
	Supported inspect-container classifications. More...

Functions
static ra8_err_t	internal_text (const ra8_fmt_sink_t sink, const char text)
	Append one literal through an injected sink.
static ra8_err_t	internal_u64 (const ra8_fmt_sink_t *sink, uint64_t value)
	Append an unsigned decimal through an injected sink.
static void	internal_error_status (const ra8_fmt_sink_t sink, const char prefix, ra8_err_t status)
	Emit one error line with an integer status.
static bool	internal_parse (int argc, char argv, const char input, const char *format, bool verbose)
	Parse the established inspect command arguments.
static ra8_err_t	internal_format (const ra8_fmt_source_t source, const char explicit_name, cli_format_t *format)
	Resolve an explicit name or four-byte container magic.
static void	internal_workspace_error (const ra8_fmt_sink_t sink, const jof_audit_requirements_t need)
	Report exact workspace requirements and capacities.
static int	internal_run_jof (const ra8_fmt_source_t source, bool verbose, ra8_fmt_cli_workspace_t workspace, const ra8_fmt_sink_t output, const ra8_fmt_sink_t errors)
	Execute inspection after CLI ownership and source resolution.
static int	internal_run_rabook (const ra8_fmt_source_t source, bool verbose, ra8_fmt_cli_workspace_t workspace, const ra8_fmt_sink_t *output)
	Bind the existing shared high-water to strict RBKC workspaces.
static int	internal_open (const char input, const char explicit_name, bool verbose, ra8_fmt_cli_workspace_t workspace, bool handled, const ra8_fmt_sink_t *errors)
	Open, classify, and inspect one bounded host source.
int	priv_fmt_try_portable_inspect (int argc, char *argv, ra8_fmt_cli_workspace_t workspace, bool *handled)
	Try strict streamed JOF or RBKC inspection.

Detailed Description

Raw-descriptor CLI composition for JOF and RBKC inspection.

Parses the inspect subset, resolves container magic, checks exact workspace requirements, and binds explicit host-edge adapters.

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

Since: 0.1.0

Definition in file ra8_fmt_portable_main.c.

Enumeration Type Documentation

◆ cli_const_t

enum cli_const_t : uint32_t

Exit values and explicit composition workspace budgets.

Enumerator
k_cli_exit_ok	Successful command.
k_cli_exit_fail	Command ran and failed.
k_cli_exit_usage	Invalid command line.
k_cli_input_cap	Maximum accepted input (256 MiB).
k_cli_decimal_radix	Status-code formatting radix.
k_cli_decimal_chars	Maximum unsigned decimal digits.

Definition at line 22 of file ra8_fmt_portable_main.c.

◆ cli_format_t

enum cli_format_t : uint8_t

Supported inspect-container classifications.

Enumerator
k_cli_format_none	Unknown or unsupported container.
k_cli_format_jof	JOF1 band-tile atlas.
k_cli_format_rabook	RBKC chunked RABOOK1 container.

Definition at line 32 of file ra8_fmt_portable_main.c.

Function Documentation

◆ internal_error_status()

void internal_error_status	(	const ra8_fmt_sink_t *	sink,
		const char *	prefix,
		ra8_err_t	status )

static

Emit one error line with an integer status.

Writes prefix, unsigned status spelling, and closing delimiter fail-fast.

Parameters

[in]	sink	Bound diagnostic sink.
[in]	prefix	NUL-terminated prefix including opening delimiter.
[in]	status	Canonical status to report.

Precondition: sink, its callback, and prefix are non-null.; prefix is NUL-terminated.

Postcondition: Complete line was attempted until the first sink error.; No command or source state changed.

Note: Diagnostic sink failures are intentionally not propagated.

Since: 0.1.0

Definition at line 105 of file ra8_fmt_portable_main.c.

References internal_text(), internal_u64(), and k_ra8_ok.

Referenced by internal_open(), and internal_run_jof().

◆ internal_format()

ra8_err_t internal_format	(	const ra8_fmt_source_t *	source,
		const char *	explicit_name,
		cli_format_t *	format )

static

Resolve an explicit name or four-byte container magic.

Reads one bounded prefix only when no explicit format was supplied.

Parameters

[in]	source	Bound portable source.
[in]	explicit_name	Optional CLI format selector.
[out]	format	Receives supported classification or none.

Returns: Canonical source status.

Return values

k_ra8_ok	Classification was produced, including an unknown source.
other	Injected positioned read failed.

Precondition: source, its callback, and format are non-null.; Source size describes the same backing used by its callback.

Postcondition: Success initializes format exactly once.; Source position and binding are unchanged.

Note: Classification is prefix evidence; full parser performs validation.

Since: 0.1.0

Definition at line 176 of file ra8_fmt_portable_main.c.

References ra8_fmt_source_t::ctx, k_cli_format_jof, k_cli_format_none, k_cli_format_rabook, k_ra8_ok, memcmp(), ra8_fmt_source_t::read_at, and strcmp().

Referenced by internal_open().

◆ internal_open()

int internal_open	(	const char *	input,
		const char *	explicit_name,
		bool	verbose,
		ra8_fmt_cli_workspace_t *	workspace,
		bool *	handled,
		const ra8_fmt_sink_t *	errors )

static

Open, classify, and inspect one bounded host source.

Opens a stable raw-descriptor view, resolves an explicit selector or magic prefix, dispatches the strict engine, and closes the source exactly once.

Parameters

[in]	input	NUL-terminated input path.
[in]	explicit_name	Optional explicit format name.
[in]	verbose	Whether to emit format-specific detail.
[in,out]	workspace	Named CLI composition storage.
[out]	handled	Receives whether a supported format owned the result.
[in]	errors	Bound diagnostic sink.

Returns: Portable process status.

Return values

k_cli_exit_ok	Inspection succeeded or the format was unknown.
k_cli_exit_fail	Open, classification, validation, or reporting failed.

Precondition: All required pointer arguments and callbacks are non-null.; input and any explicit_name are NUL-terminated.

Postcondition: Every successfully opened source descriptor is closed.; handled is false only for an unsupported format classification.

Note: Unknown formats return to the top-level usage path.

Since: 0.1.0

Definition at line 354 of file ra8_fmt_portable_main.c.

References internal_error_status(), internal_format(), internal_run_jof(), internal_run_rabook(), k_cli_exit_fail, k_cli_exit_ok, k_cli_format_jof, k_cli_format_none, k_cli_input_cap, k_ra8_ok, priv_fmt_host_fd_sink(), priv_fmt_host_source_close(), priv_fmt_host_source_open(), and ra8_fmt_host_source_t::source.

Referenced by priv_fmt_try_portable_inspect().

◆ internal_parse()

bool internal_parse	(	int	argc,
		char **	argv,
		const char **	input,
		const char **	format,
		bool *	verbose )

static

Parse the established inspect command arguments.

Recognizes bounded options while preserving positional input behavior.

Parameters

[in]	argc	Argument count.
[in]	argv	Argument vector.
[in,out]	input	Receives input path when present.
[in,out]	format	Receives explicit format when present.
[in,out]	verbose	Receives verbose-option state.

Returns: Whether every inspect argument was recognized and complete.

Return values

true	Output selections reflect the complete argument sequence.
false	Unknown, duplicate positional, or missing-value syntax occurred.

Precondition: argv contains argc NUL-terminated strings.; Output pointers are non-null and initialized by the caller.

Postcondition: Success consumes every argument from index two onward.; Parser performs no I/O and retains only pointers into argv.

Note: Parsing is deterministic and locale-independent.

Since: 0.1.0

Definition at line 138 of file ra8_fmt_portable_main.c.

References strcmp().

Referenced by priv_fmt_try_portable_inspect().

◆ internal_run_jof()

int internal_run_jof	(	const ra8_fmt_source_t *	source,
		bool	verbose,
		ra8_fmt_cli_workspace_t *	workspace,
		const ra8_fmt_sink_t *	output,
		const ra8_fmt_sink_t *	errors )

static

Execute inspection after CLI ownership and source resolution.

Derives exact needs, checks the named BSS budget, binds caller-owned views, and delegates the complete callback-driven inspection.

Parameters

[in]	source	Open bounded portable source.
[in]	verbose	Whether to emit bounded hex dumps and tile table.
[in,out]	workspace	Explicit shared composition-root storage.
[in]	output	Bound report sink.
[in]	errors	Bound diagnostic sink.

Returns: Portable command exit status.

Return values

k_cli_exit_ok	Complete audit and report succeeded.
k_cli_exit_fail	Parse, capacity, audit, or report failed.

Precondition: Source, sinks, and their callbacks are non-null and remain live.; Source size does not exceed the host-open ceiling.

Postcondition: No dynamic storage or descriptor ownership is acquired here.; Static workspace contents may change but no source byte is changed.

Note: Single-threaded through the named composition-root workspace.

Since: 0.1.0

Definition at line 259 of file ra8_fmt_portable_main.c.

References ra8_fmt_cli_workspace_t::bytes, ra8_fmt_source_t::ctx, internal_error_status(), internal_workspace_error(), jof_audit_requirements(), k_cli_exit_fail, k_cli_exit_ok, k_ra8_fmt_cli_record_cap, k_ra8_fmt_cli_scratch_cap, k_ra8_fmt_cli_tile_cap, k_ra8_ok, ra8_fmt_jof_inspect_stream(), ra8_fmt_source_t::read_at, jof_audit_requirements_t::record_count, jof_audit_requirements_t::scratch_bytes, ra8_fmt_source_t::size, and jof_audit_requirements_t::tile_bytes.

Referenced by internal_open().

◆ internal_run_rabook()

int internal_run_rabook	(	const ra8_fmt_source_t *	source,
		bool	verbose,
		ra8_fmt_cli_workspace_t *	workspace,
		const ra8_fmt_sink_t *	output )

static

Bind the existing shared high-water to strict RBKC workspaces.

Partitions the named CLI bytes into disjoint table, compressed, inflated, and semantic-validation spans before invoking the stream engine.

Parameters

[in]	source	Open immutable container source.
[in]	verbose	Whether to emit the bounded chunk inventory.
[in,out]	workspace	Existing named CLI composition storage.
[in]	output	Bound report sink.

Returns: Portable process status.

Return values

k_cli_exit_ok	Strict outer and inner validation succeeded.
k_cli_exit_fail	Validation or reporting failed.

Precondition: Pointer arguments and callbacks are non-null and remain live.; Workspace alignment and extent match ra8_fmt_cli_workspace_t.

Postcondition: Workspace contents may change but no source byte changes.; No descriptor ownership escapes the call.

Note: The partition does not increase the existing CLI storage high-water.

Since: 0.1.0

Definition at line 309 of file ra8_fmt_portable_main.c.

References ra8_fmt_cli_workspace_t::bytes, k_cli_exit_fail, k_cli_exit_ok, k_ra8_fmt_cli_rbkc_chunk_cap, k_ra8_fmt_cli_rbkc_compressed_cap, k_ra8_fmt_cli_rbkc_scratch_cap, k_ra8_fmt_cli_rbkc_table_cap, k_ra8_ok, and ra8_fmt_rabook_inspect_stream().

Referenced by internal_open().

◆ internal_text()

ra8_err_t internal_text	(	const ra8_fmt_sink_t *	sink,
		const char *	text )

static

Append one literal through an injected sink.

Measures the NUL-terminated text and delegates one exact byte span.

Parameters

[in]	sink	Bound output sink.
[in]	text	NUL-terminated literal or diagnostic string.

Returns: Canonical sink status.

Return values

k_ra8_ok	Complete text was accepted.
other	Injected sink rejected the span.

Precondition: sink, its callback, and text are non-null.; text is NUL-terminated.

Postcondition: Exactly the bytes before NUL were offered once.; Sink binding and source text are unchanged.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 54 of file ra8_fmt_portable_main.c.

References ra8_fmt_sink_t::ctx, strlen(), and ra8_fmt_sink_t::write.

Referenced by internal_error_status(), internal_workspace_error(), and priv_fmt_try_portable_inspect().

◆ internal_u64()

ra8_err_t internal_u64	(	const ra8_fmt_sink_t *	sink,
		uint64_t	value )

static

Append an unsigned decimal through an injected sink.

Converts through fixed local buffers and delegates one digit span.

Parameters

[in]	sink	Bound output sink.
[in]	value	Unsigned value to render in base ten.

Returns: Canonical sink status.

Return values

k_ra8_ok	Complete decimal spelling was accepted.
other	Injected sink rejected the span.

Precondition: sink and its callback are non-null.; Fixed digit capacity covers every uint64_t value.

Postcondition: Exactly one non-empty decimal spelling was offered.; No global or filesystem state changed.

Note: Thread safety inherits the injected sink.

Since: 0.1.0

Definition at line 75 of file ra8_fmt_portable_main.c.

References ra8_fmt_sink_t::ctx, k_cli_decimal_chars, k_cli_decimal_radix, and ra8_fmt_sink_t::write.

Referenced by internal_error_status(), and internal_workspace_error().

◆ internal_workspace_error()

void internal_workspace_error	(	const ra8_fmt_sink_t *	sink,
		const jof_audit_requirements_t *	need )

static

Report exact workspace requirements and capacities.

Emits required/supplied record, tile, and scratch bounds through callbacks.

Parameters

[in]	sink	Bound diagnostic sink.
[in]	need	Successfully derived JOF audit requirements.

Precondition: sink, its callback, and need are non-null.; At least one requirement exceeds the compiled composition budget.

Postcondition: Capacity diagnostic was attempted until the first sink failure.; Requirements and static workspace are unchanged.

Note: Diagnostic sink failures are intentionally not propagated.

Since: 0.1.0

Definition at line 215 of file ra8_fmt_portable_main.c.

References internal_text(), internal_u64(), k_ra8_ok, jof_audit_requirements_t::record_count, jof_audit_requirements_t::scratch_bytes, and jof_audit_requirements_t::tile_bytes.

Referenced by internal_run_jof().

◆ priv_fmt_try_portable_inspect()

int priv_fmt_try_portable_inspect	(	int	argc,
		char **	argv,
		ra8_fmt_cli_workspace_t *	workspace,
		bool *	handled )

nodiscard

Try strict streamed JOF or RBKC inspection.

Parameters

[in]	argc	Process argument count.
[in]	argv	Process argument vector.
[in,out]	workspace	Explicit shared composition-root arena.
[out]	handled	Set when this function owns the exit status.

Returns: Process exit status when handled; unspecified otherwise.

Definition at line 385 of file ra8_fmt_portable_main.c.

References internal_open(), internal_parse(), internal_text(), k_cli_exit_fail, k_cli_exit_ok, k_cli_exit_usage, priv_fmt_host_fd_sink(), RA8_PRIV, and strcmp().

Referenced by internal_dispatch().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ cli_const_t

◆ cli_format_t

Function Documentation

◆ internal_error_status()

◆ internal_format()

◆ internal_open()

◆ internal_parse()

◆ internal_run_jof()

◆ internal_run_rabook()

◆ internal_text()

◆ internal_u64()

◆ internal_workspace_error()

◆ priv_fmt_try_portable_inspect()