zxc_seekable.h File Reference

Seekable compression and random-access decompression API. More...

#include <stddef.h>
#include <stdint.h>
#include "zxc_export.h"

Go to the source code of this file.

Data Structures
struct	zxc_reader_t
	Storage-agnostic reader interface for seekable archives. More...

Typedefs
typedef struct zxc_seekable_s	zxc_seekable
	Opaque handle for a seekable ZXC archive.

Functions
zxc_seekable *	zxc_seekable_open (const void *src, const size_t src_size)
	Opens a seekable archive from a memory buffer.
zxc_seekable *	zxc_seekable_open_reader (const zxc_reader_t *r)
	Opens a seekable archive through a user-supplied reader.
uint64_t	zxc_seekable_get_num_blocks (const zxc_seekable *s)
	Returns the total number of blocks in the seekable archive.
uint64_t	zxc_seekable_get_decompressed_size (const zxc_seekable *s)
	Returns the total decompressed size of the seekable archive.
uint32_t	zxc_seekable_get_block_comp_size (const zxc_seekable *s, const uint64_t block_idx)
	Returns the compressed size of a specific block.
uint32_t	zxc_seekable_get_block_decomp_size (const zxc_seekable *s, const uint64_t block_idx)
	Returns the decompressed size of a specific block.
int64_t	zxc_seekable_decompress_range (zxc_seekable *s, void *dst, const size_t dst_capacity, const uint64_t offset, const size_t len)
	Decompresses an arbitrary byte range of the original data.
int64_t	zxc_seekable_decompress_range_mt (zxc_seekable *s, void *dst, const size_t dst_capacity, const uint64_t offset, const size_t len, int n_threads)
	Multi-threaded variant of zxc_seekable_decompress_range().
void	zxc_seekable_free (zxc_seekable *s)
	Frees a seekable handle and all associated resources.
int	zxc_seekable_set_checksum (zxc_seekable *s, int enabled)
	Turns per-block checksum verification on or off.
int	zxc_seekable_set_dict (zxc_seekable *s, const void *dict, size_t dict_size, const void *dict_huf)
	Attaches a pre-trained dictionary to a seekable handle.
int64_t	zxc_write_seek_table (uint8_t *dst, const size_t dst_capacity, const uint32_t *comp_sizes, const uint64_t num_blocks)
	Writes a seek table to the destination buffer.
size_t	zxc_seek_table_size (const uint64_t num_blocks)
	Returns the encoded size of a seek table for the given block count.

Detailed Description

Seekable compression and random-access decompression API.

Produce seekable ZXC archives, and decompress arbitrary byte ranges out of them without reading the whole file.

A seekable archive carries a Seek Table block (block_type = ZXC_BLOCK_SEK) after the EOF block: groups of 64 blocks, each its first block's offset then every block's on-disk size. Readers derive num_blocks from the footer and read a group when one of its blocks is accessed: open costs the same at any block count and no table stays in memory. A header flag announces it; plain decompressors skip it and refuse a tail that disagrees.

Seekable archives concatenated read as one: blocks and offsets run across the frames, at most 2^20 of them. Every frame must carry a table; block sizes, checksums and dictionaries may differ.

No field holds the block count, so nothing caps it but the footer's 64-bit size: counts and block indices are 64-bit here. Writing a table still costs four bytes of memory per block, which is what limits a producer today.

The table is not authenticated: a consistent forgery can point a block at another of the same size. Only checksums verified through zxc_seekable_set_checksum bind a block to its position.

This header is freestanding: only <stddef.h>, <stdint.h> and the rest of the ZXC public API, no <stdio.h>, so kernel-space and other freestanding environments can include it. The FILE*-based zxc_seekable_open_file entry point lives in zxc_stream.h.

Creating a seekable archive

zxc_compress_opts_t opts = { .level = 3, .seekable = 1 };
int64_t csize = zxc_compress(src, src_size, dst, dst_cap, &opts);

Random-access decompression (buffer-backed)

zxc_seekable* s = zxc_seekable_open(compressed, csize);
int64_t n = zxc_seekable_decompress_range(s, out, out_cap, offset, len);
zxc_seekable_free(s);

Random-access decompression (custom storage)

zxc_reader_t r = { .read_at = my_read_at, .ctx = my_state, .size = total };
zxc_seekable* s = zxc_seekable_open_reader(&r);

Definition in file zxc_seekable.h.