Skip to main content

Crate zxc_sys

Crate zxc_sys 

Source
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).

Crates.io Documentation

§License

BSD-3-Clause - see LICENSE for details.

Structs§

zxc_cctx
Opaque compression context. Use zxc_create_cctx to create.
zxc_cstream
Opaque push compression stream. Use zxc_cstream_create to create.
zxc_dctx
Opaque decompression context. Use zxc_create_dctx to create.
zxc_dstream
Opaque push decompression stream. Use zxc_dstream_create to 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_t from zxc_pstream.h).
zxc_outbuf_t
Output buffer descriptor for push streaming (mirrors zxc_outbuf_t from zxc_pstream.h).
zxc_reader_t
Storage-agnostic reader interface for seekable archives (mirrors zxc_reader_t from zxc_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 most ZXC_MAX_THREADS; default 0, auto-detect. The buffer, block and push APIs ignore it.
ZXC_DICT_HEADER_SIZE
Fixed size of the .zxd file 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 most ZXC_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 .zxd file (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 cctx into *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 NULL dict detaches.
zxc_cctx_set_param⚠
Sets one parameter on cctx; 0 restores its default.
zxc_cctx_set_progress⚠
Sets the progress callback; None disables it. Honoured by zxc_stream_compress only.
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 dctx into *value. See zxc_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; None disables it. Honoured by zxc_stream_decompress only.
zxc_decompress⚠
Decompresses a complete ZXC archive.
zxc_decompress_block⚠
Decompresses a single block produced by zxc_compress_block, with the parameters in force on dctx (checksum, dictionary).
zxc_decompress_block_bound⚠
Returns the minimum dst_capacity required by zxc_decompress_block for a block of uncompressed_size bytes. Accounts for the wild-copy tail pad used by the fast decoder.
zxc_decompress_block_safe⚠
Strict-sized variant of zxc_decompress_block: accepts dst_capacity == uncompressed_size exactly (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_lengths is null, else binding the (content, table) pair.
zxc_dict_huf⚠
Returns a pointer to the 128-byte shared Huffman table inside a .zxd buffer (zero-copy; aims into buf), or NULL if buf is not a valid .zxd file.
zxc_dict_load⚠
Loads and validates a .zxd dictionary file from a memory buffer.
zxc_dict_read_id⚠
Returns the dictionary ID stored in a .zxd file buffer.
zxc_dict_save⚠
Serializes dictionary content plus its shared Huffman table to the .zxd file format. The table is mandatory.
zxc_dict_save_bound⚠
Returns the .zxd file 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 .zxd bytes in zxd_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_size bytes via zxc_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_size and level (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_blocks blocks, or 0 when that size does not fit a usize.
zxc_seekable_decompress_range⚠
Decompresses len bytes starting at byte offset in 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_size and level.
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 the FILE* pipeline after each block or batch of blocks.