From e2abcdca396661cbe0ae2ddb13d5c2b85682c13a Mon Sep 17 00:00:00 2001 From: Cem Keylan Date: Fri, 16 Oct 2020 17:41:25 +0300 Subject: initial commit --- lib/libz/compress.cat3 | 1556 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1556 insertions(+) create mode 100644 lib/libz/compress.cat3 (limited to 'lib/libz/compress.cat3') diff --git a/lib/libz/compress.cat3 b/lib/libz/compress.cat3 new file mode 100644 index 0000000..bcd9add --- /dev/null +++ b/lib/libz/compress.cat3 @@ -0,0 +1,1556 @@ +COMPRESS(3) BSD Library Functions Manual COMPRESS(3) + +NAME + compress, zlibVersion, deflateInit, deflate, deflateEnd, inflateInit, + inflate, inflateEnd, deflateInit2, deflateSetDictionary, deflateCopy, + deflateReset, deflateParams, deflateTune, deflateBound, deflatePrime, + deflateSetHeader, inflateInit2, inflateSetDictionary, inflateSync, + inflateCopy, inflateReset, inflatePrime, inflateGetHeader, + inflateBackInit, inflateBack, inflateBackEnd, zlibCompileFlags, + compress2, compressBound, uncompress, gzopen, gzdopen, gzsetparams, + gzread, gzwrite, gzprintf, gzputs, gzgets, gzputc, gzgetc, gzungetc, + gzflush, gzseek, gzrewind, gztell, gzeof, gzdirect, gzclose, gzerror, + gzclearerr, adler32, adler32_combine, crc32, crc32_combine -- zlib gen- + eral purpose compression library + +SYNOPSIS + #include  + + Basic functions + + const char * + zlibVersion(void); + + int + deflateInit(z_streamp strm, int level); + + int + deflate(z_streamp strm, int flush); + + int + deflateEnd(z_streamp strm); + + int + inflateInit(z_streamp strm); + + int + inflate(z_streamp strm, int flush); + + int + inflateEnd(z_streamp strm); + + Advanced functions + + int + deflateInit2(z_streamp strm, int level, int method, int windowBits, + int memLevel, int strategy); + + int + deflateSetDictionary(z_streamp strm, const Bytef *dictionary, + uInt dictLength); + + int + deflateCopy(z_streamp dest, z_streamp source); + + int + deflateReset(z_streamp strm); + + int + deflateParams(z_streamp strm, int level, int strategy); + + int + deflateTune(z_streamp strm, int good_length, int max_lazy, + int nice_length, int max_chain); + + uLong + deflateBound(z_streamp strm, uLong sourceLen); + + int + deflatePrime(z_streamp strm, int bits, int value); + + int + deflateSetHeader(z_streamp strm, gz_headerp head); + + int + inflateInit2(z_streamp strm, int windowBits); + + int + inflateSetDictionary(z_streamp strm, const Bytef *dictionary, + uInt dictLength); + + int + inflateSync(z_streamp strm); + + int + inflateCopy(z_streamp dst, z_streamp source); + + int + inflateReset(z_streamp strm); + + int + inflatePrime(z_streamp strm, int bits, int value); + + int + inflateGetHeader(z_streamp strm, gz_headerp head); + + int + inflateBackInit(z_stream *strm, int windowBits, + unsigned char FAR *window); + + int + inflateBack(z_stream *strm, in_func in, void FAR *in_desc, out_func out, + void FAR *out_desc); + + int + inflateBackEnd(z_stream *strm); + + uLong + zlibCompileFlags(void); + + Utility functions + + typedef voidp gzFile; + + int + compress(Bytef *dest, uLongf *destLen, const Bytef *source, + uLong sourceLen); + + int + compress2(Bytef *dest, uLongf *destLen, const Bytef *source, + uLong sourceLen, int level); + + uLong + compressBound(uLong sourceLen); + + int + uncompress(Bytef *dest, uLongf *destLen, const Bytef *source, + uLong sourceLen); + + gzFile + gzopen(const char *path, const char *mode); + + gzFile + gzdopen(int fd, const char *mode); + + int + gzsetparams(gzFile file, int level, int strategy); + + int + gzread(gzFile file, voidp buf, unsigned len); + + int + gzwrite(gzFile file, voidpc buf, unsigned len); + + int + gzprintf(gzFile file, const char *format, ...); + + int + gzputs(gzFile file, const char *s); + + char * + gzgets(gzFile file, char *buf, int len); + + int + gzputc(gzFile file, int c); + + int + gzgetc(gzFile file); + + int + gzungetc(int c, gzFile file); + + int + gzflush(gzFile file, int flush); + + z_off_t + gzseek(gzFile file, z_off_t offset, int whence); + + int + gzrewind(gzFile file); + + z_off_t + gztell(gzFile file); + + int + gzeof(gzFile file); + + int + gzdirect(gzFile file); + + int + gzclose(gzFile file); + + const char * + gzerror(gzFile file, int *errnum); + + void + gzclearerr(gzFile file); + + Checksum functions + + uLong + adler32(uLong adler, const Bytef *buf, uInt len); + + uLong + adler32_combine(uLong adler1, uLong adler2, z_off_t len2); + + uLong + crc32(uLong crc, const Bytef *buf, uInt len); + + uLong + crc32_combine(uLong crc1, uLong crc2, z_off_t len2); + +DESCRIPTION + This manual page describes the zlib general purpose compression library, + version 1.2.3. + + The zlib compression library provides in-memory compression and decom- + pression functions, including integrity checks of the uncompressed data. + This version of the library supports only one compression method + (deflation) but other algorithms will be added later and will have the + same stream interface. + + Compression can be done in a single step if the buffers are large enough + (for example if an input file is mmap'ed), or can be done by repeated + calls of the compression function. In the latter case, the application + must provide more input and/or consume the output (providing more output + space) before each call. + + The compressed data format used by default by the in-memory functions is + the zlib format, which is a zlib wrapper documented in RFC 1950, wrapped + around a deflate stream, which is itself documented in RFC 1951. + + The library also supports reading and writing files in gzip(1) (.gz) for- + mat with an interface similar to that of stdio(3) using the functions + that start with "gz". The gzip format is different from the zlib format. + gzip is a gzip wrapper, documented in RFC 1952, wrapped around a deflate + stream. This library can optionally read and write gzip streams in mem- + ory as well. + + The zlib format was designed to be compact and fast for use in memory and + on communications channels. The gzip format was designed for single-file + compression on file systems, has a larger header than zlib to maintain + directory information, and uses a different, slower, check method than + zlib. + + The library does not install any signal handler. The decoder checks the + consistency of the compressed data, so the library should never crash + even in case of corrupted input. + + The functions within the library are divided into the following sections: + + - Basic functions + - Advanced functions + - Utility functions + - Checksum functions + +BASIC FUNCTIONS + const char * zlibVersion(void); + + The application can compare zlibVersion() and 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 deflateInit(z_streamp strm, int level); + + The deflateInit() function initializes the internal stream state + for compression. The fields zalloc, zfree, and opaque must be + initialized before by the caller. If zalloc and zfree are set to + Z_NULL, deflateInit() updates them to use default allocation + functions. + + The compression level must be Z_DEFAULT_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). + + Z_DEFAULT_COMPRESSION requests a default compromise between speed + and compression (currently equivalent to level 6). + + deflateInit() returns Z_OK if successful, Z_MEM_ERROR if there + was not enough memory, Z_STREAM_ERROR if level is not a valid + compression level, 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. deflateInit() does not perform any compression: this + will be done by deflate(). + + int deflate(z_streamp strm, int flush); + + 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. deflate() performs one or + both of the following actions: + + Compress more input starting at next_in and update next_in and + avail_in accordingly. If not all input can be processed (because + there is not enough room in the output buffer), next_in and + avail_in are updated and processing will resume at this point for + the next call to deflate(). + + Provide more output starting at next_out and update next_out and + avail_out accordingly. This action is forced if the parameter + flush is non-zero. Forcing flush frequently degrades the com- + pression ratio, so this parameter should be set only when neces- + sary (in interactive applications). Some output may be provided + even if flush is not set. + + Before the call to 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 avail_in or avail_out + accordingly; 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 (avail_out == 0), or after + each call to deflate(). If deflate() returns Z_OK and with zero + avail_out, it must be called again after making room in the out- + put buffer because there might be more output pending. + + Normally the parameter flush is set to Z_NO_FLUSH, which allows + deflate() to decide how much data to accumulate before producing + output, in order to maximise compression. + + If the parameter flush is set to 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, 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 Z_FULL_FLUSH, all output is flushed as with + Z_SYNC_FLUSH, and the compression state is reset so that decom- + pression can restart from this point if previous compressed data + has been damaged or if random access is desired. Using + Z_FULL_FLUSH too often can seriously degrade compression. + + If deflate() returns with avail_out == 0, this function must be + called again with the same value of the flush parameter and more + output space (updated avail_out), until the flush is complete + (deflate() returns with non-zero avail_out). In the case of a + Z_FULL_FLUSH or a Z_SYNC_FLUSH, make sure that avail_out is + greater than six to avoid repeated flush markers due to avail_out + == 0 on return. + + If the parameter flush is set to Z_FINISH, pending input is pro- + cessed, pending output is flushed and deflate() returns with + Z_STREAM_END if there was enough output space; if deflate() re- + turns with Z_OK, this function must be called again with Z_FINISH + and more output space (updated avail_out but no more input data, + until it returns with Z_STREAM_END or an error. After deflate() + has returned Z_STREAM_END, the only possible operations on the + stream are deflateReset() or deflateEnd(). + + Z_FINISH can be used immediately after deflateInit() if all the + compression is to be done in a single step. In this case, + avail_out must be at least the value returned by deflateBound() + (see below). If deflate() does not return Z_STREAM_END, then it + must be called again as described above. + + deflate() sets strm->adler to the Adler-32 checksum of all input + read so far (that is, total_in bytes). + + deflate() may update strm->data_type if it can make a good guess + about the input data type (Z_BINARY or Z_TEXT). If in doubt, the + data is considered binary. This field is only for information + purposes and does not affect the compression algorithm in any + manner. + + deflate() returns Z_OK if some progress has been made (more input + processed or more output produced), Z_STREAM_END if all input has + been consumed and all output has been produced (only when flush + is set to Z_FINISH), Z_STREAM_ERROR if the stream state was in- + consistent (for example, if next_in or next_out was NULL), + Z_BUF_ERROR if no progress is possible (for example, avail_in or + avail_out was zero). Note that Z_BUF_ERROR is not fatal, and + deflate() can be called again with more input and more output + space to continue processing. + + int deflateEnd(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. + + deflateEnd() returns Z_OK if successful, Z_STREAM_ERROR if the + stream state was inconsistent, Z_DATA_ERROR if the stream was + freed prematurely (some input or output was discarded). In the + error case, msg may be set but then points to a static string + (which must not be deallocated). + + int inflateInit(z_streamp strm); + The inflateInit() function initializes the internal stream state + for decompression. The fields next_in, avail_in, zalloc, zfree, + and opaque must be initialized before by the caller. If next_in + is not Z_NULL and avail_in is large enough (the exact value + depends on the compression method), inflateInit() determines the + compression method from the zlib header and allocates all data + structures accordingly; otherwise the allocation will be deferred + to the first call to inflate(). If zalloc and zfree are set to + Z_NULL, inflateInit() updates them to use default allocation + functions. + + inflateInit() returns Z_OK if successful, Z_MEM_ERROR if there + was not enough memory, Z_VERSION_ERROR if the zlib library ver- + sion is incompatible with the version assumed by the caller. msg + is set to null if there is no error message. inflateInit() does + not perform any decompression apart from reading the zlib header + if present: this will be done by inflate(). (So next_in and + avail_in may be modified, but next_out and avail_out are un- + changed.) + + int inflate(z_streamp strm, int flush); + inflate() decompresses 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. inflate() performs one or + both of the following actions: + + Decompress more input starting at next_in and update next_in and + avail_in accordingly. If not all input can be processed (because + there is not enough room in the output buffer), next_in is up- + dated and processing will resume at this point for the next call + to inflate(). + + Provide more output starting at next_out and update next_out and + avail_out accordingly. inflate() provides as much output as pos- + sible, until there is no more input data or no more space in the + output buffer (see below about the flush parameter). + + Before the call to inflate(), the application should ensure that + at least one of the actions is possible, by providing more input + and/or consuming more output, and updating the next_* and avail_* + values accordingly. The application can consume the uncompressed + output when it wants, for example when the output buffer is full + (avail_out == 0), or after each call to inflate(). If inflate() + returns Z_OK and with zero avail_out, it must be called again af- + ter making room in the output buffer because there might be more + output pending. + + The flush parameter of inflate() can be Z_NO_FLUSH, Z_SYNC_FLUSH, + Z_FINISH, or Z_BLOCK. Z_SYNC_FLUSH requests that inflate() flush + as much output as possible to the output buffer. Z_BLOCK re- + quests that inflate() stop if and when it gets to the next de- + flate block boundary. When decoding the zlib or gzip format, + this will cause inflate() to return immediately after the header + and before the first block. When doing a raw inflate, inflate() + will go ahead and process the first block, and will return when + it gets to the end of that block, or when it runs out of data. + + The Z_BLOCK option assists in appending to or combining deflate + streams. Also to assist in this, on return inflate() will set + strm->data_type to the number of unused bits in the last byte + taken from strm->next_in, plus 64 if inflate() is currently de- + coding the last block in the deflate stream, plus 128 if + inflate() returned immediately after decoding an end-of-block + code or decoding the complete header up to just before the first + byte of the deflate stream. The end-of-block will not be indi- + cated until all of the uncompressed data from that block has been + written to strm->next_out. The number of unused bits may in gen- + eral be greater than seven, except when bit 7 of data_type is + set, in which case the number of unused bits will be less than + eight. + + inflate() should normally be called until it returns Z_STREAM_END + or an error. However if all decompression is to be performed in + a single step (a single call to inflate), the parameter flush + should be set to Z_FINISH. In this case all pending input is + processed and all pending output is flushed; avail_out must be + large enough to hold all the uncompressed data. (The size of the + uncompressed data may have been saved by the compressor for this + purpose.) The next operation on this stream must be inflateEnd() + to deallocate the decompression state. The use of Z_FINISH is + never required, but can be used to inform inflate() that a faster + approach may be used for the single inflate() call. + + In this implementation, inflate() always flushes as much output + as possible to the output buffer, and always uses the faster ap- + proach on the first call. So the only effect of the flush param- + eter in this implementation is on the return value of inflate(), + as noted below, or when it returns early because Z_BLOCK is used. + + If a preset dictionary is needed after this call (see + inflateSetDictionary() below), inflate() sets strm->adler to the + Adler-32 checksum of the dictionary chosen by the compressor and + returns Z_NEED_DICT; otherwise it sets strm->adler to the + Adler-32 checksum of all output produced so far (that is, + total_out bytes) and returns Z_OK, Z_STREAM_END or an error code + as described below. At the end of the stream, inflate() checks + that its computed Adler-32 checksum is equal to that saved by the + compressor and returns Z_STREAM_END only if the checksum is cor- + rect. + + inflate() will decompress and check either zlib-wrapped or gzip- + wrapped deflate data. The header type is detected automatically. + Any information contained in the gzip header is not retained, so + applications that need that information should instead use raw + inflate; see inflateInit2() below, or inflateBack() and perform + their own processing of the gzip header and trailer. + + inflate() returns Z_OK if some progress has been made (more input + processed or more output produced), Z_STREAM_END if the end of + the compressed data has been reached and all uncompressed output + has been produced, Z_NEED_DICT if a preset dictionary is needed + at this point, Z_DATA_ERROR if the input data was corrupted (in- + put stream not conforming to the zlib format or incorrect check + value), Z_STREAM_ERROR if the stream structure was inconsistent + (for example, if next_in or next_out was NULL), Z_MEM_ERROR if + there was not enough memory, Z_BUF_ERROR if no progress is possi- + ble or if there was not enough room in the output buffer when + Z_FINISH is used. Note that Z_BUF_ERROR is not fatal, and + inflate() can be called again with more input and more output + space to continue compressing. If Z_DATA_ERROR is returned, the + application may then call inflateSync() to look for a good com- + pression block if a partial recovery of the data is desired. + + int inflateEnd(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. + + inflateEnd() returns Z_OK if successful, or Z_STREAM_ERROR if the + stream state was inconsistent. In the error case, msg may be set + but then points to a static string (which must not be + deallocated). + +ADVANCED FUNCTIONS + The following functions are needed only in some special applications. + + int deflateInit2(z_streamp strm, int level, int method, int windowBits, + int memLevel, int strategy); + + This is another version of deflateInit() with more compression + options. The 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 pa- + rameter result in better compression at the expense of memory us- + age. 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 gen- + erate raw deflate data with no zlib header or trailer, and will + not compute an Adler-32 check value. + + windowBits can also be greater than 15 for optional gzip encod- + ing. 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 com- + ment, 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 allo- + cated for the internal compression state. memLevel=1 uses mini- + mum 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 and Z_HUFFMAN_ONLY. Z_RLE is designed to be almost as + fast as Z_HUFFMAN_ONLY, but gives better compression for PNG im- + age 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 appli- + cations. + + deflateInit2() returns Z_OK if successful, Z_MEM_ERROR if there + was not enough memory, Z_STREAM_ERROR if a parameter is invalid + (such as an invalid method). msg is set to null if there is no + error message. deflateInit2() does not perform any compression: + this will be done by deflate(). + + int deflateSetDictionary(z_streamp strm, const Bytef *dictionary, uInt + dictLength); + + Initializes the compression dictionary from the given byte se- + quence without producing any compressed output. This function + must be called immediately after deflateInit(), deflateInit2(), + or deflateReset(), before any call to 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 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 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(). Thus the + strings most likely to be useful should be put at the end of the + dictionary, not at the front. In addition, the current implemen- + tation 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 Adler-32 + value of the dictionary; the decompressor may later use this + value to determine which dictionary has been used by the compres- + sor. (The Adler-32 value applies to the whole dictionary even if + only a subset of the dictionary is actually used by the compres- + sor.) If a raw deflate was requested, then the Adler-32 value is + not computed and strm->adler is not set. + + deflateSetDictionary() returns Z_OK if successful, 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 com- + pression method is bsort). deflateSetDictionary() does not per- + form any compression: this will be done by deflate(). + + int deflateCopy(z_streamp dest, z_streamp source); + + The deflateCopy() function sets the destination stream as a com- + plete 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 deflateEnd(). Note + that deflateCopy() duplicates the internal compression state + which can be quite large, so this strategy is slow and can con- + sume lots of memory. + + deflateCopy() returns Z_OK if successful, 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 un- + changed in both source and destination. + + int deflateReset(z_streamp strm); + + 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(). + + deflateReset() returns Z_OK if successful, or Z_STREAM_ERROR if + the source stream state was inconsistent (such as zalloc or state + being NULL). + + int deflateParams(z_streamp strm, int level, int strategy); + + The deflateParams() function dynamically updates the compression + level and compression strategy. The interpretation of level and + strategy is as in deflateInit2(). This can be used to switch be- + tween 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 avail- + able so far is compressed with the old level (and may be + flushed); the new level will take effect only at the next call to + deflate(). + + Before the call to deflateParams(), the stream state must be set + as for a call to deflate(), since the currently available input + may have to be compressed and flushed. In particular, + strm->avail_out must be non-zero. + + deflateParams() returns Z_OK if successful, Z_STREAM_ERROR if the + source stream state was inconsistent or if a parameter was in- + valid, or Z_BUF_ERROR if strm->avail_out was zero. + + int deflateTune(z_streamp strm, int good_length, int max_lazy, int + nice_length, int max_chain) + + 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(), and returns Z_OK on success, or Z_STREAM_ERROR + for an invalid deflate stream. + + uLong deflateBound(z_streamp strm, uLong sourceLen) + + deflateBound() returns an upper bound on the compressed size af- + ter 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(). + + int deflatePrime(z_streamp strm, int bits, int value) + + 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. + + deflatePrime() returns Z_OK if successful, or Z_STREAM_ERROR if + the source stream state was inconsistent. + + int deflateSetHeader(z_streamp strm, gz_headerp head) + + 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 (xflag 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(1) do not support header CRCs, and will report + that it is a "multi-part gzip file" and give up. + + If deflateSetHeader() is not used, the default gzip header has + text false, the time set to zero, and os set to 255, with no ex- + tra, name, or comment fields. The gzip header is returned to the + default state by deflateReset(). + + deflateSetHeader() returns Z_OK if successful, or Z_STREAM_ERROR + if the source stream state was inconsistent. + + int inflateInit2(z_streamp strm, int windowBits); + + 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 -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 val- + ues 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 com- + pressed data, it is recommended that a check value such as an + Adler-32 or a crc32 be applied to the uncompressed data as is + done 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 decod- + ing. 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() returns Z_OK if successful, Z_MEM_ERROR if there + was not enough memory, Z_STREAM_ERROR if a parameter is invalid + (such as a null strm). msg is set to null if there is no error + message. inflateInit2() does not perform any decompression apart + from reading the zlib header if present: this will be done by + inflate(). (So next_in and avail_in may be modified, but + next_out and avail_out are unchanged.) + + int inflateSetDictionary(z_streamp strm, const Bytef *dictionary, uInt + dictLength); + + Initializes the decompression dictionary from the given uncom- + pressed byte sequence. This function must be called immediately + after a call to inflate() if that call returned Z_NEED_DICT. The + dictionary chosen by the compressor can be determined from the + Adler-32 value returned by that call to inflate(). The compres- + sor and decompressor must use exactly the same dictionary (see + deflateSetDictionary()). For raw inflate, this function can be + called immediately after inflateInit2() or inflateReset() and be- + fore any call to inflate() to set the dictionary. The applica- + tion must ensure that the dictionary that was used for compres- + sion is provided. + + inflateSetDictionary() returns Z_OK if successful, 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 + doesn't match the expected one (incorrect Adler-32 value). + inflateSetDictionary() does not perform any decompression: this + will be done by subsequent calls of inflate(). + + int inflateSync(z_streamp strm); + + Skips invalid compressed data until a full flush point (see above + the description of deflate() with Z_FULL_FLUSH) can be found, or + until all available input is skipped. No output is provided. + + 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 applica- + tion may repeatedly call inflateSync(), providing more input each + time, until success or end of the input data. + + int inflateCopy(z_streamp dest, z_streamp source) + + 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. + + 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 dest. + + int inflateReset(z_streamp strm); + + 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(). + + inflateReset() returns Z_OK if successful, or Z_STREAM_ERROR if + the source stream state was inconsistent (such as zalloc or state + being NULL). + + int inflatePrime(z_stream strm, int bits, int value) + + This function inserts bits in the inflate input stream. The in- + tent 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. + + inflatePrime() returns Z_OK if successful, or Z_STREAM_ERROR if + the source stream state was inconsistent. + + int inflateGetHeader(z_streamp strm, gz_headerp head) + + 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 decom- + pressed. + + 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. Once done is true, extra_len contains the ac- + tual 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 charac- + ters 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 + simply discarded. The header is always checked for validity, in- + cluding 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. + + inflateGetHeader() returns Z_OK if successful, or Z_STREAM_ERROR + if the source stream state was inconsistent. + + int inflateBackInit(z_stream *strm, int windowBits, unsigned char FAR + *window) + + 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 rou- + tines are used. windowBits is the base two logarithm of the win- + dow size, in the range 8..15. window is a caller supplied buffer + of that size. Except for special applications where it is as- + sured 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. + + inflateBackInit() will return 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. + + int inflateBack(z_stream *strm, in_func in, void FAR *in_desc, out_func + out, void FAR *out_desc) + + inflateBack() does a raw inflate with a single call using a call- + back interface for input and output. This is more efficient than + inflate() for file I/O applications in that it avoids copying be- + tween the output and the sliding window by simply making the win- + dow itself the output buffer. This function trusts the applica- + tion to not change the output buffer passed by the output func- + tion, 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, hence 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 de- + flate stream and writes out all of the uncompressed data, or un- + til 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 non-zero on failure. If out() returns non- + zero, 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 win- + dow size. Any non-zero 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. Therefore 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, in- + put will initially be taken from strm->next_in[0 .. + strm->avail_in - 1]. + + The in_desc and out_desc parameters of inflateBack() are 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. The return values of inflateBack() can be + 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 ini- + tialized. In the case of 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 is not Z_NULL, + then the Z_BUF_ERROR was due to out() returning non-zero. (in() + will always be called before out(), so strm->next_in is assured + to be defined if out() returns non-zero.) Note that + inflateBack() cannot return Z_OK. + + int inflateBackEnd(z_stream *strm) + + All memory allocated by inflateBackInit() is freed. + + inflateBackEnd() returns Z_OK on success, or Z_STREAM_ERROR if + the stream state was inconsistent. + + uLong zlibCompileFlags(void) + + This function returns flags indicating compile-time options. + + Type sizes, two bits each: + + 00 16 bits + 01 32 bits + 10 64 bits + 11 other: + + 1.0 size of uInt + 3.2 size of uLong + 5.4 size of voidpf (pointer) + 7.6 size of z_off_t + + Compiler, assembler, and debug options: + + 8 DEBUG + 9 ASMV or ASMINF -- use ASM code + 10 ZLIB_WINAPI -- exported functions use the WINAPI + calling convention + 11 0 (reserved) + + One-time table building (smaller code, but not thread-safe if + true): + + 12 BUILDFIXED -- build static block decoding tables + when needed + 13 DYNAMIC_CRC_TABLE -- build CRC calculation tables + when needed + 14,15 0 (reserved) + + Library content (indicates missing functionality): + + 16 NO_GZCOMPRESS -- gz* functions cannot compress (to + avoid linking deflate code when not needed) + 17 NO_GZIP -- deflate can't write gzip streams, and + inflate can't detect and decode gzip streams (to + avoid linking CRC code) + 18-19 0 (reserved) + + Operation variations (changes in library functionality): + + 20 PKZIP_BUG_WORKAROUND -- slightly more permissive + inflate + 21 FASTEST -- deflate algorithm with only one, lowest + compression level + 22,23 0 (reserved) + + The sprintf variant used by gzprintf (zero is best): + + 24 0 = vs*, 1 = s* -- 1 means limited to 20 arguments + after the format + 25 0 = *nprintf, 1 = *printf -- 1 means gzprintf() not + secure! + 26 0 = returns value, 1 = void -- 1 means inferred + string length returned + + Remainder: + + 27-31 0 (reserved) + +UTILITY FUNCTIONS + The following utility functions are implemented on top of the basic + stream-oriented functions. To simplify the interface, some default op- + tions 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 compress(Bytef *dest, uLongf *destLen, const Bytef *source, uLong + sourceLen); + + The compress() function 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 the value returned by + compressBound(sourcelen). 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 Z_OK if successful, Z_MEM_ERROR if there was + not enough memory, or Z_BUF_ERROR if there was not enough room in + the output buffer. + + int compress2(Bytef *dest, uLongf *destLen, const Bytef *source, uLong + sourceLen, int level); + + The compress2() function compresses the source buffer into the + destination buffer. The level parameter has the same meaning as + in 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 the value returned by + compressBound(sourceLen). Upon exit, destLen is the actual size + of the compressed buffer. + + compress2() returns Z_OK if successful, Z_MEM_ERROR if there was + not enough memory, Z_BUF_ERROR if there was not enough room in + the output buffer, or Z_STREAM_ERROR if the level parameter is + invalid. + + int compressBound(uLong sourceLen) + + compressBound() returns an upper bound on the compressed size af- + ter compress() or compress2() on sourceLen bytes. It would be + used before a compress() or compress2() call to allocate the des- + tination buffer. + + int uncompress(Bytef *dest, uLongf *destLen, const Bytef *source, uLong + sourceLen); + + The uncompress() function decompresses 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 large enough to hold the entire uncom- + pressed data. (The size of the uncompressed data must have been + saved previously by the compressor and transmitted to the decom- + pressor by some mechanism outside the scope of this compression + library.) Upon exit, destLen is the actual size of the com- + pressed buffer. This function can be used to decompress a whole + file at once if the input file is mmap'ed. + + uncompress() returns Z_OK if successful, Z_MEM_ERROR if there was + not enough memory, Z_BUF_ERROR if there was not enough room in + the output buffer, or Z_DATA_ERROR if the input data was cor- + rupted or incomplete. + + gzFile gzopen(const char *path, const char *mode); + + The gzopen() function opens a gzip (.gz) file for reading or + writing. The mode parameter is as in fopen(3) ("rb" or "wb") but + can also include a compression level (wb9) or a strategy: `f' for + filtered data, as in "wb6f"; `h' for Huffman only compression, as + in "wb1h", or `R' for run-length encoding as in "wb1R". (See the + description of deflateInit2() for more information about the + strategy parameter.) + + gzopen() can be used to read a file which is not in gzip format; + in this case gzread() will directly read from the file without + decompression. + + gzopen() returns NULL if the file could not be opened or if there + was insufficient memory to allocate the (de)compression state; + errno can be checked to distinguish the two cases (if errno is + zero, the zlib error is Z_MEM_ERROR). + + gzFile gzdopen(int fd, const char *mode); + + The gzdopen() function associates a gzFile with the file descrip- + tor fd. File descriptors are obtained from calls like open(2), + dup(2), creat(3), pipe(2), or fileno(3) (if the file has been + previously opened with fopen(3)). The mode parameter is as in + gzopen(). + + The next call to gzclose() on the returned gzFile will also close + the file descriptor fd, just like fclose(fdopen(fd), mode) closes + the file descriptor fd. If you want to keep fd open, use gz- + dopen(dup(fd), mode). + + gzdopen() returns NULL if there was insufficient memory to allo- + cate the (de)compression state. + + int gzsetparams(gzFile file, int level, int strategy); + + The gzsetparams() function dynamically updates the compression + level or strategy. See the description of deflateInit2() for the + meaning of these parameters. + + gzsetparams() returns Z_OK if successful, or Z_STREAM_ERROR if + the file was not opened for writing. + + int gzread(gzFile file, voidp buf, unsigned len); + + The gzread() function reads the given number of uncompressed + bytes from the compressed file. If the input file was not in + gzip format, gzread() copies the given number of bytes into the + buffer. + + gzread() returns the number of uncompressed bytes actually read + (0 for end of file, -1 for error). + + int gzwrite(gzFile file, voidpc buf, unsigned len); + + The gzwrite() function writes the given number of uncompressed + bytes into the compressed file. gzwrite() returns the number of + uncompressed bytes actually written (0 in case of error). + + int gzprintf(gzFile file, const char *format, ...); + + The gzprintf() function converts, formats, and writes the args to + the compressed file under control of the format string, as in + fprintf(3). gzprintf() returns the number of uncompressed bytes + actually written (0 in case of error). The number of uncom- + pressed bytes written is limited to 4095. The caller should make + sure that this limit is not exceeded. If it is exceeded, then + gzprintf() will return an error (0) with nothing written. In + this case, there may also be a buffer overflow with unpredictable + consequences, which is possible only if zlib was compiled with + the insecure functions sprintf() or vsprintf() because the secure + snprintf() or vsnprintf() functions were not available. + + int gzputs(gzFile file, const char *s); + + The gzputs() function writes the given null-terminated string to + the compressed file, excluding the terminating null character. + + gzputs() returns the number of characters written, or -1 in case + of error. + + char * gzgets(gzFile file, char *buf, int len); + + The gzgets() function reads bytes from the compressed file until + len-1 characters are read, or a newline character is read and + transferred to buf, or an end-of-file condition is encountered. + The string is then terminated with a null character. + + gzgets() returns buf, or Z_NULL in case of error. + + int gzputc(gzFile file, int c); + + The gzputc() function writes c, converted to an unsigned char, + into the compressed file. gzputc() returns the value that was + written, or -1 in case of error. + + int gzgetc(gzFile file); + + The gzgetc() function reads one byte from the compressed file. + gzgetc() returns this byte or -1 in case of end of file or error. + + int gzungetc(int c, gzFile file) + + Push one character back onto the stream to be read again later. + Only one character of push-back is allowed. gzungetc() returns + the character pushed, or -1 on failure. gzungetc() will fail if + a character has been pushed but not read yet, or if c is -1. The + pushed character will be discarded if the stream is repositioned + with gzseek() or gzrewind(). + + int gzflush(gzFile file, int flush); + + The gzflush() function flushes all pending output into the com- + pressed file. The parameter flush is as in the deflate() func- + tion. The return value is the zlib error number (see function + gzerror() below). gzflush() returns Z_OK if the flush parameter + is Z_FINISH and all output could be flushed. + + gzflush() should be called only when strictly necessary because + it can degrade compression. + + z_off_t gzseek(gzFile file, z_off_t offset, int whence); + + Sets the starting position for the next gzread() or gzwrite() on + the given compressed file. The offset represents a number of + bytes in the uncompressed data stream. The whence parameter is + defined as in lseek(2); the value SEEK_END is not supported. + + If the file is opened for reading, this function is emulated but + can be extremely slow. If the file is opened for writing, only + forward seeks are supported; gzseek() then compresses a sequence + of zeroes up to the new starting position. + + gzseek() returns the resulting offset location as measured in + bytes from the beginning of the uncompressed stream, or -1 in + case of error, in particular if the file is opened for writing + and the new starting position would be before the current posi- + tion. + + int gzrewind(gzFile file); + + The gzrewind() function rewinds the given file. This function is + supported only for reading. + + gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET). + + z_off_t gztell(gzFile file); + + The gztell() function returns the starting position for the next + gzread() or gzwrite() on the given compressed file. This posi- + tion represents a number of bytes in the uncompressed data + stream. + + gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR). + + int gzeof(gzFile file); + + The gzeof() function returns 1 when EOF has previously been de- + tected reading the given input stream, otherwise zero. + + int gzdirect(gzFile file); + + The gzdirect() function returns 1 if the file is being read di- + rectly without compression; otherwise it returns 0. + + int gzclose(gzFile file); + + The gzclose() function flushes all pending output if necessary, + closes the compressed file and deallocates all the (de)compres- + sion state. The return value is the zlib error number (see func- + tion gzerror() below). + + const char * gzerror(gzFile file, int *errnum); + + The gzerror() function returns the error message for the last er- + ror which occurred on the given compressed file. errnum is set + to the zlib error number. If an error occurred in the file sys- + tem and not in the compression library, errnum is set to Z_ERRNO + and the application may consult errno to get the exact error + code. + + void gzclearerr(gzFile file) + Clears the error and end-of-file flags for file. This is analo- + gous to the clearerr() function in stdio. This is useful for + continuing to read a gzip file that is being written concur- + rently. + +CHECKSUM FUNCTIONS + These functions are not related to compression but are exported anyway + because they might be useful in applications using the compression li- + brary. + + uLong adler32(uLong adler, const Bytef *buf, uInt len); + The adler32() function updates a running Adler-32 checksum with + the bytes buf[0..len-1] and returns the updated checksum. If buf + is NULL, this function returns the required initial value for the + checksum. + + An Adler-32 checksum is almost as reliable as a CRC32 but can be + computed much faster. Usage example: + + uLong adler = adler32(0L, Z_NULL, 0); + + while (read_buffer(buffer, length) != EOF) { + adler = adler32(adler, buffer, length); + } + if (adler != original_adler) error(); + + uLong adler32_combine(uLong adler1, uLong adler2, z_off_t len2) + + The adler32_combine() function combines two Adler-32 checksums + into one. For two sequences of bytes, seq1 and seq2 with lengths + len1 and len2, Adler-32 checksums are calculated for each, adler1 + and adler2. adler32_combine() returns the Adler-32 checksum of + seq1 and seq2 concatenated, requiring only adler1, adler2, and + len2. + + uLong crc32(uLong crc, const Bytef *buf, uInt len); + + The crc32() function updates a running CRC-32 with the bytes + buf[0..len-1] and returns the updated CRC-32. If buf is NULL, + this function returns the required initial value for the CRC. + Pre- and post-conditioning (one's complement) is performed within + this function so it shouldn't be done by the application. Usage + example: + + uLong crc = crc32(0L, Z_NULL, 0); + + while (read_buffer(buffer, length) != EOF) { + crc = crc32(crc, buffer, length); + } + if (crc != original_crc) error(); + + uLong crc32_combine(uLong crc1, uLong crc2, z_off_t len2) + + The crc32_combine() function combines two CRC-32 check values + into one. For two sequences of bytes, seq1 and seq2 with lengths + len1 and len2, CRC-32 check values are calculated for each, crc1 + and crc2. crc32_combine() returns the CRC-32 check value of seq1 + and seq2 concatenated, requiring only crc1, crc2, and len2. + +STRUCTURES + struct internal_state; + + typedef struct z_stream_s { + Bytef *next_in; /* next input byte */ + uInt avail_in; /* number of bytes available at next_in */ + off_t total_in; /* total nb of input bytes read so far */ + + Bytef *next_out; /* next output byte should be put there */ + uInt avail_out; /* remaining free space at next_out */ + off_t total_out; /* total nb of bytes output so far */ + + char *msg; /* last error message, NULL if no error */ + struct internal_state FAR *state; /* not visible by applications */ + + alloc_func zalloc; /* used to allocate the internal state */ + free_func zfree; /* used to free the internal state */ + voidpf opaque; /* private data object passed to zalloc and zfree*/ + + int data_type; /* best guess about the data type: binary or text*/ + uLong adler; /* adler32 value of the uncompressed data */ + uLong reserved; /* reserved for future use */ + } z_stream; + + typedef z_stream FAR * z_streamp; + + /* + gzip header information passed to and from zlib routines. + See RFC 1952 for more details on the meanings of these fields. + */ + typedef struct gz_header_s { + int text; /* true if compressed data believed to be text */ + uLong time; /* modification time */ + int xflags; /*extra flags (not used when writing a gzip file)*/ + int os; /* operating system */ + Bytef *extra; /* pointer to extra field or Z_NULL if none */ + uInt extra_len; /* extra field length (valid if extra != Z_NULL) */ + uInt extra_max; /* space at extra (only when reading header) */ + Bytef *name; /* pointer to zero-terminated file name or Z_NULL*/ + uInt name_max; /* space at name (only when reading header) */ + Bytef *comment; /* pointer to zero-terminated comment or Z_NULL */ + uInt comm_max; /* space at comment (only when reading header) */ + int hcrc; /* true if there was or will be a header crc */ + int done; /* true when done reading gzip header (not used + when writing a gzip file) */ + } gz_header; + + typedef gz_header FAR *gz_headerp; + + The application must update next_in and avail_in when avail_in has + dropped to zero. It must update next_out and avail_out when avail_out + has dropped to zero. The application must initialize zalloc, zfree, and + opaque before calling the init function. All other fields are set by the + compression library and must not be updated by the application. + + The opaque value provided by the application will be passed as the first + parameter for calls to zalloc() and zfree(). This can be useful for cus- + tom memory management. The compression library attaches no meaning to + the opaque value. + + zalloc must return Z_NULL if there is not enough memory for the object. + If zlib is used in a multi-threaded application, zalloc and zfree must be + thread safe. + + On 16-bit systems, the functions zalloc and zfree must be able to allo- + cate exactly 65536 bytes, but will not be required to allocate more than + this if the symbol MAXSEG_64K is defined (see <zconf.h>). + + WARNING: On MSDOS, pointers returned by zalloc for objects of exactly + 65536 bytes *must* have their offset normalized to zero. The default al- + location function provided by this library ensures this (see zutil.c). + To reduce memory requirements and avoid any allocation of 64K objects, at + the expense of compression ratio, compile the library with -DMAX_WBITS=14 + (see <zconf.h>). + + The fields total_in and total_out can be used for statistics or progress + reports. After compression, total_in holds the total size of the uncom- + pressed data and may be saved for use in the decompressor (particularly + if the decompressor wants to decompress everything in a single step). + +CONSTANTS + #define Z_NO_FLUSH 0 + #define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */ + #define Z_SYNC_FLUSH 2 + #define Z_FULL_FLUSH 3 + #define Z_FINISH 4 + #define Z_BLOCK 5 + /* Allowed flush values; see deflate() and inflate() below for details */ + + #define Z_OK 0 + #define Z_STREAM_END 1 + #define Z_NEED_DICT 2 + #define Z_ERRNO (-1) + #define Z_STREAM_ERROR (-2) + #define Z_DATA_ERROR (-3) + #define Z_MEM_ERROR (-4) + #define Z_BUF_ERROR (-5) + #define Z_VERSION_ERROR (-6) + /* Return codes for the compression/decompression functions. + * Negative values are errors, + * positive values are used for special but normal events. + */ + + #define Z_NO_COMPRESSION 0 + #define Z_BEST_SPEED 1 + #define Z_BEST_COMPRESSION 9 + #define Z_DEFAULT_COMPRESSION (-1) + /* compression levels */ + + #define Z_FILTERED 1 + #define Z_HUFFMAN_ONLY 2 + #define Z_RLE 3 + #define Z_FIXED 4 + #define Z_DEFAULT_STRATEGY 0 + /* compression strategy; see deflateInit2() below for details */ + + #define Z_BINARY 0 + #define Z_TEXT 1 + #define Z_ASCII Z_TEXT /* for compatibility with 1.2.2 and earlier */ + #define Z_UNKNOWN 2 + /* Possible values of the data_type field (though see inflate()) */ + + #define Z_DEFLATED 8 + /* The deflate compression method + * (the only one supported in this version) + */ + + #define Z_NULL 0 /* for initializing zalloc, zfree, opaque */ + + #define zlib_version zlibVersion() + /* for compatibility with versions < 1.0.2 */ + +VARIOUS HACKS + deflateInit and inflateInit are macros to allow checking the zlib version + and the compiler's view of z_stream. + + int deflateInit_(z_stream strm, int level, const char *version, int + stream_size); + + int inflateInit_(z_stream strm, const char *version, int stream_size); + + int deflateInit2_(z_stream strm, int level, int method, int windowBits, + int memLevel, int strategy, const char *version, int stream_size) + + int inflateInit2_(z_stream strm, int windowBits, const char *version, int + stream_size); + + int inflateBackInit_(z_stream *strm, int windowBits, unsigned char FAR + *window, const char *version, int stream_size) + + const char * zError(int err); + + int inflateSyncPoint(z_streamp z); + + const uLongf * get_crc_table(void); + +SEE ALSO + compress(1), gzip(1) + +STANDARDS + P. Deutsch and J-L. Gailly, ZLIB Compressed Data Format Specification + version 3.3, RFC 1950, May 1996. + + P. Deutsch, DEFLATE Compressed Data Format Specification version 1.3, RFC + 1951, May 1996. + + P. Deutsch, GZIP file format specification version 4.3, RFC 1952, May + 1996. + +HISTORY + This manual page is based on an HTML version of <zlib.h> converted by + piaip <piaip@csie.ntu.edu.tw> and was converted to mdoc format by the + OpenBSD project. + +AUTHORS + Jean-loup Gailly <jloup@gzip.org> + Mark Adler <madler@alumni.caltech.edu> + +BSD March 16, 2018 BSD -- cgit v1.2.3