Buffer API

Single-shot, buffer-based compression and decompression. More...

Modules
	Block API
	Single-block compression/decompression without file framing.
	Reusable Context API
	Opaque, reusable compression / decompression contexts.

Data Structures
struct	zxc_frame_info_t
	What a frame's header and footer declare, read without decoding. More...

Functions
uint64_t	zxc_compress_bound (const size_t input_size)
	Maximum compressed size for an input of input_size bytes.
int64_t	zxc_compress (const void *src, const size_t src_size, void *dst, const size_t dst_capacity, const zxc_compress_opts_t *opts)
	Compresses a buffer into a complete ZXC archive.
int64_t	zxc_decompress (const void *src, const size_t src_size, void *dst, const size_t dst_capacity, const zxc_decompress_opts_t *opts)
	Decompresses a complete ZXC archive.
size_t	zxc_decompress_inplace_bound (const void *src, const size_t src_size)
	Buffer size required for an in-place decompression of src.
int64_t	zxc_decompress_inplace (void *buffer, const size_t buffer_capacity, const size_t comp_size, const zxc_decompress_opts_t *opts)
	Decompresses inside a single caller-owned buffer.
uint64_t	zxc_get_decompressed_size (const void *src, const size_t src_size)
	Reads the original size from the archive footers, without decoding.
uint32_t	zxc_get_dict_id (const void *src, size_t src_size)
	Reads the dictionary ID from an archive header, without decoding.
int	zxc_get_frame_info (const void *src, size_t src_size, zxc_frame_info_t *info, size_t info_size)
	Reads a frame's header and footer, without decoding.
int	zxc_get_last_frame_info (const void *src, size_t src_size, zxc_frame_info_t *info, size_t info_size)
	Reads the last frame of src, without decoding.
size_t	zxc_frame_info_size (void)
	Returns sizeof(zxc_frame_info_t) as compiled into the library.

Detailed Description

Single-shot, buffer-based compression and decompression.

Function Documentation

zxc_compress()

int64_t zxc_compress	(	const void *	src,
		const size_t	src_size,
		void *	dst,
		const size_t	dst_capacity,
		const zxc_compress_opts_t *	opts
	)

Compresses a buffer into a complete ZXC archive.

Writes the file header followed by compressed blocks. Single-threaded and blocking, so n_threads and the progress callback in opts are ignored.

Parameters

[in]	src	Source buffer; may be NULL when src_size is 0.
[in]	src_size	Source size in bytes; 0 writes the empty archive (file header + EOF block + footer).
[out]	dst	Destination buffer.
[in]	dst_capacity	Capacity of dst.
[in]	opts	Compression options, or NULL for defaults.

Note

src and dst must not overlap (same contract as memcpy).

Levels above ZXC_LEVEL_ULTRA are silently clamped to it; levels <= 0 select ZXC_LEVEL_DEFAULT.

Returns

Bytes written to dst (> 0), or a negative zxc_error_t (e.g. ZXC_ERROR_DST_TOO_SMALL).

Compresses a buffer into a complete ZXC archive.

Manages context allocation internally, loops over blocks and writes the file header / EOF block / footer.

Definition at line 643 of file zxc_dispatch.c.

References zxc_block_header_t::block_type, zxc_compress_opts_t::checksum_enabled, zxc_compress_opts_t::dict, zxc_cctx_t::dict_buffer, zxc_compress_opts_t::seekable, ZXC_BLOCK_CHECKSUM_SIZE, zxc_block_size_ceil(), ZXC_BLOCK_SIZE_DEFAULT, zxc_cctx_attach_dict_huf(), zxc_cctx_free(), zxc_cctx_init(), zxc_compress_chunk_wrapper(), zxc_dict_id(), ZXC_DICT_SIZE_MAX, zxc_digest_combine(), ZXC_ERROR_BAD_BLOCK_SIZE, ZXC_ERROR_CORRUPT_DATA, ZXC_ERROR_DICT_TOO_LARGE, ZXC_ERROR_MEMORY, ZXC_ERROR_NULL_INPUT, ZXC_FREE, zxc_le32(), ZXC_LEVEL_DEFAULT, ZXC_MALLOC, ZXC_OK, ZXC_OPTS_BLOCK_SIZE, ZXC_OPTS_DICT_HUF, ZXC_OPTS_DICT_SIZE, ZXC_OPTS_LEVEL, zxc_validate_block_size(), zxc_write_block_header(), zxc_write_empty_frame(), zxc_write_file_footer(), zxc_write_file_header(), and zxc_write_seek_table().

zxc_compress_bound()

uint64_t zxc_compress_bound

(

const size_t

input_size

)

Maximum compressed size for an input of input_size bytes.

Covers the file header, block headers, and worst-case expansion of incompressible data. Use it to size the destination buffer.

Parameters

[in]

input_size

Input size in bytes.

Returns

Required destination capacity in bytes.

Maximum compressed size for an input of input_size bytes.

The result accounts for the file header, per-block headers, block checksums, worst-case expansion, EOF block, seekable overhead (SEK block), and the file footer.

The block count is derived from ZXC_BLOCK_SIZE_MIN (4 KB) to guarantee the bound holds for all valid block sizes and seekable mode.

Definition at line 1029 of file zxc_common.c.

References ZXC_BLOCK_CHECKSUM_SIZE, ZXC_BLOCK_FORMAT_OVERHEAD, ZXC_BLOCK_HEADER_SIZE, ZXC_BLOCK_SIZE_MIN, ZXC_FILE_HEADER_SIZE, ZXC_FOOTER_MAX_SIZE_WITH_DIGEST, and zxc_seek_table_bytes().

Referenced by zxc_stream_engine_start(), and zxc_train_dict_huf().

zxc_decompress()

int64_t zxc_decompress	(	const void *	src,
		const size_t	src_size,
		void *	dst,
		const size_t	dst_capacity,
		const zxc_decompress_opts_t *	opts
	)

Decompresses a complete ZXC archive.

Expects a valid file header followed by compressed blocks. Single-threaded and blocking, so n_threads and the progress callback in opts are ignored.

Concatenated frames

src may hold several frames back to back; they decode in order into dst. Anything else after a frame is ZXC_ERROR_CORRUPT_DATA.

Asking without a destination

A NULL dst, or a dst_capacity of 0, decodes nothing and reports what the archive holds: 0 for a well-formed empty one, ZXC_ERROR_DST_TOO_SMALL when it stores a payload, its own error otherwise. Success is never handed out early: a 0 here means a call with a destination would have returned 0 too, checksum and dictionary binding included. Not the reverse, since nothing is decoded: an archive that stores a payload reports ZXC_ERROR_DST_TOO_SMALL even where a decode would name the actual fault. Caller errors outrank all of it, before anything is read from src, a source too short to hold a frame included: a NULL dst with a non-zero dst_capacity is ZXC_ERROR_NULL_INPUT, and a dict_size the library cannot honour is ZXC_ERROR_DICT_TOO_LARGE.

Parameters

[in]	src	Compressed buffer.
[in]	src_size	Compressed size in bytes.
[out]	dst	Destination buffer, or NULL to probe (see above).
[in]	dst_capacity	Capacity of dst.
[in]	opts	Decompression options, or NULL for defaults.

Note

src and dst must not overlap (same contract as memcpy).

Returns

Bytes written to dst, 0 for an empty archive, or a negative zxc_error_t (e.g. ZXC_ERROR_CORRUPT_DATA).

Decompresses a complete ZXC archive.

Validates the file header, loops over compressed blocks and checks the footer size.

Definition at line 843 of file zxc_dispatch.c.

References ZXC_DICT_SIZE_MAX, ZXC_ERROR_DICT_TOO_LARGE, ZXC_ERROR_NULL_INPUT, ZXC_FRAME_MIN_SIZE, ZXC_OPTS_DICT_SIZE, zxc_probe_without_dst(), and zxc_short_input_verdict().

zxc_decompress_inplace()

int64_t zxc_decompress_inplace	(	void *	buffer,
		const size_t	buffer_capacity,
		const size_t	comp_size,
		const zxc_decompress_opts_t *	opts
	)

Decompresses inside a single caller-owned buffer.

The archive must sit flush-right in buffer (its last comp_size bytes). Decoding runs left-to-right from buffer[0]; as long as buffer_capacity is at least zxc_decompress_inplace_bound, the write cursor provably never overtakes the read cursor; an archive whose output would reach unread input (padding, forged block sizes) is refused with ZXC_ERROR_CORRUPT_DATA first. One allocation instead of two, which is what makes this worthwhile on memory-constrained targets (embedded, FOTA, firmware).

Note

The decode context is heap-allocated for the call; to supply your own, see zxc_decompress_inplace_dctx().

buffer is both input and output: on success its first N bytes hold the decompressed data (N = the return value).

Parameters

[in,out]	buffer	Work buffer holding the flush-right archive.
[in]	buffer_capacity	Total size of buffer in bytes.
[in]	comp_size	Size of the compressed archive in bytes.
[in]	opts	Decompression options, or NULL for defaults.

Returns

Decompressed size (> 0), 0 for an empty frame, or a negative zxc_error_t (ZXC_ERROR_DST_TOO_SMALL if the margin is missing).

Decompresses inside a single caller-owned buffer.

Public API; full contract in zxc_buffer.h. Same walk as zxc_decompress_inplace_dctx, on a context created for the call once the buffer checks have passed.

Definition at line 1013 of file zxc_dispatch.c.

References zxc_create_dctx(), zxc_dctx_decode_frame(), ZXC_ERROR_MEMORY, zxc_free_dctx(), zxc_inplace_prepare(), and ZXC_OK.

zxc_decompress_inplace_bound()

size_t zxc_decompress_inplace_bound	(	const void *	src,
		const size_t	src_size
	)

Buffer size required for an in-place decompression of src.

Reads src's header and footer only (no decoding) and returns decompressed_size plus the one-block and wild-copy safety margin zxc_decompress_inplace needs. Allocate that much, place the comp_size-byte archive flush-right in it, then decode.

Parameters

[in]	src	Compressed archive (only header + footer are read).
[in]	src_size	Archive size in bytes.

Returns

Required buffer size in bytes, or 0 if src is not a valid archive.

Buffer size required for an in-place decompression of src.

Reads the archive header (block size) and footer (decompressed size) without decoding, and returns decompressed_size + zxc_inplace_margin(...) (one block + accumulated per-block overhead + footer + wild-copy tail). A buffer of at least this size lets zxc_decompress_inplace decode with the compressed data placed flush-right, the write cursor never overtaking the read cursor.

Because src_size is attacker-controlled, inserted padding bytes can slide decoding dangerously close to the output boundary. The src_size + floor term keeps block 0 clear; the walk checks every later block. For authentic archives, this adjustment grows the bound by at most 16 bytes and guarantees it never shrinks.

Definition at line 954 of file zxc_dispatch.c.

References ZXC_FRAME_MIN_SIZE, zxc_inplace_probe(), and ZXC_OK.

zxc_frame_info_size()

size_t zxc_frame_info_size

(

void

)

Returns sizeof(zxc_frame_info_t) as compiled into the library.

See also

zxc_compress_opts_size

Returns sizeof(zxc_frame_info_t) as compiled into the library.

Public API; see zxc_buffer.h.

Definition at line 51 of file zxc_common.c.

zxc_get_decompressed_size()

uint64_t zxc_get_decompressed_size	(	const void *	src,
		const size_t	src_size
	)

Reads the original size from the archive footers, without decoding.

Sums the sizes the footers store, walking the frames back from the end. Each frame is checked like zxc_get_frame_info(), its size against what its bytes can hold: a forged footer returns 0 rather than drive an oversized allocation.

Parameters

[in]	src	Compressed buffer.
[in]	src_size	Compressed size in bytes.

Returns

Original uncompressed size in bytes, or 0 if the buffer is invalid, too small, or carries an implausible footer value.

Reads the original size from the archive footers, without decoding.

Sums the footers through zxc_scan_container(), which checks each frame: a container that does not hold up returns 0.

Definition at line 1032 of file zxc_dispatch.c.

References zxc_container_info_t::dsize, ZXC_OK, zxc_scan_container(), and zxc_scan_src_mem().

zxc_get_dict_id()

uint32_t zxc_get_dict_id	(	const void *	src,
		const size_t	src_size
	)

Reads the dictionary ID from an archive header, without decoding.

Parameters

[in]	src	Compressed buffer.
[in]	src_size	Compressed size in bytes.

Returns

Dictionary ID, or 0 if no dictionary is required or the buffer is invalid.

Reads the dictionary ID from an archive header, without decoding.

Public API; see zxc_buffer.h. Validates the magic, then returns the header's dict_id field when the dictionary flag is set. Does not decompress.

Definition at line 1047 of file zxc_dispatch.c.

References ZXC_FILE_FLAG_HAS_DICTIONARY, ZXC_FILE_HEADER_SIZE, zxc_le32(), and ZXC_MAGIC_WORD.

zxc_get_frame_info()

int zxc_get_frame_info	(	const void *	src,
		const size_t	src_size,
		zxc_frame_info_t *	info,
		const size_t	info_size
	)

Reads a frame's header and footer, without decoding.

Validates the header as a decoder would, parses the footer back from the end of src, and checks that the frame spans all of src and that its stored size is reachable. The blocks are not read, so a frame that passes may still fail to decode.

Parameters

[in]	src	Compressed buffer.
[in]	src_size	Compressed size in bytes.
[out]	info	Filled on success, untouched otherwise.
[in]	info_size	sizeof(*info) as the caller compiled it.

Returns

ZXC_OK, or a negative zxc_error_t (e.g. ZXC_ERROR_BAD_MAGIC, ZXC_ERROR_CORRUPT_DATA).

Public API; see zxc_buffer.h.

Definition at line 1062 of file zxc_dispatch.c.

References zxc_buffer_frame_info(), ZXC_ERROR_NULL_INPUT, zxc_frame_info_copy(), and ZXC_OK.

zxc_get_last_frame_info()

int zxc_get_last_frame_info	(	const void *	src,
		const size_t	src_size,
		zxc_frame_info_t *	info,
		const size_t	info_size
	)

Reads the last frame of src, without decoding.

Same checks as zxc_get_frame_info(), but the frame starts at src_size - info->compressed_size, so concatenated frames walk back:

size_t n = src_size;
while (n > 0) {
    if (zxc_get_last_frame_info(src, n, &info, sizeof(info)) != ZXC_OK) break;
    n -= info.compressed_size;  // the frame before ends here
}

Parameters

[in]	src	Compressed buffer.
[in]	src_size	Bytes of src the frame ends.
[out]	info	Filled on success, untouched otherwise.
[in]	info_size	sizeof(*info) as the caller compiled it.

Returns

ZXC_OK, or a negative zxc_error_t.

Reads the last frame of src, without decoding.

Public API; see zxc_buffer.h.

Definition at line 1077 of file zxc_dispatch.c.

References ZXC_ERROR_NULL_INPUT, zxc_frame_info_copy(), ZXC_OK, zxc_scan_frame(), and zxc_scan_src_mem().