zlib Advanced Functions

Syntax

#include <cafe.h>
        
#include <zlib.h>

ZEXTERN int ZEXPORT deflateInit2 OF((z_streamp strm,
                                     int  level,
                                     int  method,
                                     int  windowBits,
                                     int  memLevel,
                                     int  strategy));

ZEXTERN int ZEXPORT deflateSetDictionary OF((z_streamp strm,
                                             const Bytef *dictionary,
                                             uInt  dictLength));

ZEXTERN int ZEXPORT deflateCopy OF((z_streamp dest,
                                    z_streamp source));

ZEXTERN int ZEXPORT deflateReset OF((z_streamp strm));

ZEXTERN int ZEXPORT deflateParams OF((z_streamp strm,
                                      int level,
                                      int strategy));

ZEXTERN int ZEXPORT deflateTune OF((z_streamp strm,
                                    int good_length,
                                    int max_lazy,
                                    int nice_length,
                                    int max_chain));

ZEXTERN uLong ZEXPORT deflateBound OF((z_streamp strm,
                                       uLong sourceLen));

ZEXTERN int ZEXPORT deflatePrime OF((z_streamp strm,
                                     int bits,
                                     int value));

ZEXTERN int ZEXPORT deflateSetHeader OF((z_streamp strm,
                                         gz_headerp head));

ZEXTERN int ZEXPORT inflateInit2 OF((z_streamp strm,
                                     int  windowBits));

ZEXTERN int ZEXPORT inflateSetDictionary OF((z_streamp strm,
                                             const Bytef *dictionary,
                                             uInt  dictLength));

ZEXTERN int ZEXPORT inflateSync OF((z_streamp strm));

ZEXTERN int ZEXPORT inflateCopy OF((z_streamp dest,
                                    z_streamp source));

ZEXTERN int ZEXPORT inflateReset OF((z_streamp strm));

ZEXTERN int ZEXPORT inflateReset2 OF((z_streamp strm,
                                      int windowBits));

ZEXTERN int ZEXPORT inflatePrime OF((z_streamp strm,
                                     int bits,
                                     int value));

ZEXTERN long ZEXPORT inflateMark OF((z_streamp strm));

ZEXTERN int ZEXPORT inflateGetHeader OF((z_streamp strm,
                                         gz_headerp head));

ZEXTERN int ZEXPORT inflateBackInit OF((z_streamp strm, int windowBits,
                                        unsigned char FAR *window));

typedef unsigned (*in_func) OF((void FAR *, unsigned char FAR * FAR *));
typedef int (*out_func) OF((void FAR *, unsigned char FAR *, unsigned));
ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm,
                                    in_func in, void FAR *in_desc,
                                    out_func out, void FAR *out_desc));

ZEXTERN int ZEXPORT inflateBackEnd OF((z_streamp strm));

ZEXTERN uLong ZEXPORT zlibCompileFlags OF((void));

Parameters

strm Pointer to a zip z_stream.
dest For deflateCopy and inflateCopy. Pointer to a destination zip z_stream.
source For deflateCopy and inflateCopy. Pointer to a source zip z_stream.
level Compression level. For more information, see deflateInit.
method Compression method. Must be Z_DEFLATED in this version of zlib
windowBits Base two logarithm of the window size. Should be in the range 8..15 (or optionally as described below) in this version of zlib.
memLevel Specify how much memory to allocate for the internal compression state.
strategy Compression strategy.
dictionary For deflateSetDictionary and inflateSetDictionary. Specifies the dictionary.
dictLength For deflateSetDictionary and inflateSetDictionary. Specifies the length of the dictionary.
good_length For deflateTune.
max_lazy For deflateTune.
nice_length For deflateTune.
max_chain For deflateTune.
sourceLen For deflateBound. The uncompressed size, before deflation.
bits For deflatePrime and inflatePrime. Number of bits to insert in the stream.
value For deflatePrime and inflatePrime. Bits to insert in the stream.
head For deflateSetHeader and inflateGetHeader. Pointer to a gz_header structure to set or get the gzip header information.
window For inflateBackInit. Window buffer for use by inflateBack
in For inflateBack. Callback function to provide more input.
out For inflateBackdeflateTune. Callback function to accept more output.

Return Value

deflateInit2

Returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_STREAM_ERROR if a parameter is invalid (such as an invalid method), or Z_VERSION_ERROR if the zlib library version (zlib_version) is incompatible with the version assumed by the caller (ZLIB_VERSION). msg is set to NULL if there is no error message.

deflateSetDictionary

deflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a parameter is invalid (such as NULL dictionary) or the stream state is inconsistent (for example if deflate has already been called for this stream or if the compression method is bsort).

deflateCopy

Returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc being NULL). msg is left unchanged in both source and destination.

deflateReset

Returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc or state being NULL).

deflateParams

Returns Z_OK if success, Z_STREAM_ERROR if the source stream state was inconsistent or if a parameter was invalid, Z_BUF_ERROR if strm->avail_out was zero.

deflateTune

Returns Z_OK on success, or Z_STREAM_ERROR for an invalid deflate stream.

deflateBound

Returns an upper bound on the compressed size after deflation of sourceLen bytes.

deflatePrime

Returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent.

deflateSetHeader

Returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent.

inflateInit2

Returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_VERSION_ERROR if the zlib library version is incompatible with the version assumed by the caller, Z_STREAM_ERROR if a parameters are invalid, such as a null pointer to the structure. msg is set to null if there is no error message.

inflateSetDictionary

Returns Z_OK if success, Z_STREAM_ERROR if a parameter is invalid (such as NULL dictionary) or the stream state is inconsistent, Z_DATA_ERROR if the given dictionary does not match the expected one (incorrect adler32 value).

inflateSync

Returns Z_OK if a full flush point has been found, Z_BUF_ERROR if no more input was provided, Z_DATA_ERROR if no flush point has been found, or Z_STREAM_ERROR if the stream structure was inconsistent. In the success case, the application may save the current value of total_in which indicates where valid compressed data was found. In the error case, the application may repeatedly call inflateSync, providing more input each time, until success or end of the input data.

inflateCopy

Returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc being NULL). msg is left unchanged in both source and destination.

inflateReset

Returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc or state being NULL).

inflateReset2

Returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc or state being Z_NULL), or if the windowBits parameter is invalid.

inflatePrime

Returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent.

inflateMark

Returns a position indicator (mark) as described below, or -1 << 16 if the provided source stream state was inconsistent.

inflateGetHeader

Returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent.

inflateBackInit

Returns Z_OK on success, Z_STREAM_ERROR if any of the parameters are invalid, Z_MEM_ERROR if the internal state could not be allocated, or Z_VERSION_ERROR if the version of the library does not match the version of the header file.

inflateBack

Returns Z_STREAM_END on success, Z_BUF_ERROR if in or out returned an error, Z_DATA_ERROR if there was a format error in the deflate stream (in which case strm->msg is set to indicate the nature of the error), or Z_STREAM_ERROR if the stream was not properly initialized. For Z_BUF_ERROR, an input or output error can be distinguished using strm->next_in which will be Z_NULL only if in returned an error. If strm->next_in is not Z_NULL, then the Z_BUF_ERROR was due to out returning nonzero. (in will always be called before out, so strm->next_in is assured to be defined if out returns nonzero.) Note that inflateBack cannot return Z_OK.

inflateBackEnd

Returns Z_OK on success, or Z_STREAM_ERROR if the stream state was inconsistent.

zlibCompileFlags

Returns flags indicating compile-time options.

Type sizes, two bits each, 00 = 16 bits, 01 = 32, 10 = 64, 11 = other:

Compiler, assembler, and debug options:

One-time table building (smaller code, but not thread-safe if true):

Library content (indicates missing functionality):

Operation variations (changes in library functionality):

Remainder:

Description

These functions are needed only in some special applications.

deflateInit2

This is another version of deflateInit with more compression options. The z_stream fields next_in, zalloc, zfree and opaque must be initialized before by the caller.

The method parameter is the compression method. It must be Z_DEFLATED in this version of the library.

The windowBits parameter is the base two logarithm of the window size (the size of the history buffer). It should be in the range 8..15 for this version of the library. Larger values of this parameter result in better compression at the expense of memory usage. The default value is 15 if deflateInit is used instead.

windowBits can also be −8..−15 for raw deflate. In this case, -windowBits determines the window size. deflate will then generate raw deflate data with no zlib header or trailer, and will not compute an adler32 check value.

windowBits can also be greater than 15 for optional gzip encoding. Add 16 to windowBits to write a simple gzip header and trailer around the compressed data instead of a zlib wrapper. The gzip header will have no file name, no extra data, no comment, no modification time (set to zero), no header crc, and the operating system will be set to 255 (unknown). If a gzip stream is being written, strm->adler is a crc32 instead of an adler32.

The memLevel parameter specifies how much memory should be allocated for the internal compression state. memLevel=1 uses minimum memory but is slow and reduces compression ratio; memLevel=9 uses maximum memory for optimal speed. The default value is 8. See zconf.h for total memory usage as a function of windowBits and memLevel.

The strategy parameter is used to tune the compression algorithm. Use the value Z_DEFAULT_STRATEGY for normal data, Z_FILTERED for data produced by a filter (or predictor), Z_HUFFMAN_ONLY to force Huffman encoding only (no string match), or Z_RLE to limit match distances to one (run-length encoding). Filtered data consists mostly of small values with a somewhat random distribution. In this case, the compression algorithm is tuned to compress them better. The effect of Z_FILTERED is to force more Huffman coding and less string matching; it is somewhat intermediate between Z_DEFAULT_STRATEGY and Z_HUFFMAN_ONLY. Z_RLE is designed to be almost as fast as Z_HUFFMAN_ONLY, but provide better compression for PNG image data. The strategy parameter only affects the compression ratio but not the correctness of the compressed output even if it is not set appropriately. Z_FIXED prevents the use of dynamic Huffman codes, allowing for a simpler decoder for special applications.

deflateInit2 does not perform any compression: this will be done by deflate.

deflateSetDictionary

Initializes the compression dictionary from the given byte sequence without producing any compressed output. This function must be called immediately after deflateInit, deflateInit2, or deflateReset, before any call of deflate. The compressor and decompressor must use exactly the same dictionary (see inflateSetDictionary).

The dictionary should consist of strings (byte sequences) that are likely to be encountered later in the data to be compressed, with the most commonly used strings preferably put toward the end of the dictionary. Using a dictionary is most useful when the data to be compressed is short and can be predicted with good accuracy; the data can then be compressed better than with the default empty dictionary.

Depending on the size of the compression data structures selected by deflateInit or deflateInit2, a part of the dictionary may in effect be discarded, for example if the dictionary is larger than the window size in deflate or deflate2. The strings most likely to be useful should be put at the end of the dictionary, not at the front. In addition, the current implementation of deflate will use at most the window size minus 262 bytes of the provided dictionary.

Upon return of this function, strm->adler is set to the adler32 value of the dictionary; the decompressor may later use this value to determine which dictionary has been used by the compressor. (The adler32 value applies to the whole dictionary even if only a subset of the dictionary is actually used by the compressor.) If a raw deflate was requested, then the adler32 value is not computed and strm->adler is not set.

deflateSetDictionary does not perform any compression: this will be done by deflate.

deflateCopy

Sets the destination stream as a complete copy of the source stream.

This function can be useful when several compression strategies will be tried, for example when there are several ways of preprocessing the input data with a filter. The streams that will be discarded should then be freed by calling deflateEnd. Note that deflateCopy duplicates the internal compression state which can be quite large, so this strategy is slow and can consume lots of memory.

deflateReset

This function is equivalent to deflateEnd followed by deflateInit, but does not free and reallocate all the internal compression state. The stream will keep the same compression level and any other attributes that may have been set by deflateInit2.

deflateParams

Dynamically update the compression level and compression strategy. The interpretation of level and strategy is as in deflateInit2. This can be used to switch between compression and straight copy of the input data, or to switch to a different type of input data requiring a different strategy. If the compression level is changed, the input available so far is compressed with the old level (and may be flushed); the new level will take effect only at the next call of deflate.

Before the call of deflateParams, the stream state must be set as for a call of deflate, since the currently available input may have to be compressed and flushed. In particular, strm->avail_out must be nonzero.

deflateTune

Fine tune deflate's internal compression parameters. This should only be used by someone who understands the algorithm used by zlib's deflate for searching for the best matching string, and even then only by the most fanatic optimizer trying to squeeze out the last compressed bit for their specific input data. Read the deflate.c source code for the meaning of the max_lazy, good_length, nice_length, and max_chain parameters.

deflateTune can be called after deflateInit or deflateInit2.

deflateBound

deflateBound returns an upper bound on the compressed size after deflation of sourceLen bytes. It must be called after deflateInit or deflateInit2. This would be used to allocate an output buffer for deflation in a single pass, and so would be called before deflate.

deflatePrime

deflatePrime inserts bits in the deflate output stream. The intent is that this function is used to start off the deflate output with the bits leftover from a previous deflate stream when appending to it. As such, this function can only be used for raw deflate, and must be used before the first deflate call after a deflateInit2 or deflateReset. bits must be less than or equal to 16, and that many of the least significant bits of value will be inserted in the output.

deflateSetHeader

deflateSetHeader provides gzip header information for when a gzip stream is requested by deflateInit2. deflateSetHeader may be called after deflateInit2 or deflateReset and before the first call of deflate. The text, time, os, extra field, name, and comment information in the provided gz_header structure are written to the gzip header (xflags is ignored — the extra flags are set according to the compression level). The caller must assure that, if not Z_NULL, name and comment are terminated with a zero byte, and that if extra is not Z_NULL, that extra_len bytes are available there. If hcrc is true, a gzip header crc is included. Note that the current versions of the command-line version of gzip (up through version 1.3.x) do not support header crc's, and will report that it is a "multi-part gzip file" and concede.

If deflateSetHeader is not used, the default gzip header has text false, the time set to zero, and os set to 255, with no extra, name, or comment fields. The gzip header is returned to the default state by deflateReset.

inflateInit2

This is another version of inflateInit with an extra parameter. The fields next_in, avail_in, zalloc, zfree and opaque must be initialized before by the caller.

The windowBits parameter is the base two logarithm of the maximum window size (the size of the history buffer). It should be in the range 8..15 for this version of the library. The default value is 15 if inflateInit is used instead. windowBits must be greater than or equal to the windowBits value provided to deflateInit2 while compressing, or it must be equal to 15 if deflateInit2 was not used. If a compressed stream with a larger window size is given as input, inflate will return with the error code Z_DATA_ERROR instead of trying to allocate a larger window.

windowBits can also be zero to request that inflate use the window size in the zlib header of the compressed stream.

windowBits can also be −8..−15 for raw inflate. In this case, -windowBits determines the window size. inflate will then process raw deflate data, not looking for a zlib or gzip header, not generating a check value, and not looking for any check values for comparison at the end of the stream. This is for use with other formats that use the deflate compressed data format such as zip. Those formats provide their own check values. If a custom format is developed using the raw deflate format for compressed data, it is recommended that a check value such as an adler32 or a crc32 be applied to the uncompressed data as is performed in the zlib, gzip, and zip formats. For most applications, the zlib format should be used as is. Note that comments above on the use in deflateInit2 applies to the magnitude of windowBits.

windowBits can also be greater than 15 for optional gzip decoding. Add 32 to windowBits to enable zlib and gzip decoding with automatic header detection, or add 16 to decode only the gzip format (the zlib format will return a Z_DATA_ERROR). If a gzip stream is being decoded, strm->adler is a crc32 instead of an adler32.

inflateInit2 does not perform any decompression apart from reading the zlib header if present: actual decompression be done by inflate. (So next_in and avail_in may be modified, but next_out and avail_out are unused and unchanged.) The current implementation of inflateInit2 does not process any header information -- that is deferred until inflate is called.

inflateSetDictionary

Initializes the decompression dictionary from the given uncompressed byte sequence. This function must be called immediately after a call of inflate, if that call returned Z_NEED_DICT. The dictionary chosen by the compressor can be determined from the adler32 value returned by that call of inflate. The compressor and decompressor must use exactly the same dictionary (see deflateSetDictionary). For raw inflate, this function can be called immediately after inflateInit2 or inflateReset and before any call of inflate to set the dictionary. The application must insure that the dictionary that was used for compression is provided.

inflateSetDictionary does not perform any decompression: this will be done by subsequent calls of inflate.

inflateSync

Skips invalid compressed data until a full flush point (see the description of deflate with Z_FULL_FLUSH) can be found, or until all available input is skipped. No output is provided.

inflateCopy

Sets the destination stream as a complete copy of the source stream.

This function can be useful when randomly accessing a large stream. The first pass through the stream can periodically record the inflate state, allowing restarting inflate at those points when randomly accessing the stream.

inflateReset

This function is equivalent to inflateEnd followed by inflateInit, but does not free and reallocate all the internal decompression state. The stream will keep attributes that may have been set by inflateInit2.

inflateReset2

This function is the same as inflateReset, but it also permits changing the wrap and window size requests. The windowBits parameter is interpreted the same as it is for inflateInit2.

inflatePrime

This function inserts bits in the inflate input stream. The intent is that this function is used to start inflating at a bit position in the middle of a byte. The provided bits will be used before any bytes are used from next_in. This function should only be used with raw inflate, and should be used before the first inflate call after inflateInit2 or inflateReset. bits must be less than or equal to 16, and that many of the least significant bits of value will be inserted in the input.

If bits is negative, then the input stream bit buffer is emptied. Then inflatePrime can be called again to put bits in the buffer. This is used to clear out bits leftover after feeding inflate a block description prior to feeding inflate codes.

inflateMark

This function returns two values, one in the lower 16 bits of the return value, and the other in the remaining upper bits, obtained by shifting the return value down 16 bits. If the upper value is −1 and the lower value is zero, then inflate is currently decoding information outside of a block. If the upper value is −1 and the lower value is nonzero, then inflate is in the middle of a stored block, with the lower value equaling the number of bytes from the input remaining to copy. If the upper value is not −1, then it is the number of bits back from the current bit position in the input of the code (literal or length/distance pair) currently being processed. In that case the lower value is the number of bytes already emitted for that code.

A code is being processed if inflate is waiting for more input to complete decoding of the code, or if it has completed decoding but is waiting for more output space to write the literal or match data.

inflateMark is used to mark locations in the input data for random access, which may be at bit positions, and to note those cases where the output of a code may span boundaries of random access blocks. The current location in the input stream can be determined from avail_in and data_type as noted in the description for the Z_BLOCK flush parameter for inflate.

inflateGetHeader

inflateGetHeader requests that gzip header information be stored in the provided gz_header structure. inflateGetHeader may be called after inflateInit2 or inflateReset, and before the first call of inflate. As inflate processes the gzip stream, head->done is zero until the header is completed, at which time head->done is set to one. If a zlib stream is being decoded, then head->done is set to −1 to indicate that there will be no gzip header information forthcoming. Note that Z_BLOCK can be used to force inflate to return immediately after header processing is complete and before any actual data is decompressed.

The text, time, xflags, and os fields are filled in with the gzip header contents. hcrc is set to true if there is a header CRC. (The header CRC was valid if done is set to one.) If extra is not Z_NULL, then extra_max contains the maximum number of bytes to write to extra. When done is true, extra_len contains the actual extra field length, and extra contains the extra field, or that field truncated if extra_max is less than extra_len. If name is not Z_NULL, then up to name_max characters are written there, terminated with a zero unless the length is greater than name_max. If comment is not Z_NULL, then up to comm_max characters are written there, terminated with a zero unless the length is greater than comm_max. When any of extra, name, or comment are not Z_NULL and the respective field is not present in the header, then that field is set to Z_NULL to signal its absence. This allows the use of deflateSetHeader with the returned structure to duplicate the header. However, if those fields are set to allocated memory, then the application will need to save those pointers elsewhere so that they can be eventually freed.

If inflateGetHeader is not used, then the header information is discarded. The header is always checked for validity, including the header CRC if present. inflateReset will reset the process to discard the header information. The application would need to call inflateGetHeader again to retrieve the header from the next gzip stream.

inflateBackInit

Initialize the internal stream state for decompression using inflateBack calls. The fields zalloc, zfree and opaque in strm must be initialized before the call. If zalloc and zfree are Z_NULL, then the default library-derived memory allocation routines are used. windowBits is the base two logarithm of the window size, in the range 8..15. window is a caller supplied buffer of that size. Except for special applications where it is assured that deflate was used with small window sizes, windowBits must be 15 and a 32K byte window must be supplied to be able to decompress general deflate streams.

See inflateBack for the usage of these routines.

inflateBack

inflateBack does a raw inflate with a single call using a callback interface for input and output. This is more efficient than inflate for file I/O applications in that it avoids copying between the output and the sliding window by making the window itself the output buffer. This function trusts the application to not change the output buffer passed by the output function, at least until inflateBack returns.

inflateBackInit must be called first to allocate the internal state and to initialize the state with the user-provided window buffer. inflateBack may then be used multiple times to inflate a complete, raw deflate stream with each call. inflateBackEnd is then called to free the allocated state.

A raw deflate stream is one with no zlib or gzip header or trailer. This routine would normally be used in a utility that reads zip or gzip files and writes out uncompressed files. The utility would decode the header and process the trailer on its own. This routine expects only the raw deflate stream to decompress. This is different from the normal behavior of inflate, which expects either a zlib or gzip header and trailer around the deflate stream.

inflateBack uses two subroutines supplied by the caller that are then called by inflateBack for input and output. inflateBack calls those routines until it reads a complete deflate stream and writes out all of the uncompressed data, or until it encounters an error. The function's parameters and return types are defined above in the in_func and out_func typedefs. inflateBack will call in(in_desc, &buf) which should return the number of bytes of provided input, and a pointer to that input in buf. If there is no input available, in must return zero—buf is ignored in that case—and inflateBack will return a buffer error. inflateBack will call out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. out should return zero on success, or nonzero on failure. If out returns nonzero, inflateBack will return with an error. Neither in nor out are permitted to change the contents of the window provided to inflateBackInit, which is also the buffer that out uses to write from. The length written by out will be at most the window size. Any nonzero amount of input may be provided by in.

For convenience, inflateBack can be provided input on the first call by setting strm->next_in and strm->avail_in. If that input is exhausted, then in will be called. strm->next_in must be initialized before calling inflateBack. If strm->next_in is Z_NULL, then in will be called immediately for input. If strm->next_in is not Z_NULL, then strm->avail_in must also be initialized, and then if strm->avail_in is not zero, input will initially be taken from strm->next_in[0 .. strm->avail_in - 1].

The in_desc and out_desc parameters of inflateBack is passed as the first parameter of in and out respectively when they are called. These descriptors can be optionally used to pass any information that the caller-supplied in and out functions need to do their job.

On return, inflateBack will set strm->next_in and strm->avail_in to pass back any unused input that was provided by the last in call.

inflateBackEnd

All memory allocated by inflateBackInit is freed.

Do Not Call From

deflateBound

None.

deflateCopy

None.

deflateInit2

None.

deflateParams

None.

deflatePrime

None.

deflateReset

None.

deflateSetDictionary

None.

deflateSetHeader

None.

deflateTune

None.

inflateBack

None.

inflateBackEnd

None.

inflateBackInit

None.

inflateCopy

None.

inflateGetHeader

None.

inflateInit2

None.

inflateMark

None.

inflatePrime

None.

inflateReset

None.

inflateReset2

None.

inflateSetDictionary

None.

inflateSync

None.

zlibCompileFlags

None.

See Also

zlib Overview
zlib Basic Functions

Revision History

2014/12/05 Creation.


CONFIDENTIAL