CBR backend: walk a RAR archive (ra8_rar.h) and index its page images. More...

#include <stddef.h>
#include <stdint.h>
#include "comic.h"
#include "comic_internal.h"
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_decomp_limits.h"
#include "ra8_rar.h"

Include dependency graph for comic_cbr.c:

Enumerations
enum	cbr_limits_t : uint32_t { k_cbr_name_max = 256U , k_cbr_max_blocks = 100000U }
	Name scratch size and the hard block-walk bound. More...

Functions
static ra8_err_t	internal_add_member (comic_t c, const ra8_rar_entry_t ent, const char *name, uint16_t nlen)
	Index one RAR block if it is a decodable page-image file member.
ra8_err_t	priv_comic_cbr_open (comic_t *c)
	Open the CBR (RAR) backend: walk the archive + build the page index.
ra8_err_t	priv_comic_cbr_extract (comic_t c, const comic_page_t p, uint8_t buf, size_t cap, size_t got)
	Extract one CBR page's encoded image (STORE copy or RAR5 decode).

Variables
static const char *const	s_tag_cbr = "comic_cbr"
	Log tag for CBR-backend diagnostics.

Detailed Description

CBR backend: walk a RAR archive (ra8_rar.h) and index its page images.

Tag: [Ring 4 / Domain] {World: NS}

The RAR half of the comic facade. priv_comic_cbr_open walks the RAR block chain one header at a time through the clean-room ra8_rar_next, appending each image file member to the shared page index. STORE members – the common case for comics whose pages are already-compressed JPEG/PNG – extract by streaming the member's data area; a RAR5-compressed member is inflated by the clean-room decompressor (ra8_rar5_decompress) through ra8_rar_extract. Only a RAR4-compressed member (legacy codec, out of scope) is indexed extractable == 0 and reported unsupported. The walk stops at the first unparseable block, keeping the pages found so far (tolerant of trailing junk).

Zero allocation (NASA Rule 3): the walker reads one header into a stack scratch, streams STORE members through the caller's buffer, and inflates compressed members through the comic's caller-owned RAR5 scratch pool.

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

Since: Version 0.1.0

Definition in file comic_cbr.c.

Enumeration Type Documentation

◆ cbr_limits_t

enum cbr_limits_t : uint32_t

Name scratch size and the hard block-walk bound.

k_cbr_max_blocks statically bounds the walk (NASA Rule 2); a comic's block count is far below it, and ra8_rar_next guarantees a strictly advancing offset so the archive size is the real terminator.

Since: Version 0.1.0

Enumerator

k_cbr_name_max

Longest member name indexed (bytes, incl.

path).

k_cbr_max_blocks

Static upper bound on blocks walked.

Definition at line 49 of file comic_cbr.c.

Function Documentation

◆ internal_add_member()

ra8_err_t internal_add_member	(	comic_t *	c,
		const ra8_rar_entry_t *	ent,
		const char *	name,
		uint16_t	nlen )

static

Index one RAR block if it is a decodable page-image file member.

Skips non-file blocks, directories and non-image / hidden names; otherwise appends the member. A STORE member and, on a RAR5 archive, a compressed member are both extractable (the RAR5 decompressor decodes the latter); only a RAR4-compressed member stays non-extractable.

Parameters

[in,out]	c	Comic accumulating its index.
[in]	ent	Decoded block from ra8_rar_next.
[in]	name	Member name bytes.
[in]	nlen	Member name length.

Returns: ra8_err_t status (k_ra8_ok also for a skipped, non-page block).

Return values

k_ra8_ok	Member indexed or intentionally skipped.
k_ra8_err_invalid_size	Page index / name arena is full.

Precondition: ent came from ra8_rar_next; name holds nlen bytes.; c has its buffers bound.

Postcondition: On k_ra8_ok either one page was added or nothing changed (a skip).; On error the index is unchanged.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 76 of file comic_cbr.c.

References ra8_rar_entry_t::data_off, ra8_rar_entry_t::is_dir, ra8_rar_entry_t::is_file, k_ra8_ok, k_ra8_rar_method_store, k_ra8_rar_ver_5, ra8_rar_entry_t::method, ra8_rar_entry_t::pack_size, priv_comic_is_page_name(), priv_comic_page_add(), ra8_decomp_check_declared(), ra8_decomp_limits_default(), comic_t::rar, ra8_rar_entry_t::unp_size, and ra8_rar_t::version.

Referenced by priv_comic_cbr_open().

◆ priv_comic_cbr_extract()

ra8_err_t priv_comic_cbr_extract	(	comic_t *	c,
		const comic_page_t *	p,
		uint8_t *	buf,
		size_t	cap,
		size_t *	got )

Extract one CBR page's encoded image (STORE copy or RAR5 decode).

Routes the page through ra8_rar_extract: a STORE member's literal bytes are streamed, a RAR5-compressed member is inflated by the decompressor into buf. A RAR4-compressed page (indexed non-extractable) is rejected.

Parameters

[in]	c	Comic with a bound CBR walker.
[in]	p	Page-index entry (its data_off / raw_size / rar_method).
[out]	buf	Destination for the encoded image bytes.
[in]	cap	Capacity of `buf`; must be >= p->raw_size.
[out]	got	Receives the bytes written.

Returns: ra8_err_t status.

Return values

k_ra8_ok	Member copied / decoded into `buf`.
k_ra8_err_not_supported	The page is a RAR4-compressed member.
k_ra8_err_no_mem	`cap` is smaller than p->raw_size.
k_ra8_err_invalid_size	A STORE member overruns the archive / short read.
k_ra8_err_validation_failed	A malformed / truncated compressed stream.

Precondition: p came from this comic's CBR index.; buf holds cap writable bytes.

Postcondition: On k_ra8_ok, *got == p->raw_size.; On any error *got == 0.

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 150 of file comic_cbr.c.

References comic_page_t::data_off, ra8_rar_entry_t::data_off, comic_page_t::extractable, ra8_rar_entry_t::is_dir, ra8_rar_entry_t::is_file, k_ra8_err_invalid_state, k_ra8_err_not_supported, k_ra8_rar_ver_none, ra8_rar_entry_t::method, comic_page_t::pack_size, ra8_rar_entry_t::pack_size, RA8_CHECK_NULL_PTR, ra8_rar_extract(), comic_t::rar, comic_t::rar5_state, comic_page_t::rar_method, comic_page_t::raw_size, s_tag_cbr, ra8_rar_entry_t::unp_size, and ra8_rar_t::version.

Referenced by comic_page_read().

◆ priv_comic_cbr_open()

ra8_err_t priv_comic_cbr_open ( comic_t * c )

Open the CBR (RAR) backend: walk the archive + build the page index.

Iterates the RAR block chain (ra8_rar_next) from c->rar.first_off, appending each image file member via priv_comic_page_add. STORE and (on a RAR5 archive) compressed members are indexed extractable == 1; only a RAR4-compressed member (legacy codec, unsupported) gets extractable == 0.

Parameters

[in,out] c Comic with c->rar bound by ra8_rar_open, kind == cbr.

Returns: ra8_err_t status.

Return values

k_ra8_ok	Archive walked; index populated.
k_ra8_err_invalid_size	The page index / name arena was too small.
k_ra8_err_*	A RAR-walk error.

Precondition: c->rar was bound by ra8_rar_open; buffers are bound.; c->size is the archive length.

Postcondition: On k_ra8_ok, the index holds every image member in archive order.; On any error the index is left partially filled (caller discards c).

Note: Not thread-safe.

Since: Version 0.1.0

Definition at line 111 of file comic_cbr.c.

References ra8_rar_t::first_off, internal_add_member(), k_cbr_max_blocks, k_cbr_name_max, k_ra8_err_invalid_state, k_ra8_ok, k_ra8_rar_ver_none, ra8_decomp_budget_t::limits, ra8_rar_entry_t::name_len, ra8_rar_entry_t::next_off, RA8_CHECK_NULL_PTR, ra8_decomp_budget_charge_entry(), ra8_decomp_limits_default(), RA8_PRIV, ra8_rar_next(), comic_t::rar, s_tag_cbr, ra8_rar_t::size, and ra8_rar_t::version.

Referenced by internal_open_detect().

Variable Documentation

◆ s_tag_cbr

const char* const s_tag_cbr = "comic_cbr"

static

Log tag for CBR-backend diagnostics.

Definition at line 39 of file comic_cbr.c.

Referenced by priv_comic_cbr_extract(), and priv_comic_cbr_open().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ cbr_limits_t

Function Documentation

◆ internal_add_member()

◆ priv_comic_cbr_extract()

◆ priv_comic_cbr_open()

Variable Documentation

◆ s_tag_cbr