Stream every requested book into the mounted image and prove the copy. More...

#include <fcntl.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
#include "mkbookimg_internal.h"
#include "mkbookimg_names.h"
#include "ra8_attributes.h"
#include "ra8_fs.h"

Include dependency graph for mkbookimg_books.c:

Data Structures
struct	mkbookimg_input_identity_t
	Stable facts used to detect input replacement or mutation. More...

Functions
static mkbookimg_input_identity_t	internal_input_identity (const struct stat *metadata)
	Extract nanosecond-resolution identity fields portably.
static bool	internal_input_same (const mkbookimg_input_identity_t expected, const struct stat actual)
	Compare a captured identity with a fresh fstat result.
static bool	internal_identity_equal (const mkbookimg_input_identity_t left, const mkbookimg_input_identity_t right)
	Compare two captured host-input identities field by field.
static bool	internal_input_open (const char path, int out_fd, mkbookimg_input_identity_t *identity)
	Open and identify one immutable regular input without following its leaf.
static bool	internal_stream_book (ra8_fs_mount_t mount, const char name, const char path, mkbookimg_input_identity_t identity)
	Stream one host input into a newly truncated filesystem file.
static bool	internal_verify_book_reopen (ra8_fs_mount_t mount, const char name, const char path, const mkbookimg_input_identity_t identity, int out_input_fd, ra8_fs_file_t *out_card)
	Reopen host and card handles and confirm identity and size.
static bool	internal_verify_book (ra8_fs_mount_t mount, const char name, const char path, const mkbookimg_input_identity_t identity)
	Re-read host and card bytes to prove the streamed copy and input stability.
static bool	internal_duplicate_name (char **arguments, int index)
	Detect whether one input would overwrite an earlier basename.
static bool	internal_format_mount (const ra8_fs_backend_t backend, ra8_fs_mount_t *mount)
	Format and mount the descriptor-backed FAT32 image.
static bool	internal_write_books (ra8_fs_mount_t mount, char *arguments, int book_count)
	Stream and verify every requested book through the mounted filesystem.
bool	priv_mkbookimg_build_image (const ra8_fs_backend_t backend, char argv, int book_count, const mkbookimg_disk_t disk)
	Format, populate, and unmount the destination image.

Detailed Description

Stream every requested book into the mounted image and prove the copy.

Owns the population pass of an image build: opening each immutable regular input, capturing the identity fields that expose replacement or mutation, streaming the bytes through one bounded stack chunk into an ra8_fs file, then re-reading both sides so no book is published unless it was reproduced byte-for-byte from an input that never moved under the tool. The host container that owns the image file, its block device, and the atomic publication rename is src/mkbookimg.c; see inc/mkbookimg_internal.h for the seam.

[Ring 7 / Tooling] {World: NS}

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

Since: 0.1.0

Definition in file mkbookimg_books.c.

Function Documentation

◆ internal_duplicate_name()

bool internal_duplicate_name	(	char **	arguments,
		int	index )

static

Detect whether one input would overwrite an earlier basename.

Compares only normalized destination basenames from earlier arguments.

Parameters

[in]	arguments	Program argument vector with inputs from index two.
[in]	index	Zero-based input index to compare with its predecessors.

Returns: true when an earlier input has the same card basename.

Return values

true	Publishing this input would replace an earlier book.
false	Its basename is unique among preceding inputs.

Precondition: arguments contains valid paths through input index.; index is non-negative.

Postcondition: No argument string is changed.; Only earlier inputs participate in the result.

Note: Pure; thread-safe for immutable arguments.

Since: 0.1.0

Definition at line 341 of file mkbookimg_books.c.

References mkbookimg_basename(), RA8_INTERNAL, and strcmp().

Referenced by internal_write_books().

◆ internal_format_mount()

bool internal_format_mount	(	const ra8_fs_backend_t *	backend,
		ra8_fs_mount_t **	mount )

static

Format and mount the descriptor-backed FAT32 image.

Applies deterministic format policy before claiming one mount slot.

Parameters

[in]	backend	Block-device facade.
[out]	mount	Receives mounted volume.

Returns: true only when both formatter and mount succeed.

Return values

true	The fresh FAT32 image is mounted.
false	Formatting or mount validation failed.

Precondition: Both arguments are non-NULL.; Backend capacity is an empty exact-size image.

Postcondition: On true caller must unmount mount.; On false no mount handle remains claimed.

Note: Not thread-safe through global ra8_fs slots.

Since: 0.1.0

Definition at line 367 of file mkbookimg_books.c.

References k_ra8_fs_type_fat32, k_ra8_ok, priv_mkbookimg_diag(), ra8_fs_format(), ra8_fs_mount(), and RA8_INTERNAL.

Referenced by priv_mkbookimg_build_image().

◆ internal_identity_equal()

bool internal_identity_equal	(	const mkbookimg_input_identity_t *	left,
		const mkbookimg_input_identity_t *	right )

static

Compare two captured host-input identities field by field.

Avoids padding comparisons while checking every mutation-sensitive field.

Parameters

[in]	left	First identity.
[in]	right	Second identity.

Returns: true only when every field matches.

Return values

true	Both values describe the same unchanged input.
false	At least one identity or timestamp field differs.

Precondition: Both arguments are non-NULL and fully initialized.; Both values came from internal_input_identity.

Postcondition: No state is changed.; Structure padding is never inspected.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 120 of file mkbookimg_books.c.

References mkbookimg_input_identity_t::changed_nsec, mkbookimg_input_identity_t::changed_sec, mkbookimg_input_identity_t::device, mkbookimg_input_identity_t::inode, mkbookimg_input_identity_t::modified_nsec, mkbookimg_input_identity_t::modified_sec, RA8_INTERNAL, and mkbookimg_input_identity_t::size.

Referenced by internal_verify_book_reopen().

◆ internal_input_identity()

mkbookimg_input_identity_t internal_input_identity ( const struct stat * metadata )

static

Extract nanosecond-resolution identity fields portably.

Normalizes Darwin and POSIX timestamp layouts into one owned value.

Parameters

[in] metadata Successful fstat result for a regular input.

Returns: Stable identity value copied from metadata.

Return values

all-fields The input's device, inode, length, mtime, and ctime.

Precondition: metadata is non-NULL and has non-negative size.; Platform timestamp members follow the selected compile-time branch.

Postcondition: No state is changed.; The returned value owns no resources.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 58 of file mkbookimg_books.c.

References RA8_INTERNAL.

Referenced by internal_input_open(), and internal_input_same().

◆ internal_input_open()

bool internal_input_open	(	const char *	path,
		int *	out_fd,
		mkbookimg_input_identity_t *	identity )

static

Open and identify one immutable regular input without following its leaf.

Rejects links, empty inputs, non-regular objects, and oversized books.

Parameters

[in]	path	Input path.
[out]	out_fd	Receives owned read descriptor.
[out]	identity	Receives initial stable identity.

Returns: true for a non-empty regular file within FAT32 size limits.

Return values

true	Descriptor and identity are populated.
false	Open/stat/type/size validation failed.

Precondition: All arguments are non-NULL.; path is NUL-terminated.

Postcondition: On true caller owns out_fd.; On false no descriptor remains open.

Note: Thread-safe for distinct output arguments.

Since: 0.1.0

Definition at line 146 of file mkbookimg_books.c.

References internal_input_identity(), O_CLOEXEC, and O_NOFOLLOW.

Referenced by internal_stream_book(), and internal_verify_book_reopen().

◆ internal_input_same()

bool internal_input_same	(	const mkbookimg_input_identity_t *	expected,
		const struct stat *	actual )

static

Compare a captured identity with a fresh fstat result.

Detects replacement, resizing, and timestamp-visible input mutation.

Parameters

[in]	expected	Previously captured input identity.
[in]	actual	Fresh metadata from the same open descriptor.

Returns: true only when every mutation-sensitive field matches.

Return values

true	The observed descriptor still names the same unchanged bytes.
false	Size or any stable identity/timestamp field differs.

Precondition: Both arguments are non-NULL.; expected came from internal_input_identity.

Postcondition: No state is changed.; The result depends on every represented identity field.

Note: Pure; thread-safe.

Since: 0.1.0

Definition at line 91 of file mkbookimg_books.c.

References mkbookimg_input_identity_t::changed_nsec, mkbookimg_input_identity_t::changed_sec, mkbookimg_input_identity_t::device, mkbookimg_input_identity_t::inode, internal_input_identity(), mkbookimg_input_identity_t::modified_nsec, mkbookimg_input_identity_t::modified_sec, RA8_INTERNAL, and mkbookimg_input_identity_t::size.

Referenced by internal_stream_book(), and internal_verify_book().

◆ internal_stream_book()

bool internal_stream_book	(	ra8_fs_mount_t *	mount,
		const char *	name,
		const char *	path,
		mkbookimg_input_identity_t *	identity )

static

Stream one host input into a newly truncated filesystem file.

Copies through a bounded stack chunk and rechecks identity before close.

Parameters

[in,out]	mount	Mounted FAT32 image.
[in]	name	Destination basename.
[in]	path	Host input path.
[out]	identity	Identity used by the verification pass.

Returns: true only when the input was stable and the card file closed cleanly.

Return values

true	The full input is present under `name`.
false	Host read, mutation check, filesystem write, or close failed.

Precondition: mount is mounted and all strings are NUL-terminated.; identity is writable.

Postcondition: On true the card file length equals identity->size.; All host/card handles opened here are closed on every path.

Note: Not thread-safe; ra8_fs owns shared static mount/file slots.

Since: 0.1.0

Definition at line 180 of file mkbookimg_books.c.

References internal_input_open(), internal_input_same(), k_ra8_fs_mode_write, k_ra8_ok, k_stream_chunk_bytes, priv_mkbookimg_pread_exact(), ra8_fs_close(), ra8_fs_open(), ra8_fs_write(), RA8_INTERNAL, and mkbookimg_input_identity_t::size.

Referenced by internal_write_books().

◆ internal_verify_book()

bool internal_verify_book	(	ra8_fs_mount_t *	mount,
		const char *	name,
		const char *	path,
		const mkbookimg_input_identity_t *	identity )

static

Re-read host and card bytes to prove the streamed copy and input stability.

Compares bounded chunks and repeats the input identity check afterward.

Parameters

[in,out]	mount	Mounted FAT32 image.
[in]	name	Card basename written by internal_stream_book.
[in]	path	Original host path.
[in]	identity	Identity observed before the write pass.

Returns: true only when every byte and all identity fields still match.

Return values

true	Host and card contents match exactly and remained stable.
false	Reopen, metadata, read, compare, or close failed.

Precondition: All strings and identity are valid.; mount remains mounted.

Postcondition: Every opened handle is closed.; The card filesystem is not modified.

Note: Not thread-safe; ra8_fs owns shared static mount/file slots.

Since: 0.1.0

Definition at line 291 of file mkbookimg_books.c.

References internal_input_same(), internal_verify_book_reopen(), k_ra8_ok, k_stream_chunk_bytes, memcmp(), priv_mkbookimg_pread_exact(), ra8_fs_close(), ra8_fs_read(), RA8_INTERNAL, and mkbookimg_input_identity_t::size.

Referenced by internal_write_books().

◆ internal_verify_book_reopen()

bool internal_verify_book_reopen	(	ra8_fs_mount_t *	mount,
		const char *	name,
		const char *	path,
		const mkbookimg_input_identity_t *	identity,
		int *	out_input_fd,
		ra8_fs_file_t **	out_card )

static

Reopen host and card handles and confirm identity and size.

Reopens the host input, confirms it is unchanged since the write pass, then opens the card copy and confirms its size matches.

Parameters

[in,out]	mount	Mounted FAT32 image.
[in]	name	Card basename written by internal_stream_book.
[in]	path	Original host path.
[in]	identity	Identity observed before the write pass.
[out]	out_input_fd	Receives the reopened host descriptor, or -1.
[out]	out_card	Receives the opened card file, or NULL.

Returns: Whether both handles are open and identity/size checks pass.

Return values

true	`out_input_fd` and `out_card` are open and consistent.
false	Reopen, identity, open, or size check failed; every handle this call itself opened has already been closed.

Precondition: All strings and identity are valid.; mount remains mounted.

Postcondition: On false, no handle this call opened remains open.; On true, both handles are the caller's to close.

Note: Not thread-safe; ra8_fs owns shared static mount/file slots.

Since: 0.1.0

Definition at line 240 of file mkbookimg_books.c.

References internal_identity_equal(), internal_input_open(), k_ra8_fs_mode_read, k_ra8_ok, ra8_fs_close(), ra8_fs_open(), ra8_fs_size(), RA8_INTERNAL, and mkbookimg_input_identity_t::size.

Referenced by internal_verify_book().

◆ internal_write_books()

bool internal_write_books	(	ra8_fs_mount_t *	mount,
		char **	arguments,
		int	book_count )

static

Stream and verify every requested book through the mounted filesystem.

Rejects name collisions and requires a second byte-for-byte read pass.

Parameters

[in,out]	mount	Mounted FAT32 volume.
[in]	arguments	Program argument vector.
[in]	book_count	Number of input paths beginning at argv[2].

Returns: true only when every source is stable and exactly reproduced.

Return values

true	Every named card file passed byte-for-byte verification.
false	Name, collision, host I/O, mutation, or filesystem I/O failed.

Precondition: book_count is in 1..k_max_books.; mount and arguments are valid.

Postcondition: No host or card file handle remains open.; Failure affects only the unpublished temporary image.

Note: Not thread-safe through global ra8_fs slots.

Since: 0.1.0

Definition at line 399 of file mkbookimg_books.c.

References internal_duplicate_name(), internal_stream_book(), internal_verify_book(), k_mkbookimg_name_cap, mkbookimg_dest_name(), priv_mkbookimg_diag(), priv_mkbookimg_diag_u64(), and mkbookimg_input_identity_t::size.

Referenced by priv_mkbookimg_build_image().

◆ priv_mkbookimg_build_image()

bool priv_mkbookimg_build_image	(	const ra8_fs_backend_t *	backend,
		char **	argv,
		int	book_count,
		const mkbookimg_disk_t *	disk )

Format, populate, and unmount the destination image.

Formats a fresh FAT32 volume, writes every input book, and unmounts before reporting the combined outcome.

Parameters

[in]	backend	Block-device backend bound to `disk`.
[in]	argv	Output path followed by book paths.
[in]	book_count	Number of book paths in `argv`.
[in,out]	disk	Block-device state; inspected for a deferred I/O fault.

Returns: Whether format, every book write, and unmount all succeeded.

Return values

true	The destination image is complete and consistent.
false	Formatting, a book write, unmount, or block I/O failed.

Precondition: backend is bound to disk and disk names an open image file.; book_count is in 1..k_max_books, already validated by the caller.

Postcondition: On true the image volume is unmounted and internally consistent.; No mount handle remains claimed on any return path.

Note: Not thread-safe through global ra8_fs slots.

Since: 0.1.0

Definition at line 435 of file mkbookimg_books.c.

References internal_format_mount(), internal_write_books(), mkbookimg_disk_t::io_failed, k_ra8_ok, and ra8_fs_unmount().

Referenced by main().

Data Structures

Functions

Detailed Description

Function Documentation

◆ internal_duplicate_name()

◆ internal_format_mount()

◆ internal_identity_equal()

◆ internal_input_identity()

◆ internal_input_open()

◆ internal_input_same()

◆ internal_stream_book()

◆ internal_verify_book()

◆ internal_verify_book_reopen()

◆ internal_write_books()

◆ priv_mkbookimg_build_image()