Expand description
§zxc-compress-sys
Low-level, unsafe FFI bindings to the ZXC
compression library. The C sources are vendored and built by the crate’s build
script; enable the system feature to link against an installed libzxc instead.
Most users want the safe wrapper, zxc-compress
(documentation).
§License
BSD-3-Clause - see LICENSE for details.
Structs§
- zxc_
cctx - Opaque compression context. Use
zxc_create_cctxto create. - zxc_
cstream - Opaque push compression stream. Use
zxc_cstream_createto create. - zxc_
dctx - Opaque decompression context. Use
zxc_create_dctxto create. - zxc_
dstream - Opaque push decompression stream. Use
zxc_dstream_createto create. - zxc_
frame_ info_ t - What a frame’s header and footer declare (mirrors
zxc_frame_info_t). - zxc_
inbuf_ t - Input buffer descriptor for push streaming
(mirrors
zxc_inbuf_tfromzxc_pstream.h). - zxc_
outbuf_ t - Output buffer descriptor for push streaming
(mirrors
zxc_outbuf_tfromzxc_pstream.h). - zxc_
reader_ t - Storage-agnostic reader interface for seekable archives (mirrors
zxc_reader_tfromzxc_seekable.h). - zxc_
seekable - Opaque handle for a seekable ZXC archive.
Constants§
- ZXC_
C_ BLOCK_ SIZE - Block size in bytes, a power of two in 4 KB..2 MB; default 512 KB.
- ZXC_
C_ CHECKSUM - 1 appends the block checksums and the archive digest; default 0.
- ZXC_
C_ LEVEL - Compression level, 1 to 7; default
ZXC_LEVEL_DEFAULT. - ZXC_
C_ SEEKABLE - 1 appends a seek table for random-access decompression; default 0.
- ZXC_
C_ THREADS - Worker threads for the
FILE*pipeline, at mostZXC_MAX_THREADS; default 0, auto-detect. The buffer, block and push APIs ignore it. - ZXC_
DICT_ HEADER_ SIZE - Fixed size of the
.zxdfile header in bytes. - ZXC_
DICT_ SIZE_ MAX - Maximum dictionary content size in bytes (65535).
- ZXC_
D_ CHECKSUM - 1 verifies the block checksums and the archive digest when the archive carries them; default 0, no verification.
- ZXC_
D_ THREADS - Worker threads for the
FILE*pipeline, at mostZXC_MAX_THREADS; default 0, auto-detect. - ZXC_
ERROR_ BAD_ BLOCK_ SIZE - Invalid block size
- ZXC_
ERROR_ BAD_ BLOCK_ TYPE - Unknown or unexpected block type
- ZXC_
ERROR_ BAD_ CHECKSUM - A block’s decoded bytes fail its checksum, or the archive digest mismatches
- ZXC_
ERROR_ BAD_ HEADER - Corrupted or invalid header (checksum mismatch)
- ZXC_
ERROR_ BAD_ LEVEL - Compression level out of range, or not supported by this context’s workspace
- ZXC_
ERROR_ BAD_ MAGIC - Invalid magic word in file header
- ZXC_
ERROR_ BAD_ OFFSET - Invalid match offset during decompression
- ZXC_
ERROR_ BAD_ PARAM - Unknown parameter, or value out of its bounds (
zxc_cctx_set_param,zxc_dctx_set_param) - ZXC_
ERROR_ BAD_ VERSION - Unsupported file format version
- ZXC_
ERROR_ CORRUPT_ DATA - Corrupted compressed data
- ZXC_
ERROR_ DICT_ MISMATCH - Provided dictionary ID does not match the file header
- ZXC_
ERROR_ DICT_ REQUIRED - File requires a dictionary but none was provided
- ZXC_
ERROR_ DICT_ TOO_ LARGE - Dictionary exceeds maximum allowed size
- ZXC_
ERROR_ DICT_ UNSUPPORTED - Dictionary not supported by this context’s workspace (static contexts)
- ZXC_
ERROR_ DST_ TOO_ SMALL - Destination buffer too small
- ZXC_
ERROR_ IO - Read/write/seek failure on file
- ZXC_
ERROR_ MEMORY - Memory allocation failure
- ZXC_
ERROR_ NULL_ INPUT - Required input pointer is NULL
- ZXC_
ERROR_ OVERFLOW - Buffer overflow detected during processing
- ZXC_
ERROR_ SRC_ TOO_ SMALL - Source buffer too small or truncated input
- ZXC_
HUF_ TABLE_ SIZE - Size in bytes of the shared literal Huffman table carried by a
.zxdfile (packed 4-bit code lengths for 256 symbols). - ZXC_
LEVEL_ BALANCED - Good ratio, good decode speed
- ZXC_
LEVEL_ COMPACT - High density. Best for storage/firmware/assets.
- ZXC_
LEVEL_ DEFAULT - Recommended: ratio > LZ4, decode speed > LZ4
- ZXC_
LEVEL_ DENSITY - High density: Huffman-coded literals on top of COMPACT, price-based optimal LZ77 parser.
- ZXC_
LEVEL_ FAST - Fast compression, good for real-time applications
- ZXC_
LEVEL_ FASTEST - Fastest compression, best for real-time applications
- ZXC_
LEVEL_ ULTRA - Maximum density: Huffman-coded literals and sequence tokens, deep parse. Slowest compression, best ratio (level 7 / ULTRA).
- ZXC_
MAX_ THREADS - Maximum worker thread count accepted by
ZXC_C_THREADS/ZXC_D_THREADS. - ZXC_OK
- Success (no error)
- ZXC_
VERSION_ MAJOR - ZXC_
VERSION_ MINOR - ZXC_
VERSION_ PATCH
Functions§
- zxc_
cctx_ ⚠get_ param - Reads one parameter of
cctxinto*value. - zxc_
cctx_ ⚠reset - Restores every parameter to its default, detaches the dictionary and the callback. The working buffers are kept. On a static context the pinned block size and level are the defaults.
- zxc_
cctx_ ⚠set_ dict - Attaches a pre-trained dictionary to
cctx; a NULLdictdetaches. - zxc_
cctx_ ⚠set_ param - Sets one parameter on
cctx; 0 restores its default. - zxc_
cctx_ ⚠set_ progress - Sets the progress callback;
Nonedisables it. Honoured byzxc_stream_compressonly. - zxc_
compress ⚠ - Compresses a data buffer into a complete ZXC archive, at
level. - zxc_
compress_ ⚠block - Compresses a single block without file framing, with the parameters
in force on
cctx(level, checksum, dictionary). - zxc_
compress_ ⚠block_ bound - Returns the maximum compressed size for a single block (no file framing).
- zxc_
compress_ ⚠bound - Calculates the maximum compressed size for a given input.
- zxc_
compress_ ⚠cctx - Compresses a full file-framed buffer using a reusable context, with the parameters in force on it (level, block size, checksum, seek table, dictionary).
- zxc_
cparam_ ⚠bounds - Reports the accepted range of a compression parameter.
- zxc_
create_ ⚠cctx - Creates a heap-allocated compression context, every parameter at its default (level 3, 512 KB blocks, no checksum, no seek table).
- zxc_
create_ ⚠dctx - Creates a heap-allocated decompression context, every parameter at its default (no checksum verification, no dictionary).
- zxc_
cstream_ ⚠compress - Pushes input bytes into the stream and drains compressed output.
- zxc_
cstream_ ⚠create - Creates a push compression stream.
- zxc_
cstream_ ⚠end - Finalises the stream: flushes pending data, writes EOF block + footer.
- zxc_
cstream_ ⚠free - Releases a push compression stream. Safe to call with null.
- zxc_
cstream_ ⚠in_ size - Suggested input chunk size for best compressor throughput.
- zxc_
cstream_ ⚠out_ size - Suggested output chunk size for the compressor.
- zxc_
dctx_ ⚠get_ param - Reads one parameter of
dctxinto*value. Seezxc_cctx_get_param. - zxc_
dctx_ ⚠reset - Restores every parameter to its default, detaches the dictionary and the callback. The working buffers are kept.
- zxc_
dctx_ ⚠set_ dict - Attaches the dictionary the archives were compressed with; NULL
detaches. Same ownership rules as
zxc_cctx_set_dict; the header’s dict_id is checked against the (dict, table) pair at decode time. - zxc_
dctx_ ⚠set_ param - Sets one parameter on
dctx; 0 restores its default. - zxc_
dctx_ ⚠set_ progress - Sets the progress callback;
Nonedisables it. Honoured byzxc_stream_decompressonly. - zxc_
decompress ⚠ - Decompresses a complete ZXC archive.
- zxc_
decompress_ ⚠block - Decompresses a single block produced by
zxc_compress_block, with the parameters in force ondctx(checksum, dictionary). - zxc_
decompress_ ⚠block_ bound - Returns the minimum
dst_capacityrequired byzxc_decompress_blockfor a block ofuncompressed_sizebytes. Accounts for the wild-copy tail pad used by the fast decoder. - zxc_
decompress_ ⚠block_ safe - Strict-sized variant of
zxc_decompress_block: acceptsdst_capacity == uncompressed_sizeexactly (no tail pad required). Slightly slower than the fast path; output is bit-identical. - zxc_
decompress_ ⚠dctx - Decompresses a full file-framed buffer using a reusable context, with the parameters in force on it (checksum, dictionary).
- zxc_
decompress_ ⚠inplace - Decompresses in place inside a single caller-owned buffer.
- zxc_
decompress_ ⚠inplace_ bound - Returns the minimum single-buffer size for an in-place decompression.
- zxc_
decompress_ ⚠inplace_ dctx - In-place decompression with a caller-supplied context.
- zxc_
default_ ⚠level - Returns the default compression level (currently 3).
- zxc_
dict_ ⚠compute_ id - Computes the dictionary ID: content-only when
huf_lengthsis null, else binding the (content, table) pair. - zxc_
dict_ ⚠huf - Returns a pointer to the 128-byte shared Huffman table inside a
.zxdbuffer (zero-copy; aims intobuf), or NULL ifbufis not a valid.zxdfile. - zxc_
dict_ ⚠load - Loads and validates a
.zxddictionary file from a memory buffer. - zxc_
dict_ ⚠read_ id - Returns the dictionary ID stored in a
.zxdfile buffer. - zxc_
dict_ ⚠save - Serializes dictionary content plus its shared Huffman table to the
.zxdfile format. The table is mandatory. - zxc_
dict_ ⚠save_ bound - Returns the
.zxdfile size for a given content size (= 16 +content_size+ 128 for the shared Huffman table). - zxc_
dict_ ⚠train - One-call dictionary creation: trains content + shared table and
serializes to ready-to-write
.zxdbytes inzxd_buf. - zxc_
dict_ ⚠train_ content - Trains a dictionary from a corpus of samples.
- zxc_
dict_ ⚠train_ huf - Trains the shared literal Huffman table for an already-trained dictionary.
- zxc_
dparam_ ⚠bounds - Reports the accepted range of a decompression parameter. See
zxc_cparam_bounds. - zxc_
dstream_ ⚠create - Creates a push decompression stream.
- zxc_
dstream_ ⚠decompress - Pushes compressed input and drains decompressed output.
- zxc_
dstream_ ⚠finished - Returns 1 iff the decoder reached and validated the file footer.
- zxc_
dstream_ ⚠free - Releases a push decompression stream. Safe to call with null.
- zxc_
dstream_ ⚠in_ size - Suggested input chunk size for the decompressor.
- zxc_
dstream_ ⚠out_ size - Suggested output chunk size for the decompressor.
- zxc_
error_ ⚠name - Returns a human-readable name for the given error code.
- zxc_
estimate_ ⚠cctx_ size - Estimates the memory reserved by a compression context for a single
block of
src_sizebytes viazxc_compress_block. - zxc_
frame_ ⚠info_ size - Returns
sizeof(zxc_frame_info_t)as compiled into the C library. - zxc_
free_ ⚠cctx - Frees a compression context. Safe to call with a null pointer.
- zxc_
free_ ⚠dctx - Frees a decompression context. Safe to call with a null pointer.
- zxc_
get_ ⚠decompressed_ size - Returns the decompressed size stored in a ZXC compressed buffer.
- zxc_
get_ ⚠dict_ id - Returns the dictionary ID a ZXC compressed buffer requires.
- zxc_
get_ ⚠frame_ info - Reads a frame’s header and footer, without decoding.
- zxc_
init_ ⚠static_ cctx - Initialises a compression context inside a caller-supplied workspace
(no heap allocation), carved for
block_sizeandlevel(1..7). - zxc_
init_ ⚠static_ dctx - Initialises a decompression context inside a caller-supplied workspace (no heap allocation).
- zxc_
max_ ⚠level - Returns the maximum supported compression level (currently 7).
- zxc_
min_ ⚠level - Returns the minimum supported compression level (currently 1).
- zxc_
seek_ ⚠table_ size - Returns the encoded byte size of a seek table for
num_blocksblocks, or 0 when that size does not fit ausize. - zxc_
seekable_ ⚠decompress_ range - Decompresses
lenbytes starting at byteoffsetin the original uncompressed data. Only the blocks overlapping the requested range are read and decompressed. - zxc_
seekable_ ⚠decompress_ range_ mt - Multi-threaded variant of
zxc_seekable_decompress_range. - zxc_
seekable_ ⚠free - Frees a seekable handle and all associated resources. Safe to call with a null pointer.
- zxc_
seekable_ ⚠get_ block_ comp_ size - Returns the on-disk compressed size of a specific block (block header + payload + optional per-block checksum).
- zxc_
seekable_ ⚠get_ block_ decomp_ size - Returns the decompressed size of a specific block.
- zxc_
seekable_ ⚠get_ decompressed_ size - Returns the total decompressed size of the archive in bytes.
- zxc_
seekable_ ⚠get_ num_ blocks - Returns the total number of data blocks in the archive (excluding EOF).
- zxc_
seekable_ ⚠open - Opens a seekable archive from a memory buffer.
- zxc_
seekable_ ⚠open_ file - Opens a seekable archive from a
FILE*. The file must be seekable (not stdin/pipe). The current file position is saved and restored. The FILE* must remain open for the lifetime of the handle. - zxc_
seekable_ ⚠open_ reader - Opens a seekable archive through a user-supplied
zxc_reader_t. - zxc_
seekable_ ⚠set_ checksum - zxc_
seekable_ ⚠set_ dict - Attaches a dictionary to a seekable handle. The dictionary content must remain valid for the lifetime of the handle (or until replaced).
- zxc_
static_ ⚠cctx_ workspace_ size - Returns the exact byte count required by a static compression
workspace for the given
block_sizeandlevel. - zxc_
static_ ⚠dctx_ workspace_ size - Returns the exact byte count required by a static decompression
workspace for the given
block_size. - zxc_
stream_ ⚠compress - Compresses data from an input stream to an output stream.
- zxc_
stream_ ⚠decompress - Decompresses data from an input stream to an output stream.
- zxc_
stream_ ⚠get_ decompressed_ size - Returns the decompressed size stored in a ZXC compressed file.
- zxc_
version_ ⚠codename - Returns the release code name of the library as a null-terminated
string (e.g.
"Hydrogen"). Informational only. - zxc_
version_ ⚠number - Returns the library version as
MAJOR * 10000 + MINOR * 100 + PATCH. - zxc_
version_ ⚠string - Returns the library version as a null-terminated string.
- zxc_
write_ ⚠seek_ table - Low-level: writes a seek table (block header + entries) to
dst.
Type Aliases§
- zxc_
cparam_ t - Compression parameter identifier (mirrors the C enum
zxc_cparam_t). - zxc_
dparam_ t - Decompression parameter identifier (mirrors the C enum
zxc_dparam_t). - zxc_
progress_ callback_ t - Progress callback (mirrors
zxc_progress_callback_t), called from the writer thread of theFILE*pipeline after each block or batch of blocks.