mdl_export_rabook_io.c File Reference

Portable temporary EPUB and flat-blob adapters for RABOOK export. More...

#include <string.h>
#include "mdl_export_rabook_internal.h"

Include dependency graph for mdl_export_rabook_io.c:

Go to the source code of this file.

Enumerations
enum	mdl_rabook_io_limit_t : uint32_t {   k_rabook_temp_attempts = 16U ,   k_rabook_read_calls = 1000000U ,   k_rabook_fnv_offset = 2166136261U ,   k_rabook_fnv_prime = 16777619U ,   k_rabook_hex_digits = 7U ,   k_rabook_hex_mask = 0x0FU ,   k_rabook_suffix_bytes = 5U ,   k_rabook_value_mask = 0x0FFFFFFFU }
	Bounded I/O and collision-attempt limits. More...

Functions
static uint32_t	internal_temp_seed (const char *destination)
	Hash one destination into a stable temporary-name seed.
static void	internal_temp_leaf (uint32_t value, char leaf[13])
	Render one collision candidate as an 8.3-compatible EPUB leaf.
ra8_err_t	priv_mdl_rabook_temp_begin (mdl_export_output_t *output, mdl_storage_t *storage, const char *directory, const char *destination, char *path, size_t capacity)
	Reserve one collision-free temporary EPUB publication path.
ra8_err_t	priv_mdl_rabook_epub_open (mdl_rabook_epub_source_t *source, mdl_storage_t *storage, const char *path)
	Open one validated temporary EPUB as a portable random-read stream.
ra8_err_t	priv_mdl_rabook_epub_close (mdl_rabook_epub_source_t *source)
	Close one temporary EPUB stream.
size_t	priv_mdl_rabook_epub_read (void *opaque, uint64_t offset, void *destination, size_t length)
	Serve one exact random EPUB read to the streamed reader.
ra8_err_t	priv_mdl_rabook_flat_read (void *opaque, uint32_t offset, uint8_t *destination, uint32_t requested, uint32_t *out_read)
	Serve one exact flat-blob read to the RBKC writer.

Detailed Description

Portable temporary EPUB and flat-blob adapters for RABOOK export.

Owns bounded collision handling plus exact random-read callbacks; it contains no compiler profile or final publication policy.

[Ring 4 / Domain] {World: NS}

Copyright

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

Since

0.1.0

Definition in file mdl_export_rabook_io.c.

Enumeration Type Documentation

mdl_rabook_io_limit_t

enum mdl_rabook_io_limit_t : uint32_t

Bounded I/O and collision-attempt limits.

Enumerator
k_rabook_temp_attempts	Create-new sibling candidates.
k_rabook_read_calls	EPUB random-read ceiling.
k_rabook_fnv_offset	FNV-1a seed for temp names.
k_rabook_fnv_prime	FNV-1a multiplier.
k_rabook_hex_digits	Hex digits in a temp leaf.
k_rabook_hex_mask	One hexadecimal nibble.
k_rabook_suffix_bytes	.EPB plus NUL terminator.
k_rabook_value_mask	Low 28 temporary-name bits.

Definition at line 19 of file mdl_export_rabook_io.c.

Function Documentation

internal_temp_leaf()

void internal_temp_leaf ( uint32_t value, char leaf[13] )

static

Render one collision candidate as an 8.3-compatible EPUB leaf.

Writes R plus seven uppercase hexadecimal digits and .EPB without a variadic formatter or hidden stream dependency.

Parameters

[in]	value	Low 28 bits used for the hexadecimal suffix.
[out]	leaf	Writable thirteen-byte leaf buffer.

Precondition

leaf is non-NULL and spans exactly thirteen writable bytes.

Higher bits of value are ignored by design.

Postcondition

leaf contains one complete NUL-terminated 8.3 name.

No global or filesystem state is changed.

Note

Thread-safe across distinct destinations.

Since

0.1.0

Definition at line 66 of file mdl_export_rabook_io.c.

References k_rabook_hex_digits, k_rabook_hex_mask, k_rabook_suffix_bytes, memcpy(), and RA8_INTERNAL.

Referenced by priv_mdl_rabook_temp_begin().

internal_temp_seed()

uint32_t internal_temp_seed ( const char * destination )

static

Hash one destination into a stable temporary-name seed.

Applies 32-bit FNV-1a to the complete NUL-terminated path.

Parameters

[in]

destination

Stable final destination path.

Returns

Deterministic non-cryptographic path hash.

Return values

other

The 32-bit FNV-1a hash of the complete destination string.

Precondition

destination is non-NULL and NUL-terminated.

The string remains stable for the call.

Postcondition

No caller-owned memory is changed.

Equal byte strings produce equal hashes.

Note

Used only to spread collision candidates, never for trust.

Since

0.1.0

Definition at line 43 of file mdl_export_rabook_io.c.

References k_rabook_fnv_offset, k_rabook_fnv_prime, and RA8_INTERNAL.

Referenced by priv_mdl_rabook_temp_begin().

priv_mdl_rabook_epub_close()

ra8_err_t priv_mdl_rabook_epub_close

(

mdl_rabook_epub_source_t *

source

)

Close one temporary EPUB stream.

Delegates to the injected file adapter and clears retained state only after the close operation succeeds.

Parameters

[in,out]

source

Open source state.

Returns

Portable close status.

Return values

k_ra8_ok	The file closed and state was cleared.
other	The portable close operation failed.

Precondition

source is non-NULL and owns an open file.

No EPUB reader continues to borrow the source callback.

Postcondition

Success clears the complete source state.

Failure remains visible and the state is not claimed reusable.

Note

Not thread-safe for a shared source.

Since

0.1.0

Definition at line 148 of file mdl_export_rabook_io.c.

References mdl_rabook_epub_source_t::file, fw_fs_close(), fw_fs_file_t::is_open, k_ra8_err_invalid_arg, k_ra8_ok, and RA8_PRIV.

Referenced by internal_close_compile_sources().

priv_mdl_rabook_epub_open()

ra8_err_t priv_mdl_rabook_epub_open	(	mdl_rabook_epub_source_t *	source,
		mdl_storage_t *	storage,
		const char *	path )

Open one validated temporary EPUB as a portable random-read stream.

Stats and opens one regular file, retaining its exact immutable extent for the callback lifetime.

Parameters

[out]	source	Caller-owned stream state.
[in,out]	storage	Exclusive portable storage binding.
[in]	path	Canonical temporary EPUB path.

Returns

File metadata/open status.

Return values

k_ra8_ok	A nonempty regular file is open with a stable extent.
k_ra8_err_invalid_arg	The node is nonregular or an argument is invalid.

Precondition

Pointers are non-NULL and source owns no open file.

No concurrent writer mutates path.

Postcondition

Success initializes the complete source state.

Failure leaves source clear and owns no file.

Note

The storage file workspace is borrowed until close.

Since

0.1.0

Definition at line 108 of file mdl_export_rabook_io.c.

References fw_fs_stat_t::exists, mdl_rabook_epub_source_t::file, mdl_storage_t::file_workspace, mdl_storage_t::file_workspace_bytes, mdl_storage_t::fs, fw_fs_close(), fw_fs_file_size(), fw_fs_open(), fw_fs_stat(), fw_fs_file_t::is_open, k_fw_fs_node_file, k_fw_fs_open_read, k_ra8_err_invalid_arg, k_ra8_err_protocol_error, k_ra8_ok, fw_fs_t::names, RA8_PRIV, fw_fs_stat_t::size_bytes, mdl_rabook_epub_source_t::size_bytes, fw_fs_t::streams, and fw_fs_stat_t::type.

Referenced by internal_compile_temp().

priv_mdl_rabook_epub_read()

size_t priv_mdl_rabook_epub_read	(	void *	opaque,
		uint64_t	offset,
		void *	destination,
		size_t	length )

Serve one exact random EPUB read to the streamed reader.

Bounds the request against the retained extent, seeks explicitly, and latches any short read or excessive callback count.

Parameters

[in,out]	opaque	Bound mdl_rabook_epub_source_t.
[in]	offset	Absolute archive byte offset.
[out]	destination	Writable destination.
[in]	length	Exact requested byte count.

Returns

length on complete success, otherwise zero.

Return values

0	The request was invalid, out of range, short, or faulted.
other	The exact positive length requested by the reader.

Precondition

Pointer arguments are non-NULL and the file remains open.

destination spans length writable bytes.

Postcondition

Success initializes every requested destination byte.

Failure latches the first canonical error in the source state.

Note

The callback is serialized by the EPUB reader.

Since

0.1.0

Definition at line 160 of file mdl_export_rabook_io.c.

References mdl_rabook_epub_source_t::calls, mdl_rabook_epub_source_t::error, mdl_rabook_epub_source_t::file, fw_fs_read(), fw_fs_seek(), fw_fs_file_t::is_open, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_out_of_range, k_ra8_ok, k_rabook_read_calls, RA8_PRIV, and mdl_rabook_epub_source_t::size_bytes.

Referenced by internal_compile_temp().

priv_mdl_rabook_flat_read()

ra8_err_t priv_mdl_rabook_flat_read	(	void *	opaque,
		uint32_t	offset,
		uint8_t *	destination,
		uint32_t	requested,
		uint32_t *	out_read )

Serve one exact flat-blob read to the RBKC writer.

Validates offset arithmetic before copying the requested resident span and reporting its exact transferred count.

Parameters

[in]	opaque	Bound mdl_rabook_flat_source_t.
[in]	offset	Flat blob byte offset.
[out]	destination	Writable destination.
[in]	requested	Exact requested byte count.
[out]	out_read	Exact copied count on success.

Returns

Range or copy status.

Return values

k_ra8_ok	The complete requested range was copied.
k_ra8_err_out_of_range	The range exceeds the flat blob.

Precondition

All pointers are non-NULL and spans match their declared extents.

The flat blob remains immutable for the call.

Postcondition

Success initializes the complete destination range.

Failure sets out_read to zero.

Note

Thread-safe for immutable distinct destinations.

Since

0.1.0

Definition at line 197 of file mdl_export_rabook_io.c.

References mdl_rabook_flat_source_t::bytes, k_ra8_err_invalid_arg, k_ra8_err_out_of_range, k_ra8_ok, memcpy(), RA8_PRIV, and mdl_rabook_flat_source_t::size_bytes.

Referenced by internal_emit_container().

priv_mdl_rabook_temp_begin()

ra8_err_t priv_mdl_rabook_temp_begin	(	mdl_export_output_t *	output,
		mdl_storage_t *	storage,
		const char *	directory,
		const char *	destination,
		char *	path,
		size_t	capacity )

Reserve one collision-free temporary EPUB publication path.

Hashes the final destination into bounded 8.3-compatible sibling names and uses create-new transactions so no prior file is replaced.

Parameters

[out]	output	Active create-new EPUB output on success.
[in,out]	storage	Exclusive portable storage binding.
[in]	directory	Canonical directory that will contain the temporary file.
[in]	destination	Final RABOOK path used only as a deterministic salt.
[out]	path	Destination for the chosen canonical temporary path.
[in]	capacity	Writable bytes at path.

Returns

Path construction or transaction-open status.

Return values

k_ra8_ok	One private EPUB stage is active.
k_ra8_err_exists	Every bounded candidate already exists.
k_ra8_err_invalid_size	The temporary path cannot fit.

Precondition

Pointers are non-NULL and strings are NUL-terminated.

output is inactive and storage is exclusively owned.

Postcondition

Success initializes path and one active output transaction.

Failure changes no named file and leaves output inactive.

Note

At most sixteen candidate names are attempted.

Since

0.1.0

Definition at line 77 of file mdl_export_rabook_io.c.

References internal_temp_leaf(), internal_temp_seed(), k_mdl_format_epub, k_ra8_err_exists, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, k_rabook_temp_attempts, k_rabook_value_mask, priv_mdl_export_output_begin_new(), priv_mdl_export_path_join(), and RA8_PRIV.

Referenced by internal_write_temp_epub().