#include <librock/target/types.c>
#include <librock/zlibh.h>
const char *
librock_z_zlibVersion (void);
- The application can compare zlibVersion and librock_ZLIB_VERSION for consistency.
If the first character differs, the library code actually used is
not compatible with the zlib.h header file used by the application.
This check is automatically made by deflateInit and inflateInit.
int
librock_z_compress (librock_z_Bytef *dest,
librock_z_uLongf *destLen,
librock_z_Bytef *source,
librock_z_uLong sourceLen);
-
Compresses the source buffer into the destination buffer.
sourceLen is
the byte length of the source buffer. Upon entry, destLen is the total
size of the destination buffer, which must be at least 0.1% larger than
sourceLen plus 12 bytes. Upon exit, destLen is the actual size of the
compressed buffer.
This function can be used to compress a whole file at once if the
input file is mmap'ed.
compress returns librock_Z_OK if success, librock_Z_MEM_ERROR if there was not
enough memory, librock_Z_BUF_ERROR if there was not enough room in the output
buffer.
This is a utility function implemented by calling the
basic stream-oriented librock_z_deflate* functions described below. To simplify
the interface, some default options are assumed (compression level
and memory usage, standard memory allocation functions). The source
code of these utility functions can easily be modified if you need
special options.
Typical use:
int err;
const char *data; /* Data to compress */
librock_z_uLong len; /* Length of data to compress */
librock_z_Byte *compr, *uncompr;
librock_z_uLong comprLen, uncomprLen;
/* Set up compr, comprLen */
err = librock_z_compress(compr, &comprLen, (const librock_z_Bytef*)data, len);
if (err != librock_Z_OK) {
error handling here;
}
.
.
.
err = librock_z_uncompress(uncompr, &uncomprLen, compr, comprLen);
if (err != librock_Z_OK) {
error handling here;
}
int
librock_z_compress2 (librock_z_Bytef *dest,
librock_z_uLongf *destLen,
const librock_z_Bytef *source,
librock_z_uLong sourceLen,
int level);
-
Compresses the source buffer into the destination buffer. The level
parameter has the same meaning as in
librock_z_deflateInit().
sourceLen is the byte
length of the source buffer. Upon entry, destLen is the total size of the
destination buffer, which must be at least 0.1% larger than sourceLen plus
12 bytes. Upon exit, destLen is the actual size of the compressed buffer.
compress2 returns librock_Z_OK if success, librock_Z_MEM_ERROR if there was not enough
memory, librock_Z_BUF_ERROR if there was not enough room in the output buffer,
librock_Z_STREAM_ERROR if the level parameter is invalid.
This is a utility function implemented by calling the
basic stream-oriented librock_z_deflate* functions described below. To simplify
the interface, some default options are assumed (compression level
and memory usage, standard memory allocation functions). The source
code of these utility functions can easily be modified if you need
special options.
int
librock_z_deflateInit (struct librock_z_stream_s *strm,
int level);
-
Initializes the internal stream state for compression. The fields
strm->zalloc , strm->zfree and strm->opaque must be initialized before by the caller.
If strm->zalloc and strm->zfree are set to librock_Z_NULL, librock_z_deflateInit() updates them to
use default allocation functions, malloc() and free()
The opaque value provided by the application will be passed as the first
parameter for calls of custom zalloc and zfree. This can be useful for custom
memory management. The compression library attaches no meaning to the
opaque value. A custom strm->zalloc must return librock_Z_NULL if there is not enough memory for the object.
If zlib is used in a multi-threaded application, the allocation functions must be
thread safe.
The application must update strm->next_in and strm->avail_in when strm->avail_in has
dropped to zero. It must update strm->next_out and strm->avail_out when strm->avail_out
has dropped to zero. All other fields are set by the
compression library and must not be updated by the application.
The fields strm->total_in and strm->total_out can be used for statistics or
progress reports. After compression, strm->total_in holds the total size of
the uncompressed data and may be saved for use in the decompressor
(particularly if the decompressor wants to decompress everything in
a single step).
The complete fields of struct librock_z_stream_s are:
struct librock_z_stream_s {
librock_z_Bytef *next_in; /* next input byte */
librock_z_uInt avail_in; /* number of bytes available at next_in */
librock_z_uLong total_in; /* total nb of input bytes read so librock_PTR */
librock_z_Bytef *next_out; /* next output byte should be put there */
librock_z_uInt avail_out; /* remaining free space at next_out */
librock_z_uLong total_out; /* total nb of bytes output so librock_PTR */
char *msg; /* last error message, NULL if no error */
struct librock_z_internal_state librock_PTR *state; /* not visible by applications */
librock_z_alloc_func zalloc; /* used to allocate the internal state */
librock_z_free_func zfree; /* used to free the internal state */
librock_z_voidpf opaque; /* private data object passed to zalloc and zfree */
int data_type; /* best guess about the data type: ascii or binary */
librock_z_uLong adler; /* adler32 value of the uncompressed data */
librock_z_uLong reserved; /* reserved for future use */
};
The level parameter is the compression level which must be librock_Z_DEFAULT_COMPRESSION ,
librock_Z_BEST_SPEED , librock_Z_NO_COMPRESSION, librock_Z_BEST_COMPRESSION , or
between 0 and 9:
1 gives best speed, 9 gives best compression, 0 gives no compression at
all (the input data is simply copied a block at a time).
librock_Z_DEFAULT_COMPRESSION requests a default compromise between speed and
compression (currently equivalent to level 6).
librock_z_deflateInit returns librock_Z_OK if success, librock_Z_MEM_ERROR if there was not
enough memory, librock_Z_STREAM_ERROR if level is not a valid compression level,
librock_Z_VERSION_ERROR if the zlib library version (librock_zlib_version() ) is incompatible
with the version assumed by the caller (librock_ZLIB_VERSION).
strm->msg is set to null if there is no error message. librock_z_deflateInit() does not
perform any compression: this will be done by librock_z_deflate().
librock_z_deflateInit() is implemented as a macro which expands to be a call to
int librock_z_deflateInit_ (librock_z_streamp strm,
int level,
const char *version,
int stream_size);
-
int
librock_z_deflateInit2 (librock_z_streamp strm,
int level,
int method,
int windowBits,
int memLevel,
int strategy);
- This is another version of
librock_z_deflateInit with more compression options.
The fields strm->next_in , strm->zalloc , strm->zfree and strm->opaque must be initialized before by
the caller.
The method parameter is the compression method. It must be librock_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.
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 librock_Z_DEFAULT_STRATEGY for normal data, librock_Z_FILTERED for data produced by a
filter (or predictor), or librock_Z_HUFFMAN_ONLY to force Huffman encoding only (no
string match). 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 librock_Z_FILTERED is to force more
Huffman coding and less string matching; it is somewhat intermediate
between librock_Z_DEFAULT and librock_Z_HUFFMAN_ONLY. The strategy parameter only affects
the compression ratio but not the correctness of the compressed output even
if it is not set appropriately.
librock_z_deflateInit2() returns librock_Z_OK if success, librock_Z_MEM_ERROR if there was not enough
memory, librock_Z_STREAM_ERROR if a parameter is invalid (such as an invalid
method). strm->msg is set to null if there is no error message. librock_z_deflateInit2 does
not perform any compression: this will be done by librock_z_deflate().
This is implemented as a macro which calls
int librock_z_deflateInit2_ (librock_z_streamp strm,
int level,
int method,
int windowBits,
int memLevel,
int strategy,
const char *version,
int stream_size);
-
int
librock_z_deflate (librock_z_streamp strm,
int flush);
librock_z_deflate() compresses as much data as possible, and stops when the input
buffer becomes empty or the output buffer becomes full. It may introduce some
output latency (reading input without producing any output) except when
forced to flush.
The detailed semantics are as follows. librock_z_deflate() performs one or both of the
following actions:
- Compress more input starting at
strm->next_in and update strm->next_in and strm->avail_in
accordingly. If not all input can be processed (because there is not
enough room in the output buffer), strm->next_in and strm->avail_in are updated and
processing will resume at this point for the next call of librock_z_deflate() .
- Provide more output starting at
strm->next_out and update strm->next_out and strm->avail_out
accordingly. This action is forced if the parameter flush is non zero.
Forcing flush frequently degrades the compression ratio, so this parameter
should be set only when necessary (in interactive applications).
Some output may be provided even if flush is not set.
Before the call of librock_z_deflate() , the application should ensure that at least
one of the actions is possible, by providing more input and/or consuming
more output, and updating strm->avail_in or strm->avail_out accordingly; strm->avail_out
should never be zero before the call. The application can consume the
compressed output when it wants, for example when the output buffer is full
(strm->avail_out == 0), or after each call of librock_z_deflate() . If librock_z_deflate() returns librock_Z_OK
and with zero strm->avail_out, it must be called again after making room in the
output buffer because there might be more output pending.
If the parameter flush is set to librock_Z_SYNC_FLUSH, all pending output is
flushed to the output buffer and the output is aligned on a byte boundary, so
that the decompressor can get all input data available so far. (In particular
strm->avail_in is zero after the call if enough output space has been provided
before the call.) Flushing may degrade compression for some compression
algorithms and so it should be used only when necessary.
If flush is set to librock_Z_FULL_FLUSH, all output is flushed as with
librock_Z_SYNC_FLUSH, and the compression state is reset so that decompression can
restart from this point if previous compressed data has been damaged or if
random access is desired. Using librock_Z_FULL_FLUSH too often can seriously degrade
the compression.
If librock_z_deflate() returns with strm->avail_out == 0, this function must be called again
with the same value of the flush parameter and more output space (updated
strm->avail_out), until the flush is complete (librock_z_deflate returns with non-zero
strm->avail_out).
If the parameter flush is set to librock_Z_FINISH, pending input is processed,
pending output is flushed and librock_z_deflate returns with librock_Z_STREAM_END
(if there was enough output space) and librock_Z_OK (if this function must be called again
with librock_Z_FINISH and more output space (updated strm->avail_out) but no
more input data) The caller should repeat until it returns with librock_Z_STREAM_END
or an error.
After librock_z_deflate has returned librock_Z_STREAM_END, the only possible operations on the
stream are librock_z_deflateReset or librock_z_deflateEnd.
librock_Z_FINISH can be used immediately after librock_z_deflateInit() if all the compression
is to be done in a single step. In this case, strm->avail_out must be at least
0.1% larger than avail_in plus 12 bytes. If librock_z_deflate does not return
librock_Z_STREAM_END, then it must be called again as described above.
librock_z_deflate() sets strm->adler to the librock_z_adler32 checksum of all input read
so far (that is, strm->total_in bytes).
librock_z_deflate() may update strm->data_type if it can make a good guess about
the input data type (librock_Z_ASCII or librock_Z_BINARY). In doubt, the data is considered
binary. This field is only for information purposes and does not affect
the compression algorithm in any manner.
librock_z_deflate() returns librock_Z_OK if some progress has been made (more input
processed or more output produced), librock_Z_STREAM_END if all input has been
consumed and all output has been produced (only when flush is set to
librock_Z_FINISH), librock_Z_STREAM_ERROR if the stream state was inconsistent (for example
if next_in or next_out was NULL ), librock_Z_BUF_ERROR if no progress is possible
(for example strm->avail_in or strm->avail_out was zero).
int
librock_z_deflateEnd (librock_z_streamp strm);
-
All dynamically allocated data structures for this stream are freed.
This function discards any unprocessed input and does not flush any
pending output.
librock_z_deflateEnd returns librock_Z_OK if success, librock_Z_STREAM_ERROR if the
stream state was inconsistent, librock_Z_DATA_ERROR if the stream was freed
prematurely (some input or output was discarded). In the error case,
strm->msg may be set but then points to a static string (which must not be
deallocated).
int
librock_z_deflateSetDictionary (librock_z_streamp strm,
const librock_z_Bytef *dictionary,
librock_z_uInt dictLength);
-
Initializes the compression dictionary from the given byte sequence
without producing any compressed output. This function must be called
immediately after
librock_z_deflateInit() , librock_z_deflateInit2 or librock_z_deflateReset() , before any
call of librock_z_deflate. The compressor and decompressor must use exactly the same
dictionary (see librock_z_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 towards 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
librock_z_deflateInit() or librock_z_deflateInit2() , a part of the dictionary may in effect be
discarded, for example if the dictionary is larger than the window size in
librock_z_deflate or deflate2. Thus the strings most likely to be useful should be
put at the end of the dictionary, not at the front.
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.)
librock_z_deflateSetDictionary() returns librock_Z_OK if success, or librock_Z_STREAM_ERROR if a
parameter is invalid (such as NULL dictionary) or the stream state is
inconsistent (for example if librock_z_deflate() has already been called for this stream
or if the compression method is bsort ). librock_z_deflateSetDictionary() does not
perform any compression: this will be done by librock_z_deflate() .
int
librock_z_deflateCopy (librock_z_streamp dest,
librock_z_streamp source);
-
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 pre-processing the input
data with a filter. The streams that will be discarded should then be freed
by calling librock_z_deflateEnd(). Note that librock_z_deflateCopy duplicates the internal
compression state which can be quite large, so this strategy is slow and
can consume lots of memory.
librock_z_deflateCopy() returns librock_Z_OK if success, librock_Z_MEM_ERROR if there was not
enough memory, librock_Z_STREAM_ERROR if the source stream state was inconsistent
(such as strm->zalloc being NULL). strm->msg is left unchanged in both source and
destination.
int
librock_z_deflateReset (librock_z_streamp strm);
-
This function is equivalent to
librock_z_deflateEnd() followed by librock_z_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 librock_z_deflateInit2() .
librock_z_deflateReset() returns librock_Z_OK if success, or librock_Z_STREAM_ERROR if the source
stream state was inconsistent (such as strm->zalloc or state being NULL).
int
librock_z_deflateParams (librock_z_streamp strm,
int level,
int strategy);
-
Dynamically update the compression level and compression strategy. The
interpretation of level and strategy is as in
librock_z_deflateInit2() . This can be
used to switch between compression and straight copy of the input data, or
to switch to a different kind 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 librock_z_deflate() .
Before the call of librock_z_deflateParams() , the stream state must be set as for
a call of librock_z_deflate() , since the currently available input may have to
be compressed and flushed. In particular, strm->avail_out must be non-zero.
librock_z_deflateParams() returns librock_Z_OK if success, librock_Z_STREAM_ERROR if the source
stream state was inconsistent or if a parameter was invalid, librock_Z_BUF_ERROR
if strm->avail_out was zero.
const char *
librock_z_zError (int err);
- allow conversion of error code to string for
librock_z_compress() and
librock_z_uncompress(). For most other functions strm->msg is already set.
Verbatim copying and distribution of this generated page is permitted in any medium provided that no changes are made.
(The source of this manual page may be covered by a more permissive license which allows modifications.)
