1/* 2 * Copyright (c) 2008 Apple Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28/* zlib.h -- interface of the 'zlib' general purpose compression library 29 version 1.2.3, July 18th, 2005 30 31 Copyright (C) 1995-2005 Jean-loup Gailly and Mark Adler 32 33 This software is provided 'as-is', without any express or implied 34 warranty. In no event will the authors be held liable for any damages 35 arising from the use of this software. 36 37 Permission is granted to anyone to use this software for any purpose, 38 including commercial applications, and to alter it and redistribute it 39 freely, subject to the following restrictions: 40 41 1. The origin of this software must not be misrepresented; you must not 42 claim that you wrote the original software. If you use this software 43 in a product, an acknowledgment in the product documentation would be 44 appreciated but is not required. 45 2. Altered source versions must be plainly marked as such, and must not be 46 misrepresented as being the original software. 47 3. This notice may not be removed or altered from any source distribution. 48 49 Jean-loup Gailly Mark Adler 50 jloup@gzip.org madler@alumni.caltech.edu 51 52 53 The data format used by the zlib library is described by RFCs (Request for 54 Comments) 1950 to 1952 in the files http://www.ietf.org/rfc/rfc1950.txt 55 (zlib format), rfc1951.txt (deflate format) and rfc1952.txt (gzip format). 56*/ 57 58#ifndef ZLIB_H 59#define ZLIB_H 60 61#ifdef __cplusplus 62extern "C" { 63#endif 64 65#include "zconf.h" 66 67#define ZLIB_VERSION "1.2.3" 68#define ZLIB_VERNUM 0x1230 69 70/* 71 The 'zlib' compression library provides in-memory compression and 72 decompression functions, including integrity checks of the uncompressed 73 data. This version of the library supports only one compression method 74 (deflation) but other algorithms will be added later and will have the same 75 stream interface. 76 77 Compression can be done in a single step if the buffers are large 78 enough (for example if an input file is mmap'ed), or can be done by 79 repeated calls of the compression function. In the latter case, the 80 application must provide more input and/or consume the output 81 (providing more output space) before each call. 82 83 The compressed data format used by default by the in-memory functions is 84 the zlib format, which is a zlib wrapper documented in RFC 1950, wrapped 85 around a deflate stream, which is itself documented in RFC 1951. 86 87 The library also supports reading and writing files in gzip (.gz) format 88 with an interface similar to that of stdio using the functions that start 89 with "gz". The gzip format is different from the zlib format. gzip is a 90 gzip wrapper, documented in RFC 1952, wrapped around a deflate stream. 91 92 This library can optionally read and write gzip streams in memory as well. 93 94 The zlib format was designed to be compact and fast for use in memory 95 and on communications channels. The gzip format was designed for single- 96 file compression on file systems, has a larger header than zlib to maintain 97 directory information, and uses a different, slower check method than zlib. 98 99 The library does not install any signal handler. The decoder checks 100 the consistency of the compressed data, so the library should never 101 crash even in case of corrupted input. 102*/ 103 104typedef voidpf (*alloc_func) OF((voidpf opaque, uInt items, uInt size)); 105typedef void (*free_func) OF((voidpf opaque, voidpf address)); 106 107struct internal_state; 108 109typedef struct z_stream_s { 110 Bytef *next_in; /* next input byte */ 111 uInt avail_in; /* number of bytes available at next_in */ 112 uLong total_in; /* total nb of input bytes read so far */ 113 114 Bytef *next_out; /* next output byte should be put there */ 115 uInt avail_out; /* remaining free space at next_out */ 116 uLong total_out; /* total nb of bytes output so far */ 117 118 char *msg; /* last error message, NULL if no error */ 119 struct internal_state FAR *state; /* not visible by applications */ 120 121 alloc_func zalloc; /* used to allocate the internal state */ 122 free_func zfree; /* used to free the internal state */ 123 voidpf opaque; /* private data object passed to zalloc and zfree */ 124 125 int data_type; /* best guess about the data type: binary or text */ 126 uLong adler; /* adler32 value of the uncompressed data */ 127 uLong reserved; /* reserved for future use */ 128} z_stream; 129 130typedef z_stream FAR *z_streamp; 131 132/* 133 gzip header information passed to and from zlib routines. See RFC 1952 134 for more details on the meanings of these fields. 135*/ 136typedef struct gz_header_s { 137 int text; /* true if compressed data believed to be text */ 138 uLong time; /* modification time */ 139 int xflags; /* extra flags (not used when writing a gzip file) */ 140 int os; /* operating system */ 141 Bytef *extra; /* pointer to extra field or Z_NULL if none */ 142 uInt extra_len; /* extra field length (valid if extra != Z_NULL) */ 143 uInt extra_max; /* space at extra (only when reading header) */ 144 Bytef *name; /* pointer to zero-terminated file name or Z_NULL */ 145 uInt name_max; /* space at name (only when reading header) */ 146 Bytef *comment; /* pointer to zero-terminated comment or Z_NULL */ 147 uInt comm_max; /* space at comment (only when reading header) */ 148 int hcrc; /* true if there was or will be a header crc */ 149 int done; /* true when done reading gzip header (not used 150 when writing a gzip file) */ 151} gz_header; 152 153typedef gz_header FAR *gz_headerp; 154 155/* 156 The application must update next_in and avail_in when avail_in has 157 dropped to zero. It must update next_out and avail_out when avail_out 158 has dropped to zero. The application must initialize zalloc, zfree and 159 opaque before calling the init function. All other fields are set by the 160 compression library and must not be updated by the application. 161 162 The opaque value provided by the application will be passed as the first 163 parameter for calls of zalloc and zfree. This can be useful for custom 164 memory management. The compression library attaches no meaning to the 165 opaque value. 166 167 zalloc must return Z_NULL if there is not enough memory for the object. 168 If zlib is used in a multi-threaded application, zalloc and zfree must be 169 thread safe. 170 171 On 16-bit systems, the functions zalloc and zfree must be able to allocate 172 exactly 65536 bytes, but will not be required to allocate more than this 173 if the symbol MAXSEG_64K is defined (see zconf.h). WARNING: On MSDOS, 174 pointers returned by zalloc for objects of exactly 65536 bytes *must* 175 have their offset normalized to zero. The default allocation function 176 provided by this library ensures this (see zutil.c). To reduce memory 177 requirements and avoid any allocation of 64K objects, at the expense of 178 compression ratio, compile the library with -DMAX_WBITS=14 (see zconf.h). 179 180 The fields total_in and total_out can be used for statistics or 181 progress reports. After compression, total_in holds the total size of 182 the uncompressed data and may be saved for use in the decompressor 183 (particularly if the decompressor wants to decompress everything in 184 a single step). 185*/ 186 187 /* constants */ 188 189#define Z_NO_FLUSH 0 190#define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */ 191/* 2 is a reserved value (in zlib 1.2.3, Z_PACKET_FLUSH was removed) */ 192#define Z_SYNC_FLUSH 3 193#define Z_FULL_FLUSH 4 194#define Z_FINISH 5 195#define Z_BLOCK 6 196 197/* Allowed flush values; see deflate() and inflate() below for details */ 198 199#define Z_OK 0 200#define Z_STREAM_END 1 201#define Z_NEED_DICT 2 202#define Z_ERRNO (-1) 203#define Z_STREAM_ERROR (-2) 204#define Z_DATA_ERROR (-3) 205#define Z_MEM_ERROR (-4) 206#define Z_BUF_ERROR (-5) 207#define Z_VERSION_ERROR (-6) 208/* Return codes for the compression/decompression functions. Negative 209 * values are errors, positive values are used for special but normal events. 210 */ 211 212#define Z_NO_COMPRESSION 0 213#define Z_BEST_SPEED 1 214#define Z_BEST_COMPRESSION 9 215#define Z_DEFAULT_COMPRESSION (-1) 216/* compression levels */ 217 218#define Z_FILTERED 1 219#define Z_HUFFMAN_ONLY 2 220#define Z_RLE 3 221#define Z_FIXED 4 222#define Z_DEFAULT_STRATEGY 0 223/* compression strategy; see deflateInit2() below for details */ 224 225#define Z_BINARY 0 226#define Z_TEXT 1 227#define Z_ASCII Z_TEXT /* for compatibility with 1.2.2 and earlier */ 228#define Z_UNKNOWN 2 229/* Possible values of the data_type field (though see inflate()) */ 230 231#define Z_DEFLATED 8 232/* The deflate compression method (the only one supported in this version) */ 233 234#define Z_NULL 0 /* for initializing zalloc, zfree, opaque */ 235 236#define zlib_version zlibVersion() 237/* for compatibility with versions < 1.0.2 */ 238 239 /* basic functions */ 240 241ZEXTERN const char * ZEXPORT zlibVersion OF((void)); 242/* The application can compare zlibVersion and ZLIB_VERSION for consistency. 243 If the first character differs, the library code actually used is 244 not compatible with the zlib.h header file used by the application. 245 This check is automatically made by deflateInit and inflateInit. 246 */ 247 248/* 249ZEXTERN int ZEXPORT deflateInit OF((z_streamp strm, int level)); 250 251 Initializes the internal stream state for compression. The fields 252 zalloc, zfree and opaque must be initialized before by the caller. 253 If zalloc and zfree are set to Z_NULL, deflateInit updates them to 254 use default allocation functions. 255 256 The compression level must be Z_DEFAULT_COMPRESSION, or between 0 and 9: 257 1 gives best speed, 9 gives best compression, 0 gives no compression at 258 all (the input data is simply copied a block at a time). 259 Z_DEFAULT_COMPRESSION requests a default compromise between speed and 260 compression (currently equivalent to level 6). 261 262 deflateInit returns Z_OK if success, Z_MEM_ERROR if there was not 263 enough memory, Z_STREAM_ERROR if level is not a valid compression level, 264 Z_VERSION_ERROR if the zlib library version (zlib_version) is incompatible 265 with the version assumed by the caller (ZLIB_VERSION). 266 msg is set to null if there is no error message. deflateInit does not 267 perform any compression: this will be done by deflate(). 268*/ 269 270 271ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); 272/* 273 deflate compresses as much data as possible, and stops when the input 274 buffer becomes empty or the output buffer becomes full. It may introduce some 275 output latency (reading input without producing any output) except when 276 forced to flush. 277 278 The detailed semantics are as follows. deflate performs one or both of the 279 following actions: 280 281 - Compress more input starting at next_in and update next_in and avail_in 282 accordingly. If not all input can be processed (because there is not 283 enough room in the output buffer), next_in and avail_in are updated and 284 processing will resume at this point for the next call of deflate(). 285 286 - Provide more output starting at next_out and update next_out and avail_out 287 accordingly. This action is forced if the parameter flush is non zero. 288 Forcing flush frequently degrades the compression ratio, so this parameter 289 should be set only when necessary (in interactive applications). 290 Some output may be provided even if flush is not set. 291 292 Before the call of deflate(), the application should ensure that at least 293 one of the actions is possible, by providing more input and/or consuming 294 more output, and updating avail_in or avail_out accordingly; avail_out 295 should never be zero before the call. The application can consume the 296 compressed output when it wants, for example when the output buffer is full 297 (avail_out == 0), or after each call of deflate(). If deflate returns Z_OK 298 and with zero avail_out, it must be called again after making room in the 299 output buffer because there might be more output pending. 300 301 Normally the parameter flush is set to Z_NO_FLUSH, which allows deflate to 302 decide how much data to accumualte before producing output, in order to 303 maximize compression. 304 305 If the parameter flush is set to Z_SYNC_FLUSH, all pending output is 306 flushed to the output buffer and the output is aligned on a byte boundary, so 307 that the decompressor can get all input data available so far. (In particular 308 avail_in is zero after the call if enough output space has been provided 309 before the call.) Flushing may degrade compression for some compression 310 algorithms and so it should be used only when necessary. 311 312 If flush is set to Z_FULL_FLUSH, all output is flushed as with 313 Z_SYNC_FLUSH, and the compression state is reset so that decompression can 314 restart from this point if previous compressed data has been damaged or if 315 random access is desired. Using Z_FULL_FLUSH too often can seriously degrade 316 compression. 317 318 If deflate returns with avail_out == 0, this function must be called again 319 with the same value of the flush parameter and more output space (updated 320 avail_out), until the flush is complete (deflate returns with non-zero 321 avail_out). In the case of a Z_FULL_FLUSH or Z_SYNC_FLUSH, make sure that 322 avail_out is greater than six to avoid repeated flush markers due to 323 avail_out == 0 on return. 324 325 If the parameter flush is set to Z_FINISH, pending input is processed, 326 pending output is flushed and deflate returns with Z_STREAM_END if there 327 was enough output space; if deflate returns with Z_OK, this function must be 328 called again with Z_FINISH and more output space (updated avail_out) but no 329 more input data, until it returns with Z_STREAM_END or an error. After 330 deflate has returned Z_STREAM_END, the only possible operations on the 331 stream are deflateReset or deflateEnd. 332 333 Z_FINISH can be used immediately after deflateInit if all the compression 334 is to be done in a single step. In this case, avail_out must be at least 335 the value returned by deflateBound (see below). If deflate does not return 336 Z_STREAM_END, then it must be called again as described above. 337 338 deflate() sets strm->adler to the adler32 checksum of all input read 339 so far (that is, total_in bytes). 340 341 deflate() may update strm->data_type if it can make a good guess about 342 the input data type (Z_BINARY or Z_TEXT). In doubt, the data is considered 343 binary. This field is only for information purposes and does not affect 344 the compression algorithm in any manner. 345 346 deflate() returns Z_OK if some progress has been made (more input 347 processed or more output produced), Z_STREAM_END if all input has been 348 consumed and all output has been produced (only when flush is set to 349 Z_FINISH), Z_STREAM_ERROR if the stream state was inconsistent (for example 350 if next_in or next_out was NULL), Z_BUF_ERROR if no progress is possible 351 (for example avail_in or avail_out was zero). Note that Z_BUF_ERROR is not 352 fatal, and deflate() can be called again with more input and more output 353 space to continue compressing. 354*/ 355 356 357ZEXTERN int ZEXPORT deflateEnd OF((z_streamp strm)); 358/* 359 All dynamically allocated data structures for this stream are freed. 360 This function discards any unprocessed input and does not flush any 361 pending output. 362 363 deflateEnd returns Z_OK if success, Z_STREAM_ERROR if the 364 stream state was inconsistent, Z_DATA_ERROR if the stream was freed 365 prematurely (some input or output was discarded). In the error case, 366 msg may be set but then points to a static string (which must not be 367 deallocated). 368*/ 369 370 371/* 372ZEXTERN int ZEXPORT inflateInit OF((z_streamp strm)); 373 374 Initializes the internal stream state for decompression. The fields 375 next_in, avail_in, zalloc, zfree and opaque must be initialized before by 376 the caller. If next_in is not Z_NULL and avail_in is large enough (the exact 377 value depends on the compression method), inflateInit determines the 378 compression method from the zlib header and allocates all data structures 379 accordingly; otherwise the allocation will be deferred to the first call of 380 inflate. If zalloc and zfree are set to Z_NULL, inflateInit updates them to 381 use default allocation functions. 382 383 inflateInit returns Z_OK if success, Z_MEM_ERROR if there was not enough 384 memory, Z_VERSION_ERROR if the zlib library version is incompatible with the 385 version assumed by the caller. msg is set to null if there is no error 386 message. inflateInit does not perform any decompression apart from reading 387 the zlib header if present: this will be done by inflate(). (So next_in and 388 avail_in may be modified, but next_out and avail_out are unchanged.) 389*/ 390 391 392ZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush)); 393/* 394 inflate decompresses as much data as possible, and stops when the input 395 buffer becomes empty or the output buffer becomes full. It may introduce 396 some output latency (reading input without producing any output) except when 397 forced to flush. 398 399 The detailed semantics are as follows. inflate performs one or both of the 400 following actions: 401 402 - Decompress more input starting at next_in and update next_in and avail_in 403 accordingly. If not all input can be processed (because there is not 404 enough room in the output buffer), next_in is updated and processing 405 will resume at this point for the next call of inflate(). 406 407 - Provide more output starting at next_out and update next_out and avail_out 408 accordingly. inflate() provides as much output as possible, until there 409 is no more input data or no more space in the output buffer (see below 410 about the flush parameter). 411 412 Before the call of inflate(), the application should ensure that at least 413 one of the actions is possible, by providing more input and/or consuming 414 more output, and updating the next_* and avail_* values accordingly. 415 The application can consume the uncompressed output when it wants, for 416 example when the output buffer is full (avail_out == 0), or after each 417 call of inflate(). If inflate returns Z_OK and with zero avail_out, it 418 must be called again after making room in the output buffer because there 419 might be more output pending. 420 421 The flush parameter of inflate() can be Z_NO_FLUSH, Z_SYNC_FLUSH, 422 Z_FINISH, or Z_BLOCK. Z_SYNC_FLUSH requests that inflate() flush as much 423 output as possible to the output buffer. Z_BLOCK requests that inflate() stop 424 if and when it gets to the next deflate block boundary. When decoding the 425 zlib or gzip format, this will cause inflate() to return immediately after 426 the header and before the first block. When doing a raw inflate, inflate() 427 will go ahead and process the first block, and will return when it gets to 428 the end of that block, or when it runs out of data. 429 430 The Z_BLOCK option assists in appending to or combining deflate streams. 431 Also to assist in this, on return inflate() will set strm->data_type to the 432 number of unused bits in the last byte taken from strm->next_in, plus 64 433 if inflate() is currently decoding the last block in the deflate stream, 434 plus 128 if inflate() returned immediately after decoding an end-of-block 435 code or decoding the complete header up to just before the first byte of the 436 deflate stream. The end-of-block will not be indicated until all of the 437 uncompressed data from that block has been written to strm->next_out. The 438 number of unused bits may in general be greater than seven, except when 439 bit 7 of data_type is set, in which case the number of unused bits will be 440 less than eight. 441 442 inflate() should normally be called until it returns Z_STREAM_END or an 443 error. However if all decompression is to be performed in a single step 444 (a single call of inflate), the parameter flush should be set to 445 Z_FINISH. In this case all pending input is processed and all pending 446 output is flushed; avail_out must be large enough to hold all the 447 uncompressed data. (The size of the uncompressed data may have been saved 448 by the compressor for this purpose.) The next operation on this stream must 449 be inflateEnd to deallocate the decompression state. The use of Z_FINISH 450 is never required, but can be used to inform inflate that a faster approach 451 may be used for the single inflate() call. 452 453 In this implementation, inflate() always flushes as much output as 454 possible to the output buffer, and always uses the faster approach on the 455 first call. So the only effect of the flush parameter in this implementation 456 is on the return value of inflate(), as noted below, or when it returns early 457 because Z_BLOCK is used. 458 459 If a preset dictionary is needed after this call (see inflateSetDictionary 460 below), inflate sets strm->adler to the adler32 checksum of the dictionary 461 chosen by the compressor and returns Z_NEED_DICT; otherwise it sets 462 strm->adler to the adler32 checksum of all output produced so far (that is, 463 total_out bytes) and returns Z_OK, Z_STREAM_END or an error code as described 464 below. At the end of the stream, inflate() checks that its computed adler32 465 checksum is equal to that saved by the compressor and returns Z_STREAM_END 466 only if the checksum is correct. 467 468 inflate() will decompress and check either zlib-wrapped or gzip-wrapped 469 deflate data. The header type is detected automatically. Any information 470 contained in the gzip header is not retained, so applications that need that 471 information should instead use raw inflate, see inflateInit2() below, or 472 inflateBack() and perform their own processing of the gzip header and 473 trailer. 474 475 inflate() returns Z_OK if some progress has been made (more input processed 476 or more output produced), Z_STREAM_END if the end of the compressed data has 477 been reached and all uncompressed output has been produced, Z_NEED_DICT if a 478 preset dictionary is needed at this point, Z_DATA_ERROR if the input data was 479 corrupted (input stream not conforming to the zlib format or incorrect check 480 value), Z_STREAM_ERROR if the stream structure was inconsistent (for example 481 if next_in or next_out was NULL), Z_MEM_ERROR if there was not enough memory, 482 Z_BUF_ERROR if no progress is possible or if there was not enough room in the 483 output buffer when Z_FINISH is used. Note that Z_BUF_ERROR is not fatal, and 484 inflate() can be called again with more input and more output space to 485 continue decompressing. If Z_DATA_ERROR is returned, the application may then 486 call inflateSync() to look for a good compression block if a partial recovery 487 of the data is desired. 488*/ 489 490 491ZEXTERN int ZEXPORT inflateEnd OF((z_streamp strm)); 492/* 493 All dynamically allocated data structures for this stream are freed. 494 This function discards any unprocessed input and does not flush any 495 pending output. 496 497 inflateEnd returns Z_OK if success, Z_STREAM_ERROR if the stream state 498 was inconsistent. In the error case, msg may be set but then points to a 499 static string (which must not be deallocated). 500*/ 501 502 /* Advanced functions */ 503 504/* 505 The following functions are needed only in some special applications. 506*/ 507 508/* 509ZEXTERN int ZEXPORT deflateInit2 OF((z_streamp strm, 510 int level, 511 int method, 512 int windowBits, 513 int memLevel, 514 int strategy)); 515 516 This is another version of deflateInit with more compression options. The 517 fields next_in, zalloc, zfree and opaque must be initialized before by 518 the caller. 519 520 The method parameter is the compression method. It must be Z_DEFLATED in 521 this version of the library. 522 523 The windowBits parameter is the base two logarithm of the window size 524 (the size of the history buffer). It should be in the range 8..15 for this 525 version of the library. Larger values of this parameter result in better 526 compression at the expense of memory usage. The default value is 15 if 527 deflateInit is used instead. 528 529 windowBits can also be -8..-15 for raw deflate. In this case, -windowBits 530 determines the window size. deflate() will then generate raw deflate data 531 with no zlib header or trailer, and will not compute an adler32 check value. 532 533 windowBits can also be greater than 15 for optional gzip encoding. Add 534 16 to windowBits to write a simple gzip header and trailer around the 535 compressed data instead of a zlib wrapper. The gzip header will have no 536 file name, no extra data, no comment, no modification time (set to zero), 537 no header crc, and the operating system will be set to 255 (unknown). If a 538 gzip stream is being written, strm->adler is a crc32 instead of an adler32. 539 540 The memLevel parameter specifies how much memory should be allocated 541 for the internal compression state. memLevel=1 uses minimum memory but 542 is slow and reduces compression ratio; memLevel=9 uses maximum memory 543 for optimal speed. The default value is 8. See zconf.h for total memory 544 usage as a function of windowBits and memLevel. 545 546 The strategy parameter is used to tune the compression algorithm. Use the 547 value Z_DEFAULT_STRATEGY for normal data, Z_FILTERED for data produced by a 548 filter (or predictor), Z_HUFFMAN_ONLY to force Huffman encoding only (no 549 string match), or Z_RLE to limit match distances to one (run-length 550 encoding). Filtered data consists mostly of small values with a somewhat 551 random distribution. In this case, the compression algorithm is tuned to 552 compress them better. The effect of Z_FILTERED is to force more Huffman 553 coding and less string matching; it is somewhat intermediate between 554 Z_DEFAULT and Z_HUFFMAN_ONLY. Z_RLE is designed to be almost as fast as 555 Z_HUFFMAN_ONLY, but give better compression for PNG image data. The strategy 556 parameter only affects the compression ratio but not the correctness of the 557 compressed output even if it is not set appropriately. Z_FIXED prevents the 558 use of dynamic Huffman codes, allowing for a simpler decoder for special 559 applications. 560 561 deflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough 562 memory, Z_STREAM_ERROR if a parameter is invalid (such as an invalid 563 method). msg is set to null if there is no error message. deflateInit2 does 564 not perform any compression: this will be done by deflate(). 565*/ 566 567ZEXTERN int ZEXPORT deflateSetDictionary OF((z_streamp strm, 568 const Bytef *dictionary, 569 uInt dictLength)); 570/* 571 Initializes the compression dictionary from the given byte sequence 572 without producing any compressed output. This function must be called 573 immediately after deflateInit, deflateInit2 or deflateReset, before any 574 call of deflate. The compressor and decompressor must use exactly the same 575 dictionary (see inflateSetDictionary). 576 577 The dictionary should consist of strings (byte sequences) that are likely 578 to be encountered later in the data to be compressed, with the most commonly 579 used strings preferably put towards the end of the dictionary. Using a 580 dictionary is most useful when the data to be compressed is short and can be 581 predicted with good accuracy; the data can then be compressed better than 582 with the default empty dictionary. 583 584 Depending on the size of the compression data structures selected by 585 deflateInit or deflateInit2, a part of the dictionary may in effect be 586 discarded, for example if the dictionary is larger than the window size in 587 deflate or deflate2. Thus the strings most likely to be useful should be 588 put at the end of the dictionary, not at the front. In addition, the 589 current implementation of deflate will use at most the window size minus 590 262 bytes of the provided dictionary. 591 592 Upon return of this function, strm->adler is set to the adler32 value 593 of the dictionary; the decompressor may later use this value to determine 594 which dictionary has been used by the compressor. (The adler32 value 595 applies to the whole dictionary even if only a subset of the dictionary is 596 actually used by the compressor.) If a raw deflate was requested, then the 597 adler32 value is not computed and strm->adler is not set. 598 599 deflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a 600 parameter is invalid (such as NULL dictionary) or the stream state is 601 inconsistent (for example if deflate has already been called for this stream 602 or if the compression method is bsort). deflateSetDictionary does not 603 perform any compression: this will be done by deflate(). 604*/ 605 606ZEXTERN int ZEXPORT deflateCopy OF((z_streamp dest, 607 z_streamp source)); 608/* 609 Sets the destination stream as a complete copy of the source stream. 610 611 This function can be useful when several compression strategies will be 612 tried, for example when there are several ways of pre-processing the input 613 data with a filter. The streams that will be discarded should then be freed 614 by calling deflateEnd. Note that deflateCopy duplicates the internal 615 compression state which can be quite large, so this strategy is slow and 616 can consume lots of memory. 617 618 deflateCopy returns Z_OK if success, Z_MEM_ERROR if there was not 619 enough memory, Z_STREAM_ERROR if the source stream state was inconsistent 620 (such as zalloc being NULL). msg is left unchanged in both source and 621 destination. 622*/ 623 624ZEXTERN int ZEXPORT deflateReset OF((z_streamp strm)); 625/* 626 This function is equivalent to deflateEnd followed by deflateInit, 627 but does not free and reallocate all the internal compression state. 628 The stream will keep the same compression level and any other attributes 629 that may have been set by deflateInit2. 630 631 deflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source 632 stream state was inconsistent (such as zalloc or state being NULL). 633*/ 634 635ZEXTERN int ZEXPORT deflateParams OF((z_streamp strm, 636 int level, 637 int strategy)); 638/* 639 Dynamically update the compression level and compression strategy. The 640 interpretation of level and strategy is as in deflateInit2. This can be 641 used to switch between compression and straight copy of the input data, or 642 to switch to a different kind of input data requiring a different 643 strategy. If the compression level is changed, the input available so far 644 is compressed with the old level (and may be flushed); the new level will 645 take effect only at the next call of deflate(). 646 647 Before the call of deflateParams, the stream state must be set as for 648 a call of deflate(), since the currently available input may have to 649 be compressed and flushed. In particular, strm->avail_out must be non-zero. 650 651 deflateParams returns Z_OK if success, Z_STREAM_ERROR if the source 652 stream state was inconsistent or if a parameter was invalid, Z_BUF_ERROR 653 if strm->avail_out was zero. 654*/ 655 656ZEXTERN int ZEXPORT deflateTune OF((z_streamp strm, 657 int good_length, 658 int max_lazy, 659 int nice_length, 660 int max_chain)); 661/* 662 Fine tune deflate's internal compression parameters. This should only be 663 used by someone who understands the algorithm used by zlib's deflate for 664 searching for the best matching string, and even then only by the most 665 fanatic optimizer trying to squeeze out the last compressed bit for their 666 specific input data. Read the deflate.c source code for the meaning of the 667 max_lazy, good_length, nice_length, and max_chain parameters. 668 669 deflateTune() can be called after deflateInit() or deflateInit2(), and 670 returns Z_OK on success, or Z_STREAM_ERROR for an invalid deflate stream. 671 */ 672 673ZEXTERN uLong ZEXPORT deflateBound OF((z_streamp strm, 674 uLong sourceLen)); 675/* 676 deflateBound() returns an upper bound on the compressed size after 677 deflation of sourceLen bytes. It must be called after deflateInit() 678 or deflateInit2(). This would be used to allocate an output buffer 679 for deflation in a single pass, and so would be called before deflate(). 680*/ 681 682ZEXTERN int ZEXPORT deflatePrime OF((z_streamp strm, 683 int bits, 684 int value)); 685/* 686 deflatePrime() inserts bits in the deflate output stream. The intent 687 is that this function is used to start off the deflate output with the 688 bits leftover from a previous deflate stream when appending to it. As such, 689 this function can only be used for raw deflate, and must be used before the 690 first deflate() call after a deflateInit2() or deflateReset(). bits must be 691 less than or equal to 16, and that many of the least significant bits of 692 value will be inserted in the output. 693 694 deflatePrime returns Z_OK if success, or Z_STREAM_ERROR if the source 695 stream state was inconsistent. 696*/ 697 698ZEXTERN int ZEXPORT deflateSetHeader OF((z_streamp strm, 699 gz_headerp head)); 700/* 701 deflateSetHeader() provides gzip header information for when a gzip 702 stream is requested by deflateInit2(). deflateSetHeader() may be called 703 after deflateInit2() or deflateReset() and before the first call of 704 deflate(). The text, time, os, extra field, name, and comment information 705 in the provided gz_header structure are written to the gzip header (xflag is 706 ignored -- the extra flags are set according to the compression level). The 707 caller must assure that, if not Z_NULL, name and comment are terminated with 708 a zero byte, and that if extra is not Z_NULL, that extra_len bytes are 709 available there. If hcrc is true, a gzip header crc is included. Note that 710 the current versions of the command-line version of gzip (up through version 711 1.3.x) do not support header crc's, and will report that it is a "multi-part 712 gzip file" and give up. 713 714 If deflateSetHeader is not used, the default gzip header has text false, 715 the time set to zero, and os set to 255, with no extra, name, or comment 716 fields. The gzip header is returned to the default state by deflateReset(). 717 718 deflateSetHeader returns Z_OK if success, or Z_STREAM_ERROR if the source 719 stream state was inconsistent. 720*/ 721 722/* 723ZEXTERN int ZEXPORT inflateInit2 OF((z_streamp strm, 724 int windowBits)); 725 726 This is another version of inflateInit with an extra parameter. The 727 fields next_in, avail_in, zalloc, zfree and opaque must be initialized 728 before by the caller. 729 730 The windowBits parameter is the base two logarithm of the maximum window 731 size (the size of the history buffer). It should be in the range 8..15 for 732 this version of the library. The default value is 15 if inflateInit is used 733 instead. windowBits must be greater than or equal to the windowBits value 734 provided to deflateInit2() while compressing, or it must be equal to 15 if 735 deflateInit2() was not used. If a compressed stream with a larger window 736 size is given as input, inflate() will return with the error code 737 Z_DATA_ERROR instead of trying to allocate a larger window. 738 739 windowBits can also be -8..-15 for raw inflate. In this case, -windowBits 740 determines the window size. inflate() will then process raw deflate data, 741 not looking for a zlib or gzip header, not generating a check value, and not 742 looking for any check values for comparison at the end of the stream. This 743 is for use with other formats that use the deflate compressed data format 744 such as zip. Those formats provide their own check values. If a custom 745 format is developed using the raw deflate format for compressed data, it is 746 recommended that a check value such as an adler32 or a crc32 be applied to 747 the uncompressed data as is done in the zlib, gzip, and zip formats. For 748 most applications, the zlib format should be used as is. Note that comments 749 above on the use in deflateInit2() applies to the magnitude of windowBits. 750 751 windowBits can also be greater than 15 for optional gzip decoding. Add 752 32 to windowBits to enable zlib and gzip decoding with automatic header 753 detection, or add 16 to decode only the gzip format (the zlib format will 754 return a Z_DATA_ERROR). If a gzip stream is being decoded, strm->adler is 755 a crc32 instead of an adler32. 756 757 inflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough 758 memory, Z_STREAM_ERROR if a parameter is invalid (such as a null strm). msg 759 is set to null if there is no error message. inflateInit2 does not perform 760 any decompression apart from reading the zlib header if present: this will 761 be done by inflate(). (So next_in and avail_in may be modified, but next_out 762 and avail_out are unchanged.) 763*/ 764 765ZEXTERN int ZEXPORT inflateSetDictionary OF((z_streamp strm, 766 const Bytef *dictionary, 767 uInt dictLength)); 768/* 769 Initializes the decompression dictionary from the given uncompressed byte 770 sequence. This function must be called immediately after a call of inflate, 771 if that call returned Z_NEED_DICT. The dictionary chosen by the compressor 772 can be determined from the adler32 value returned by that call of inflate. 773 The compressor and decompressor must use exactly the same dictionary (see 774 deflateSetDictionary). For raw inflate, this function can be called 775 immediately after inflateInit2() or inflateReset() and before any call of 776 inflate() to set the dictionary. The application must insure that the 777 dictionary that was used for compression is provided. 778 779 inflateSetDictionary returns Z_OK if success, Z_STREAM_ERROR if a 780 parameter is invalid (such as NULL dictionary) or the stream state is 781 inconsistent, Z_DATA_ERROR if the given dictionary doesn't match the 782 expected one (incorrect adler32 value). inflateSetDictionary does not 783 perform any decompression: this will be done by subsequent calls of 784 inflate(). 785*/ 786 787ZEXTERN int ZEXPORT inflateSync OF((z_streamp strm)); 788/* 789 Skips invalid compressed data until a full flush point (see above the 790 description of deflate with Z_FULL_FLUSH) can be found, or until all 791 available input is skipped. No output is provided. 792 793 inflateSync returns Z_OK if a full flush point has been found, Z_BUF_ERROR 794 if no more input was provided, Z_DATA_ERROR if no flush point has been found, 795 or Z_STREAM_ERROR if the stream structure was inconsistent. In the success 796 case, the application may save the current current value of total_in which 797 indicates where valid compressed data was found. In the error case, the 798 application may repeatedly call inflateSync, providing more input each time, 799 until success or end of the input data. 800*/ 801 802ZEXTERN int ZEXPORT inflateCopy OF((z_streamp dest, 803 z_streamp source)); 804/* 805 Sets the destination stream as a complete copy of the source stream. 806 807 This function can be useful when randomly accessing a large stream. The 808 first pass through the stream can periodically record the inflate state, 809 allowing restarting inflate at those points when randomly accessing the 810 stream. 811 812 inflateCopy returns Z_OK if success, Z_MEM_ERROR if there was not 813 enough memory, Z_STREAM_ERROR if the source stream state was inconsistent 814 (such as zalloc being NULL). msg is left unchanged in both source and 815 destination. 816*/ 817 818ZEXTERN int ZEXPORT inflateReset OF((z_streamp strm)); 819/* 820 This function is equivalent to inflateEnd followed by inflateInit, 821 but does not free and reallocate all the internal decompression state. 822 The stream will keep attributes that may have been set by inflateInit2. 823 824 inflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source 825 stream state was inconsistent (such as zalloc or state being NULL). 826*/ 827 828ZEXTERN int ZEXPORT inflatePrime OF((z_streamp strm, 829 int bits, 830 int value)); 831/* 832 This function inserts bits in the inflate input stream. The intent is 833 that this function is used to start inflating at a bit position in the 834 middle of a byte. The provided bits will be used before any bytes are used 835 from next_in. This function should only be used with raw inflate, and 836 should be used before the first inflate() call after inflateInit2() or 837 inflateReset(). bits must be less than or equal to 16, and that many of the 838 least significant bits of value will be inserted in the input. 839 840 inflatePrime returns Z_OK if success, or Z_STREAM_ERROR if the source 841 stream state was inconsistent. 842*/ 843 844ZEXTERN int ZEXPORT inflateGetHeader OF((z_streamp strm, 845 gz_headerp head)); 846/* 847 inflateGetHeader() requests that gzip header information be stored in the 848 provided gz_header structure. inflateGetHeader() may be called after 849 inflateInit2() or inflateReset(), and before the first call of inflate(). 850 As inflate() processes the gzip stream, head->done is zero until the header 851 is completed, at which time head->done is set to one. If a zlib stream is 852 being decoded, then head->done is set to -1 to indicate that there will be 853 no gzip header information forthcoming. Note that Z_BLOCK can be used to 854 force inflate() to return immediately after header processing is complete 855 and before any actual data is decompressed. 856 857 The text, time, xflags, and os fields are filled in with the gzip header 858 contents. hcrc is set to true if there is a header CRC. (The header CRC 859 was valid if done is set to one.) If extra is not Z_NULL, then extra_max 860 contains the maximum number of bytes to write to extra. Once done is true, 861 extra_len contains the actual extra field length, and extra contains the 862 extra field, or that field truncated if extra_max is less than extra_len. 863 If name is not Z_NULL, then up to name_max characters are written there, 864 terminated with a zero unless the length is greater than name_max. If 865 comment is not Z_NULL, then up to comm_max characters are written there, 866 terminated with a zero unless the length is greater than comm_max. When 867 any of extra, name, or comment are not Z_NULL and the respective field is 868 not present in the header, then that field is set to Z_NULL to signal its 869 absence. This allows the use of deflateSetHeader() with the returned 870 structure to duplicate the header. However if those fields are set to 871 allocated memory, then the application will need to save those pointers 872 elsewhere so that they can be eventually freed. 873 874 If inflateGetHeader is not used, then the header information is simply 875 discarded. The header is always checked for validity, including the header 876 CRC if present. inflateReset() will reset the process to discard the header 877 information. The application would need to call inflateGetHeader() again to 878 retrieve the header from the next gzip stream. 879 880 inflateGetHeader returns Z_OK if success, or Z_STREAM_ERROR if the source 881 stream state was inconsistent. 882*/ 883 884/* 885ZEXTERN int ZEXPORT inflateBackInit OF((z_streamp strm, int windowBits, 886 unsigned char FAR *window)); 887 888 Initialize the internal stream state for decompression using inflateBack() 889 calls. The fields zalloc, zfree and opaque in strm must be initialized 890 before the call. If zalloc and zfree are Z_NULL, then the default library- 891 derived memory allocation routines are used. windowBits is the base two 892 logarithm of the window size, in the range 8..15. window is a caller 893 supplied buffer of that size. Except for special applications where it is 894 assured that deflate was used with small window sizes, windowBits must be 15 895 and a 32K byte window must be supplied to be able to decompress general 896 deflate streams. 897 898 See inflateBack() for the usage of these routines. 899 900 inflateBackInit will return Z_OK on success, Z_STREAM_ERROR if any of 901 the paramaters are invalid, Z_MEM_ERROR if the internal state could not 902 be allocated, or Z_VERSION_ERROR if the version of the library does not 903 match the version of the header file. 904*/ 905 906typedef unsigned (*in_func) OF((void FAR *, unsigned char FAR * FAR *)); 907typedef int (*out_func) OF((void FAR *, unsigned char FAR *, unsigned)); 908 909ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, 910 in_func in, void FAR *in_desc, 911 out_func out, void FAR *out_desc)); 912/* 913 inflateBack() does a raw inflate with a single call using a call-back 914 interface for input and output. This is more efficient than inflate() for 915 file i/o applications in that it avoids copying between the output and the 916 sliding window by simply making the window itself the output buffer. This 917 function trusts the application to not change the output buffer passed by 918 the output function, at least until inflateBack() returns. 919 920 inflateBackInit() must be called first to allocate the internal state 921 and to initialize the state with the user-provided window buffer. 922 inflateBack() may then be used multiple times to inflate a complete, raw 923 deflate stream with each call. inflateBackEnd() is then called to free 924 the allocated state. 925 926 A raw deflate stream is one with no zlib or gzip header or trailer. 927 This routine would normally be used in a utility that reads zip or gzip 928 files and writes out uncompressed files. The utility would decode the 929 header and process the trailer on its own, hence this routine expects 930 only the raw deflate stream to decompress. This is different from the 931 normal behavior of inflate(), which expects either a zlib or gzip header and 932 trailer around the deflate stream. 933 934 inflateBack() uses two subroutines supplied by the caller that are then 935 called by inflateBack() for input and output. inflateBack() calls those 936 routines until it reads a complete deflate stream and writes out all of the 937 uncompressed data, or until it encounters an error. The function's 938 parameters and return types are defined above in the in_func and out_func 939 typedefs. inflateBack() will call in(in_desc, &buf) which should return the 940 number of bytes of provided input, and a pointer to that input in buf. If 941 there is no input available, in() must return zero--buf is ignored in that 942 case--and inflateBack() will return a buffer error. inflateBack() will call 943 out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. out() 944 should return zero on success, or non-zero on failure. If out() returns 945 non-zero, inflateBack() will return with an error. Neither in() nor out() 946 are permitted to change the contents of the window provided to 947 inflateBackInit(), which is also the buffer that out() uses to write from. 948 The length written by out() will be at most the window size. Any non-zero 949 amount of input may be provided by in(). 950 951 For convenience, inflateBack() can be provided input on the first call by 952 setting strm->next_in and strm->avail_in. If that input is exhausted, then 953 in() will be called. Therefore strm->next_in must be initialized before 954 calling inflateBack(). If strm->next_in is Z_NULL, then in() will be called 955 immediately for input. If strm->next_in is not Z_NULL, then strm->avail_in 956 must also be initialized, and then if strm->avail_in is not zero, input will 957 initially be taken from strm->next_in[0 .. strm->avail_in - 1]. 958 959 The in_desc and out_desc parameters of inflateBack() is passed as the 960 first parameter of in() and out() respectively when they are called. These 961 descriptors can be optionally used to pass any information that the caller- 962 supplied in() and out() functions need to do their job. 963 964 On return, inflateBack() will set strm->next_in and strm->avail_in to 965 pass back any unused input that was provided by the last in() call. The 966 return values of inflateBack() can be Z_STREAM_END on success, Z_BUF_ERROR 967 if in() or out() returned an error, Z_DATA_ERROR if there was a format 968 error in the deflate stream (in which case strm->msg is set to indicate the 969 nature of the error), or Z_STREAM_ERROR if the stream was not properly 970 initialized. In the case of Z_BUF_ERROR, an input or output error can be 971 distinguished using strm->next_in which will be Z_NULL only if in() returned 972 an error. If strm->next is not Z_NULL, then the Z_BUF_ERROR was due to 973 out() returning non-zero. (in() will always be called before out(), so 974 strm->next_in is assured to be defined if out() returns non-zero.) Note 975 that inflateBack() cannot return Z_OK. 976*/ 977 978ZEXTERN int ZEXPORT inflateBackEnd OF((z_streamp strm)); 979/* 980 All memory allocated by inflateBackInit() is freed. 981 982 inflateBackEnd() returns Z_OK on success, or Z_STREAM_ERROR if the stream 983 state was inconsistent. 984*/ 985 986ZEXTERN uLong ZEXPORT zlibCompileFlags OF((void)); 987/* Return flags indicating compile-time options. 988 989 Type sizes, two bits each, 00 = 16 bits, 01 = 32, 10 = 64, 11 = other: 990 1.0: size of uInt 991 3.2: size of uLong 992 5.4: size of voidpf (pointer) 993 7.6: size of z_off_t 994 995 Compiler, assembler, and debug options: 996 8: DEBUG 997 9: ASMV or ASMINF -- use ASM code 998 10: ZLIB_WINAPI -- exported functions use the WINAPI calling convention 999 11: 0 (reserved) 1000 1001 One-time table building (smaller code, but not thread-safe if true): 1002 12: BUILDFIXED -- build static block decoding tables when needed 1003 13: DYNAMIC_CRC_TABLE -- build CRC calculation tables when needed 1004 14,15: 0 (reserved) 1005 1006 Library content (indicates missing functionality): 1007 16: NO_GZCOMPRESS -- gz* functions cannot compress (to avoid linking 1008 deflate code when not needed) 1009 17: NO_GZIP -- deflate can't write gzip streams, and inflate can't detect 1010 and decode gzip streams (to avoid linking crc code) 1011 18-19: 0 (reserved) 1012 1013 Operation variations (changes in library functionality): 1014 20: PKZIP_BUG_WORKAROUND -- slightly more permissive inflate 1015 21: FASTEST -- deflate algorithm with only one, lowest compression level 1016 22,23: 0 (reserved) 1017 1018 The sprintf variant used by gzprintf (zero is best): 1019 24: 0 = vs*, 1 = s* -- 1 means limited to 20 arguments after the format 1020 25: 0 = *nprintf, 1 = *printf -- 1 means gzprintf() not secure! 1021 26: 0 = returns value, 1 = void -- 1 means inferred string length returned 1022 1023 Remainder: 1024 27-31: 0 (reserved) 1025 */ 1026 1027 1028 /* utility functions */ 1029 1030/* 1031 The following utility functions are implemented on top of the 1032 basic stream-oriented functions. To simplify the interface, some 1033 default options are assumed (compression level and memory usage, 1034 standard memory allocation functions). The source code of these 1035 utility functions can easily be modified if you need special options. 1036*/ 1037 1038ZEXTERN int ZEXPORT compress OF((Bytef *dest, uLongf *destLen, 1039 const Bytef *source, uLong sourceLen)); 1040/* 1041 Compresses the source buffer into the destination buffer. sourceLen is 1042 the byte length of the source buffer. Upon entry, destLen is the total 1043 size of the destination buffer, which must be at least the value returned 1044 by compressBound(sourceLen). Upon exit, destLen is the actual size of the 1045 compressed buffer. 1046 This function can be used to compress a whole file at once if the 1047 input file is mmap'ed. 1048 compress returns Z_OK if success, Z_MEM_ERROR if there was not 1049 enough memory, Z_BUF_ERROR if there was not enough room in the output 1050 buffer. 1051*/ 1052 1053ZEXTERN int ZEXPORT compress2 OF((Bytef *dest, uLongf *destLen, 1054 const Bytef *source, uLong sourceLen, 1055 int level)); 1056/* 1057 Compresses the source buffer into the destination buffer. The level 1058 parameter has the same meaning as in deflateInit. sourceLen is the byte 1059 length of the source buffer. Upon entry, destLen is the total size of the 1060 destination buffer, which must be at least the value returned by 1061 compressBound(sourceLen). Upon exit, destLen is the actual size of the 1062 compressed buffer. 1063 1064 compress2 returns Z_OK if success, Z_MEM_ERROR if there was not enough 1065 memory, Z_BUF_ERROR if there was not enough room in the output buffer, 1066 Z_STREAM_ERROR if the level parameter is invalid. 1067*/ 1068 1069ZEXTERN uLong ZEXPORT compressBound OF((uLong sourceLen)); 1070/* 1071 compressBound() returns an upper bound on the compressed size after 1072 compress() or compress2() on sourceLen bytes. It would be used before 1073 a compress() or compress2() call to allocate the destination buffer. 1074*/ 1075 1076ZEXTERN int ZEXPORT uncompress OF((Bytef *dest, uLongf *destLen, 1077 const Bytef *source, uLong sourceLen)); 1078/* 1079 Decompresses the source buffer into the destination buffer. sourceLen is 1080 the byte length of the source buffer. Upon entry, destLen is the total 1081 size of the destination buffer, which must be large enough to hold the 1082 entire uncompressed data. (The size of the uncompressed data must have 1083 been saved previously by the compressor and transmitted to the decompressor 1084 by some mechanism outside the scope of this compression library.) 1085 Upon exit, destLen is the actual size of the compressed buffer. 1086 This function can be used to decompress a whole file at once if the 1087 input file is mmap'ed. 1088 1089 uncompress returns Z_OK if success, Z_MEM_ERROR if there was not 1090 enough memory, Z_BUF_ERROR if there was not enough room in the output 1091 buffer, or Z_DATA_ERROR if the input data was corrupted or incomplete. 1092*/ 1093 1094#if !KERNEL 1095 1096typedef voidp gzFile; 1097 1098ZEXTERN gzFile ZEXPORT gzopen OF((const char *path, const char *mode)); 1099/* 1100 Opens a gzip (.gz) file for reading or writing. The mode parameter 1101 is as in fopen ("rb" or "wb") but can also include a compression level 1102 ("wb9") or a strategy: 'f' for filtered data as in "wb6f", 'h' for 1103 Huffman only compression as in "wb1h", or 'R' for run-length encoding 1104 as in "wb1R". (See the description of deflateInit2 for more information 1105 about the strategy parameter.) 1106 1107 gzopen can be used to read a file which is not in gzip format; in this 1108 case gzread will directly read from the file without decompression. 1109 1110 gzopen returns NULL if the file could not be opened or if there was 1111 insufficient memory to allocate the (de)compression state; errno 1112 can be checked to distinguish the two cases (if errno is zero, the 1113 zlib error is Z_MEM_ERROR). */ 1114 1115ZEXTERN gzFile ZEXPORT gzdopen OF((int fd, const char *mode)); 1116/* 1117 gzdopen() associates a gzFile with the file descriptor fd. File 1118 descriptors are obtained from calls like open, dup, creat, pipe or 1119 fileno (in the file has been previously opened with fopen). 1120 The mode parameter is as in gzopen. 1121 The next call of gzclose on the returned gzFile will also close the 1122 file descriptor fd, just like fclose(fdopen(fd), mode) closes the file 1123 descriptor fd. If you want to keep fd open, use gzdopen(dup(fd), mode). 1124 gzdopen returns NULL if there was insufficient memory to allocate 1125 the (de)compression state. 1126*/ 1127 1128ZEXTERN int ZEXPORT gzsetparams OF((gzFile file, int level, int strategy)); 1129/* 1130 Dynamically update the compression level or strategy. See the description 1131 of deflateInit2 for the meaning of these parameters. 1132 gzsetparams returns Z_OK if success, or Z_STREAM_ERROR if the file was not 1133 opened for writing. 1134*/ 1135 1136ZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len)); 1137/* 1138 Reads the given number of uncompressed bytes from the compressed file. 1139 If the input file was not in gzip format, gzread copies the given number 1140 of bytes into the buffer. 1141 gzread returns the number of uncompressed bytes actually read (0 for 1142 end of file, -1 for error). */ 1143 1144ZEXTERN int ZEXPORT gzwrite OF((gzFile file, 1145 voidpc buf, unsigned len)); 1146/* 1147 Writes the given number of uncompressed bytes into the compressed file. 1148 gzwrite returns the number of uncompressed bytes actually written 1149 (0 in case of error). 1150*/ 1151 1152ZEXTERN int ZEXPORTVA gzprintf OF((gzFile file, const char *format, ...)); 1153/* 1154 Converts, formats, and writes the args to the compressed file under 1155 control of the format string, as in fprintf. gzprintf returns the number of 1156 uncompressed bytes actually written (0 in case of error). The number of 1157 uncompressed bytes written is limited to 4095. The caller should assure that 1158 this limit is not exceeded. If it is exceeded, then gzprintf() will return 1159 return an error (0) with nothing written. In this case, there may also be a 1160 buffer overflow with unpredictable consequences, which is possible only if 1161 zlib was compiled with the insecure functions sprintf() or vsprintf() 1162 because the secure snprintf() or vsnprintf() functions were not available. 1163*/ 1164 1165ZEXTERN int ZEXPORT gzputs OF((gzFile file, const char *s)); 1166/* 1167 Writes the given null-terminated string to the compressed file, excluding 1168 the terminating null character. 1169 gzputs returns the number of characters written, or -1 in case of error. 1170*/ 1171 1172ZEXTERN char * ZEXPORT gzgets OF((gzFile file, char *buf, int len)); 1173/* 1174 Reads bytes from the compressed file until len-1 characters are read, or 1175 a newline character is read and transferred to buf, or an end-of-file 1176 condition is encountered. The string is then terminated with a null 1177 character. 1178 gzgets returns buf, or Z_NULL in case of error. 1179*/ 1180 1181ZEXTERN int ZEXPORT gzputc OF((gzFile file, int c)); 1182/* 1183 Writes c, converted to an unsigned char, into the compressed file. 1184 gzputc returns the value that was written, or -1 in case of error. 1185*/ 1186 1187ZEXTERN int ZEXPORT gzgetc OF((gzFile file)); 1188/* 1189 Reads one byte from the compressed file. gzgetc returns this byte 1190 or -1 in case of end of file or error. 1191*/ 1192 1193ZEXTERN int ZEXPORT gzungetc OF((int c, gzFile file)); 1194/* 1195 Push one character back onto the stream to be read again later. 1196 Only one character of push-back is allowed. gzungetc() returns the 1197 character pushed, or -1 on failure. gzungetc() will fail if a 1198 character has been pushed but not read yet, or if c is -1. The pushed 1199 character will be discarded if the stream is repositioned with gzseek() 1200 or gzrewind(). 1201*/ 1202 1203ZEXTERN int ZEXPORT gzflush OF((gzFile file, int flush)); 1204/* 1205 Flushes all pending output into the compressed file. The parameter 1206 flush is as in the deflate() function. The return value is the zlib 1207 error number (see function gzerror below). gzflush returns Z_OK if 1208 the flush parameter is Z_FINISH and all output could be flushed. 1209 gzflush should be called only when strictly necessary because it can 1210 degrade compression. 1211*/ 1212 1213ZEXTERN z_off_t ZEXPORT gzseek OF((gzFile file, 1214 z_off_t offset, int whence)); 1215/* 1216 Sets the starting position for the next gzread or gzwrite on the 1217 given compressed file. The offset represents a number of bytes in the 1218 uncompressed data stream. The whence parameter is defined as in lseek(2); 1219 the value SEEK_END is not supported. 1220 If the file is opened for reading, this function is emulated but can be 1221 extremely slow. If the file is opened for writing, only forward seeks are 1222 supported; gzseek then compresses a sequence of zeroes up to the new 1223 starting position. 1224 1225 gzseek returns the resulting offset location as measured in bytes from 1226 the beginning of the uncompressed stream, or -1 in case of error, in 1227 particular if the file is opened for writing and the new starting position 1228 would be before the current position. 1229*/ 1230 1231ZEXTERN int ZEXPORT gzrewind OF((gzFile file)); 1232/* 1233 Rewinds the given file. This function is supported only for reading. 1234 1235 gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET) 1236*/ 1237 1238ZEXTERN z_off_t ZEXPORT gztell OF((gzFile file)); 1239/* 1240 Returns the starting position for the next gzread or gzwrite on the 1241 given compressed file. This position represents a number of bytes in the 1242 uncompressed data stream. 1243 1244 gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR) 1245*/ 1246 1247ZEXTERN int ZEXPORT gzeof OF((gzFile file)); 1248/* 1249 Returns 1 when EOF has previously been detected reading the given 1250 input stream, otherwise zero. 1251*/ 1252 1253ZEXTERN int ZEXPORT gzdirect OF((gzFile file)); 1254/* 1255 Returns 1 if file is being read directly without decompression, otherwise 1256 zero. 1257*/ 1258 1259ZEXTERN int ZEXPORT gzclose OF((gzFile file)); 1260/* 1261 Flushes all pending output if necessary, closes the compressed file 1262 and deallocates all the (de)compression state. The return value is the zlib 1263 error number (see function gzerror below). 1264*/ 1265 1266ZEXTERN const char * ZEXPORT gzerror OF((gzFile file, int *errnum)); 1267/* 1268 Returns the error message for the last error which occurred on the 1269 given compressed file. errnum is set to zlib error number. If an 1270 error occurred in the file system and not in the compression library, 1271 errnum is set to Z_ERRNO and the application may consult errno 1272 to get the exact error code. 1273*/ 1274 1275ZEXTERN void ZEXPORT gzclearerr OF((gzFile file)); 1276/* 1277 Clears the error and end-of-file flags for file. This is analogous to the 1278 clearerr() function in stdio. This is useful for continuing to read a gzip 1279 file that is being written concurrently. 1280*/ 1281 1282#endif /* KERNEL */ 1283 1284 /* checksum functions */ 1285 1286/* 1287 These functions are not related to compression but are exported 1288 anyway because they might be useful in applications using the 1289 compression library. 1290*/ 1291 1292ZEXTERN uLong ZEXPORT adler32 OF((uLong adler, const Bytef *buf, uInt len)); 1293/* 1294 Update a running Adler-32 checksum with the bytes buf[0..len-1] and 1295 return the updated checksum. If buf is NULL, this function returns 1296 the required initial value for the checksum. 1297 An Adler-32 checksum is almost as reliable as a CRC32 but can be computed 1298 much faster. Usage example: 1299 1300 uLong adler = adler32(0L, Z_NULL, 0); 1301 1302 while (read_buffer(buffer, length) != EOF) { 1303 adler = adler32(adler, buffer, length); 1304 } 1305 if (adler != original_adler) error(); 1306*/ 1307 1308ZEXTERN uLong ZEXPORT adler32_combine OF((uLong adler1, uLong adler2, 1309 z_off_t len2)); 1310/* 1311 Combine two Adler-32 checksums into one. For two sequences of bytes, seq1 1312 and seq2 with lengths len1 and len2, Adler-32 checksums were calculated for 1313 each, adler1 and adler2. adler32_combine() returns the Adler-32 checksum of 1314 seq1 and seq2 concatenated, requiring only adler1, adler2, and len2. 1315*/ 1316 1317ZEXTERN uLong ZEXPORT z_crc32 OF((uLong crc, const Bytef *buf, uInt len)); 1318/* 1319 Update a running CRC-32 with the bytes buf[0..len-1] and return the 1320 updated CRC-32. If buf is NULL, this function returns the required initial 1321 value for the for the crc. Pre- and post-conditioning (one's complement) is 1322 performed within this function so it shouldn't be done by the application. 1323 Usage example: 1324 1325 uLong crc = crc32(0L, Z_NULL, 0); 1326 1327 while (read_buffer(buffer, length) != EOF) { 1328 crc = crc32(crc, buffer, length); 1329 } 1330 if (crc != original_crc) error(); 1331*/ 1332 1333ZEXTERN uLong ZEXPORT z_crc32_combine OF((uLong crc1, uLong crc2, z_off_t len2)); 1334 1335/* 1336 Combine two CRC-32 check values into one. For two sequences of bytes, 1337 seq1 and seq2 with lengths len1 and len2, CRC-32 check values were 1338 calculated for each, crc1 and crc2. crc32_combine() returns the CRC-32 1339 check value of seq1 and seq2 concatenated, requiring only crc1, crc2, and 1340 len2. 1341*/ 1342 1343 1344 /* various hacks, don't look :) */ 1345 1346/* deflateInit and inflateInit are macros to allow checking the zlib version 1347 * and the compiler's view of z_stream: 1348 */ 1349ZEXTERN int ZEXPORT deflateInit_ OF((z_streamp strm, int level, 1350 const char *version, int stream_size)); 1351ZEXTERN int ZEXPORT inflateInit_ OF((z_streamp strm, 1352 const char *version, int stream_size)); 1353ZEXTERN int ZEXPORT deflateInit2_ OF((z_streamp strm, int level, int method, 1354 int windowBits, int memLevel, 1355 int strategy, const char *version, 1356 int stream_size)); 1357ZEXTERN int ZEXPORT inflateInit2_ OF((z_streamp strm, int windowBits, 1358 const char *version, int stream_size)); 1359ZEXTERN int ZEXPORT inflateBackInit_ OF((z_streamp strm, int windowBits, 1360 unsigned char FAR *window, 1361 const char *version, 1362 int stream_size)); 1363#define deflateInit(strm, level) \ 1364 deflateInit_((strm), (level), ZLIB_VERSION, sizeof(z_stream)) 1365#define inflateInit(strm) \ 1366 inflateInit_((strm), ZLIB_VERSION, sizeof(z_stream)) 1367#define deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ 1368 deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ 1369 (strategy), ZLIB_VERSION, sizeof(z_stream)) 1370#define inflateInit2(strm, windowBits) \ 1371 inflateInit2_((strm), (windowBits), ZLIB_VERSION, sizeof(z_stream)) 1372#define inflateBackInit(strm, windowBits, window) \ 1373 inflateBackInit_((strm), (windowBits), (window), \ 1374 ZLIB_VERSION, sizeof(z_stream)) 1375 1376 1377#if !defined(ZUTIL_H) && !defined(NO_DUMMY_DECL) 1378 struct internal_state {int dummy;}; /* hack for buggy compilers */ 1379#endif 1380 1381ZEXTERN const char * ZEXPORT zError OF((int)); 1382ZEXTERN int ZEXPORT inflateSyncPoint OF((z_streamp z)); 1383ZEXTERN const uLongf * ZEXPORT get_crc_table OF((void)); 1384 1385#ifdef __cplusplus 1386} 1387#endif 1388 1389#endif /* ZLIB_H */ 1390