SHRINK(3)

NAME
shrink - compression wrapper

SYNOPSIS
#include <shrink.h>
struct shrink_ctx *
shrink_init(int algorithm, int level);
void
shrink_cleanup(void);
size_t
shrink_compress_bounds(struct shrink_ctx *ctx, size_t blocksize);
void *
shrink_malloc(struct shrink_ctx *ctx, size_t blocksize);
int
shrink_compress(struct shrink_ctx *ctx, uint8_t *src, uint8_t *dst, size_t slen, size_t *comp_sz, struct timeval *elapsed);
int
shrink_decompress(struct shrink_ctx *ctx, uint8_t *src, uint8_t *dst, size_t slen, size_t *uncomp_sz, struct timeval *elapsed);
const char *
shrink_get_algorithm(struct shrink_ctx *);

DESCRIPTION
The shrink library provides a single API into several compression algorithms. It enables developers to easily add compression and decompression functionality to an existing code base.

shrink_init() prepares the library for first use. This function shall be called before any other function is called. The context pointer returned by this function should be passed to all other shrink calls. shrink_cleanup() may be called after all work is done to deallocate any resources.

The algorithm parameter delineates which compression algorithm to use. The following algorithms are available:
SHRINK_ALG_NULL
    Do not attempt to compress data. Simply use bcopy(3) as the transformation algorithm.
SHRINK_ALG_LZO
    Use the LZO algorithm. LZO is optimized for speed at a compression cost. It typically compresses ~10% less than LZW or LZMA. Note: LZO is not standardized.
SHRINK_ALG_LZW
    LZW is the most widely used algorithm. It provides higher compression than LZO but can be quite a bit slower. The algorithm is widely adopted and the output is standardized.
SHRINK_ALG_LZMA
    LZMA is considered the best compression algorithm however it is significantly slower than LZO or even LZW. It is also heavier on resources than the other two algorithms.

There is no one answer to help one pick a compression algorithm. Please use the accompanied shrink binary to get an idea how the algorithms perform in the best and worst case scenarios.

shrink_compress_bounds() is a helper function to help determine how much memory a compressed (destination) buffer might require. This value can be higher than the source buffer size for incompressible data. The function will return a value based on the blocksize parameter.

shrink_malloc() is identical to the malloc(3) call but it handles the shrink_compress_bounds() sizes automatically. This means that the allocated buffer is larger than the requested size.

shrink_compress() compresses src buffer into dst buffer. The slen parameter holds the src buffer size. Prior to calling shrink_compress() the comp_sz parameter must be set to the maximum compressible blocksize. This blocksize can be determined by calling shrink_compress_bounds().

On success the function returns SHRINK_OK and comp_sz holds the actual compressed size of the buffer.

Additionally if elapsed is set it will return a struct timeval that contains the time it took to compress the src buffer.

shrink_decompress() is analogous to shrink_compress(). It decompresses src into dst. The slen parameter holds the size of the src buffer. Prior to calling shrink_decompress() the uncomp_sz parameter must be set to the maximum dst size.

Additionally if elapsed is set it will return a struct timeval that contains the time it took to decompress the src buffer.

The shrink_get_algorithm() function may be called to obtain a character string with the currently in use compression algorithm.

SEE ALSO
This library wraps the following excellent open source libraries:
http://www.oberhumer.com/opensource/lzo/
http://www.zlib.net/
http://tukaani.org/xz/

HISTORY
-nosplit shrink was written by Marco Peereboom <marco@conformal.com> in order to have a single API while testing several different compression algorithms.