117651Speter/* zlib.h -- interface of the 'zlib' general purpose compression library 2313796Sdelphij version 1.2.11, January 15th, 2017 317651Speter 4313796Sdelphij Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler 517651Speter 617651Speter This software is provided 'as-is', without any express or implied 717651Speter warranty. In no event will the authors be held liable for any damages 817651Speter arising from the use of this software. 917651Speter 1017651Speter Permission is granted to anyone to use this software for any purpose, 1117651Speter including commercial applications, and to alter it and redistribute it 1217651Speter freely, subject to the following restrictions: 1317651Speter 1417651Speter 1. The origin of this software must not be misrepresented; you must not 1517651Speter claim that you wrote the original software. If you use this software 1617651Speter in a product, an acknowledgment in the product documentation would be 1717651Speter appreciated but is not required. 1817651Speter 2. Altered source versions must be plainly marked as such, and must not be 1917651Speter misrepresented as being the original software. 2017651Speter 3. This notice may not be removed or altered from any source distribution. 2117651Speter 2217651Speter Jean-loup Gailly Mark Adler 2333904Ssteve jloup@gzip.org madler@alumni.caltech.edu 2417651Speter 2517651Speter 2617651Speter The data format used by the zlib library is described by RFCs (Request for 27230837Sdelphij Comments) 1950 to 1952 in the files http://tools.ietf.org/html/rfc1950 28230837Sdelphij (zlib format), rfc1951 (deflate format) and rfc1952 (gzip format). 2917651Speter*/ 3017651Speter 31131377Stjr#ifndef ZLIB_H 32131377Stjr#define ZLIB_H 3317651Speter 3442468Speter#include "zconf.h" 3542468Speter 3617651Speter#ifdef __cplusplus 3717651Speterextern "C" { 3817651Speter#endif 3917651Speter 40313796Sdelphij#define ZLIB_VERSION "1.2.11" 41313796Sdelphij#define ZLIB_VERNUM 0x12b0 42205194Sdelphij#define ZLIB_VER_MAJOR 1 43205194Sdelphij#define ZLIB_VER_MINOR 2 44313796Sdelphij#define ZLIB_VER_REVISION 11 45206905Sdelphij#define ZLIB_VER_SUBREVISION 0 4617651Speter 47131377Stjr/* 48205194Sdelphij The 'zlib' compression library provides in-memory compression and 49205194Sdelphij decompression functions, including integrity checks of the uncompressed data. 50205194Sdelphij This version of the library supports only one compression method (deflation) 51205194Sdelphij but other algorithms will be added later and will have the same stream 52205194Sdelphij interface. 5317651Speter 54205194Sdelphij Compression can be done in a single step if the buffers are large enough, 55205194Sdelphij or can be done by repeated calls of the compression function. In the latter 56205194Sdelphij case, the application must provide more input and/or consume the output 5717651Speter (providing more output space) before each call. 5817651Speter 59205194Sdelphij The compressed data format used by default by the in-memory functions is 60145474Skientzle the zlib format, which is a zlib wrapper documented in RFC 1950, wrapped 61145474Skientzle around a deflate stream, which is itself documented in RFC 1951. 62131377Stjr 63205194Sdelphij The library also supports reading and writing files in gzip (.gz) format 64131377Stjr with an interface similar to that of stdio using the functions that start 65131377Stjr with "gz". The gzip format is different from the zlib format. gzip is a 66131377Stjr gzip wrapper, documented in RFC 1952, wrapped around a deflate stream. 6733904Ssteve 68313796Sdelphij This library can optionally read and write gzip and raw deflate streams in 69313796Sdelphij memory as well. 70145474Skientzle 71205194Sdelphij The zlib format was designed to be compact and fast for use in memory 72131377Stjr and on communications channels. The gzip format was designed for single- 73131377Stjr file compression on file systems, has a larger header than zlib to maintain 74131377Stjr directory information, and uses a different, slower check method than zlib. 75131377Stjr 76205194Sdelphij The library does not install any signal handler. The decoder checks 77205194Sdelphij the consistency of the compressed data, so the library should never crash 78313796Sdelphij even in the case of corrupted input. 7917651Speter*/ 8017651Speter 8117651Spetertypedef voidpf (*alloc_func) OF((voidpf opaque, uInt items, uInt size)); 8217651Spetertypedef void (*free_func) OF((voidpf opaque, voidpf address)); 8317651Speter 8417651Speterstruct internal_state; 8517651Speter 8617651Spetertypedef struct z_stream_s { 87230837Sdelphij z_const Bytef *next_in; /* next input byte */ 8817651Speter uInt avail_in; /* number of bytes available at next_in */ 89230837Sdelphij uLong total_in; /* total number of input bytes read so far */ 9017651Speter 91313796Sdelphij Bytef *next_out; /* next output byte will go here */ 9217651Speter uInt avail_out; /* remaining free space at next_out */ 93230837Sdelphij uLong total_out; /* total number of bytes output so far */ 9417651Speter 95230837Sdelphij z_const char *msg; /* last error message, NULL if no error */ 9617651Speter struct internal_state FAR *state; /* not visible by applications */ 9717651Speter 9817651Speter alloc_func zalloc; /* used to allocate the internal state */ 9917651Speter free_func zfree; /* used to free the internal state */ 10017651Speter voidpf opaque; /* private data object passed to zalloc and zfree */ 10117651Speter 102313796Sdelphij int data_type; /* best guess about the data type: binary or text 103313796Sdelphij for deflate, or the decoding state for inflate */ 104313796Sdelphij uLong adler; /* Adler-32 or CRC-32 value of the uncompressed data */ 10517651Speter uLong reserved; /* reserved for future use */ 10617651Speter} z_stream; 10717651Speter 10817651Spetertypedef z_stream FAR *z_streamp; 10917651Speter 11017651Speter/* 111157043Sdes gzip header information passed to and from zlib routines. See RFC 1952 112157043Sdes for more details on the meanings of these fields. 113157043Sdes*/ 114157043Sdestypedef struct gz_header_s { 115157043Sdes int text; /* true if compressed data believed to be text */ 116157043Sdes uLong time; /* modification time */ 117157043Sdes int xflags; /* extra flags (not used when writing a gzip file) */ 118157043Sdes int os; /* operating system */ 119157043Sdes Bytef *extra; /* pointer to extra field or Z_NULL if none */ 120157043Sdes uInt extra_len; /* extra field length (valid if extra != Z_NULL) */ 121157043Sdes uInt extra_max; /* space at extra (only when reading header) */ 122157043Sdes Bytef *name; /* pointer to zero-terminated file name or Z_NULL */ 123157043Sdes uInt name_max; /* space at name (only when reading header) */ 124157043Sdes Bytef *comment; /* pointer to zero-terminated comment or Z_NULL */ 125157043Sdes uInt comm_max; /* space at comment (only when reading header) */ 126157043Sdes int hcrc; /* true if there was or will be a header crc */ 127157043Sdes int done; /* true when done reading gzip header (not used 128157043Sdes when writing a gzip file) */ 129157043Sdes} gz_header; 130157043Sdes 131157043Sdestypedef gz_header FAR *gz_headerp; 132157043Sdes 133157043Sdes/* 134205194Sdelphij The application must update next_in and avail_in when avail_in has dropped 135205194Sdelphij to zero. It must update next_out and avail_out when avail_out has dropped 136205194Sdelphij to zero. The application must initialize zalloc, zfree and opaque before 137205194Sdelphij calling the init function. All other fields are set by the compression 138205194Sdelphij library and must not be updated by the application. 13917651Speter 140205194Sdelphij The opaque value provided by the application will be passed as the first 141205194Sdelphij parameter for calls of zalloc and zfree. This can be useful for custom 142205194Sdelphij memory management. The compression library attaches no meaning to the 14317651Speter opaque value. 14417651Speter 145205194Sdelphij zalloc must return Z_NULL if there is not enough memory for the object. 14633904Ssteve If zlib is used in a multi-threaded application, zalloc and zfree must be 147313796Sdelphij thread safe. In that case, zlib is thread-safe. When zalloc and zfree are 148313796Sdelphij Z_NULL on entry to the initialization function, they are set to internal 149313796Sdelphij routines that use the standard library functions malloc() and free(). 15033904Ssteve 151205194Sdelphij On 16-bit systems, the functions zalloc and zfree must be able to allocate 152205194Sdelphij exactly 65536 bytes, but will not be required to allocate more than this if 153205194Sdelphij the symbol MAXSEG_64K is defined (see zconf.h). WARNING: On MSDOS, pointers 154205194Sdelphij returned by zalloc for objects of exactly 65536 bytes *must* have their 155205194Sdelphij offset normalized to zero. The default allocation function provided by this 156205194Sdelphij library ensures this (see zutil.c). To reduce memory requirements and avoid 157205194Sdelphij any allocation of 64K objects, at the expense of compression ratio, compile 158205194Sdelphij the library with -DMAX_WBITS=14 (see zconf.h). 15917651Speter 160205194Sdelphij The fields total_in and total_out can be used for statistics or progress 161205194Sdelphij reports. After compression, total_in holds the total size of the 162313796Sdelphij uncompressed data and may be saved for use by the decompressor (particularly 163205194Sdelphij if the decompressor wants to decompress everything in a single step). 16417651Speter*/ 16517651Speter 16617651Speter /* constants */ 16717651Speter 16817651Speter#define Z_NO_FLUSH 0 169205194Sdelphij#define Z_PARTIAL_FLUSH 1 17017651Speter#define Z_SYNC_FLUSH 2 17117651Speter#define Z_FULL_FLUSH 3 17217651Speter#define Z_FINISH 4 173131377Stjr#define Z_BLOCK 5 174205194Sdelphij#define Z_TREES 6 175131377Stjr/* Allowed flush values; see deflate() and inflate() below for details */ 17617651Speter 17717651Speter#define Z_OK 0 17817651Speter#define Z_STREAM_END 1 17917651Speter#define Z_NEED_DICT 2 18017651Speter#define Z_ERRNO (-1) 18117651Speter#define Z_STREAM_ERROR (-2) 18217651Speter#define Z_DATA_ERROR (-3) 18317651Speter#define Z_MEM_ERROR (-4) 18417651Speter#define Z_BUF_ERROR (-5) 18517651Speter#define Z_VERSION_ERROR (-6) 186205194Sdelphij/* Return codes for the compression/decompression functions. Negative values 187205194Sdelphij * are errors, positive values are used for special but normal events. 18817651Speter */ 18917651Speter 19017651Speter#define Z_NO_COMPRESSION 0 19117651Speter#define Z_BEST_SPEED 1 19217651Speter#define Z_BEST_COMPRESSION 9 19317651Speter#define Z_DEFAULT_COMPRESSION (-1) 19417651Speter/* compression levels */ 19517651Speter 19617651Speter#define Z_FILTERED 1 19717651Speter#define Z_HUFFMAN_ONLY 2 198131377Stjr#define Z_RLE 3 199157043Sdes#define Z_FIXED 4 20017651Speter#define Z_DEFAULT_STRATEGY 0 20117651Speter/* compression strategy; see deflateInit2() below for details */ 20217651Speter 20317651Speter#define Z_BINARY 0 204157043Sdes#define Z_TEXT 1 205157043Sdes#define Z_ASCII Z_TEXT /* for compatibility with 1.2.2 and earlier */ 20617651Speter#define Z_UNKNOWN 2 207313796Sdelphij/* Possible values of the data_type field for deflate() */ 20817651Speter 20917651Speter#define Z_DEFLATED 8 21017651Speter/* The deflate compression method (the only one supported in this version) */ 21117651Speter 21217651Speter#define Z_NULL 0 /* for initializing zalloc, zfree, opaque */ 21317651Speter 21417651Speter#define zlib_version zlibVersion() 21517651Speter/* for compatibility with versions < 1.0.2 */ 21617651Speter 217205194Sdelphij 21817651Speter /* basic functions */ 21917651Speter 22042468SpeterZEXTERN const char * ZEXPORT zlibVersion OF((void)); 22117651Speter/* The application can compare zlibVersion and ZLIB_VERSION for consistency. 222205194Sdelphij If the first character differs, the library code actually used is not 223205194Sdelphij compatible with the zlib.h header file used by the application. This check 224205194Sdelphij is automatically made by deflateInit and inflateInit. 22517651Speter */ 22617651Speter 227131377Stjr/* 22842468SpeterZEXTERN int ZEXPORT deflateInit OF((z_streamp strm, int level)); 22917651Speter 230205194Sdelphij Initializes the internal stream state for compression. The fields 231205194Sdelphij zalloc, zfree and opaque must be initialized before by the caller. If 232205194Sdelphij zalloc and zfree are set to Z_NULL, deflateInit updates them to use default 233205194Sdelphij allocation functions. 23417651Speter 23517651Speter The compression level must be Z_DEFAULT_COMPRESSION, or between 0 and 9: 236205194Sdelphij 1 gives best speed, 9 gives best compression, 0 gives no compression at all 237205194Sdelphij (the input data is simply copied a block at a time). Z_DEFAULT_COMPRESSION 238205194Sdelphij requests a default compromise between speed and compression (currently 239205194Sdelphij equivalent to level 6). 24017651Speter 241205194Sdelphij deflateInit returns Z_OK if success, Z_MEM_ERROR if there was not enough 242205194Sdelphij memory, Z_STREAM_ERROR if level is not a valid compression level, or 24317651Speter Z_VERSION_ERROR if the zlib library version (zlib_version) is incompatible 244205194Sdelphij with the version assumed by the caller (ZLIB_VERSION). msg is set to null 245205194Sdelphij if there is no error message. deflateInit does not perform any compression: 246205194Sdelphij this will be done by deflate(). 24717651Speter*/ 24817651Speter 24917651Speter 25042468SpeterZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); 25117651Speter/* 25233904Ssteve deflate compresses as much data as possible, and stops when the input 253205194Sdelphij buffer becomes empty or the output buffer becomes full. It may introduce 254205194Sdelphij some output latency (reading input without producing any output) except when 25533904Ssteve forced to flush. 25617651Speter 257205194Sdelphij The detailed semantics are as follows. deflate performs one or both of the 25833904Ssteve following actions: 25933904Ssteve 26017651Speter - Compress more input starting at next_in and update next_in and avail_in 261205194Sdelphij accordingly. If not all input can be processed (because there is not 26217651Speter enough room in the output buffer), next_in and avail_in are updated and 26317651Speter processing will resume at this point for the next call of deflate(). 26417651Speter 265313796Sdelphij - Generate more output starting at next_out and update next_out and avail_out 266205194Sdelphij accordingly. This action is forced if the parameter flush is non zero. 26717651Speter Forcing flush frequently degrades the compression ratio, so this parameter 268313796Sdelphij should be set only when necessary. Some output may be provided even if 269313796Sdelphij flush is zero. 27017651Speter 271205194Sdelphij Before the call of deflate(), the application should ensure that at least 272205194Sdelphij one of the actions is possible, by providing more input and/or consuming more 273205194Sdelphij output, and updating avail_in or avail_out accordingly; avail_out should 274205194Sdelphij never be zero before the call. The application can consume the compressed 275205194Sdelphij output when it wants, for example when the output buffer is full (avail_out 276205194Sdelphij == 0), or after each call of deflate(). If deflate returns Z_OK and with 277205194Sdelphij zero avail_out, it must be called again after making room in the output 278313796Sdelphij buffer because there might be more output pending. See deflatePending(), 279313796Sdelphij which can be used if desired to determine whether or not there is more ouput 280313796Sdelphij in that case. 28117651Speter 282157043Sdes Normally the parameter flush is set to Z_NO_FLUSH, which allows deflate to 283205194Sdelphij decide how much data to accumulate before producing output, in order to 284157043Sdes maximize compression. 285157043Sdes 28633904Ssteve If the parameter flush is set to Z_SYNC_FLUSH, all pending output is 28733904Ssteve flushed to the output buffer and the output is aligned on a byte boundary, so 288205194Sdelphij that the decompressor can get all input data available so far. (In 289205194Sdelphij particular avail_in is zero after the call if enough output space has been 290205194Sdelphij provided before the call.) Flushing may degrade compression for some 291205194Sdelphij compression algorithms and so it should be used only when necessary. This 292205194Sdelphij completes the current deflate block and follows it with an empty stored block 293205194Sdelphij that is three bits plus filler bits to the next byte, followed by four bytes 294205194Sdelphij (00 00 ff ff). 29517651Speter 296205194Sdelphij If flush is set to Z_PARTIAL_FLUSH, all pending output is flushed to the 297205194Sdelphij output buffer, but the output is not aligned to a byte boundary. All of the 298205194Sdelphij input data so far will be available to the decompressor, as for Z_SYNC_FLUSH. 299205194Sdelphij This completes the current deflate block and follows it with an empty fixed 300205194Sdelphij codes block that is 10 bits long. This assures that enough bytes are output 301313796Sdelphij in order for the decompressor to finish the block before the empty fixed 302313796Sdelphij codes block. 303205194Sdelphij 304205194Sdelphij If flush is set to Z_BLOCK, a deflate block is completed and emitted, as 305205194Sdelphij for Z_SYNC_FLUSH, but the output is not aligned on a byte boundary, and up to 306205194Sdelphij seven bits of the current block are held to be written as the next byte after 307205194Sdelphij the next deflate block is completed. In this case, the decompressor may not 308205194Sdelphij be provided enough bits at this point in order to complete decompression of 309205194Sdelphij the data provided so far to the compressor. It may need to wait for the next 310205194Sdelphij block to be emitted. This is for advanced applications that need to control 311205194Sdelphij the emission of deflate blocks. 312205194Sdelphij 31333904Ssteve If flush is set to Z_FULL_FLUSH, all output is flushed as with 31433904Ssteve Z_SYNC_FLUSH, and the compression state is reset so that decompression can 31533904Ssteve restart from this point if previous compressed data has been damaged or if 316205194Sdelphij random access is desired. Using Z_FULL_FLUSH too often can seriously degrade 317157043Sdes compression. 31833904Ssteve 31933904Ssteve If deflate returns with avail_out == 0, this function must be called again 32033904Ssteve with the same value of the flush parameter and more output space (updated 32133904Ssteve avail_out), until the flush is complete (deflate returns with non-zero 322205194Sdelphij avail_out). In the case of a Z_FULL_FLUSH or Z_SYNC_FLUSH, make sure that 323131377Stjr avail_out is greater than six to avoid repeated flush markers due to 324131377Stjr avail_out == 0 on return. 32533904Ssteve 32617651Speter If the parameter flush is set to Z_FINISH, pending input is processed, 327205194Sdelphij pending output is flushed and deflate returns with Z_STREAM_END if there was 328313796Sdelphij enough output space. If deflate returns with Z_OK or Z_BUF_ERROR, this 329313796Sdelphij function must be called again with Z_FINISH and more output space (updated 330313796Sdelphij avail_out) but no more input data, until it returns with Z_STREAM_END or an 331313796Sdelphij error. After deflate has returned Z_STREAM_END, the only possible operations 332313796Sdelphij on the stream are deflateReset or deflateEnd. 333131377Stjr 334313796Sdelphij Z_FINISH can be used in the first deflate call after deflateInit if all the 335313796Sdelphij compression is to be done in a single step. In order to complete in one 336313796Sdelphij call, avail_out must be at least the value returned by deflateBound (see 337313796Sdelphij below). Then deflate is guaranteed to return Z_STREAM_END. If not enough 338313796Sdelphij output space is provided, deflate will not return Z_STREAM_END, and it must 339313796Sdelphij be called again as described above. 34017651Speter 341313796Sdelphij deflate() sets strm->adler to the Adler-32 checksum of all input read 342313796Sdelphij so far (that is, total_in bytes). If a gzip stream is being generated, then 343313796Sdelphij strm->adler will be the CRC-32 checksum of the input read so far. (See 344313796Sdelphij deflateInit2 below.) 34533904Ssteve 346157043Sdes deflate() may update strm->data_type if it can make a good guess about 347313796Sdelphij the input data type (Z_BINARY or Z_TEXT). If in doubt, the data is 348313796Sdelphij considered binary. This field is only for information purposes and does not 349313796Sdelphij affect the compression algorithm in any manner. 35017651Speter 35117651Speter deflate() returns Z_OK if some progress has been made (more input 35217651Speter processed or more output produced), Z_STREAM_END if all input has been 35317651Speter consumed and all output has been produced (only when flush is set to 35417651Speter Z_FINISH), Z_STREAM_ERROR if the stream state was inconsistent (for example 355313796Sdelphij if next_in or next_out was Z_NULL or the state was inadvertently written over 356313796Sdelphij by the application), or Z_BUF_ERROR if no progress is possible (for example 357313796Sdelphij avail_in or avail_out was zero). Note that Z_BUF_ERROR is not fatal, and 358313796Sdelphij deflate() can be called again with more input and more output space to 359313796Sdelphij continue compressing. 36017651Speter*/ 36117651Speter 36217651Speter 36342468SpeterZEXTERN int ZEXPORT deflateEnd OF((z_streamp strm)); 36417651Speter/* 36517651Speter All dynamically allocated data structures for this stream are freed. 366205194Sdelphij This function discards any unprocessed input and does not flush any pending 367205194Sdelphij output. 36817651Speter 36917651Speter deflateEnd returns Z_OK if success, Z_STREAM_ERROR if the 37017651Speter stream state was inconsistent, Z_DATA_ERROR if the stream was freed 371205194Sdelphij prematurely (some input or output was discarded). In the error case, msg 372205194Sdelphij may be set but then points to a static string (which must not be 37317651Speter deallocated). 37417651Speter*/ 37517651Speter 37617651Speter 377131377Stjr/* 37842468SpeterZEXTERN int ZEXPORT inflateInit OF((z_streamp strm)); 37917651Speter 380205194Sdelphij Initializes the internal stream state for decompression. The fields 38133904Ssteve next_in, avail_in, zalloc, zfree and opaque must be initialized before by 382313796Sdelphij the caller. In the current version of inflate, the provided input is not 383313796Sdelphij read or consumed. The allocation of a sliding window will be deferred to 384313796Sdelphij the first call of inflate (if the decompression does not complete on the 385313796Sdelphij first call). If zalloc and zfree are set to Z_NULL, inflateInit updates 386313796Sdelphij them to use default allocation functions. 38717651Speter 38833904Ssteve inflateInit returns Z_OK if success, Z_MEM_ERROR if there was not enough 38933904Ssteve memory, Z_VERSION_ERROR if the zlib library version is incompatible with the 390205194Sdelphij version assumed by the caller, or Z_STREAM_ERROR if the parameters are 391205194Sdelphij invalid, such as a null pointer to the structure. msg is set to null if 392313796Sdelphij there is no error message. inflateInit does not perform any decompression. 393313796Sdelphij Actual decompression will be done by inflate(). So next_in, and avail_in, 394313796Sdelphij next_out, and avail_out are unused and unchanged. The current 395313796Sdelphij implementation of inflateInit() does not process any header information -- 396313796Sdelphij that is deferred until inflate() is called. 39717651Speter*/ 39817651Speter 39917651Speter 40042468SpeterZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush)); 40117651Speter/* 40233904Ssteve inflate decompresses as much data as possible, and stops when the input 403205194Sdelphij buffer becomes empty or the output buffer becomes full. It may introduce 404131377Stjr some output latency (reading input without producing any output) except when 405131377Stjr forced to flush. 40617651Speter 407205194Sdelphij The detailed semantics are as follows. inflate performs one or both of the 40833904Ssteve following actions: 40933904Ssteve 41017651Speter - Decompress more input starting at next_in and update next_in and avail_in 411205194Sdelphij accordingly. If not all input can be processed (because there is not 412313796Sdelphij enough room in the output buffer), then next_in and avail_in are updated 413313796Sdelphij accordingly, and processing will resume at this point for the next call of 414313796Sdelphij inflate(). 41517651Speter 416313796Sdelphij - Generate more output starting at next_out and update next_out and avail_out 417205194Sdelphij accordingly. inflate() provides as much output as possible, until there is 418205194Sdelphij no more input data or no more space in the output buffer (see below about 419205194Sdelphij the flush parameter). 42017651Speter 421205194Sdelphij Before the call of inflate(), the application should ensure that at least 422205194Sdelphij one of the actions is possible, by providing more input and/or consuming more 423313796Sdelphij output, and updating the next_* and avail_* values accordingly. If the 424313796Sdelphij caller of inflate() does not provide both available input and available 425313796Sdelphij output space, it is possible that there will be no progress made. The 426205194Sdelphij application can consume the uncompressed output when it wants, for example 427205194Sdelphij when the output buffer is full (avail_out == 0), or after each call of 428205194Sdelphij inflate(). If inflate returns Z_OK and with zero avail_out, it must be 429205194Sdelphij called again after making room in the output buffer because there might be 430205194Sdelphij more output pending. 43117651Speter 432205194Sdelphij The flush parameter of inflate() can be Z_NO_FLUSH, Z_SYNC_FLUSH, Z_FINISH, 433205194Sdelphij Z_BLOCK, or Z_TREES. Z_SYNC_FLUSH requests that inflate() flush as much 434205194Sdelphij output as possible to the output buffer. Z_BLOCK requests that inflate() 435205194Sdelphij stop if and when it gets to the next deflate block boundary. When decoding 436205194Sdelphij the zlib or gzip format, this will cause inflate() to return immediately 437205194Sdelphij after the header and before the first block. When doing a raw inflate, 438205194Sdelphij inflate() will go ahead and process the first block, and will return when it 439205194Sdelphij gets to the end of that block, or when it runs out of data. 44017651Speter 441131377Stjr The Z_BLOCK option assists in appending to or combining deflate streams. 442313796Sdelphij To assist in this, on return inflate() always sets strm->data_type to the 443205194Sdelphij number of unused bits in the last byte taken from strm->next_in, plus 64 if 444205194Sdelphij inflate() is currently decoding the last block in the deflate stream, plus 445205194Sdelphij 128 if inflate() returned immediately after decoding an end-of-block code or 446205194Sdelphij decoding the complete header up to just before the first byte of the deflate 447205194Sdelphij stream. The end-of-block will not be indicated until all of the uncompressed 448205194Sdelphij data from that block has been written to strm->next_out. The number of 449205194Sdelphij unused bits may in general be greater than seven, except when bit 7 of 450205194Sdelphij data_type is set, in which case the number of unused bits will be less than 451205194Sdelphij eight. data_type is set as noted here every time inflate() returns for all 452205194Sdelphij flush options, and so can be used to determine the amount of currently 453205194Sdelphij consumed input in bits. 454131377Stjr 455205194Sdelphij The Z_TREES option behaves as Z_BLOCK does, but it also returns when the 456205194Sdelphij end of each deflate block header is reached, before any actual data in that 457205194Sdelphij block is decoded. This allows the caller to determine the length of the 458205194Sdelphij deflate block header for later use in random access within a deflate block. 459205194Sdelphij 256 is added to the value of strm->data_type when inflate() returns 460205194Sdelphij immediately after reaching the end of the deflate block header. 461205194Sdelphij 46217651Speter inflate() should normally be called until it returns Z_STREAM_END or an 463205194Sdelphij error. However if all decompression is to be performed in a single step (a 464205194Sdelphij single call of inflate), the parameter flush should be set to Z_FINISH. In 465205194Sdelphij this case all pending input is processed and all pending output is flushed; 466237248Sdelphij avail_out must be large enough to hold all of the uncompressed data for the 467237248Sdelphij operation to complete. (The size of the uncompressed data may have been 468313796Sdelphij saved by the compressor for this purpose.) The use of Z_FINISH is not 469237248Sdelphij required to perform an inflation in one step. However it may be used to 470237248Sdelphij inform inflate that a faster approach can be used for the single inflate() 471237248Sdelphij call. Z_FINISH also informs inflate to not maintain a sliding window if the 472237248Sdelphij stream completes, which reduces inflate's memory footprint. If the stream 473237248Sdelphij does not complete, either because not all of the stream is provided or not 474237248Sdelphij enough output space is provided, then a sliding window will be allocated and 475237248Sdelphij inflate() can be called again to continue the operation as if Z_NO_FLUSH had 476237248Sdelphij been used. 47717651Speter 478131377Stjr In this implementation, inflate() always flushes as much output as 479131377Stjr possible to the output buffer, and always uses the faster approach on the 480230837Sdelphij first call. So the effects of the flush parameter in this implementation are 481230837Sdelphij on the return value of inflate() as noted below, when inflate() returns early 482230837Sdelphij when Z_BLOCK or Z_TREES is used, and when inflate() avoids the allocation of 483230837Sdelphij memory for a sliding window when Z_FINISH is used. 48433904Ssteve 485131377Stjr If a preset dictionary is needed after this call (see inflateSetDictionary 486230837Sdelphij below), inflate sets strm->adler to the Adler-32 checksum of the dictionary 487131377Stjr chosen by the compressor and returns Z_NEED_DICT; otherwise it sets 488230837Sdelphij strm->adler to the Adler-32 checksum of all output produced so far (that is, 489131377Stjr total_out bytes) and returns Z_OK, Z_STREAM_END or an error code as described 490313796Sdelphij below. At the end of the stream, inflate() checks that its computed Adler-32 491131377Stjr checksum is equal to that saved by the compressor and returns Z_STREAM_END 492131377Stjr only if the checksum is correct. 493131377Stjr 494205194Sdelphij inflate() can decompress and check either zlib-wrapped or gzip-wrapped 495205194Sdelphij deflate data. The header type is detected automatically, if requested when 496205194Sdelphij initializing with inflateInit2(). Any information contained in the gzip 497313796Sdelphij header is not retained unless inflateGetHeader() is used. When processing 498230837Sdelphij gzip-wrapped deflate data, strm->adler32 is set to the CRC-32 of the output 499313796Sdelphij produced so far. The CRC-32 is checked against the gzip trailer, as is the 500313796Sdelphij uncompressed length, modulo 2^32. 501131377Stjr 50233904Ssteve inflate() returns Z_OK if some progress has been made (more input processed 50333904Ssteve or more output produced), Z_STREAM_END if the end of the compressed data has 50433904Ssteve been reached and all uncompressed output has been produced, Z_NEED_DICT if a 50533904Ssteve preset dictionary is needed at this point, Z_DATA_ERROR if the input data was 506131377Stjr corrupted (input stream not conforming to the zlib format or incorrect check 507313796Sdelphij value, in which case strm->msg points to a string with a more specific 508313796Sdelphij error), Z_STREAM_ERROR if the stream structure was inconsistent (for example 509313796Sdelphij next_in or next_out was Z_NULL, or the state was inadvertently written over 510313796Sdelphij by the application), Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR 511313796Sdelphij if no progress was possible or if there was not enough room in the output 512313796Sdelphij buffer when Z_FINISH is used. Note that Z_BUF_ERROR is not fatal, and 513131377Stjr inflate() can be called again with more input and more output space to 514205194Sdelphij continue decompressing. If Z_DATA_ERROR is returned, the application may 515205194Sdelphij then call inflateSync() to look for a good compression block if a partial 516313796Sdelphij recovery of the data is to be attempted. 51717651Speter*/ 51817651Speter 51917651Speter 52042468SpeterZEXTERN int ZEXPORT inflateEnd OF((z_streamp strm)); 52117651Speter/* 52217651Speter All dynamically allocated data structures for this stream are freed. 523205194Sdelphij This function discards any unprocessed input and does not flush any pending 524205194Sdelphij output. 52517651Speter 526313796Sdelphij inflateEnd returns Z_OK if success, or Z_STREAM_ERROR if the stream state 527313796Sdelphij was inconsistent. 52817651Speter*/ 52917651Speter 530205194Sdelphij 53117651Speter /* Advanced functions */ 53217651Speter 53317651Speter/* 53417651Speter The following functions are needed only in some special applications. 53517651Speter*/ 53617651Speter 537131377Stjr/* 53842468SpeterZEXTERN int ZEXPORT deflateInit2 OF((z_streamp strm, 53942468Speter int level, 54042468Speter int method, 54142468Speter int windowBits, 54242468Speter int memLevel, 54342468Speter int strategy)); 54417651Speter 545205194Sdelphij This is another version of deflateInit with more compression options. The 546205194Sdelphij fields next_in, zalloc, zfree and opaque must be initialized before by the 547205194Sdelphij caller. 54817651Speter 549205194Sdelphij The method parameter is the compression method. It must be Z_DEFLATED in 55033904Ssteve this version of the library. 55117651Speter 55217651Speter The windowBits parameter is the base two logarithm of the window size 553205194Sdelphij (the size of the history buffer). It should be in the range 8..15 for this 554205194Sdelphij version of the library. Larger values of this parameter result in better 555205194Sdelphij compression at the expense of memory usage. The default value is 15 if 55633904Ssteve deflateInit is used instead. 55717651Speter 558313796Sdelphij For the current implementation of deflate(), a windowBits value of 8 (a 559313796Sdelphij window size of 256 bytes) is not supported. As a result, a request for 8 560313796Sdelphij will result in 9 (a 512-byte window). In that case, providing 8 to 561313796Sdelphij inflateInit2() will result in an error when the zlib header with 9 is 562313796Sdelphij checked against the initialization of inflate(). The remedy is to not use 8 563313796Sdelphij with deflateInit2() with this initialization, or at least in that case use 9 564313796Sdelphij with inflateInit2(). 565313796Sdelphij 566205194Sdelphij windowBits can also be -8..-15 for raw deflate. In this case, -windowBits 567205194Sdelphij determines the window size. deflate() will then generate raw deflate data 568313796Sdelphij with no zlib header or trailer, and will not compute a check value. 569131377Stjr 570205194Sdelphij windowBits can also be greater than 15 for optional gzip encoding. Add 571131377Stjr 16 to windowBits to write a simple gzip header and trailer around the 572205194Sdelphij compressed data instead of a zlib wrapper. The gzip header will have no 573205194Sdelphij file name, no extra data, no comment, no modification time (set to zero), no 574313796Sdelphij header crc, and the operating system will be set to the appropriate value, 575313796Sdelphij if the operating system was determined at compile time. If a gzip stream is 576313796Sdelphij being written, strm->adler is a CRC-32 instead of an Adler-32. 577131377Stjr 578313796Sdelphij For raw deflate or gzip encoding, a request for a 256-byte window is 579313796Sdelphij rejected as invalid, since only the zlib header provides a means of 580313796Sdelphij transmitting the window size to the decompressor. 581313796Sdelphij 58217651Speter The memLevel parameter specifies how much memory should be allocated 583205194Sdelphij for the internal compression state. memLevel=1 uses minimum memory but is 584205194Sdelphij slow and reduces compression ratio; memLevel=9 uses maximum memory for 585205194Sdelphij optimal speed. The default value is 8. See zconf.h for total memory usage 586205194Sdelphij as a function of windowBits and memLevel. 58717651Speter 588205194Sdelphij The strategy parameter is used to tune the compression algorithm. Use the 58917651Speter value Z_DEFAULT_STRATEGY for normal data, Z_FILTERED for data produced by a 590131377Stjr filter (or predictor), Z_HUFFMAN_ONLY to force Huffman encoding only (no 591131377Stjr string match), or Z_RLE to limit match distances to one (run-length 592205194Sdelphij encoding). Filtered data consists mostly of small values with a somewhat 593205194Sdelphij random distribution. In this case, the compression algorithm is tuned to 594205194Sdelphij compress them better. The effect of Z_FILTERED is to force more Huffman 595131377Stjr coding and less string matching; it is somewhat intermediate between 596205194Sdelphij Z_DEFAULT_STRATEGY and Z_HUFFMAN_ONLY. Z_RLE is designed to be almost as 597205194Sdelphij fast as Z_HUFFMAN_ONLY, but give better compression for PNG image data. The 598205194Sdelphij strategy parameter only affects the compression ratio but not the 599205194Sdelphij correctness of the compressed output even if it is not set appropriately. 600205194Sdelphij Z_FIXED prevents the use of dynamic Huffman codes, allowing for a simpler 601205194Sdelphij decoder for special applications. 60217651Speter 603205194Sdelphij deflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough 604205194Sdelphij memory, Z_STREAM_ERROR if any parameter is invalid (such as an invalid 605205194Sdelphij method), or Z_VERSION_ERROR if the zlib library version (zlib_version) is 606205194Sdelphij incompatible with the version assumed by the caller (ZLIB_VERSION). msg is 607205194Sdelphij set to null if there is no error message. deflateInit2 does not perform any 608205194Sdelphij compression: this will be done by deflate(). 60917651Speter*/ 610131377Stjr 61142468SpeterZEXTERN int ZEXPORT deflateSetDictionary OF((z_streamp strm, 61242468Speter const Bytef *dictionary, 61342468Speter uInt dictLength)); 61417651Speter/* 61533904Ssteve Initializes the compression dictionary from the given byte sequence 616230837Sdelphij without producing any compressed output. When using the zlib format, this 617230837Sdelphij function must be called immediately after deflateInit, deflateInit2 or 618230837Sdelphij deflateReset, and before any call of deflate. When doing raw deflate, this 619230837Sdelphij function must be called either before any call of deflate, or immediately 620230837Sdelphij after the completion of a deflate block, i.e. after all input has been 621230837Sdelphij consumed and all output has been delivered when using any of the flush 622230837Sdelphij options Z_BLOCK, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, or Z_FULL_FLUSH. The 623230837Sdelphij compressor and decompressor must use exactly the same dictionary (see 624230837Sdelphij inflateSetDictionary). 62533904Ssteve 62617651Speter The dictionary should consist of strings (byte sequences) that are likely 62717651Speter to be encountered later in the data to be compressed, with the most commonly 628205194Sdelphij used strings preferably put towards the end of the dictionary. Using a 62933904Ssteve dictionary is most useful when the data to be compressed is short and can be 63033904Ssteve predicted with good accuracy; the data can then be compressed better than 63133904Ssteve with the default empty dictionary. 63233904Ssteve 63333904Ssteve Depending on the size of the compression data structures selected by 63433904Ssteve deflateInit or deflateInit2, a part of the dictionary may in effect be 635205194Sdelphij discarded, for example if the dictionary is larger than the window size 636205194Sdelphij provided in deflateInit or deflateInit2. Thus the strings most likely to be 637205194Sdelphij useful should be put at the end of the dictionary, not at the front. In 638205194Sdelphij addition, the current implementation of deflate will use at most the window 639205194Sdelphij size minus 262 bytes of the provided dictionary. 64033904Ssteve 641313796Sdelphij Upon return of this function, strm->adler is set to the Adler-32 value 64217651Speter of the dictionary; the decompressor may later use this value to determine 643313796Sdelphij which dictionary has been used by the compressor. (The Adler-32 value 64417651Speter applies to the whole dictionary even if only a subset of the dictionary is 645131377Stjr actually used by the compressor.) If a raw deflate was requested, then the 646313796Sdelphij Adler-32 value is not computed and strm->adler is not set. 64717651Speter 64817651Speter deflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a 649205194Sdelphij parameter is invalid (e.g. dictionary being Z_NULL) or the stream state is 65033904Ssteve inconsistent (for example if deflate has already been called for this stream 651230837Sdelphij or if not at a block boundary for raw deflate). deflateSetDictionary does 652230837Sdelphij not perform any compression: this will be done by deflate(). 65317651Speter*/ 65417651Speter 655313796SdelphijZEXTERN int ZEXPORT deflateGetDictionary OF((z_streamp strm, 656313796Sdelphij Bytef *dictionary, 657313796Sdelphij uInt *dictLength)); 658313796Sdelphij/* 659313796Sdelphij Returns the sliding dictionary being maintained by deflate. dictLength is 660313796Sdelphij set to the number of bytes in the dictionary, and that many bytes are copied 661313796Sdelphij to dictionary. dictionary must have enough space, where 32768 bytes is 662313796Sdelphij always enough. If deflateGetDictionary() is called with dictionary equal to 663313796Sdelphij Z_NULL, then only the dictionary length is returned, and nothing is copied. 664313796Sdelphij Similary, if dictLength is Z_NULL, then it is not set. 665313796Sdelphij 666313796Sdelphij deflateGetDictionary() may return a length less than the window size, even 667313796Sdelphij when more than the window size in input has been provided. It may return up 668313796Sdelphij to 258 bytes less in that case, due to how zlib's implementation of deflate 669313796Sdelphij manages the sliding window and lookahead for matches, where matches can be 670313796Sdelphij up to 258 bytes long. If the application needs the last window-size bytes of 671313796Sdelphij input, then that would need to be saved by the application outside of zlib. 672313796Sdelphij 673313796Sdelphij deflateGetDictionary returns Z_OK on success, or Z_STREAM_ERROR if the 674313796Sdelphij stream state is inconsistent. 675313796Sdelphij*/ 676313796Sdelphij 67742468SpeterZEXTERN int ZEXPORT deflateCopy OF((z_streamp dest, 67842468Speter z_streamp source)); 67917651Speter/* 68033904Ssteve Sets the destination stream as a complete copy of the source stream. 68117651Speter 68217651Speter This function can be useful when several compression strategies will be 68317651Speter tried, for example when there are several ways of pre-processing the input 684205194Sdelphij data with a filter. The streams that will be discarded should then be freed 68517651Speter by calling deflateEnd. Note that deflateCopy duplicates the internal 686205194Sdelphij compression state which can be quite large, so this strategy is slow and can 687205194Sdelphij consume lots of memory. 68817651Speter 68917651Speter deflateCopy returns Z_OK if success, Z_MEM_ERROR if there was not 69017651Speter enough memory, Z_STREAM_ERROR if the source stream state was inconsistent 691205194Sdelphij (such as zalloc being Z_NULL). msg is left unchanged in both source and 69217651Speter destination. 69317651Speter*/ 69417651Speter 69542468SpeterZEXTERN int ZEXPORT deflateReset OF((z_streamp strm)); 69617651Speter/* 697313796Sdelphij This function is equivalent to deflateEnd followed by deflateInit, but 698313796Sdelphij does not free and reallocate the internal compression state. The stream 699313796Sdelphij will leave the compression level and any other attributes that may have been 700313796Sdelphij set unchanged. 70117651Speter 702205194Sdelphij deflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source 703205194Sdelphij stream state was inconsistent (such as zalloc or state being Z_NULL). 70417651Speter*/ 70517651Speter 70642468SpeterZEXTERN int ZEXPORT deflateParams OF((z_streamp strm, 707131377Stjr int level, 708131377Stjr int strategy)); 70917651Speter/* 71033904Ssteve Dynamically update the compression level and compression strategy. The 711313796Sdelphij interpretation of level and strategy is as in deflateInit2(). This can be 71233904Ssteve used to switch between compression and straight copy of the input data, or 713205194Sdelphij to switch to a different kind of input data requiring a different strategy. 714313796Sdelphij If the compression approach (which is a function of the level) or the 715323565Smarius strategy is changed, and if there have been any deflate() calls since the 716323565Smarius state was initialized or reset, then the input available so far is 717323565Smarius compressed with the old level and strategy using deflate(strm, Z_BLOCK). 718323565Smarius There are three approaches for the compression levels 0, 1..3, and 4..9 719323565Smarius respectively. The new level and strategy will take effect at the next call 720323565Smarius of deflate(). 72117651Speter 722313796Sdelphij If a deflate(strm, Z_BLOCK) is performed by deflateParams(), and it does 723313796Sdelphij not have enough output space to complete, then the parameter change will not 724313796Sdelphij take effect. In this case, deflateParams() can be called again with the 725313796Sdelphij same parameters and more output space to try again. 72617651Speter 727313796Sdelphij In order to assure a change in the parameters on the first try, the 728313796Sdelphij deflate stream should be flushed using deflate() with Z_BLOCK or other flush 729313796Sdelphij request until strm.avail_out is not zero, before calling deflateParams(). 730313796Sdelphij Then no more input data should be provided before the deflateParams() call. 731313796Sdelphij If this is done, the old level and strategy will be applied to the data 732313796Sdelphij compressed before deflateParams(), and the new level and strategy will be 733313796Sdelphij applied to the the data compressed after deflateParams(). 734313796Sdelphij 735313796Sdelphij deflateParams returns Z_OK on success, Z_STREAM_ERROR if the source stream 736313796Sdelphij state was inconsistent or if a parameter was invalid, or Z_BUF_ERROR if 737313796Sdelphij there was not enough output space to complete the compression of the 738313796Sdelphij available input data before a change in the strategy or approach. Note that 739313796Sdelphij in the case of a Z_BUF_ERROR, the parameters are not changed. A return 740313796Sdelphij value of Z_BUF_ERROR is not fatal, in which case deflateParams() can be 741313796Sdelphij retried with more output space. 74217651Speter*/ 74317651Speter 744157043SdesZEXTERN int ZEXPORT deflateTune OF((z_streamp strm, 745157043Sdes int good_length, 746157043Sdes int max_lazy, 747157043Sdes int nice_length, 748157043Sdes int max_chain)); 749157043Sdes/* 750157043Sdes Fine tune deflate's internal compression parameters. This should only be 751157043Sdes used by someone who understands the algorithm used by zlib's deflate for 752157043Sdes searching for the best matching string, and even then only by the most 753157043Sdes fanatic optimizer trying to squeeze out the last compressed bit for their 754157043Sdes specific input data. Read the deflate.c source code for the meaning of the 755157043Sdes max_lazy, good_length, nice_length, and max_chain parameters. 756157043Sdes 757157043Sdes deflateTune() can be called after deflateInit() or deflateInit2(), and 758157043Sdes returns Z_OK on success, or Z_STREAM_ERROR for an invalid deflate stream. 759157043Sdes */ 760157043Sdes 761131377StjrZEXTERN uLong ZEXPORT deflateBound OF((z_streamp strm, 762131377Stjr uLong sourceLen)); 763131377Stjr/* 764131377Stjr deflateBound() returns an upper bound on the compressed size after 765205194Sdelphij deflation of sourceLen bytes. It must be called after deflateInit() or 766205194Sdelphij deflateInit2(), and after deflateSetHeader(), if used. This would be used 767205194Sdelphij to allocate an output buffer for deflation in a single pass, and so would be 768230837Sdelphij called before deflate(). If that first deflate() call is provided the 769230837Sdelphij sourceLen input bytes, an output buffer allocated to the size returned by 770230837Sdelphij deflateBound(), and the flush value Z_FINISH, then deflate() is guaranteed 771230837Sdelphij to return Z_STREAM_END. Note that it is possible for the compressed size to 772230837Sdelphij be larger than the value returned by deflateBound() if flush options other 773230837Sdelphij than Z_FINISH or Z_NO_FLUSH are used. 774131377Stjr*/ 775131377Stjr 776230837SdelphijZEXTERN int ZEXPORT deflatePending OF((z_streamp strm, 777230837Sdelphij unsigned *pending, 778230837Sdelphij int *bits)); 779230837Sdelphij/* 780230837Sdelphij deflatePending() returns the number of bytes and bits of output that have 781230837Sdelphij been generated, but not yet provided in the available output. The bytes not 782230837Sdelphij provided would be due to the available output space having being consumed. 783230837Sdelphij The number of bits of output not provided are between 0 and 7, where they 784230837Sdelphij await more bits to join them in order to fill out a full byte. If pending 785230837Sdelphij or bits are Z_NULL, then those values are not set. 786230837Sdelphij 787230837Sdelphij deflatePending returns Z_OK if success, or Z_STREAM_ERROR if the source 788230837Sdelphij stream state was inconsistent. 789230837Sdelphij */ 790230837Sdelphij 791131377StjrZEXTERN int ZEXPORT deflatePrime OF((z_streamp strm, 792131377Stjr int bits, 793131377Stjr int value)); 794131377Stjr/* 795131377Stjr deflatePrime() inserts bits in the deflate output stream. The intent 796205194Sdelphij is that this function is used to start off the deflate output with the bits 797205194Sdelphij leftover from a previous deflate stream when appending to it. As such, this 798205194Sdelphij function can only be used for raw deflate, and must be used before the first 799205194Sdelphij deflate() call after a deflateInit2() or deflateReset(). bits must be less 800205194Sdelphij than or equal to 16, and that many of the least significant bits of value 801205194Sdelphij will be inserted in the output. 802131377Stjr 803230837Sdelphij deflatePrime returns Z_OK if success, Z_BUF_ERROR if there was not enough 804230837Sdelphij room in the internal buffer to insert the bits, or Z_STREAM_ERROR if the 805230837Sdelphij source stream state was inconsistent. 806131377Stjr*/ 807131377Stjr 808157043SdesZEXTERN int ZEXPORT deflateSetHeader OF((z_streamp strm, 809157043Sdes gz_headerp head)); 810131377Stjr/* 811205194Sdelphij deflateSetHeader() provides gzip header information for when a gzip 812157043Sdes stream is requested by deflateInit2(). deflateSetHeader() may be called 813157043Sdes after deflateInit2() or deflateReset() and before the first call of 814157043Sdes deflate(). The text, time, os, extra field, name, and comment information 815157043Sdes in the provided gz_header structure are written to the gzip header (xflag is 816157043Sdes ignored -- the extra flags are set according to the compression level). The 817157043Sdes caller must assure that, if not Z_NULL, name and comment are terminated with 818157043Sdes a zero byte, and that if extra is not Z_NULL, that extra_len bytes are 819157043Sdes available there. If hcrc is true, a gzip header crc is included. Note that 820157043Sdes the current versions of the command-line version of gzip (up through version 821157043Sdes 1.3.x) do not support header crc's, and will report that it is a "multi-part 822157043Sdes gzip file" and give up. 823157043Sdes 824205194Sdelphij If deflateSetHeader is not used, the default gzip header has text false, 825157043Sdes the time set to zero, and os set to 255, with no extra, name, or comment 826157043Sdes fields. The gzip header is returned to the default state by deflateReset(). 827157043Sdes 828205194Sdelphij deflateSetHeader returns Z_OK if success, or Z_STREAM_ERROR if the source 829157043Sdes stream state was inconsistent. 830157043Sdes*/ 831157043Sdes 832157043Sdes/* 83342468SpeterZEXTERN int ZEXPORT inflateInit2 OF((z_streamp strm, 83442468Speter int windowBits)); 83517651Speter 836205194Sdelphij This is another version of inflateInit with an extra parameter. The 83733904Ssteve fields next_in, avail_in, zalloc, zfree and opaque must be initialized 83833904Ssteve before by the caller. 83917651Speter 84017651Speter The windowBits parameter is the base two logarithm of the maximum window 84117651Speter size (the size of the history buffer). It should be in the range 8..15 for 842205194Sdelphij this version of the library. The default value is 15 if inflateInit is used 843205194Sdelphij instead. windowBits must be greater than or equal to the windowBits value 844131377Stjr provided to deflateInit2() while compressing, or it must be equal to 15 if 845205194Sdelphij deflateInit2() was not used. If a compressed stream with a larger window 846131377Stjr size is given as input, inflate() will return with the error code 847131377Stjr Z_DATA_ERROR instead of trying to allocate a larger window. 84817651Speter 849205194Sdelphij windowBits can also be zero to request that inflate use the window size in 850205194Sdelphij the zlib header of the compressed stream. 851205194Sdelphij 852205194Sdelphij windowBits can also be -8..-15 for raw inflate. In this case, -windowBits 853205194Sdelphij determines the window size. inflate() will then process raw deflate data, 854131377Stjr not looking for a zlib or gzip header, not generating a check value, and not 855205194Sdelphij looking for any check values for comparison at the end of the stream. This 856131377Stjr is for use with other formats that use the deflate compressed data format 857205194Sdelphij such as zip. Those formats provide their own check values. If a custom 858131377Stjr format is developed using the raw deflate format for compressed data, it is 859313796Sdelphij recommended that a check value such as an Adler-32 or a CRC-32 be applied to 860131377Stjr the uncompressed data as is done in the zlib, gzip, and zip formats. For 861205194Sdelphij most applications, the zlib format should be used as is. Note that comments 862131377Stjr above on the use in deflateInit2() applies to the magnitude of windowBits. 863131377Stjr 864205194Sdelphij windowBits can also be greater than 15 for optional gzip decoding. Add 865131377Stjr 32 to windowBits to enable zlib and gzip decoding with automatic header 866131377Stjr detection, or add 16 to decode only the gzip format (the zlib format will 867205194Sdelphij return a Z_DATA_ERROR). If a gzip stream is being decoded, strm->adler is a 868313796Sdelphij CRC-32 instead of an Adler-32. Unlike the gunzip utility and gzread() (see 869313796Sdelphij below), inflate() will not automatically decode concatenated gzip streams. 870313796Sdelphij inflate() will return Z_STREAM_END at the end of the gzip stream. The state 871313796Sdelphij would need to be reset to continue decoding a subsequent gzip stream. 872131377Stjr 873131377Stjr inflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough 874205194Sdelphij memory, Z_VERSION_ERROR if the zlib library version is incompatible with the 875205194Sdelphij version assumed by the caller, or Z_STREAM_ERROR if the parameters are 876205194Sdelphij invalid, such as a null pointer to the structure. msg is set to null if 877205194Sdelphij there is no error message. inflateInit2 does not perform any decompression 878205194Sdelphij apart from possibly reading the zlib header if present: actual decompression 879205194Sdelphij will be done by inflate(). (So next_in and avail_in may be modified, but 880205194Sdelphij next_out and avail_out are unused and unchanged.) The current implementation 881205194Sdelphij of inflateInit2() does not process any header information -- that is 882205194Sdelphij deferred until inflate() is called. 88317651Speter*/ 88417651Speter 88542468SpeterZEXTERN int ZEXPORT inflateSetDictionary OF((z_streamp strm, 88642468Speter const Bytef *dictionary, 88742468Speter uInt dictLength)); 88817651Speter/* 88933904Ssteve Initializes the decompression dictionary from the given uncompressed byte 890205194Sdelphij sequence. This function must be called immediately after a call of inflate, 891205194Sdelphij if that call returned Z_NEED_DICT. The dictionary chosen by the compressor 892313796Sdelphij can be determined from the Adler-32 value returned by that call of inflate. 893157043Sdes The compressor and decompressor must use exactly the same dictionary (see 894230837Sdelphij deflateSetDictionary). For raw inflate, this function can be called at any 895230837Sdelphij time to set the dictionary. If the provided dictionary is smaller than the 896230837Sdelphij window and there is already data in the window, then the provided dictionary 897230837Sdelphij will amend what's there. The application must insure that the dictionary 898230837Sdelphij that was used for compression is provided. 89917651Speter 90017651Speter inflateSetDictionary returns Z_OK if success, Z_STREAM_ERROR if a 901205194Sdelphij parameter is invalid (e.g. dictionary being Z_NULL) or the stream state is 90217651Speter inconsistent, Z_DATA_ERROR if the given dictionary doesn't match the 903313796Sdelphij expected one (incorrect Adler-32 value). inflateSetDictionary does not 90417651Speter perform any decompression: this will be done by subsequent calls of 90517651Speter inflate(). 90617651Speter*/ 90717651Speter 908250224SdelphijZEXTERN int ZEXPORT inflateGetDictionary OF((z_streamp strm, 909250224Sdelphij Bytef *dictionary, 910250224Sdelphij uInt *dictLength)); 911250224Sdelphij/* 912250224Sdelphij Returns the sliding dictionary being maintained by inflate. dictLength is 913250224Sdelphij set to the number of bytes in the dictionary, and that many bytes are copied 914250224Sdelphij to dictionary. dictionary must have enough space, where 32768 bytes is 915250224Sdelphij always enough. If inflateGetDictionary() is called with dictionary equal to 916250224Sdelphij Z_NULL, then only the dictionary length is returned, and nothing is copied. 917250224Sdelphij Similary, if dictLength is Z_NULL, then it is not set. 918250224Sdelphij 919250224Sdelphij inflateGetDictionary returns Z_OK on success, or Z_STREAM_ERROR if the 920250224Sdelphij stream state is inconsistent. 921250224Sdelphij*/ 922250224Sdelphij 92342468SpeterZEXTERN int ZEXPORT inflateSync OF((z_streamp strm)); 924131377Stjr/* 925230837Sdelphij Skips invalid compressed data until a possible full flush point (see above 926230837Sdelphij for the description of deflate with Z_FULL_FLUSH) can be found, or until all 927205194Sdelphij available input is skipped. No output is provided. 92817651Speter 929230837Sdelphij inflateSync searches for a 00 00 FF FF pattern in the compressed data. 930250224Sdelphij All full flush points have this pattern, but not all occurrences of this 931230837Sdelphij pattern are full flush points. 932230837Sdelphij 933230837Sdelphij inflateSync returns Z_OK if a possible full flush point has been found, 934230837Sdelphij Z_BUF_ERROR if no more input was provided, Z_DATA_ERROR if no flush point 935230837Sdelphij has been found, or Z_STREAM_ERROR if the stream structure was inconsistent. 936230837Sdelphij In the success case, the application may save the current current value of 937230837Sdelphij total_in which indicates where valid compressed data was found. In the 938230837Sdelphij error case, the application may repeatedly call inflateSync, providing more 939230837Sdelphij input each time, until success or end of the input data. 94017651Speter*/ 94117651Speter 942131377StjrZEXTERN int ZEXPORT inflateCopy OF((z_streamp dest, 943131377Stjr z_streamp source)); 944131377Stjr/* 945131377Stjr Sets the destination stream as a complete copy of the source stream. 946131377Stjr 947131377Stjr This function can be useful when randomly accessing a large stream. The 948131377Stjr first pass through the stream can periodically record the inflate state, 949131377Stjr allowing restarting inflate at those points when randomly accessing the 950131377Stjr stream. 951131377Stjr 952131377Stjr inflateCopy returns Z_OK if success, Z_MEM_ERROR if there was not 953131377Stjr enough memory, Z_STREAM_ERROR if the source stream state was inconsistent 954205194Sdelphij (such as zalloc being Z_NULL). msg is left unchanged in both source and 955131377Stjr destination. 956131377Stjr*/ 957131377Stjr 95842468SpeterZEXTERN int ZEXPORT inflateReset OF((z_streamp strm)); 95917651Speter/* 96017651Speter This function is equivalent to inflateEnd followed by inflateInit, 961313796Sdelphij but does not free and reallocate the internal decompression state. The 962205194Sdelphij stream will keep attributes that may have been set by inflateInit2. 96317651Speter 964205194Sdelphij inflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source 965205194Sdelphij stream state was inconsistent (such as zalloc or state being Z_NULL). 96617651Speter*/ 96717651Speter 968205194SdelphijZEXTERN int ZEXPORT inflateReset2 OF((z_streamp strm, 969205194Sdelphij int windowBits)); 970205194Sdelphij/* 971205194Sdelphij This function is the same as inflateReset, but it also permits changing 972205194Sdelphij the wrap and window size requests. The windowBits parameter is interpreted 973313796Sdelphij the same as it is for inflateInit2. If the window size is changed, then the 974313796Sdelphij memory allocated for the window is freed, and the window will be reallocated 975313796Sdelphij by inflate() if needed. 976205194Sdelphij 977205194Sdelphij inflateReset2 returns Z_OK if success, or Z_STREAM_ERROR if the source 978205194Sdelphij stream state was inconsistent (such as zalloc or state being Z_NULL), or if 979205194Sdelphij the windowBits parameter is invalid. 980205194Sdelphij*/ 981205194Sdelphij 982157043SdesZEXTERN int ZEXPORT inflatePrime OF((z_streamp strm, 983157043Sdes int bits, 984157043Sdes int value)); 985131377Stjr/* 986157043Sdes This function inserts bits in the inflate input stream. The intent is 987205194Sdelphij that this function is used to start inflating at a bit position in the 988205194Sdelphij middle of a byte. The provided bits will be used before any bytes are used 989205194Sdelphij from next_in. This function should only be used with raw inflate, and 990205194Sdelphij should be used before the first inflate() call after inflateInit2() or 991205194Sdelphij inflateReset(). bits must be less than or equal to 16, and that many of the 992205194Sdelphij least significant bits of value will be inserted in the input. 993157043Sdes 994205194Sdelphij If bits is negative, then the input stream bit buffer is emptied. Then 995205194Sdelphij inflatePrime() can be called again to put bits in the buffer. This is used 996205194Sdelphij to clear out bits leftover after feeding inflate a block description prior 997205194Sdelphij to feeding inflate codes. 998205194Sdelphij 999205194Sdelphij inflatePrime returns Z_OK if success, or Z_STREAM_ERROR if the source 1000157043Sdes stream state was inconsistent. 1001157043Sdes*/ 1002157043Sdes 1003205194SdelphijZEXTERN long ZEXPORT inflateMark OF((z_streamp strm)); 1004205194Sdelphij/* 1005205194Sdelphij This function returns two values, one in the lower 16 bits of the return 1006205194Sdelphij value, and the other in the remaining upper bits, obtained by shifting the 1007205194Sdelphij return value down 16 bits. If the upper value is -1 and the lower value is 1008205194Sdelphij zero, then inflate() is currently decoding information outside of a block. 1009205194Sdelphij If the upper value is -1 and the lower value is non-zero, then inflate is in 1010205194Sdelphij the middle of a stored block, with the lower value equaling the number of 1011205194Sdelphij bytes from the input remaining to copy. If the upper value is not -1, then 1012205194Sdelphij it is the number of bits back from the current bit position in the input of 1013205194Sdelphij the code (literal or length/distance pair) currently being processed. In 1014205194Sdelphij that case the lower value is the number of bytes already emitted for that 1015205194Sdelphij code. 1016205194Sdelphij 1017205194Sdelphij A code is being processed if inflate is waiting for more input to complete 1018205194Sdelphij decoding of the code, or if it has completed decoding but is waiting for 1019205194Sdelphij more output space to write the literal or match data. 1020205194Sdelphij 1021205194Sdelphij inflateMark() is used to mark locations in the input data for random 1022205194Sdelphij access, which may be at bit positions, and to note those cases where the 1023205194Sdelphij output of a code may span boundaries of random access blocks. The current 1024205194Sdelphij location in the input stream can be determined from avail_in and data_type 1025205194Sdelphij as noted in the description for the Z_BLOCK flush parameter for inflate. 1026205194Sdelphij 1027313796Sdelphij inflateMark returns the value noted above, or -65536 if the provided 1028205194Sdelphij source stream state was inconsistent. 1029205194Sdelphij*/ 1030205194Sdelphij 1031157043SdesZEXTERN int ZEXPORT inflateGetHeader OF((z_streamp strm, 1032157043Sdes gz_headerp head)); 1033157043Sdes/* 1034205194Sdelphij inflateGetHeader() requests that gzip header information be stored in the 1035157043Sdes provided gz_header structure. inflateGetHeader() may be called after 1036157043Sdes inflateInit2() or inflateReset(), and before the first call of inflate(). 1037157043Sdes As inflate() processes the gzip stream, head->done is zero until the header 1038157043Sdes is completed, at which time head->done is set to one. If a zlib stream is 1039157043Sdes being decoded, then head->done is set to -1 to indicate that there will be 1040205194Sdelphij no gzip header information forthcoming. Note that Z_BLOCK or Z_TREES can be 1041205194Sdelphij used to force inflate() to return immediately after header processing is 1042205194Sdelphij complete and before any actual data is decompressed. 1043157043Sdes 1044205194Sdelphij The text, time, xflags, and os fields are filled in with the gzip header 1045157043Sdes contents. hcrc is set to true if there is a header CRC. (The header CRC 1046205194Sdelphij was valid if done is set to one.) If extra is not Z_NULL, then extra_max 1047157043Sdes contains the maximum number of bytes to write to extra. Once done is true, 1048157043Sdes extra_len contains the actual extra field length, and extra contains the 1049157043Sdes extra field, or that field truncated if extra_max is less than extra_len. 1050157043Sdes If name is not Z_NULL, then up to name_max characters are written there, 1051157043Sdes terminated with a zero unless the length is greater than name_max. If 1052157043Sdes comment is not Z_NULL, then up to comm_max characters are written there, 1053205194Sdelphij terminated with a zero unless the length is greater than comm_max. When any 1054205194Sdelphij of extra, name, or comment are not Z_NULL and the respective field is not 1055205194Sdelphij present in the header, then that field is set to Z_NULL to signal its 1056157043Sdes absence. This allows the use of deflateSetHeader() with the returned 1057157043Sdes structure to duplicate the header. However if those fields are set to 1058157043Sdes allocated memory, then the application will need to save those pointers 1059157043Sdes elsewhere so that they can be eventually freed. 1060157043Sdes 1061205194Sdelphij If inflateGetHeader is not used, then the header information is simply 1062157043Sdes discarded. The header is always checked for validity, including the header 1063157043Sdes CRC if present. inflateReset() will reset the process to discard the header 1064157043Sdes information. The application would need to call inflateGetHeader() again to 1065157043Sdes retrieve the header from the next gzip stream. 1066157043Sdes 1067205194Sdelphij inflateGetHeader returns Z_OK if success, or Z_STREAM_ERROR if the source 1068157043Sdes stream state was inconsistent. 1069157043Sdes*/ 1070157043Sdes 1071157043Sdes/* 1072157043SdesZEXTERN int ZEXPORT inflateBackInit OF((z_streamp strm, int windowBits, 1073131377Stjr unsigned char FAR *window)); 107417651Speter 1075131377Stjr Initialize the internal stream state for decompression using inflateBack() 1076131377Stjr calls. The fields zalloc, zfree and opaque in strm must be initialized 1077131377Stjr before the call. If zalloc and zfree are Z_NULL, then the default library- 1078131377Stjr derived memory allocation routines are used. windowBits is the base two 1079131377Stjr logarithm of the window size, in the range 8..15. window is a caller 1080131377Stjr supplied buffer of that size. Except for special applications where it is 1081131377Stjr assured that deflate was used with small window sizes, windowBits must be 15 1082131377Stjr and a 32K byte window must be supplied to be able to decompress general 1083131377Stjr deflate streams. 1084131377Stjr 1085131377Stjr See inflateBack() for the usage of these routines. 1086131377Stjr 1087131377Stjr inflateBackInit will return Z_OK on success, Z_STREAM_ERROR if any of 1088230837Sdelphij the parameters are invalid, Z_MEM_ERROR if the internal state could not be 1089205194Sdelphij allocated, or Z_VERSION_ERROR if the version of the library does not match 1090205194Sdelphij the version of the header file. 1091131377Stjr*/ 1092131377Stjr 1093250224Sdelphijtypedef unsigned (*in_func) OF((void FAR *, 1094250224Sdelphij z_const unsigned char FAR * FAR *)); 1095131377Stjrtypedef int (*out_func) OF((void FAR *, unsigned char FAR *, unsigned)); 1096131377Stjr 1097157043SdesZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, 1098131377Stjr in_func in, void FAR *in_desc, 1099131377Stjr out_func out, void FAR *out_desc)); 1100131377Stjr/* 1101131377Stjr inflateBack() does a raw inflate with a single call using a call-back 1102250224Sdelphij interface for input and output. This is potentially more efficient than 1103250224Sdelphij inflate() for file i/o applications, in that it avoids copying between the 1104250224Sdelphij output and the sliding window by simply making the window itself the output 1105250224Sdelphij buffer. inflate() can be faster on modern CPUs when used with large 1106250224Sdelphij buffers. inflateBack() trusts the application to not change the output 1107250224Sdelphij buffer passed by the output function, at least until inflateBack() returns. 1108131377Stjr 1109131377Stjr inflateBackInit() must be called first to allocate the internal state 1110131377Stjr and to initialize the state with the user-provided window buffer. 1111131377Stjr inflateBack() may then be used multiple times to inflate a complete, raw 1112205194Sdelphij deflate stream with each call. inflateBackEnd() is then called to free the 1113205194Sdelphij allocated state. 1114131377Stjr 1115131377Stjr A raw deflate stream is one with no zlib or gzip header or trailer. 1116131377Stjr This routine would normally be used in a utility that reads zip or gzip 1117131377Stjr files and writes out uncompressed files. The utility would decode the 1118205194Sdelphij header and process the trailer on its own, hence this routine expects only 1119313796Sdelphij the raw deflate stream to decompress. This is different from the default 1120313796Sdelphij behavior of inflate(), which expects a zlib header and trailer around the 1121313796Sdelphij deflate stream. 1122131377Stjr 1123131377Stjr inflateBack() uses two subroutines supplied by the caller that are then 1124131377Stjr called by inflateBack() for input and output. inflateBack() calls those 1125131377Stjr routines until it reads a complete deflate stream and writes out all of the 1126131377Stjr uncompressed data, or until it encounters an error. The function's 1127131377Stjr parameters and return types are defined above in the in_func and out_func 1128131377Stjr typedefs. inflateBack() will call in(in_desc, &buf) which should return the 1129131377Stjr number of bytes of provided input, and a pointer to that input in buf. If 1130313796Sdelphij there is no input available, in() must return zero -- buf is ignored in that 1131313796Sdelphij case -- and inflateBack() will return a buffer error. inflateBack() will 1132313796Sdelphij call out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. 1133313796Sdelphij out() should return zero on success, or non-zero on failure. If out() 1134313796Sdelphij returns non-zero, inflateBack() will return with an error. Neither in() nor 1135313796Sdelphij out() are permitted to change the contents of the window provided to 1136131377Stjr inflateBackInit(), which is also the buffer that out() uses to write from. 1137131377Stjr The length written by out() will be at most the window size. Any non-zero 1138131377Stjr amount of input may be provided by in(). 1139131377Stjr 1140131377Stjr For convenience, inflateBack() can be provided input on the first call by 1141131377Stjr setting strm->next_in and strm->avail_in. If that input is exhausted, then 1142131377Stjr in() will be called. Therefore strm->next_in must be initialized before 1143131377Stjr calling inflateBack(). If strm->next_in is Z_NULL, then in() will be called 1144131377Stjr immediately for input. If strm->next_in is not Z_NULL, then strm->avail_in 1145131377Stjr must also be initialized, and then if strm->avail_in is not zero, input will 1146205194Sdelphij initially be taken from strm->next_in[0 .. strm->avail_in - 1]. 1147131377Stjr 1148131377Stjr The in_desc and out_desc parameters of inflateBack() is passed as the 1149131377Stjr first parameter of in() and out() respectively when they are called. These 1150131377Stjr descriptors can be optionally used to pass any information that the caller- 1151131377Stjr supplied in() and out() functions need to do their job. 1152131377Stjr 1153131377Stjr On return, inflateBack() will set strm->next_in and strm->avail_in to 1154131377Stjr pass back any unused input that was provided by the last in() call. The 1155131377Stjr return values of inflateBack() can be Z_STREAM_END on success, Z_BUF_ERROR 1156205194Sdelphij if in() or out() returned an error, Z_DATA_ERROR if there was a format error 1157205194Sdelphij in the deflate stream (in which case strm->msg is set to indicate the nature 1158205194Sdelphij of the error), or Z_STREAM_ERROR if the stream was not properly initialized. 1159205194Sdelphij In the case of Z_BUF_ERROR, an input or output error can be distinguished 1160205194Sdelphij using strm->next_in which will be Z_NULL only if in() returned an error. If 1161205194Sdelphij strm->next_in is not Z_NULL, then the Z_BUF_ERROR was due to out() returning 1162205194Sdelphij non-zero. (in() will always be called before out(), so strm->next_in is 1163313796Sdelphij assured to be defined if out() returns non-zero.) Note that inflateBack() 1164205194Sdelphij cannot return Z_OK. 1165131377Stjr*/ 1166131377Stjr 1167157043SdesZEXTERN int ZEXPORT inflateBackEnd OF((z_streamp strm)); 1168131377Stjr/* 1169131377Stjr All memory allocated by inflateBackInit() is freed. 1170131377Stjr 1171131377Stjr inflateBackEnd() returns Z_OK on success, or Z_STREAM_ERROR if the stream 1172131377Stjr state was inconsistent. 1173131377Stjr*/ 1174131377Stjr 1175131377StjrZEXTERN uLong ZEXPORT zlibCompileFlags OF((void)); 1176131377Stjr/* Return flags indicating compile-time options. 1177131377Stjr 1178131377Stjr Type sizes, two bits each, 00 = 16 bits, 01 = 32, 10 = 64, 11 = other: 1179131377Stjr 1.0: size of uInt 1180131377Stjr 3.2: size of uLong 1181131377Stjr 5.4: size of voidpf (pointer) 1182131377Stjr 7.6: size of z_off_t 1183131377Stjr 1184131377Stjr Compiler, assembler, and debug options: 1185313796Sdelphij 8: ZLIB_DEBUG 1186131377Stjr 9: ASMV or ASMINF -- use ASM code 1187131377Stjr 10: ZLIB_WINAPI -- exported functions use the WINAPI calling convention 1188131377Stjr 11: 0 (reserved) 1189131377Stjr 1190131377Stjr One-time table building (smaller code, but not thread-safe if true): 1191131377Stjr 12: BUILDFIXED -- build static block decoding tables when needed 1192131377Stjr 13: DYNAMIC_CRC_TABLE -- build CRC calculation tables when needed 1193131377Stjr 14,15: 0 (reserved) 1194131377Stjr 1195131377Stjr Library content (indicates missing functionality): 1196131377Stjr 16: NO_GZCOMPRESS -- gz* functions cannot compress (to avoid linking 1197131377Stjr deflate code when not needed) 1198131377Stjr 17: NO_GZIP -- deflate can't write gzip streams, and inflate can't detect 1199131377Stjr and decode gzip streams (to avoid linking crc code) 1200131377Stjr 18-19: 0 (reserved) 1201131377Stjr 1202131377Stjr Operation variations (changes in library functionality): 1203131377Stjr 20: PKZIP_BUG_WORKAROUND -- slightly more permissive inflate 1204131377Stjr 21: FASTEST -- deflate algorithm with only one, lowest compression level 1205131377Stjr 22,23: 0 (reserved) 1206131377Stjr 1207131377Stjr The sprintf variant used by gzprintf (zero is best): 1208131377Stjr 24: 0 = vs*, 1 = s* -- 1 means limited to 20 arguments after the format 1209131377Stjr 25: 0 = *nprintf, 1 = *printf -- 1 means gzprintf() not secure! 1210131377Stjr 26: 0 = returns value, 1 = void -- 1 means inferred string length returned 1211131377Stjr 1212131377Stjr Remainder: 1213131377Stjr 27-31: 0 (reserved) 1214131377Stjr */ 1215131377Stjr 1216230837Sdelphij#ifndef Z_SOLO 1217131377Stjr 121817651Speter /* utility functions */ 121917651Speter 122017651Speter/* 1221205194Sdelphij The following utility functions are implemented on top of the basic 1222205194Sdelphij stream-oriented functions. To simplify the interface, some default options 1223205194Sdelphij are assumed (compression level and memory usage, standard memory allocation 1224205194Sdelphij functions). The source code of these utility functions can be modified if 1225205194Sdelphij you need special options. 122617651Speter*/ 122717651Speter 122842468SpeterZEXTERN int ZEXPORT compress OF((Bytef *dest, uLongf *destLen, 122942468Speter const Bytef *source, uLong sourceLen)); 123017651Speter/* 123117651Speter Compresses the source buffer into the destination buffer. sourceLen is 1232205194Sdelphij the byte length of the source buffer. Upon entry, destLen is the total size 1233205194Sdelphij of the destination buffer, which must be at least the value returned by 1234205194Sdelphij compressBound(sourceLen). Upon exit, destLen is the actual size of the 1235313796Sdelphij compressed data. compress() is equivalent to compress2() with a level 1236313796Sdelphij parameter of Z_DEFAULT_COMPRESSION. 1237205194Sdelphij 123817651Speter compress returns Z_OK if success, Z_MEM_ERROR if there was not 123917651Speter enough memory, Z_BUF_ERROR if there was not enough room in the output 124017651Speter buffer. 124117651Speter*/ 124217651Speter 124342468SpeterZEXTERN int ZEXPORT compress2 OF((Bytef *dest, uLongf *destLen, 124442468Speter const Bytef *source, uLong sourceLen, 124542468Speter int level)); 124617651Speter/* 1247205194Sdelphij Compresses the source buffer into the destination buffer. The level 124833904Ssteve parameter has the same meaning as in deflateInit. sourceLen is the byte 1249205194Sdelphij length of the source buffer. Upon entry, destLen is the total size of the 1250131377Stjr destination buffer, which must be at least the value returned by 1251205194Sdelphij compressBound(sourceLen). Upon exit, destLen is the actual size of the 1252313796Sdelphij compressed data. 125333904Ssteve 125433904Ssteve compress2 returns Z_OK if success, Z_MEM_ERROR if there was not enough 125533904Ssteve memory, Z_BUF_ERROR if there was not enough room in the output buffer, 125633904Ssteve Z_STREAM_ERROR if the level parameter is invalid. 125733904Ssteve*/ 125833904Ssteve 1259131377StjrZEXTERN uLong ZEXPORT compressBound OF((uLong sourceLen)); 1260131377Stjr/* 1261131377Stjr compressBound() returns an upper bound on the compressed size after 1262205194Sdelphij compress() or compress2() on sourceLen bytes. It would be used before a 1263205194Sdelphij compress() or compress2() call to allocate the destination buffer. 1264131377Stjr*/ 1265131377Stjr 126642468SpeterZEXTERN int ZEXPORT uncompress OF((Bytef *dest, uLongf *destLen, 126742468Speter const Bytef *source, uLong sourceLen)); 126833904Ssteve/* 126917651Speter Decompresses the source buffer into the destination buffer. sourceLen is 1270205194Sdelphij the byte length of the source buffer. Upon entry, destLen is the total size 1271205194Sdelphij of the destination buffer, which must be large enough to hold the entire 1272205194Sdelphij uncompressed data. (The size of the uncompressed data must have been saved 1273205194Sdelphij previously by the compressor and transmitted to the decompressor by some 1274205194Sdelphij mechanism outside the scope of this compression library.) Upon exit, destLen 1275313796Sdelphij is the actual size of the uncompressed data. 127617651Speter 127717651Speter uncompress returns Z_OK if success, Z_MEM_ERROR if there was not 127817651Speter enough memory, Z_BUF_ERROR if there was not enough room in the output 1279230837Sdelphij buffer, or Z_DATA_ERROR if the input data was corrupted or incomplete. In 1280230837Sdelphij the case where there is not enough room, uncompress() will fill the output 1281230837Sdelphij buffer with the uncompressed data up to that point. 128217651Speter*/ 128317651Speter 1284313796SdelphijZEXTERN int ZEXPORT uncompress2 OF((Bytef *dest, uLongf *destLen, 1285313796Sdelphij const Bytef *source, uLong *sourceLen)); 1286313796Sdelphij/* 1287313796Sdelphij Same as uncompress, except that sourceLen is a pointer, where the 1288313796Sdelphij length of the source is *sourceLen. On return, *sourceLen is the number of 1289313796Sdelphij source bytes consumed. 1290313796Sdelphij*/ 1291313796Sdelphij 1292205194Sdelphij /* gzip file access functions */ 129317651Speter 129417651Speter/* 1295205194Sdelphij This library supports reading and writing files in gzip (.gz) format with 1296205194Sdelphij an interface similar to that of stdio, using the functions that start with 1297205194Sdelphij "gz". The gzip format is different from the zlib format. gzip is a gzip 1298205194Sdelphij wrapper, documented in RFC 1952, wrapped around a deflate stream. 1299205194Sdelphij*/ 130033904Ssteve 1301230837Sdelphijtypedef struct gzFile_s *gzFile; /* semi-opaque gzip file descriptor */ 1302205194Sdelphij 1303205194Sdelphij/* 1304205194SdelphijZEXTERN gzFile ZEXPORT gzopen OF((const char *path, const char *mode)); 1305205194Sdelphij 1306205194Sdelphij Opens a gzip (.gz) file for reading or writing. The mode parameter is as 1307205194Sdelphij in fopen ("rb" or "wb") but can also include a compression level ("wb9") or 1308205194Sdelphij a strategy: 'f' for filtered data as in "wb6f", 'h' for Huffman-only 1309205194Sdelphij compression as in "wb1h", 'R' for run-length encoding as in "wb1R", or 'F' 1310205194Sdelphij for fixed code compression as in "wb9F". (See the description of 1311230837Sdelphij deflateInit2 for more information about the strategy parameter.) 'T' will 1312230837Sdelphij request transparent writing or appending with no compression and not using 1313230837Sdelphij the gzip format. 1314205194Sdelphij 1315230837Sdelphij "a" can be used instead of "w" to request that the gzip stream that will 1316230837Sdelphij be written be appended to the file. "+" will result in an error, since 1317237248Sdelphij reading and writing to the same gzip file is not supported. The addition of 1318237248Sdelphij "x" when writing will create the file exclusively, which fails if the file 1319237248Sdelphij already exists. On systems that support it, the addition of "e" when 1320237248Sdelphij reading or writing will set the flag to close the file on an execve() call. 1321230837Sdelphij 1322230837Sdelphij These functions, as well as gzip, will read and decode a sequence of gzip 1323230837Sdelphij streams in a file. The append function of gzopen() can be used to create 1324230837Sdelphij such a file. (Also see gzflush() for another way to do this.) When 1325230837Sdelphij appending, gzopen does not test whether the file begins with a gzip stream, 1326230837Sdelphij nor does it look for the end of the gzip streams to begin appending. gzopen 1327230837Sdelphij will simply append a gzip stream to the existing file. 1328230837Sdelphij 132933904Ssteve gzopen can be used to read a file which is not in gzip format; in this 1330230837Sdelphij case gzread will directly read from the file without decompression. When 1331230837Sdelphij reading, this will be detected automatically by looking for the magic two- 1332230837Sdelphij byte gzip header. 133333904Ssteve 1334205194Sdelphij gzopen returns NULL if the file could not be opened, if there was 1335205194Sdelphij insufficient memory to allocate the gzFile state, or if an invalid mode was 1336205194Sdelphij specified (an 'r', 'w', or 'a' was not provided, or '+' was provided). 1337205194Sdelphij errno can be checked to determine if the reason gzopen failed was that the 1338205194Sdelphij file could not be opened. 1339205194Sdelphij*/ 134017651Speter 1341205194SdelphijZEXTERN gzFile ZEXPORT gzdopen OF((int fd, const char *mode)); 134217651Speter/* 1343205194Sdelphij gzdopen associates a gzFile with the file descriptor fd. File descriptors 1344205194Sdelphij are obtained from calls like open, dup, creat, pipe or fileno (if the file 1345205194Sdelphij has been previously opened with fopen). The mode parameter is as in gzopen. 1346205194Sdelphij 1347205194Sdelphij The next call of gzclose on the returned gzFile will also close the file 1348205194Sdelphij descriptor fd, just like fclose(fdopen(fd, mode)) closes the file descriptor 1349205194Sdelphij fd. If you want to keep fd open, use fd = dup(fd_keep); gz = gzdopen(fd, 1350205194Sdelphij mode);. The duplicated descriptor should be saved to avoid a leak, since 1351230837Sdelphij gzdopen does not close fd if it fails. If you are using fileno() to get the 1352230837Sdelphij file descriptor from a FILE *, then you will have to use dup() to avoid 1353230837Sdelphij double-close()ing the file descriptor. Both gzclose() and fclose() will 1354230837Sdelphij close the associated file descriptor, so they need to have different file 1355230837Sdelphij descriptors. 1356205194Sdelphij 1357205194Sdelphij gzdopen returns NULL if there was insufficient memory to allocate the 1358205194Sdelphij gzFile state, if an invalid mode was specified (an 'r', 'w', or 'a' was not 1359205194Sdelphij provided, or '+' was provided), or if fd is -1. The file descriptor is not 1360205194Sdelphij used until the next gz* read, write, seek, or close operation, so gzdopen 1361205194Sdelphij will not detect if fd is invalid (unless fd is -1). 136217651Speter*/ 136317651Speter 1364205194SdelphijZEXTERN int ZEXPORT gzbuffer OF((gzFile file, unsigned size)); 1365205194Sdelphij/* 1366205194Sdelphij Set the internal buffer size used by this library's functions. The 1367205194Sdelphij default buffer size is 8192 bytes. This function must be called after 1368205194Sdelphij gzopen() or gzdopen(), and before any other calls that read or write the 1369205194Sdelphij file. The buffer memory allocation is always deferred to the first read or 1370313796Sdelphij write. Three times that size in buffer space is allocated. A larger buffer 1371313796Sdelphij size of, for example, 64K or 128K bytes will noticeably increase the speed 1372313796Sdelphij of decompression (reading). 1373205194Sdelphij 1374205194Sdelphij The new buffer size also affects the maximum length for gzprintf(). 1375205194Sdelphij 1376205194Sdelphij gzbuffer() returns 0 on success, or -1 on failure, such as being called 1377205194Sdelphij too late. 1378205194Sdelphij*/ 1379205194Sdelphij 138042468SpeterZEXTERN int ZEXPORT gzsetparams OF((gzFile file, int level, int strategy)); 138117651Speter/* 1382205194Sdelphij Dynamically update the compression level or strategy. See the description 1383313796Sdelphij of deflateInit2 for the meaning of these parameters. Previously provided 1384313796Sdelphij data is flushed before the parameter change. 1385205194Sdelphij 1386313796Sdelphij gzsetparams returns Z_OK if success, Z_STREAM_ERROR if the file was not 1387313796Sdelphij opened for writing, Z_ERRNO if there is an error writing the flushed data, 1388313796Sdelphij or Z_MEM_ERROR if there is a memory allocation error. 138933904Ssteve*/ 139033904Ssteve 1391205194SdelphijZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len)); 139233904Ssteve/* 1393205194Sdelphij Reads the given number of uncompressed bytes from the compressed file. If 1394230837Sdelphij the input file is not in gzip format, gzread copies the given number of 1395230837Sdelphij bytes into the buffer directly from the file. 139617651Speter 1397205194Sdelphij After reaching the end of a gzip stream in the input, gzread will continue 1398230837Sdelphij to read, looking for another gzip stream. Any number of gzip streams may be 1399230837Sdelphij concatenated in the input file, and will all be decompressed by gzread(). 1400230837Sdelphij If something other than a gzip stream is encountered after a gzip stream, 1401230837Sdelphij that remaining trailing garbage is ignored (and no error is returned). 1402205194Sdelphij 1403230837Sdelphij gzread can be used to read a gzip file that is being concurrently written. 1404230837Sdelphij Upon reaching the end of the input, gzread will return with the available 1405230837Sdelphij data. If the error code returned by gzerror is Z_OK or Z_BUF_ERROR, then 1406230837Sdelphij gzclearerr can be used to clear the end of file indicator in order to permit 1407230837Sdelphij gzread to be tried again. Z_OK indicates that a gzip stream was completed 1408230837Sdelphij on the last gzread. Z_BUF_ERROR indicates that the input file ended in the 1409230837Sdelphij middle of a gzip stream. Note that gzread does not return -1 in the event 1410230837Sdelphij of an incomplete gzip stream. This error is deferred until gzclose(), which 1411230837Sdelphij will return Z_BUF_ERROR if the last gzread ended in the middle of a gzip 1412230837Sdelphij stream. Alternatively, gzerror can be used before gzclose to detect this 1413230837Sdelphij case. 1414230837Sdelphij 1415205194Sdelphij gzread returns the number of uncompressed bytes actually read, less than 1416313796Sdelphij len for end of file, or -1 for error. If len is too large to fit in an int, 1417313796Sdelphij then nothing is read, -1 is returned, and the error state is set to 1418313796Sdelphij Z_STREAM_ERROR. 1419205194Sdelphij*/ 1420205194Sdelphij 1421313796SdelphijZEXTERN z_size_t ZEXPORT gzfread OF((voidp buf, z_size_t size, z_size_t nitems, 1422313796Sdelphij gzFile file)); 1423313796Sdelphij/* 1424313796Sdelphij Read up to nitems items of size size from file to buf, otherwise operating 1425313796Sdelphij as gzread() does. This duplicates the interface of stdio's fread(), with 1426313796Sdelphij size_t request and return types. If the library defines size_t, then 1427313796Sdelphij z_size_t is identical to size_t. If not, then z_size_t is an unsigned 1428313796Sdelphij integer type that can contain a pointer. 1429313796Sdelphij 1430313796Sdelphij gzfread() returns the number of full items read of size size, or zero if 1431313796Sdelphij the end of the file was reached and a full item could not be read, or if 1432313796Sdelphij there was an error. gzerror() must be consulted if zero is returned in 1433313796Sdelphij order to determine if there was an error. If the multiplication of size and 1434313796Sdelphij nitems overflows, i.e. the product does not fit in a z_size_t, then nothing 1435313796Sdelphij is read, zero is returned, and the error state is set to Z_STREAM_ERROR. 1436313796Sdelphij 1437313796Sdelphij In the event that the end of file is reached and only a partial item is 1438313796Sdelphij available at the end, i.e. the remaining uncompressed data length is not a 1439313796Sdelphij multiple of size, then the final partial item is nevetheless read into buf 1440313796Sdelphij and the end-of-file flag is set. The length of the partial item read is not 1441313796Sdelphij provided, but could be inferred from the result of gztell(). This behavior 1442313796Sdelphij is the same as the behavior of fread() implementations in common libraries, 1443313796Sdelphij but it prevents the direct use of gzfread() to read a concurrently written 1444313796Sdelphij file, reseting and retrying on end-of-file, when size is not 1. 1445313796Sdelphij*/ 1446313796Sdelphij 1447205194SdelphijZEXTERN int ZEXPORT gzwrite OF((gzFile file, 1448205194Sdelphij voidpc buf, unsigned len)); 144917651Speter/* 145017651Speter Writes the given number of uncompressed bytes into the compressed file. 1451205194Sdelphij gzwrite returns the number of uncompressed bytes written or 0 in case of 1452205194Sdelphij error. 145317651Speter*/ 145417651Speter 1455313796SdelphijZEXTERN z_size_t ZEXPORT gzfwrite OF((voidpc buf, z_size_t size, 1456313796Sdelphij z_size_t nitems, gzFile file)); 1457313796Sdelphij/* 1458313796Sdelphij gzfwrite() writes nitems items of size size from buf to file, duplicating 1459313796Sdelphij the interface of stdio's fwrite(), with size_t request and return types. If 1460313796Sdelphij the library defines size_t, then z_size_t is identical to size_t. If not, 1461313796Sdelphij then z_size_t is an unsigned integer type that can contain a pointer. 1462313796Sdelphij 1463313796Sdelphij gzfwrite() returns the number of full items written of size size, or zero 1464313796Sdelphij if there was an error. If the multiplication of size and nitems overflows, 1465313796Sdelphij i.e. the product does not fit in a z_size_t, then nothing is written, zero 1466313796Sdelphij is returned, and the error state is set to Z_STREAM_ERROR. 1467313796Sdelphij*/ 1468313796Sdelphij 1469230837SdelphijZEXTERN int ZEXPORTVA gzprintf Z_ARG((gzFile file, const char *format, ...)); 147017651Speter/* 1471205194Sdelphij Converts, formats, and writes the arguments to the compressed file under 1472205194Sdelphij control of the format string, as in fprintf. gzprintf returns the number of 1473313796Sdelphij uncompressed bytes actually written, or a negative zlib error code in case 1474313796Sdelphij of error. The number of uncompressed bytes written is limited to 8191, or 1475313796Sdelphij one less than the buffer size given to gzbuffer(). The caller should assure 1476313796Sdelphij that this limit is not exceeded. If it is exceeded, then gzprintf() will 1477313796Sdelphij return an error (0) with nothing written. In this case, there may also be a 1478313796Sdelphij buffer overflow with unpredictable consequences, which is possible only if 1479313796Sdelphij zlib was compiled with the insecure functions sprintf() or vsprintf() 1480313796Sdelphij because the secure snprintf() or vsnprintf() functions were not available. 1481313796Sdelphij This can be determined using zlibCompileFlags(). 148233904Ssteve*/ 148333904Ssteve 148442468SpeterZEXTERN int ZEXPORT gzputs OF((gzFile file, const char *s)); 148533904Ssteve/* 1486205194Sdelphij Writes the given null-terminated string to the compressed file, excluding 148733904Ssteve the terminating null character. 1488205194Sdelphij 1489205194Sdelphij gzputs returns the number of characters written, or -1 in case of error. 149033904Ssteve*/ 149133904Ssteve 149242468SpeterZEXTERN char * ZEXPORT gzgets OF((gzFile file, char *buf, int len)); 149333904Ssteve/* 1494205194Sdelphij Reads bytes from the compressed file until len-1 characters are read, or a 1495205194Sdelphij newline character is read and transferred to buf, or an end-of-file 1496205194Sdelphij condition is encountered. If any characters are read or if len == 1, the 1497205194Sdelphij string is terminated with a null character. If no characters are read due 1498205194Sdelphij to an end-of-file or len < 1, then the buffer is left untouched. 1499205194Sdelphij 1500205194Sdelphij gzgets returns buf which is a null-terminated string, or it returns NULL 1501205194Sdelphij for end-of-file or in case of error. If there was an error, the contents at 1502205194Sdelphij buf are indeterminate. 150333904Ssteve*/ 150433904Ssteve 1505205194SdelphijZEXTERN int ZEXPORT gzputc OF((gzFile file, int c)); 150633904Ssteve/* 1507205194Sdelphij Writes c, converted to an unsigned char, into the compressed file. gzputc 1508205194Sdelphij returns the value that was written, or -1 in case of error. 150933904Ssteve*/ 151033904Ssteve 1511205194SdelphijZEXTERN int ZEXPORT gzgetc OF((gzFile file)); 151233904Ssteve/* 1513205194Sdelphij Reads one byte from the compressed file. gzgetc returns this byte or -1 1514230837Sdelphij in case of end of file or error. This is implemented as a macro for speed. 1515230837Sdelphij As such, it does not do all of the checking the other functions do. I.e. 1516230837Sdelphij it does not check to see if file is NULL, nor whether the structure file 1517230837Sdelphij points to has been clobbered or not. 151833904Ssteve*/ 151933904Ssteve 1520205194SdelphijZEXTERN int ZEXPORT gzungetc OF((int c, gzFile file)); 1521131377Stjr/* 1522205194Sdelphij Push one character back onto the stream to be read as the first character 1523205194Sdelphij on the next read. At least one character of push-back is allowed. 1524205194Sdelphij gzungetc() returns the character pushed, or -1 on failure. gzungetc() will 1525205194Sdelphij fail if c is -1, and may fail if a character has been pushed but not read 1526205194Sdelphij yet. If gzungetc is used immediately after gzopen or gzdopen, at least the 1527205194Sdelphij output buffer size of pushed characters is allowed. (See gzbuffer above.) 1528205194Sdelphij The pushed character will be discarded if the stream is repositioned with 1529205194Sdelphij gzseek() or gzrewind(). 1530131377Stjr*/ 1531131377Stjr 1532205194SdelphijZEXTERN int ZEXPORT gzflush OF((gzFile file, int flush)); 153333904Ssteve/* 1534205194Sdelphij Flushes all pending output into the compressed file. The parameter flush 1535205194Sdelphij is as in the deflate() function. The return value is the zlib error number 1536205194Sdelphij (see function gzerror below). gzflush is only permitted when writing. 1537205194Sdelphij 1538205194Sdelphij If the flush parameter is Z_FINISH, the remaining data is written and the 1539205194Sdelphij gzip stream is completed in the output. If gzwrite() is called again, a new 1540205194Sdelphij gzip stream will be started in the output. gzread() is able to read such 1541313796Sdelphij concatenated gzip streams. 1542205194Sdelphij 1543205194Sdelphij gzflush should be called only when strictly necessary because it will 1544205194Sdelphij degrade compression if called too often. 154517651Speter*/ 154617651Speter 1547131377Stjr/* 1548205194SdelphijZEXTERN z_off_t ZEXPORT gzseek OF((gzFile file, 1549205194Sdelphij z_off_t offset, int whence)); 1550205194Sdelphij 1551205194Sdelphij Sets the starting position for the next gzread or gzwrite on the given 1552205194Sdelphij compressed file. The offset represents a number of bytes in the 1553205194Sdelphij uncompressed data stream. The whence parameter is defined as in lseek(2); 155433904Ssteve the value SEEK_END is not supported. 1555205194Sdelphij 155633904Ssteve If the file is opened for reading, this function is emulated but can be 1557205194Sdelphij extremely slow. If the file is opened for writing, only forward seeks are 155833904Ssteve supported; gzseek then compresses a sequence of zeroes up to the new 155933904Ssteve starting position. 156033904Ssteve 1561205194Sdelphij gzseek returns the resulting offset location as measured in bytes from 156233904Ssteve the beginning of the uncompressed stream, or -1 in case of error, in 156333904Ssteve particular if the file is opened for writing and the new starting position 156433904Ssteve would be before the current position. 156533904Ssteve*/ 156633904Ssteve 156742468SpeterZEXTERN int ZEXPORT gzrewind OF((gzFile file)); 156817651Speter/* 156933904Ssteve Rewinds the given file. This function is supported only for reading. 157033904Ssteve 1571205194Sdelphij gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET) 157233904Ssteve*/ 157333904Ssteve 1574205194Sdelphij/* 157542468SpeterZEXTERN z_off_t ZEXPORT gztell OF((gzFile file)); 1576205194Sdelphij 1577205194Sdelphij Returns the starting position for the next gzread or gzwrite on the given 1578205194Sdelphij compressed file. This position represents a number of bytes in the 1579205194Sdelphij uncompressed data stream, and is zero when starting, even if appending or 1580205194Sdelphij reading a gzip stream from the middle of a file using gzdopen(). 1581205194Sdelphij 1582205194Sdelphij gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR) 1583205194Sdelphij*/ 1584205194Sdelphij 158533904Ssteve/* 1586205194SdelphijZEXTERN z_off_t ZEXPORT gzoffset OF((gzFile file)); 158733904Ssteve 1588205194Sdelphij Returns the current offset in the file being read or written. This offset 1589205194Sdelphij includes the count of bytes that precede the gzip stream, for example when 1590205194Sdelphij appending or when using gzdopen() for reading. When reading, the offset 1591205194Sdelphij does not include as yet unused buffered input. This information can be used 1592205194Sdelphij for a progress indicator. On error, gzoffset() returns -1. 159333904Ssteve*/ 159433904Ssteve 159542468SpeterZEXTERN int ZEXPORT gzeof OF((gzFile file)); 159633904Ssteve/* 1597205194Sdelphij Returns true (1) if the end-of-file indicator has been set while reading, 1598205194Sdelphij false (0) otherwise. Note that the end-of-file indicator is set only if the 1599205194Sdelphij read tried to go past the end of the input, but came up short. Therefore, 1600205194Sdelphij just like feof(), gzeof() may return false even if there is no more data to 1601205194Sdelphij read, in the event that the last read request was for the exact number of 1602205194Sdelphij bytes remaining in the input file. This will happen if the input file size 1603205194Sdelphij is an exact multiple of the buffer size. 1604205194Sdelphij 1605205194Sdelphij If gzeof() returns true, then the read functions will return no more data, 1606205194Sdelphij unless the end-of-file indicator is reset by gzclearerr() and the input file 1607205194Sdelphij has grown since the previous end of file was detected. 160833904Ssteve*/ 160933904Ssteve 1610157043SdesZEXTERN int ZEXPORT gzdirect OF((gzFile file)); 1611157043Sdes/* 1612205194Sdelphij Returns true (1) if file is being copied directly while reading, or false 1613230837Sdelphij (0) if file is a gzip stream being decompressed. 1614205194Sdelphij 1615205194Sdelphij If the input file is empty, gzdirect() will return true, since the input 1616205194Sdelphij does not contain a gzip stream. 1617205194Sdelphij 1618205194Sdelphij If gzdirect() is used immediately after gzopen() or gzdopen() it will 1619205194Sdelphij cause buffers to be allocated to allow reading the file to determine if it 1620205194Sdelphij is a gzip file. Therefore if gzbuffer() is used, it should be called before 1621205194Sdelphij gzdirect(). 1622230837Sdelphij 1623230837Sdelphij When writing, gzdirect() returns true (1) if transparent writing was 1624230837Sdelphij requested ("wT" for the gzopen() mode), or false (0) otherwise. (Note: 1625230837Sdelphij gzdirect() is not needed when writing. Transparent writing must be 1626230837Sdelphij explicitly requested, so the application already knows the answer. When 1627230837Sdelphij linking statically, using gzdirect() will include all of the zlib code for 1628230837Sdelphij gzip file reading and decompression, which may not be desired.) 1629157043Sdes*/ 1630157043Sdes 163142468SpeterZEXTERN int ZEXPORT gzclose OF((gzFile file)); 163233904Ssteve/* 1633205194Sdelphij Flushes all pending output if necessary, closes the compressed file and 1634205194Sdelphij deallocates the (de)compression state. Note that once file is closed, you 1635205194Sdelphij cannot call gzerror with file, since its structures have been deallocated. 1636205194Sdelphij gzclose must not be called more than once on the same file, just as free 1637205194Sdelphij must not be called more than once on the same allocation. 1638205194Sdelphij 1639205194Sdelphij gzclose will return Z_STREAM_ERROR if file is not valid, Z_ERRNO on a 1640230837Sdelphij file operation error, Z_MEM_ERROR if out of memory, Z_BUF_ERROR if the 1641230837Sdelphij last read ended in the middle of a gzip stream, or Z_OK on success. 164217651Speter*/ 164317651Speter 1644205194SdelphijZEXTERN int ZEXPORT gzclose_r OF((gzFile file)); 1645205194SdelphijZEXTERN int ZEXPORT gzclose_w OF((gzFile file)); 1646205194Sdelphij/* 1647205194Sdelphij Same as gzclose(), but gzclose_r() is only for use when reading, and 1648205194Sdelphij gzclose_w() is only for use when writing or appending. The advantage to 1649205194Sdelphij using these instead of gzclose() is that they avoid linking in zlib 1650205194Sdelphij compression or decompression code that is not used when only reading or only 1651205194Sdelphij writing respectively. If gzclose() is used, then both compression and 1652205194Sdelphij decompression code will be included the application when linking to a static 1653205194Sdelphij zlib library. 1654205194Sdelphij*/ 1655205194Sdelphij 165642468SpeterZEXTERN const char * ZEXPORT gzerror OF((gzFile file, int *errnum)); 165717651Speter/* 1658205194Sdelphij Returns the error message for the last error which occurred on the given 1659205194Sdelphij compressed file. errnum is set to zlib error number. If an error occurred 1660205194Sdelphij in the file system and not in the compression library, errnum is set to 1661205194Sdelphij Z_ERRNO and the application may consult errno to get the exact error code. 1662205194Sdelphij 1663205194Sdelphij The application must not modify the returned string. Future calls to 1664205194Sdelphij this function may invalidate the previously returned string. If file is 1665205194Sdelphij closed, then the string previously returned by gzerror will no longer be 1666205194Sdelphij available. 1667205194Sdelphij 1668205194Sdelphij gzerror() should be used to distinguish errors from end-of-file for those 1669205194Sdelphij functions above that do not distinguish those cases in their return values. 167017651Speter*/ 167117651Speter 1672131377StjrZEXTERN void ZEXPORT gzclearerr OF((gzFile file)); 1673131377Stjr/* 1674205194Sdelphij Clears the error and end-of-file flags for file. This is analogous to the 1675205194Sdelphij clearerr() function in stdio. This is useful for continuing to read a gzip 1676131377Stjr file that is being written concurrently. 1677131377Stjr*/ 1678131377Stjr 1679230837Sdelphij#endif /* !Z_SOLO */ 1680205194Sdelphij 168117651Speter /* checksum functions */ 168217651Speter 168317651Speter/* 168417651Speter These functions are not related to compression but are exported 1685205194Sdelphij anyway because they might be useful in applications using the compression 1686205194Sdelphij library. 168717651Speter*/ 168817651Speter 168942468SpeterZEXTERN uLong ZEXPORT adler32 OF((uLong adler, const Bytef *buf, uInt len)); 169017651Speter/* 169117651Speter Update a running Adler-32 checksum with the bytes buf[0..len-1] and 1692205194Sdelphij return the updated checksum. If buf is Z_NULL, this function returns the 1693205194Sdelphij required initial value for the checksum. 169417651Speter 1695313796Sdelphij An Adler-32 checksum is almost as reliable as a CRC-32 but can be computed 1696205194Sdelphij much faster. 1697205194Sdelphij 1698205194Sdelphij Usage example: 1699205194Sdelphij 170017651Speter uLong adler = adler32(0L, Z_NULL, 0); 170117651Speter 170217651Speter while (read_buffer(buffer, length) != EOF) { 170317651Speter adler = adler32(adler, buffer, length); 170417651Speter } 170517651Speter if (adler != original_adler) error(); 170617651Speter*/ 170717651Speter 1708313796SdelphijZEXTERN uLong ZEXPORT adler32_z OF((uLong adler, const Bytef *buf, 1709313796Sdelphij z_size_t len)); 1710205194Sdelphij/* 1711313796Sdelphij Same as adler32(), but with a size_t length. 1712313796Sdelphij*/ 1713313796Sdelphij 1714313796Sdelphij/* 1715157043SdesZEXTERN uLong ZEXPORT adler32_combine OF((uLong adler1, uLong adler2, 1716157043Sdes z_off_t len2)); 1717205194Sdelphij 1718157043Sdes Combine two Adler-32 checksums into one. For two sequences of bytes, seq1 1719157043Sdes and seq2 with lengths len1 and len2, Adler-32 checksums were calculated for 1720157043Sdes each, adler1 and adler2. adler32_combine() returns the Adler-32 checksum of 1721230837Sdelphij seq1 and seq2 concatenated, requiring only adler1, adler2, and len2. Note 1722230837Sdelphij that the z_off_t type (like off_t) is a signed integer. If len2 is 1723230837Sdelphij negative, the result has no meaning or utility. 1724157043Sdes*/ 1725157043Sdes 172642468SpeterZEXTERN uLong ZEXPORT crc32 OF((uLong crc, const Bytef *buf, uInt len)); 172717651Speter/* 1728157043Sdes Update a running CRC-32 with the bytes buf[0..len-1] and return the 1729205194Sdelphij updated CRC-32. If buf is Z_NULL, this function returns the required 1730237248Sdelphij initial value for the crc. Pre- and post-conditioning (one's complement) is 1731237248Sdelphij performed within this function so it shouldn't be done by the application. 1732205194Sdelphij 173317651Speter Usage example: 173417651Speter 173517651Speter uLong crc = crc32(0L, Z_NULL, 0); 173617651Speter 173717651Speter while (read_buffer(buffer, length) != EOF) { 173817651Speter crc = crc32(crc, buffer, length); 173917651Speter } 174017651Speter if (crc != original_crc) error(); 174117651Speter*/ 174217651Speter 1743313796SdelphijZEXTERN uLong ZEXPORT crc32_z OF((uLong adler, const Bytef *buf, 1744313796Sdelphij z_size_t len)); 1745205194Sdelphij/* 1746313796Sdelphij Same as crc32(), but with a size_t length. 1747313796Sdelphij*/ 1748313796Sdelphij 1749313796Sdelphij/* 1750157043SdesZEXTERN uLong ZEXPORT crc32_combine OF((uLong crc1, uLong crc2, z_off_t len2)); 175117651Speter 1752157043Sdes Combine two CRC-32 check values into one. For two sequences of bytes, 1753157043Sdes seq1 and seq2 with lengths len1 and len2, CRC-32 check values were 1754157043Sdes calculated for each, crc1 and crc2. crc32_combine() returns the CRC-32 1755157043Sdes check value of seq1 and seq2 concatenated, requiring only crc1, crc2, and 1756157043Sdes len2. 1757157043Sdes*/ 1758157043Sdes 1759157043Sdes 176017651Speter /* various hacks, don't look :) */ 176117651Speter 176217651Speter/* deflateInit and inflateInit are macros to allow checking the zlib version 176317651Speter * and the compiler's view of z_stream: 176417651Speter */ 176542468SpeterZEXTERN int ZEXPORT deflateInit_ OF((z_streamp strm, int level, 176633904Ssteve const char *version, int stream_size)); 176742468SpeterZEXTERN int ZEXPORT inflateInit_ OF((z_streamp strm, 176842468Speter const char *version, int stream_size)); 176942468SpeterZEXTERN int ZEXPORT deflateInit2_ OF((z_streamp strm, int level, int method, 177042468Speter int windowBits, int memLevel, 177142468Speter int strategy, const char *version, 177242468Speter int stream_size)); 177342468SpeterZEXTERN int ZEXPORT inflateInit2_ OF((z_streamp strm, int windowBits, 177442468Speter const char *version, int stream_size)); 1775157043SdesZEXTERN int ZEXPORT inflateBackInit_ OF((z_streamp strm, int windowBits, 1776131377Stjr unsigned char FAR *window, 1777131377Stjr const char *version, 1778131377Stjr int stream_size)); 1779313796Sdelphij#ifdef Z_PREFIX_SET 1780313796Sdelphij# define z_deflateInit(strm, level) \ 1781313796Sdelphij deflateInit_((strm), (level), ZLIB_VERSION, (int)sizeof(z_stream)) 1782313796Sdelphij# define z_inflateInit(strm) \ 1783313796Sdelphij inflateInit_((strm), ZLIB_VERSION, (int)sizeof(z_stream)) 1784313796Sdelphij# define z_deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ 1785313796Sdelphij deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ 1786313796Sdelphij (strategy), ZLIB_VERSION, (int)sizeof(z_stream)) 1787313796Sdelphij# define z_inflateInit2(strm, windowBits) \ 1788313796Sdelphij inflateInit2_((strm), (windowBits), ZLIB_VERSION, \ 1789313796Sdelphij (int)sizeof(z_stream)) 1790313796Sdelphij# define z_inflateBackInit(strm, windowBits, window) \ 1791313796Sdelphij inflateBackInit_((strm), (windowBits), (window), \ 1792313796Sdelphij ZLIB_VERSION, (int)sizeof(z_stream)) 1793313796Sdelphij#else 1794313796Sdelphij# define deflateInit(strm, level) \ 1795313796Sdelphij deflateInit_((strm), (level), ZLIB_VERSION, (int)sizeof(z_stream)) 1796313796Sdelphij# define inflateInit(strm) \ 1797313796Sdelphij inflateInit_((strm), ZLIB_VERSION, (int)sizeof(z_stream)) 1798313796Sdelphij# define deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ 1799313796Sdelphij deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ 1800313796Sdelphij (strategy), ZLIB_VERSION, (int)sizeof(z_stream)) 1801313796Sdelphij# define inflateInit2(strm, windowBits) \ 1802313796Sdelphij inflateInit2_((strm), (windowBits), ZLIB_VERSION, \ 1803313796Sdelphij (int)sizeof(z_stream)) 1804313796Sdelphij# define inflateBackInit(strm, windowBits, window) \ 1805313796Sdelphij inflateBackInit_((strm), (windowBits), (window), \ 1806313796Sdelphij ZLIB_VERSION, (int)sizeof(z_stream)) 1807313796Sdelphij#endif 180817651Speter 1809230837Sdelphij#ifndef Z_SOLO 1810230837Sdelphij 1811230837Sdelphij/* gzgetc() macro and its supporting function and exposed data structure. Note 1812230837Sdelphij * that the real internal state is much larger than the exposed structure. 1813230837Sdelphij * This abbreviated structure exposes just enough for the gzgetc() macro. The 1814230837Sdelphij * user should not mess with these exposed elements, since their names or 1815230837Sdelphij * behavior could change in the future, perhaps even capriciously. They can 1816230837Sdelphij * only be used by the gzgetc() macro. You have been warned. 1817230837Sdelphij */ 1818230837Sdelphijstruct gzFile_s { 1819230837Sdelphij unsigned have; 1820230837Sdelphij unsigned char *next; 1821230837Sdelphij z_off64_t pos; 1822230837Sdelphij}; 1823237248SdelphijZEXTERN int ZEXPORT gzgetc_ OF((gzFile file)); /* backward compatibility */ 1824237248Sdelphij#ifdef Z_PREFIX_SET 1825237248Sdelphij# undef z_gzgetc 1826237248Sdelphij# define z_gzgetc(g) \ 1827313796Sdelphij ((g)->have ? ((g)->have--, (g)->pos++, *((g)->next)++) : (gzgetc)(g)) 1828237248Sdelphij#else 1829237248Sdelphij# define gzgetc(g) \ 1830313796Sdelphij ((g)->have ? ((g)->have--, (g)->pos++, *((g)->next)++) : (gzgetc)(g)) 1831237248Sdelphij#endif 1832230837Sdelphij 1833206499Sdelphij/* provide 64-bit offset functions if _LARGEFILE64_SOURCE defined, and/or 1834206499Sdelphij * change the regular functions to 64 bits if _FILE_OFFSET_BITS is 64 (if 1835206499Sdelphij * both are true, the application gets the *64 functions, and the regular 1836206499Sdelphij * functions are changed to 64 bits) -- in case these are set on systems 1837206499Sdelphij * without large file support, _LFS64_LARGEFILE must also be true 1838206499Sdelphij */ 1839237248Sdelphij#ifdef Z_LARGE64 1840205194Sdelphij ZEXTERN gzFile ZEXPORT gzopen64 OF((const char *, const char *)); 1841206499Sdelphij ZEXTERN z_off64_t ZEXPORT gzseek64 OF((gzFile, z_off64_t, int)); 1842206499Sdelphij ZEXTERN z_off64_t ZEXPORT gztell64 OF((gzFile)); 1843206499Sdelphij ZEXTERN z_off64_t ZEXPORT gzoffset64 OF((gzFile)); 1844206499Sdelphij ZEXTERN uLong ZEXPORT adler32_combine64 OF((uLong, uLong, z_off64_t)); 1845206499Sdelphij ZEXTERN uLong ZEXPORT crc32_combine64 OF((uLong, uLong, z_off64_t)); 1846205194Sdelphij#endif 184733904Ssteve 1848237248Sdelphij#if !defined(ZLIB_INTERNAL) && defined(Z_WANT64) 1849230837Sdelphij# ifdef Z_PREFIX_SET 1850230837Sdelphij# define z_gzopen z_gzopen64 1851230837Sdelphij# define z_gzseek z_gzseek64 1852230837Sdelphij# define z_gztell z_gztell64 1853230837Sdelphij# define z_gzoffset z_gzoffset64 1854230837Sdelphij# define z_adler32_combine z_adler32_combine64 1855230837Sdelphij# define z_crc32_combine z_crc32_combine64 1856230837Sdelphij# else 1857230837Sdelphij# define gzopen gzopen64 1858230837Sdelphij# define gzseek gzseek64 1859230837Sdelphij# define gztell gztell64 1860230837Sdelphij# define gzoffset gzoffset64 1861230837Sdelphij# define adler32_combine adler32_combine64 1862230837Sdelphij# define crc32_combine crc32_combine64 1863230837Sdelphij# endif 1864237248Sdelphij# ifndef Z_LARGE64 1865205194Sdelphij ZEXTERN gzFile ZEXPORT gzopen64 OF((const char *, const char *)); 1866206499Sdelphij ZEXTERN z_off_t ZEXPORT gzseek64 OF((gzFile, z_off_t, int)); 1867206499Sdelphij ZEXTERN z_off_t ZEXPORT gztell64 OF((gzFile)); 1868206499Sdelphij ZEXTERN z_off_t ZEXPORT gzoffset64 OF((gzFile)); 1869206499Sdelphij ZEXTERN uLong ZEXPORT adler32_combine64 OF((uLong, uLong, z_off_t)); 1870206499Sdelphij ZEXTERN uLong ZEXPORT crc32_combine64 OF((uLong, uLong, z_off_t)); 1871205194Sdelphij# endif 1872205194Sdelphij#else 1873205194Sdelphij ZEXTERN gzFile ZEXPORT gzopen OF((const char *, const char *)); 1874205194Sdelphij ZEXTERN z_off_t ZEXPORT gzseek OF((gzFile, z_off_t, int)); 1875205194Sdelphij ZEXTERN z_off_t ZEXPORT gztell OF((gzFile)); 1876205194Sdelphij ZEXTERN z_off_t ZEXPORT gzoffset OF((gzFile)); 1877205194Sdelphij ZEXTERN uLong ZEXPORT adler32_combine OF((uLong, uLong, z_off_t)); 1878205194Sdelphij ZEXTERN uLong ZEXPORT crc32_combine OF((uLong, uLong, z_off_t)); 1879205194Sdelphij#endif 1880205194Sdelphij 1881230837Sdelphij#else /* Z_SOLO */ 1882230837Sdelphij 1883230837Sdelphij ZEXTERN uLong ZEXPORT adler32_combine OF((uLong, uLong, z_off_t)); 1884230837Sdelphij ZEXTERN uLong ZEXPORT crc32_combine OF((uLong, uLong, z_off_t)); 1885230837Sdelphij 1886230837Sdelphij#endif /* !Z_SOLO */ 1887230837Sdelphij 1888206499Sdelphij/* undocumented functions */ 1889145474SkientzleZEXTERN const char * ZEXPORT zError OF((int)); 1890205194SdelphijZEXTERN int ZEXPORT inflateSyncPoint OF((z_streamp)); 1891237248SdelphijZEXTERN const z_crc_t FAR * ZEXPORT get_crc_table OF((void)); 1892205194SdelphijZEXTERN int ZEXPORT inflateUndermine OF((z_streamp, int)); 1893313796SdelphijZEXTERN int ZEXPORT inflateValidate OF((z_streamp, int)); 1894313796SdelphijZEXTERN unsigned long ZEXPORT inflateCodesUsed OF ((z_streamp)); 1895230837SdelphijZEXTERN int ZEXPORT inflateResetKeep OF((z_streamp)); 1896230837SdelphijZEXTERN int ZEXPORT deflateResetKeep OF((z_streamp)); 1897313796Sdelphij#if (defined(_WIN32) || defined(__CYGWIN__)) && !defined(Z_SOLO) 1898237248SdelphijZEXTERN gzFile ZEXPORT gzopen_w OF((const wchar_t *path, 1899237248Sdelphij const char *mode)); 1900230837Sdelphij#endif 1901250224Sdelphij#if defined(STDC) || defined(Z_HAVE_STDARG_H) 1902250224Sdelphij# ifndef Z_SOLO 1903250224SdelphijZEXTERN int ZEXPORTVA gzvprintf Z_ARG((gzFile file, 1904250224Sdelphij const char *format, 1905250224Sdelphij va_list va)); 1906250224Sdelphij# endif 1907250224Sdelphij#endif 190817651Speter 190917651Speter#ifdef __cplusplus 191017651Speter} 191117651Speter#endif 191217651Speter 1913131377Stjr#endif /* ZLIB_H */ 1914