Caller-driven, single-threaded streaming compression and decompression. More...

Data Structures
struct	zxc_inbuf_t
	Input buffer descriptor for push streaming. More...

struct	zxc_outbuf_t
	Output buffer descriptor for push streaming. More...

Typedefs
typedef struct zxc_cstream_s	zxc_cstream
	Opaque push-model compression stream (see zxc_cstream_create).

typedef struct zxc_dstream_s	zxc_dstream
	Opaque push-model decompression stream (see zxc_dstream_create).

Functions
zxc_cstream *	zxc_cstream_create (const zxc_compress_opts_t *opts)
	Creates a push compression stream.

void	zxc_cstream_free (zxc_cstream *cs)
	Releases a compression stream and all internal buffers.

int64_t	zxc_cstream_compress (zxc_cstream cs, zxc_outbuf_t out, zxc_inbuf_t *in)
	Pushes input bytes into the stream and drains compressed output.

int64_t	zxc_cstream_end (zxc_cstream cs, zxc_outbuf_t out)
	Finalises the stream: flushes pending data, writes EOF block + footer.

size_t	zxc_cstream_in_size (const zxc_cstream *cs)
	Suggested input chunk size for best throughput.

size_t	zxc_cstream_out_size (const zxc_cstream *cs)
	Suggested output chunk size that never triggers a partial drain.

zxc_dstream *	zxc_dstream_create (const zxc_decompress_opts_t *opts)
	Creates a push decompression stream.

void	zxc_dstream_free (zxc_dstream *ds)
	Releases a decompression stream.

int64_t	zxc_dstream_decompress (zxc_dstream ds, zxc_outbuf_t out, zxc_inbuf_t *in)
	Pushes compressed input and drains decompressed output.

int	zxc_dstream_finished (const zxc_dstream *ds)
	Reports whether the decoder has fully consumed a valid stream.

size_t	zxc_dstream_in_size (const zxc_dstream *ds)
	Suggested input chunk size for the decompressor.

size_t	zxc_dstream_out_size (const zxc_dstream *ds)
	Suggested output chunk size for the decompressor.

Detailed Description

Caller-driven, single-threaded streaming compression and decompression.

Typedef Documentation

◆ zxc_cstream

typedef struct zxc_cstream_s zxc_cstream

Opaque push-model compression stream (see zxc_cstream_create).

Definition at line 108 of file zxc_pstream.h.

◆ zxc_dstream

typedef struct zxc_dstream_s zxc_dstream

Opaque push-model decompression stream (see zxc_dstream_create).

Definition at line 110 of file zxc_pstream.h.

Function Documentation

◆ zxc_cstream_compress()

int64_t zxc_cstream_compress	(	zxc_cstream *	cs,
		zxc_outbuf_t *	out,
		zxc_inbuf_t *	in
	)

Pushes input bytes into the stream and drains compressed output.

Reads from in->src at in->pos, writes to out->dst at out->pos, advancing both as data flows. Each call goes as far as the two buffers allow:

emits the file header on the first invocation (16 B);
copies input into the internal block accumulator;
compresses one block into out whenever the accumulator fills;
returns once in is fully consumed and nothing is pending, or as soon as out has no room left.

Fully reentrant: if out fills mid-block, the next call picks up where this one stopped. Calling with in->size == in->pos drains only.

Errors: Errors are sticky: once one is returned, zxc_cstream_compress and zxc_cstream_end keep returning the same code and do no further work. Only zxc_cstream_free is safe from there.

Parameters

[in,out]	cs	Compression stream.
[in,out]	out	Output descriptor; `pos` is advanced by produced bytes.
[in,out]	in	Input descriptor; `pos` is advanced by consumed bytes.

Returns: 0 in fully consumed and nothing pending in staging; >0 bytes still pending, drain out and call again with the same (or new) input; <0 a zxc_error_t code.

Pushes input bytes into the stream and drains compressed output.

Drives the cstream_state_t machine: emits the file header on the first call, then accumulates input until a block is full, compresses it, and drains the result into out. Each call makes as much progress as either buffer allows; the function is fully reentrant. See the public contract in zxc_cstream_compress for full semantics.

The terminal states (CS_DRAIN_LAST, CS_DRAIN_EOF, CS_DRAIN_FOOTER, CS_DONE, CS_ERRORED) are owned by zxc_cstream_end; reaching them here yields ZXC_ERROR_NULL_INPUT.

Definition at line 425 of file zxc_pstream.c.

References CS_ACCUMULATE, cs_compress_block_from(), cs_compress_one_block(), CS_DONE, CS_DRAIN_BLOCK, CS_DRAIN_EOF, CS_DRAIN_FOOTER, CS_DRAIN_HEADER, CS_DRAIN_LAST, cs_drain_pending(), CS_ERRORED, CS_INIT, cs_set_error(), cs_stage_file_header(), zxc_outbuf_t::dst, zxc_inbuf_t::pos, zxc_outbuf_t::pos, zxc_inbuf_t::size, zxc_outbuf_t::size, zxc_inbuf_t::src, and ZXC_ERROR_NULL_INPUT.

◆ zxc_cstream_create()

zxc_cstream * zxc_cstream_create ( const zxc_compress_opts_t * opts )

Creates a push compression stream.

opts is copied into the context and may be freed or reused afterwards.

Only level, block_size and checksum_enabled are honoured, and they must be valid (an unsupported block_size fails creation); levels above ZXC_LEVEL_ULTRA are clamped. n_threads is ignored, this API being single-threaded, see zxc_stream_compress for the multi-threaded FILE* pipeline. Dictionary options are rejected outright: push streams take no dictionary yet (support can be added if a need arises), so dict / dict_size / dict_huf fail creation rather than being silently dropped.

Parameters

[in] opts Compression options, or NULL for all defaults.

Returns: Context to release with zxc_cstream_free, or NULL on allocation failure or invalid options.

Creates a push compression stream.

Copies opts into the new context, applying defaults for any zero-valued field (level -> ZXC_LEVEL_DEFAULT, block_size -> ZXC_BLOCK_SIZE_DEFAULT; levels above ZXC_LEVEL_ULTRA are clamped). Forces single-threaded operation (n_threads = 0) and disables progress callbacks and seekable framing (those modes belong to the FILE*-based pipeline). Dictionary options are REJECTED (the push-stream format carries no dict_id, so a dictionary would produce undecodable archives): passing any of dict / dict_size / dict_huf returns NULL rather than silently dropping them. Pre-sizes the pending buffer so that the file header / footer paths never need a realloc.

Definition at line 266 of file zxc_pstream.c.

References CS_INIT, ZXC_BLOCK_SIZE_DEFAULT, ZXC_CALLOC, zxc_create_cctx(), ZXC_FILE_HEADER_SIZE, ZXC_FOOTER_MAX_SIZE_WITH_DIGEST, ZXC_FREE, zxc_free_cctx(), ZXC_LEVEL_DEFAULT, ZXC_MALLOC, ZXC_OPTS_BLOCK_SIZE, and ZXC_OPTS_LEVEL.

◆ zxc_cstream_end()

int64_t zxc_cstream_end	(	zxc_cstream *	cs,
		zxc_outbuf_t *	out
	)

Finalises the stream: flushes pending data, writes EOF block + footer.

Required after the last zxc_cstream_compress call to end up with a valid ZXC file. Reentrant like it: if out fills first, it returns a positive count and the caller drains and calls again.

Once it returns 0 the stream is DONE and any further call returns ZXC_ERROR_NULL_INPUT; release it with zxc_cstream_free.

Parameters

[in,out]	cs	Compression stream.
[in,out]	out	Output descriptor.

Returns: 0 finalised, the file is now valid; >0 bytes still pending, drain out and call again; <0 a zxc_error_t code.

Finalises the stream: flushes pending data, writes EOF block + footer.

Continues the same state machine as zxc_cstream_compress through the terminal states (CS_DRAIN_LAST -> CS_DRAIN_EOF -> CS_DRAIN_FOOTER -> CS_DONE). Reentrant: when out fills mid-drain, returns the number of bytes still pending and resumes from where it left off on the next call. See the public contract in zxc_cstream_end.

Definition at line 498 of file zxc_pstream.c.

References CS_ACCUMULATE, cs_compress_one_block(), CS_DONE, CS_DRAIN_BLOCK, CS_DRAIN_EOF, CS_DRAIN_FOOTER, CS_DRAIN_HEADER, CS_DRAIN_LAST, cs_drain_pending(), CS_ERRORED, CS_INIT, cs_set_error(), cs_stage_eof(), cs_stage_file_header(), cs_stage_footer(), and ZXC_ERROR_NULL_INPUT.

◆ zxc_cstream_free()

void zxc_cstream_free ( zxc_cstream * cs )

Releases a compression stream and all internal buffers.

Safe to call with NULL (no-op).

Parameters

[in] cs Stream returned by zxc_cstream_create.

Definition at line 386 of file zxc_pstream.c.

References ZXC_FREE, and zxc_free_cctx().

◆ zxc_cstream_in_size()

size_t zxc_cstream_in_size ( const zxc_cstream * cs )

Suggested input chunk size for best throughput.

The configured block size (512 KB by default).

Parameters

[in] cs Compression stream.

Returns: Suggested in_buf capacity in bytes, or 0 if cs is NULL.

Suggested input chunk size for best throughput.

Definition at line 397 of file zxc_pstream.c.

◆ zxc_cstream_out_size()

size_t zxc_cstream_out_size ( const zxc_cstream * cs )

Suggested output chunk size that never triggers a partial drain.

Holds one full compressed block plus framing overhead. Smaller outputs work, at the cost of an extra drain loop.

Parameters

[in] cs Compression stream.

Returns: Suggested out_buf capacity in bytes, or 0 if cs is NULL.

Suggested output chunk size that never triggers a partial drain.

Sized to hold one full compressed block plus framing overhead, i.e. zxc_compress_block_bound applied to the configured block size. Falls back to block_size when the bound overflows size_t.

Definition at line 406 of file zxc_pstream.c.

References zxc_compress_block_bound().

◆ zxc_dstream_create()

zxc_dstream * zxc_dstream_create ( const zxc_decompress_opts_t * opts )

Creates a push decompression stream.

opts is copied into the context. Only checksum_enabled is honoured: it decides whether the block checksums and archive digest are verified when present. Push streams take no dictionary yet (support can be added if a need arises): dict / dict_size / dict_huf fail creation, and an archive whose header requires one fails with ZXC_ERROR_DICT_REQUIRED at the first decompress call.

Parameters

[in] opts Decompression options, or NULL for defaults.

Returns: Context to release with zxc_dstream_free, or NULL on allocation failure or dictionary options in opts.

Creates a push decompression stream.

Copies opts into the new context. The internal multi-threading, progress-callback, and seekable knobs are forced off (those modes belong to the FILE*-based pipeline). block_size, file_has_checksum, and the payload / decoded buffers are filled in lazily once the file header is parsed.

Definition at line 798 of file zxc_pstream.c.

References ds_start_frame(), ZXC_CALLOC, and ZXC_FREE.

◆ zxc_dstream_decompress()

int64_t zxc_dstream_decompress	(	zxc_dstream *	ds,
		zxc_outbuf_t *	out,
		zxc_inbuf_t *	in
	)

Pushes compressed input and drains decompressed output.

Drives a parser state machine: file header -> per-block (header + payload + optional checksum) -> EOF block -> optional SEK block -> file footer. Each call goes as far as in and out allow.

End of stream: Validating a frame's footer puts the stream in DONE state and ends the call, in->pos just past the frame: a caller after one frame stops there. A later call with input decodes the next frame (archives concatenated) into the same output. Input that does not open with the magic word is ZXC_ERROR_CORRUPT_DATA, from its first byte; a frame that does is checked like the first, so a bad header gets its own code.

Errors: Sticky: once a negative code comes back, every later call returns it too.

Parameters

[in,out]	ds	Decompression stream.
[in,out]	out	Output descriptor; `pos` advanced by produced bytes.
[in,out]	in	Input descriptor; `pos` advanced by consumed bytes.

Returns: >0 decompressed bytes written into out by this call; 0 stream complete (DONE), or no progress possible and more input is needed; <0 a zxc_error_t code.

Pushes compressed input and drains decompressed output.

Drives the dstream_state_t machine: file header, then per-block (header + payload + optional checksum) -> decode -> emit, repeated until the EOF block, optional SEK index block, and file footer have been parsed and validated. Each call makes as much progress as in and out allow; the function is fully reentrant. See the public contract in zxc_dstream_decompress for full semantics.

End of stream: Once DS_VALIDATE_FOOTER succeeds, the stream is in DS_DONE and the call returns, in->pos just past the frame. A later call with input starts the next frame; without, it returns 0.

Errors: On any negative return the stream becomes errored (sticky); subsequent calls keep returning the same code until zxc_dstream_free.

Definition at line 1010 of file zxc_pstream.c.

References DS_DECODE_BLOCK, DS_DONE, ds_drain_decoded(), DS_DRAIN_SEK_PAYLOAD, DS_EMIT_DECODED, DS_ERRORED, ds_handle_need_block_header(), ds_handle_need_file_header(), DS_NEED_BLOCK_HEADER, DS_NEED_BLOCK_PAYLOAD, DS_NEED_FILE_HEADER, DS_NEED_FOOTER, DS_NEED_SEK_HEADER, ds_pull(), ds_set_error(), ds_start_frame(), DS_VALIDATE_FOOTER, zxc_outbuf_t::dst, zxc_footer_layout_t::len, zxc_inbuf_t::pos, zxc_outbuf_t::pos, zxc_inbuf_t::size, zxc_outbuf_t::size, zxc_inbuf_t::src, ZXC_BLOCK_CHECKSUM_SIZE, ZXC_BLOCK_HEADER_SIZE, zxc_check_file_footer(), zxc_check_seek_header(), zxc_decompress_chunk_wrapper(), zxc_digest_combine(), ZXC_ERROR_BAD_CHECKSUM, ZXC_ERROR_CORRUPT_DATA, ZXC_ERROR_NULL_INPUT, zxc_footer_layout(), zxc_le32(), and zxc_le64().

◆ zxc_dstream_finished()

int zxc_dstream_finished ( const zxc_dstream * ds )

Reports whether the decoder has fully consumed a valid stream.

True when the last call ended on a validated footer, until a call with more input starts the next frame. That is how a caller done feeding input detects truncation: if zxc_dstream_decompress returns 0 with no output and this returns 0, the input ended early.

Parameters

[in] ds Decompression stream.

Returns: 1 if DONE, 0 otherwise (including errored).

Reports whether the decoder has fully consumed a valid stream.

Definition at line 827 of file zxc_pstream.c.

References DS_DONE.

◆ zxc_dstream_free()

void zxc_dstream_free ( zxc_dstream * ds )

Releases a decompression stream.

Safe to call with NULL.

Parameters

[in] ds Stream returned by zxc_dstream_create.

Releases a decompression stream.

Safe to call with NULL.

Definition at line 818 of file zxc_pstream.c.

References ds_free_buffers(), and ZXC_FREE.

◆ zxc_dstream_in_size()

size_t zxc_dstream_in_size ( const zxc_dstream * ds )

Suggested input chunk size for the decompressor.

Parameters

[in] ds Decompression stream.

Returns: Suggested in_buf capacity in bytes, or 0 if ds is NULL.

Suggested input chunk size for the decompressor.

Before the file header is parsed the call returns ZXC_BLOCK_SIZE_DEFAULT; afterwards it returns the maximal compressed block size derived from the negotiated block_size.

Definition at line 836 of file zxc_pstream.c.

References ZXC_BLOCK_SIZE_DEFAULT, and zxc_compress_block_bound().

◆ zxc_dstream_out_size()

size_t zxc_dstream_out_size ( const zxc_dstream * ds )

Suggested output chunk size for the decompressor.

Sized to hold at least one full decompressed block.

Parameters

[in] ds Decompression stream.

Returns: Suggested out_buf capacity in bytes, or 0 if ds is NULL.

Suggested output chunk size for the decompressor.

Equals the negotiated block_size; before the file header is parsed, returns ZXC_BLOCK_SIZE_DEFAULT.

Definition at line 849 of file zxc_pstream.c.

References ZXC_BLOCK_SIZE_DEFAULT.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ zxc_cstream

◆ zxc_dstream

Function Documentation

◆ zxc_cstream_compress()

◆ zxc_cstream_create()

◆ zxc_cstream_end()

◆ zxc_cstream_free()

◆ zxc_cstream_in_size()

◆ zxc_cstream_out_size()

◆ zxc_dstream_create()

◆ zxc_dstream_decompress()

◆ zxc_dstream_finished()

◆ zxc_dstream_free()

◆ zxc_dstream_in_size()

◆ zxc_dstream_out_size()