z3dlib(3)

NAME
z3lib - compression/decompression library

SYNOPSIS
#include <z3lib.h>
#include <z3blib.h>
#include <z3dlib.h>

struct z3de_handle *z3d_encode_init(void *memory, unsigned int memsize, __u32 tellwhen, __u8 thrmin, __u8 thrmax, __u32 initialgrant, int preferlonger, int limitlength3);

struct z3de_handle *z3d_encode(struct z3de_handle *zh, __u8 *data, __u32 datasize, __u32 *taken, __u8 *code, __u32 codesize, __u32 *given);

struct z3dd_handle *z3d_decode_init(__u32 pending_bits, int pending_nb, void *memory, unsigned int memsize);

struct z3dd_handle *z3d_decode(struct z3dd_handle *zh, int *error, __u32 *pending_bits, int *pending_nb, __u8 *code, __u32 codesize, __u32 *taken, __u8 **data, __u32 *given);

static inline struct z3dd_handle *z3d_decode_relative(struct z3dd_handle *zh, int *error, __u32 *pending_bits, int *pending_nb, __u8 *code, __u32 codesize, __u32 *taken, __u32 *index, __u32 *given);

DESCRIPTION
This is the second layer of z3lib, it provides functions to compress and decompress arbitrary amounts of data in main memory, according to RFC1951.

ENCODE
To encode data, first call z3d_encode_init once to obtain a valid handle, giving it the following parameters:

memory
    Refers to a memory block of size memsize, reserved for the compressor, where memsize must not be less than Z3DE_MEMSIZE_MIN

tellwhen
    Frequency for code size estimation and block close decision. 0 for none (i.e. full block usage always), minimum value is Z3DE_SLICE_MIN, values larger than (memsize-Z3DE_MEMSIZE_MIN)/2 are not useful

thrmin, thrmax
    Threshold for block close decision, in range 0..Z3DE_THRESHOLD_ONE (on behalf of rational range 0..1); a block will be closed when compression ratio is less than all previously determined ratios times thrmin/Z3DE_THRESHOLD_ONE, or when it is greater than all previously determined ratios times Z3DE_THRESHOLD_ONE/thrmax

initialgrant
    For threshold comparision, all but the first slice are asumed to be incremented by this value to roughly compensate RFC1951 block dynamic table size

preferlonger
    When non-zero, the compressor will try to find a longer match at fInfR+1 and prefer it over a previous match at fInfR

limitlength3
    When non-zero, then for codes with length 3 and large distance, check whether coding as literal is better

Now call z3d_encode repeatedly, until it returns NULL:

data, datasize
    A number of bytes that are available to compress datasize must be greater than 0 unless end of data is reached

code, codesize
    Refers to a buffer for readily compressed code, and its maximum size

taken
    Returns the number of bytes actually taken from the data buffer, in range 0..datasize

given
    Returns the number of bytes stored into the code buffer, in range 0..codesize

Note, that all output parameters are still valid when the function returns NULL. In particular, on the last call of the function it may return pending code, which is indicated by a non-zero value for given.

DECODE
To decode data, first call z3d_decode_init once to obtain a valid handle, giving it the following parameters:

pending_bits, pending_nb
    For data which does not start on a byte boundary, the initial bits are given here. Otherwise, both parameters must be 0

memory, memsize
    memory reserved for the decompressor, memsize shall be and must not be less than Z3DD_MEMSIZE

Now call z3d_decode repeatedly, until it returns NULL:

code, codesize
    a number of bytes that are available to decompress

error
    Finally returns an error code, see z3lib.h

pending_bits, pending_nb
    Finally returns a number of bits pending

taken
    Returns the number of bytes actually taken from code, in range 0..codesize.

data
    Returns a pointer to a number of bytes readily decompressed

given
    Returns the number of bytes available at the data pointer

Note, that the last three output parameters are valid only as long as the function does not return NULL.

For use with garbage collectable systems, one may want to use the function z3d_decode_relative which returns a relative index instead of the absolute data pointer:

index
    Returns an index into (char *)zh, where to find the output bytes

SEE ALSO
z3lib(3), z3flib(3), http://rfc.net/rfc1951.html.

AUTHOR
Oskar Schirmer (oskar@scara.com).