Module-private seams shared by the two mkbookimg translation units. More...

#include <fcntl.h>
#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_fs.h"

Include dependency graph for mkbookimg_internal.h:

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

Data Structures
struct	mkbookimg_disk_t
	Host descriptor-backed block device bound into ra8_fs. More...

Macros
#define	O_CLOEXEC (0)
	No-op close-on-exec fallback for hosts lacking the flag.
#define	O_DIRECTORY (0)
	No-op directory-open fallback for hosts lacking the flag.
#define	O_NOFOLLOW (0)
	No-op no-follow fallback for hosts lacking the flag.

Enumerations
enum	mkbookimg_limit_t : uint32_t { k_block_size = 512U , k_img_sectors = 131072U , k_max_books = 32U , k_stream_chunk_bytes = 16U * 1024U , k_host_path_cap = 4096U , k_host_name_cap = 256U , k_temp_create_attempts = 128U , k_decimal_u64_digits = 20U , k_decimal_base = 10U , k_output_create_mode = 0666U }
	Fixed image geometry and bounded host-I/O capacities. More...

Functions
void	priv_mkbookimg_diag (const char *text)
	Write a complete diagnostic fragment to the standard-error descriptor.
void	priv_mkbookimg_diag_u64 (uint64_t value)
	Emit an unsigned decimal value without a formatting runtime.
bool	priv_mkbookimg_pread_exact (int fd, uint64_t offset, uint8_t *bytes, size_t length)
	Read exactly one bounded positioned byte range.
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

Module-private seams shared by the two mkbookimg translation units.

The image builder is split across two translation units to keep each under the maintainability line cap:

src/mkbookimg.c – the host container: descriptor-level diagnostics, exact positioned host I/O, the descriptor-backed ra8_fs block device, the atomic sibling-temporary publication, and the main entry point.
src/mkbookimg_books.c – the population pass: opening and identifying each immutable host input, streaming it into the mounted volume, and proving the stored copy byte-for-byte before the image may be published.

This header carries the fixed image geometry (mkbookimg_limit_t), the descriptor-backed device state (mkbookimg_disk_t), the open-flag fallbacks both units need, and the RA8_PRIV declarations of every helper shared across them. Nothing here is a reusable surface: the tool links ra8_fs and publishes no library of its own.

[Ring 7 / Tooling] {World: NS}

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

Since: 0.1.0

Definition in file mkbookimg_internal.h.

Macro Definition Documentation

◆ O_CLOEXEC

#define O_CLOEXEC (0)

No-op close-on-exec fallback for hosts lacking the flag.

Definition at line 39 of file mkbookimg_internal.h.

◆ O_DIRECTORY

#define O_DIRECTORY (0)

No-op directory-open fallback for hosts lacking the flag.

Definition at line 44 of file mkbookimg_internal.h.

◆ O_NOFOLLOW

#define O_NOFOLLOW (0)

No-op no-follow fallback for hosts lacking the flag.

Definition at line 49 of file mkbookimg_internal.h.

Enumeration Type Documentation

◆ mkbookimg_limit_t

enum mkbookimg_limit_t : uint32_t

Fixed image geometry and bounded host-I/O capacities.

Enumerator
k_block_size	Bytes per image sector.
k_img_sectors	Sectors in the 64 MiB image.
k_max_books	Maximum input-book count.
k_stream_chunk_bytes	Bounded copy chunk bytes.
k_host_path_cap	Hosted path capacity.
k_host_name_cap	Hosted leaf capacity.
k_temp_create_attempts	Exclusive-create retry bound.
k_decimal_u64_digits	Maximum uint64_t digits.
k_decimal_base	Decimal conversion radix.
k_output_create_mode	Hosted output creation mode.

Definition at line 53 of file mkbookimg_internal.h.

Function Documentation

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

◆ priv_mkbookimg_diag()

void priv_mkbookimg_diag ( const char * text )

Write a complete diagnostic fragment to the standard-error descriptor.

Retries interrupted and short writes without involving stdio streams.

Parameters

[in] text NUL-terminated fragment.

Precondition: text is non-NULL and NUL-terminated.; Standard error may be written or may reject the diagnostic.

Postcondition: The complete fragment was attempted.; No application state changed.

Note: Fragments may interleave with another process's diagnostics.

Since: 0.1.0

Definition at line 41 of file mkbookimg.c.

References strlen().

Referenced by internal_format_mount(), internal_print_success(), internal_write_books(), main(), and priv_mkbookimg_diag_u64().

◆ priv_mkbookimg_diag_u64()

void priv_mkbookimg_diag_u64 ( uint64_t value )

Emit an unsigned decimal value without a formatting runtime.

Converts into fixed local buffers and forwards one bounded string.

Parameters

[in] value Value to emit.

Precondition: Standard error may be written or may reject the diagnostic.; k_decimal_u64_digits holds every uint64 decimal spelling.

Postcondition: The decimal spelling was attempted on standard error.; No application state changed.

Note: Fragments may interleave with another process's diagnostics.

Since: 0.1.0

Definition at line 58 of file mkbookimg.c.

References k_decimal_base, k_decimal_u64_digits, and priv_mkbookimg_diag().

Referenced by internal_print_success(), and internal_write_books().

◆ priv_mkbookimg_pread_exact()

bool priv_mkbookimg_pread_exact	(	int	fd,
		uint64_t	offset,
		uint8_t *	bytes,
		size_t	length )

Read exactly one bounded positioned byte range.

Retries interrupted calls and rejects EOF before the requested end.

Parameters

[in]	fd	Open regular-file descriptor.
[in]	offset	Absolute starting byte offset.
[out]	bytes	Destination spanning `length` bytes.
[in]	length	Exact byte count.

Returns: true only when every byte was read.

Return values

true	The destination contains the complete requested range.
false	EOF, overflow, or an unrecoverable read error occurred.

Precondition: bytes spans length writable bytes.; The descriptor remains open for this call.

Postcondition: Descriptor position is unchanged.; On false bytes may hold a strict prefix.

Note: Thread-safe for independent buffers while the descriptor remains open.

Since: 0.1.0

Definition at line 75 of file mkbookimg.c.

Referenced by internal_disk_read(), internal_stream_book(), and internal_verify_book().

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ O_CLOEXEC

◆ O_DIRECTORY

◆ O_NOFOLLOW

Enumeration Type Documentation

◆ mkbookimg_limit_t

Function Documentation

◆ priv_mkbookimg_build_image()

◆ priv_mkbookimg_diag()

◆ priv_mkbookimg_diag_u64()

◆ priv_mkbookimg_pread_exact()