zlib.h

   1 /* zlib.h -- interface of the 'zlib' general purpose compression library
   2   version 1.0.8, Jan 27th, 1998
   3
   4   Copyright (C) 1995-1998 Jean-loup Gailly and Mark Adler
   5
   6   This software is provided 'as-is', without any express or implied
   7   warranty.  In no event will the authors be held liable for any damages
   8   arising from the use of this software.
   9
  10   Permission is granted to anyone to use this software for any purpose,
  11   including commercial applications, and to alter it and redistribute it
  12   freely, subject to the following restrictions:
  13
  14   1. The origin of this software must not be misrepresented; you must not
  15      claim that you wrote the original software. If you use this software
  16      in a product, an acknowledgment in the product documentation would be
  17      appreciated but is not required.
  18   2. Altered source versions must be plainly marked as such, and must not be
  19      misrepresented as being the original software.
  20   3. This notice may not be removed or altered from any source distribution.
  21
  22   Jean-loup Gailly        Mark Adler
  23   jloup@gzip.org          madler@alumni.caltech.edu
  24
  25
  26   The data format used by the zlib library is described by RFCs (Request for
  27   Comments) 1950 to 1952 in the files ftp://ds.internic.net/rfc/rfc1950.txt
  28   (zlib format), rfc1951.txt (deflate format) and rfc1952.txt (gzip format).
  29 */
  30
  31 #ifndef _ZLIB_H
  32 #define _ZLIB_H
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 #include "zconf.h"
  39
  40 #define ZLIB_VERSION "1.0.8"
  41
  42 /*
  43      The 'zlib' compression library provides in-memory compression and
  44   decompression functions, including integrity checks of the uncompressed
  45   data.  This version of the library supports only one compression method
  46   (deflation) but other algorithms will be added later and will have the same
  47   stream interface.
  48
  49      Compression can be done in a single step if the buffers are large
  50   enough (for example if an input file is mmap'ed), or can be done by
  51   repeated calls of the compression function.  In the latter case, the
  52   application must provide more input and/or consume the output
  53   (providing more output space) before each call.
  54
  55      The library also supports reading and writing files in gzip (.gz) format
  56   with an interface similar to that of stdio.
  57
  58      The library does not install any signal handler. The decoder checks
  59   the consistency of the compressed data, so the library should never
  60   crash even in case of corrupted input.
  61 */
  62
  63 typedef voidpf (*alloc_func) OF((voidpf opaque, uInt items, uInt size));
  64 typedef void   (*free_func)  OF((voidpf opaque, voidpf address));
  65
  66 struct internal_state;
  67
  68 typedef struct z_stream_s {
  69     Bytef    *next_in;  /* next input byte */
  70     uInt     avail_in;  /* number of bytes available at next_in */
  71     uLong    total_in;  /* total nb of input bytes read so far */
  72
  73     Bytef    *next_out; /* next output byte should be put there */
  74     uInt     avail_out; /* remaining free space at next_out */
  75     uLong    total_out; /* total nb of bytes output so far */
  76
  77     char     *msg;      /* last error message, NULL if no error */
  78     struct internal_state FAR *state; /* not visible by applications */
  79
  80     alloc_func zalloc;  /* used to allocate the internal state */
  81     free_func  zfree;   /* used to free the internal state */
  82     voidpf     opaque;  /* private data object passed to zalloc and zfree */
  83
  84     int     data_type;  /* best guess about the data type: ascii or binary */
  85     uLong   adler;      /* adler32 value of the uncompressed data */
  86     uLong   reserved;   /* reserved for future use */
  87 } z_stream;
  88
  89 typedef z_stream FAR *z_streamp;
  90
  91 /*
  92    The application must update next_in and avail_in when avail_in has
  93    dropped to zero. It must update next_out and avail_out when avail_out
  94    has dropped to zero. The application must initialize zalloc, zfree and
  95    opaque before calling the init function. All other fields are set by the
  96    compression library and must not be updated by the application.
  97
  98    The opaque value provided by the application will be passed as the first
  99    parameter for calls of zalloc and zfree. This can be useful for custom
 100    memory management. The compression library attaches no meaning to the
 101    opaque value.
 102
 103    zalloc must return Z_NULL if there is not enough memory for the object.
 104    On 16-bit systems, the functions zalloc and zfree must be able to allocate
 105    exactly 65536 bytes, but will not be required to allocate more than this
 106    if the symbol MAXSEG_64K is defined (see zconf.h). WARNING: On MSDOS,
 107    pointers returned by zalloc for objects of exactly 65536 bytes *must*
 108    have their offset normalized to zero. The default allocation function
 109    provided by this library ensures this (see zutil.c). To reduce memory
 110    requirements and avoid any allocation of 64K objects, at the expense of
 111    compression ratio, compile the library with -DMAX_WBITS=14 (see zconf.h).
 112
 113    The fields total_in and total_out can be used for statistics or
 114    progress reports. After compression, total_in holds the total size of
 115    the uncompressed data and may be saved for use in the decompressor
 116    (particularly if the decompressor wants to decompress everything in
 117    a single step).
 118 */
 119
 120                         /* constants */
 121
 122 #define Z_NO_FLUSH      0
 123 #define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */
 124 #define Z_SYNC_FLUSH    2
 125 #define Z_FULL_FLUSH    3
 126 #define Z_FINISH        4
 127 /* Allowed flush values; see deflate() below for details */
 128
 129 #define Z_OK            0
 130 #define Z_STREAM_END    1
 131 #define Z_NEED_DICT     2
 132 #define Z_ERRNO        (-1)
 133 #define Z_STREAM_ERROR (-2)
 134 #define Z_DATA_ERROR   (-3)
 135 #define Z_MEM_ERROR    (-4)
 136 #define Z_BUF_ERROR    (-5)
 137 #define Z_VERSION_ERROR (-6)
 138 /* Return codes for the compression/decompression functions. Negative
 139  * values are errors, positive values are used for special but normal events.
 140  */
 141
 142 #define Z_NO_COMPRESSION         0
 143 #define Z_BEST_SPEED             1
 144 #define Z_BEST_COMPRESSION       9
 145 #define Z_DEFAULT_COMPRESSION  (-1)
 146 /* compression levels */
 147
 148 #define Z_FILTERED            1
 149 #define Z_HUFFMAN_ONLY        2
 150 #define Z_DEFAULT_STRATEGY    0
 151 /* compression strategy; see deflateInit2() below for details */
 152
 153 #define Z_BINARY   0
 154 #define Z_ASCII    1
 155 #define Z_UNKNOWN  2
 156 /* Possible values of the data_type field */
 157
 158 #define Z_DEFLATED   8
 159 /* The deflate compression method (the only one supported in this version) */
 160
 161 #define Z_NULL  0  /* for initializing zalloc, zfree, opaque */
 162
 163 #define zlib_version zlibVersion()
 164 /* for compatibility with versions < 1.0.2 */
 165
 166                         /* basic functions */
 167
 168 extern const char * EXPORT zlibVersion OF((void));
 169 /* The application can compare zlibVersion and ZLIB_VERSION for consistency.
 170    If the first character differs, the library code actually used is
 171    not compatible with the zlib.h header file used by the application.
 172    This check is automatically made by deflateInit and inflateInit.
 173  */
 174
 175 /*
 176 extern int EXPORT deflateInit OF((z_streamp strm, int level));
 177
 178      Initializes the internal stream state for compression. The fields
 179    zalloc, zfree and opaque must be initialized before by the caller.
 180    If zalloc and zfree are set to Z_NULL, deflateInit updates them to
 181    use default allocation functions.
 182
 183      The compression level must be Z_DEFAULT_COMPRESSION, or between 0 and 9:
 184    1 gives best speed, 9 gives best compression, 0 gives no compression at
 185    all (the input data is simply copied a block at a time).
 186    Z_DEFAULT_COMPRESSION requests a default compromise between speed and
 187    compression (currently equivalent to level 6).
 188
 189      deflateInit returns Z_OK if success, Z_MEM_ERROR if there was not
 190    enough memory, Z_STREAM_ERROR if level is not a valid compression level,
 191    Z_VERSION_ERROR if the zlib library version (zlib_version) is incompatible
 192    with the version assumed by the caller (ZLIB_VERSION).
 193    msg is set to null if there is no error message.  deflateInit does not
 194    perform any compression: this will be done by deflate().
 195 */
 196
 197
 198 extern int EXPORT deflate OF((z_streamp strm, int flush));
 199 /*
 200     deflate compresses as much data as possible, and stops when the input
 201   buffer becomes empty or the output buffer becomes full. It may introduce some
 202   output latency (reading input without producing any output) except when
 203   forced to flush.
 204
 205     The detailed semantics are as follows. deflate performs one or both of the
 206   following actions:
 207
 208   - Compress more input starting at next_in and update next_in and avail_in
 209     accordingly. If not all input can be processed (because there is not
 210     enough room in the output buffer), next_in and avail_in are updated and
 211     processing will resume at this point for the next call of deflate().
 212
 213   - Provide more output starting at next_out and update next_out and avail_out
 214     accordingly. This action is forced if the parameter flush is non zero.
 215     Forcing flush frequently degrades the compression ratio, so this parameter
 216     should be set only when necessary (in interactive applications).
 217     Some output may be provided even if flush is not set.
 218
 219   Before the call of deflate(), the application should ensure that at least
 220   one of the actions is possible, by providing more input and/or consuming
 221   more output, and updating avail_in or avail_out accordingly; avail_out
 222   should never be zero before the call. The application can consume the
 223   compressed output when it wants, for example when the output buffer is full
 224   (avail_out == 0), or after each call of deflate(). If deflate returns Z_OK
 225   and with zero avail_out, it must be called again after making room in the
 226   output buffer because there might be more output pending.
 227
 228     If the parameter flush is set to Z_SYNC_FLUSH, all pending output is
 229   flushed to the output buffer and the output is aligned on a byte boundary, so
 230   that the decompressor can get all input data available so far. (In particular
 231   avail_in is zero after the call if enough output space has been provided
 232   before the call.)  Flushing may degrade compression for some compression
 233   algorithms and so it should be used only when necessary.
 234
 235     If flush is set to Z_FULL_FLUSH, all output is flushed as with
 236   Z_SYNC_FLUSH, and the compression state is reset so that decompression can
 237   restart from this point if previous compressed data has been damaged or if
 238   random access is desired. Using Z_FULL_FLUSH too often can seriously degrade
 239   the compression.
 240
 241     If deflate returns with avail_out == 0, this function must be called again
 242   with the same value of the flush parameter and more output space (updated
 243   avail_out), until the flush is complete (deflate returns with non-zero
 244   avail_out).
 245
 246     If the parameter flush is set to Z_FINISH, pending input is processed,
 247   pending output is flushed and deflate returns with Z_STREAM_END if there
 248   was enough output space; if deflate returns with Z_OK, this function must be
 249   called again with Z_FINISH and more output space (updated avail_out) but no
 250   more input data, until it returns with Z_STREAM_END or an error. After
 251   deflate has returned Z_STREAM_END, the only possible operations on the
 252   stream are deflateReset or deflateEnd.
 253
 254     Z_FINISH can be used immediately after deflateInit if all the compression
 255   is to be done in a single step. In this case, avail_out must be at least
 256   0.1% larger than avail_in plus 12 bytes.  If deflate does not return
 257   Z_STREAM_END, then it must be called again as described above.
 258
 259     deflate() sets strm->adler to the adler32 checksum of all input read
 260   so far (that is, total_in bytes).
 261
 262     deflate() may update data_type if it can make a good guess about
 263   the input data type (Z_ASCII or Z_BINARY). In doubt, the data is considered
 264   binary. This field is only for information purposes and does not affect
 265   the compression algorithm in any manner.
 266
 267     deflate() returns Z_OK if some progress has been made (more input
 268   processed or more output produced), Z_STREAM_END if all input has been
 269   consumed and all output has been produced (only when flush is set to
 270   Z_FINISH), Z_STREAM_ERROR if the stream state was inconsistent (for example
 271   if next_in or next_out was NULL), Z_BUF_ERROR if no progress is possible.
 272 */
 273
 274
 275 extern int EXPORT deflateEnd OF((z_streamp strm));
 276 /*
 277      All dynamically allocated data structures for this stream are freed.
 278    This function discards any unprocessed input and does not flush any
 279    pending output.
 280
 281      deflateEnd returns Z_OK if success, Z_STREAM_ERROR if the
 282    stream state was inconsistent, Z_DATA_ERROR if the stream was freed
 283    prematurely (some input or output was discarded). In the error case,
 284    msg may be set but then points to a static string (which must not be
 285    deallocated).
 286 */
 287
 288
 289 /*
 290 extern int EXPORT inflateInit OF((z_streamp strm));
 291
 292      Initializes the internal stream state for decompression. The fields
 293    next_in, avail_in, zalloc, zfree and opaque must be initialized before by
 294    the caller. If next_in is not Z_NULL and avail_in is large enough (the exact
 295    value depends on the compression method), inflateInit determines the
 296    compression method from the zlib header and allocates all data structures
 297    accordingly; otherwise the allocation will be deferred to the first call of
 298    inflate.  If zalloc and zfree are set to Z_NULL, inflateInit updates them to
 299    use default allocation functions.
 300
 301      inflateInit returns Z_OK if success, Z_MEM_ERROR if there was not enough
 302    memory, Z_VERSION_ERROR if the zlib library version is incompatible with the
 303    version assumed by the caller.  msg is set to null if there is no error
 304    message. inflateInit does not perform any decompression apart from reading
 305    the zlib header if present: this will be done by inflate().  (So next_in and
 306    avail_in may be modified, but next_out and avail_out are unchanged.)
 307 */
 308
 309
 310 extern int EXPORT inflate OF((z_streamp strm, int flush));
 311 /*
 312     inflate decompresses as much data as possible, and stops when the input
 313   buffer becomes empty or the output buffer becomes full. It may some
 314   introduce some output latency (reading input without producing any output)
 315   except when forced to flush.
 316
 317   The detailed semantics are as follows. inflate performs one or both of the
 318   following actions:
 319
 320   - Decompress more input starting at next_in and update next_in and avail_in
 321     accordingly. If not all input can be processed (because there is not
 322     enough room in the output buffer), next_in is updated and processing
 323     will resume at this point for the next call of inflate().
 324
 325   - Provide more output starting at next_out and update next_out and avail_out
 326     accordingly.  inflate() provides as much output as possible, until there
 327     is no more input data or no more space in the output buffer (see below
 328     about the flush parameter).
 329
 330   Before the call of inflate(), the application should ensure that at least
 331   one of the actions is possible, by providing more input and/or consuming
 332   more output, and updating the next_* and avail_* values accordingly.
 333   The application can consume the uncompressed output when it wants, for
 334   example when the output buffer is full (avail_out == 0), or after each
 335   call of inflate(). If inflate returns Z_OK and with zero avail_out, it
 336   must be called again after making room in the output buffer because there
 337   might be more output pending.
 338
 339     If the parameter flush is set to Z_SYNC_FLUSH, inflate flushes as much
 340   output as possible to the output buffer. The flushing behavior of inflate is
 341   not specified for values of the flush parameter other than Z_SYNC_FLUSH
 342   and Z_FINISH, but the current implementation actually flushes as much output
 343   as possible anyway.
 344
 345     inflate() should normally be called until it returns Z_STREAM_END or an
 346   error. However if all decompression is to be performed in a single step
 347   (a single call of inflate), the parameter flush should be set to
 348   Z_FINISH. In this case all pending input is processed and all pending
 349   output is flushed; avail_out must be large enough to hold all the
 350   uncompressed data. (The size of the uncompressed data may have been saved
 351   by the compressor for this purpose.) The next operation on this stream must
 352   be inflateEnd to deallocate the decompression state. The use of Z_FINISH
 353   is never required, but can be used to inform inflate that a faster routine
 354   may be used for the single inflate() call.
 355
 356      If a preset dictionary is needed at this point (see inflateSetDictionary
 357   below), inflate sets strm-adler to the adler32 checksum of the
 358   dictionary chosen by the compressor and returns Z_NEED_DICT; otherwise
 359   it sets strm->adler to the adler32 checksum of all output produced
 360   so far (that is, total_out bytes) and returns Z_OK, Z_STREAM_END or
 361   an error code as described below. At the end of the stream, inflate()
 362   checks that its computed adler32 checksum is equal to that saved by the
 363   compressor and returns Z_STREAM_END only if the checksum is correct.
 364
 365     inflate() returns Z_OK if some progress has been made (more input processed
 366   or more output produced), Z_STREAM_END if the end of the compressed data has
 367   been reached and all uncompressed output has been produced, Z_NEED_DICT if a
 368   preset dictionary is needed at this point, Z_DATA_ERROR if the input data was
 369   corrupted (input stream not conforming to the zlib format or incorrect
 370   adler32 checksum), Z_STREAM_ERROR if the stream structure was inconsistent
 371   (for example if next_in or next_out was NULL), Z_MEM_ERROR if there was not
 372   enough memory, Z_BUF_ERROR if no progress is possible or if there was not
 373   enough room in the output buffer when Z_FINISH is used. In the Z_DATA_ERROR
 374   case, the application may then call inflateSync to look for a good
 375   compression block.
 376 */
 377
 378
 379 extern int EXPORT inflateEnd OF((z_streamp strm));
 380 /*
 381      All dynamically allocated data structures for this stream are freed.
 382    This function discards any unprocessed input and does not flush any
 383    pending output.
 384
 385      inflateEnd returns Z_OK if success, Z_STREAM_ERROR if the stream state
 386    was inconsistent. In the error case, msg may be set but then points to a
 387    static string (which must not be deallocated).
 388 */
 389
 390                         /* Advanced functions */
 391
 392 /*
 393     The following functions are needed only in some special applications.
 394 */
 395
 396 /*
 397 extern int EXPORT deflateInit2 OF((z_streamp strm,
 398                                    int  level,
 399                                    int  method,
 400                                    int  windowBits,
 401                                    int  memLevel,
 402                                    int  strategy));
 403
 404      This is another version of deflateInit with more compression options. The
 405    fields next_in, zalloc, zfree and opaque must be initialized before by
 406    the caller.
 407
 408      The method parameter is the compression method. It must be Z_DEFLATED in
 409    this version of the library.
 410
 411      The windowBits parameter is the base two logarithm of the window size
 412    (the size of the history buffer).  It should be in the range 8..15 for this
 413    version of the library. Larger values of this parameter result in better
 414    compression at the expense of memory usage. The default value is 15 if
 415    deflateInit is used instead.
 416
 417      The memLevel parameter specifies how much memory should be allocated
 418    for the internal compression state. memLevel=1 uses minimum memory but
 419    is slow and reduces compression ratio; memLevel=9 uses maximum memory
 420    for optimal speed. The default value is 8. See zconf.h for total memory
 421    usage as a function of windowBits and memLevel.
 422
 423      The strategy parameter is used to tune the compression algorithm. Use the
 424    value Z_DEFAULT_STRATEGY for normal data, Z_FILTERED for data produced by a
 425    filter (or predictor), or Z_HUFFMAN_ONLY to force Huffman encoding only (no
 426    string match).  Filtered data consists mostly of small values with a
 427    somewhat random distribution. In this case, the compression algorithm is
 428    tuned to compress them better. The effect of Z_FILTERED is to force more
 429    Huffman coding and less string matching; it is somewhat intermediate
 430    between Z_DEFAULT and Z_HUFFMAN_ONLY. The strategy parameter only affects
 431    the compression ratio but not the correctness of the compressed output even
 432    if it is not set appropriately.
 433
 434       deflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough
 435    memory, Z_STREAM_ERROR if a parameter is invalid (such as an invalid
 436    method). msg is set to null if there is no error message.  deflateInit2 does
 437    not perform any compression: this will be done by deflate().
 438 */
 439
 440 extern int EXPORT deflateSetDictionary OF((z_streamp strm,
 441                                            const Bytef *dictionary,
 442                                            uInt  dictLength));
 443 /*
 444      Initializes the compression dictionary from the given byte sequence
 445    without producing any compressed output. This function must be called
 446    immediately after deflateInit or deflateInit2, before any call of
 447    deflate. The compressor and decompressor must use exactly the same
 448    dictionary (see inflateSetDictionary).
 449
 450      The dictionary should consist of strings (byte sequences) that are likely
 451    to be encountered later in the data to be compressed, with the most commonly
 452    used strings preferably put towards the end of the dictionary. Using a
 453    dictionary is most useful when the data to be compressed is short and can be
 454    predicted with good accuracy; the data can then be compressed better than
 455    with the default empty dictionary.
 456
 457      Depending on the size of the compression data structures selected by
 458    deflateInit or deflateInit2, a part of the dictionary may in effect be
 459    discarded, for example if the dictionary is larger than the window size in
 460    deflate or deflate2. Thus the strings most likely to be useful should be
 461    put at the end of the dictionary, not at the front.
 462
 463      Upon return of this function, strm->adler is set to the Adler32 value
 464    of the dictionary; the decompressor may later use this value to determine
 465    which dictionary has been used by the compressor. (The Adler32 value
 466    applies to the whole dictionary even if only a subset of the dictionary is
 467    actually used by the compressor.)
 468
 469      deflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a
 470    parameter is invalid (such as NULL dictionary) or the stream state is
 471    inconsistent (for example if deflate has already been called for this stream
 472    or if the compression method is bsort). deflateSetDictionary does not
 473    perform any compression: this will be done by deflate().
 474 */
 475
 476 extern int EXPORT deflateCopy OF((z_streamp dest,
 477                                   z_streamp source));
 478 /*
 479      Sets the destination stream as a complete copy of the source stream.
 480
 481      This function can be useful when several compression strategies will be
 482    tried, for example when there are several ways of pre-processing the input
 483    data with a filter. The streams that will be discarded should then be freed
 484    by calling deflateEnd.  Note that deflateCopy duplicates the internal
 485    compression state which can be quite large, so this strategy is slow and
 486    can consume lots of memory.
 487
 488      deflateCopy returns Z_OK if success, Z_MEM_ERROR if there was not
 489    enough memory, Z_STREAM_ERROR if the source stream state was inconsistent
 490    (such as zalloc being NULL). msg is left unchanged in both source and
 491    destination.
 492 */
 493
 494 extern int EXPORT deflateReset OF((z_streamp strm));
 495 /*
 496      This function is equivalent to deflateEnd followed by deflateInit,
 497    but does not free and reallocate all the internal compression state.
 498    The stream will keep the same compression level and any other attributes
 499    that may have been set by deflateInit2.
 500
 501       deflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source
 502    stream state was inconsistent (such as zalloc or state being NULL).
 503 */
 504
 505 extern int EXPORT deflateParams OF((z_streamp strm, int level, int strategy));
 506 /*
 507      Dynamically update the compression level and compression strategy.  The
 508    interpretation of level and strategy is as in deflateInit2.  This can be
 509    used to switch between compression and straight copy of the input data, or
 510    to switch to a different kind of input data requiring a different
 511    strategy. If the compression level is changed, the input available so far
 512    is compressed with the old level (and may be flushed); the new level will
 513    take effect only at the next call of deflate().
 514
 515      Before the call of deflateParams, the stream state must be set as for
 516    a call of deflate(), since the currently available input may have to
 517    be compressed and flushed. In particular, strm->avail_out must be non-zero.
 518
 519      deflateParams returns Z_OK if success, Z_STREAM_ERROR if the source
 520    stream state was inconsistent or if a parameter was invalid, Z_BUF_ERROR
 521    if strm->avail_out was zero.
 522 */
 523
 524 /*
 525 extern int EXPORT inflateInit2 OF((z_streamp strm,
 526                                    int  windowBits));
 527
 528      This is another version of inflateInit with an extra parameter. The
 529    fields next_in, avail_in, zalloc, zfree and opaque must be initialized
 530    before by the caller.
 531
 532      The windowBits parameter is the base two logarithm of the maximum window
 533    size (the size of the history buffer).  It should be in the range 8..15 for
 534    this version of the library. The default value is 15 if inflateInit is used
 535    instead. If a compressed stream with a larger window size is given as
 536    input, inflate() will return with the error code Z_DATA_ERROR instead of
 537    trying to allocate a larger window.
 538
 539       inflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough
 540    memory, Z_STREAM_ERROR if a parameter is invalid (such as a negative
 541    memLevel). msg is set to null if there is no error message.  inflateInit2
 542    does not perform any decompression apart from reading the zlib header if
 543    present: this will be done by inflate(). (So next_in and avail_in may be
 544    modified, but next_out and avail_out are unchanged.)
 545 */
 546
 547 extern int EXPORT inflateSetDictionary OF((z_streamp strm,
 548                                            const Bytef *dictionary,
 549                                            uInt  dictLength));
 550 /*
 551      Initializes the decompression dictionary from the given uncompressed byte
 552    sequence. This function must be called immediately after a call of inflate
 553    if this call returned Z_NEED_DICT. The dictionary chosen by the compressor
 554    can be determined from the Adler32 value returned by this call of
 555    inflate. The compressor and decompressor must use exactly the same
 556    dictionary (see deflateSetDictionary).
 557
 558      inflateSetDictionary returns Z_OK if success, Z_STREAM_ERROR if a
 559    parameter is invalid (such as NULL dictionary) or the stream state is
 560    inconsistent, Z_DATA_ERROR if the given dictionary doesn't match the
 561    expected one (incorrect Adler32 value). inflateSetDictionary does not
 562    perform any decompression: this will be done by subsequent calls of
 563    inflate().
 564 */
 565
 566 extern int EXPORT inflateSync OF((z_streamp strm));
 567 /*
 568     Skips invalid compressed data until a full flush point (see above the
 569   description of deflate with Z_FULL_FLUSH) can be found, or until all
 570   available input is skipped. No output is provided.
 571
 572     inflateSync returns Z_OK if a full flush point has been found, Z_BUF_ERROR
 573   if no more input was provided, Z_DATA_ERROR if no flush point has been found,
 574   or Z_STREAM_ERROR if the stream structure was inconsistent. In the success
 575   case, the application may save the current current value of total_in which
 576   indicates where valid compressed data was found. In the error case, the
 577   application may repeatedly call inflateSync, providing more input each time,
 578   until success or end of the input data.
 579 */
 580
 581 extern int EXPORT inflateReset OF((z_streamp strm));
 582 /*
 583      This function is equivalent to inflateEnd followed by inflateInit,
 584    but does not free and reallocate all the internal decompression state.
 585    The stream will keep attributes that may have been set by inflateInit2.
 586
 587       inflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source
 588    stream state was inconsistent (such as zalloc or state being NULL).
 589 */
 590
 591
 592                         /* utility functions */
 593
 594 /*
 595      The following utility functions are implemented on top of the
 596    basic stream-oriented functions. To simplify the interface, some
 597    default options are assumed (compression level and memory usage,
 598    standard memory allocation functions). The source code of these
 599    utility functions can easily be modified if you need special options.
 600 */
 601
 602 extern int EXPORT compress OF((Bytef *dest,   uLongf *destLen,
 603                                const Bytef *source, uLong sourceLen));
 604 /*
 605      Compresses the source buffer into the destination buffer.  sourceLen is
 606    the byte length of the source buffer. Upon entry, destLen is the total
 607    size of the destination buffer, which must be at least 0.1% larger than
 608    sourceLen plus 12 bytes. Upon exit, destLen is the actual size of the
 609    compressed buffer.
 610      This function can be used to compress a whole file at once if the
 611    input file is mmap'ed.
 612      compress returns Z_OK if success, Z_MEM_ERROR if there was not
 613    enough memory, Z_BUF_ERROR if there was not enough room in the output
 614    buffer.
 615 */
 616
 617 extern int EXPORT compress2 OF((Bytef *dest,   uLongf *destLen,
 618                                 const Bytef *source, uLong sourceLen,
 619                                 int level));
 620 /*
 621      Compresses the source buffer into the destination buffer. The level
 622    parameter has the same meaning as in deflateInit.  sourceLen is the byte
 623    length of the source buffer. Upon entry, destLen is the total size of the
 624    destination buffer, which must be at least 0.1% larger than sourceLen plus
 625    12 bytes. Upon exit, destLen is the actual size of the compressed buffer.
 626
 627      compress2 returns Z_OK if success, Z_MEM_ERROR if there was not enough
 628    memory, Z_BUF_ERROR if there was not enough room in the output buffer,
 629    Z_STREAM_ERROR if the level parameter is invalid.
 630 */
 631
 632 extern int EXPORT uncompress OF((Bytef *dest,   uLongf *destLen,
 633                                  const Bytef *source, uLong sourceLen));
 634 /*
 635      Decompresses the source buffer into the destination buffer.  sourceLen is
 636    the byte length of the source buffer. Upon entry, destLen is the total
 637    size of the destination buffer, which must be large enough to hold the
 638    entire uncompressed data. (The size of the uncompressed data must have
 639    been saved previously by the compressor and transmitted to the decompressor
 640    by some mechanism outside the scope of this compression library.)
 641    Upon exit, destLen is the actual size of the compressed buffer.
 642      This function can be used to decompress a whole file at once if the
 643    input file is mmap'ed.
 644
 645      uncompress returns Z_OK if success, Z_MEM_ERROR if there was not
 646    enough memory, Z_BUF_ERROR if there was not enough room in the output
 647    buffer, or Z_DATA_ERROR if the input data was corrupted.
 648 */
 649
 650
 651 typedef voidp gzFile;
 652
 653 extern gzFile EXPORT gzopen  OF((const char *path, const char *mode));
 654 /*
 655      Opens a gzip (.gz) file for reading or writing. The mode parameter
 656    is as in fopen ("rb" or "wb") but can also include a compression level
 657    ("wb9") or a strategy: 'f' for filtered data as in "wb6f", 'h' for
 658    Huffman only compression as in "wb1h". (See the description
 659    of deflateInit2 for more information about the strategy parameter.)
 660
 661      gzopen can be used to read a file which is not in gzip format; in this
 662    case gzread will directly read from the file without decompression.
 663
 664      gzopen returns NULL if the file could not be opened or if there was
 665    insufficient memory to allocate the (de)compression state; errno
 666    can be checked to distinguish the two cases (if errno is zero, the
 667    zlib error is Z_MEM_ERROR).  */
 668
 669 extern gzFile EXPORT gzdopen  OF((int fd, const char *mode));
 670 /*
 671      gzdopen() associates a gzFile with the file descriptor fd.  File
 672    descriptors are obtained from calls like open, dup, creat, pipe or
 673    fileno (in the file has been previously opened with fopen).
 674    The mode parameter is as in gzopen.
 675      The next call of gzclose on the returned gzFile will also close the
 676    file descriptor fd, just like fclose(fdopen(fd), mode) closes the file
 677    descriptor fd. If you want to keep fd open, use gzdopen(dup(fd), mode).
 678      gzdopen returns NULL if there was insufficient memory to allocate
 679    the (de)compression state.
 680 */
 681
 682 extern int EXPORT gzsetparams OF((gzFile file, int level, int strategy));
 683 /*
 684      Dynamically update the compression level or strategy. See the description
 685    of deflateInit2 for the meaning of these parameters.
 686      gzsetparams returns Z_OK if success, or Z_STREAM_ERROR if the file was not
 687    opened for writing.
 688 */
 689
 690 extern int EXPORT    gzread  OF((gzFile file, voidp buf, unsigned len));
 691 /*
 692      Reads the given number of uncompressed bytes from the compressed file.
 693    If the input file was not in gzip format, gzread copies the given number
 694    of bytes into the buffer.
 695      gzread returns the number of uncompressed bytes actually read (0 for
 696    end of file, -1 for error). */
 697
 698 extern int EXPORT    gzwrite OF((gzFile file, const voidp buf, unsigned len));
 699 /*
 700      Writes the given number of uncompressed bytes into the compressed file.
 701    gzwrite returns the number of uncompressed bytes actually written
 702    (0 in case of error).
 703 */
 704
 705 extern int EXPORTVA   gzprintf OF((gzFile file, const char *format, ...));
 706 /*
 707      Converts, formats, and writes the args to the compressed file under
 708    control of the format string, as in fprintf. gzprintf returns the number of
 709    uncompressed bytes actually written (0 in case of error).
 710 */
 711
 712 extern int EXPORT    gzputc OF((gzFile file, int c));
 713 /*
 714       Writes c, converted to an unsigned char, into the compressed file.
 715    gzputc returns the value that was written, or -1 in case of error.
 716 */
 717
 718 extern int EXPORT    gzgetc OF((gzFile file));
 719 /*
 720       Reads one byte from the compressed file. gzgetc returns this byte
 721    or -1 in case of end of file or error.
 722 */
 723
 724 extern int EXPORT    gzflush OF((gzFile file, int flush));
 725 /*
 726      Flushes all pending output into the compressed file. The parameter
 727    flush is as in the deflate() function. The return value is the zlib
 728    error number (see function gzerror below). gzflush returns Z_OK if
 729    the flush parameter is Z_FINISH and all output could be flushed.
 730      gzflush should be called only when strictly necessary because it can
 731    degrade compression.
 732 */
 733
 734 extern z_off_t EXPORT    gzseek OF((gzFile file, z_off_t offset, int whence));
 735 /*
 736       Sets the starting position for the next gzread or gzwrite on the given
 737    compressed file. The offset represents a number of bytes in the
 738    uncompressed data stream. The whence parameter is defined as in lseek(2);
 739    the value SEEK_END is not supported.
 740      If the file is opened for reading, this function is emulated but can be
 741    extremely slow. If the file is opened for writing, only forward seeks are
 742    supported; gzseek then compresses a sequence of zeroes up to the new
 743    starting position.
 744
 745       gzseek returns the resulting offset location as measured in bytes from
 746    the beginning of the uncompressed stream, or -1 in case of error, in
 747    particular if the file is opened for writing and the new starting position
 748    would be before the current position.
 749 */
 750
 751 extern int EXPORT    gzrewind OF((gzFile file));
 752 /*
 753      Rewinds the given file. This function is supported only for reading.
 754
 755    gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET)
 756 */
 757
 758 extern z_off_t EXPORT    gztell OF((gzFile file));
 759 /*
 760      Returns the starting position for the next gzread or gzwrite on the
 761    given compressed file. This position represents a number of bytes in the
 762    uncompressed data stream.
 763
 764    gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR)
 765 */
 766
 767 extern int EXPORT gzeof OF((gzFile file));
 768 /*
 769      Returns 1 when EOF has previously been detected reading the given
 770    input stream, otherwise zero.
 771 */
 772
 773 extern int EXPORT    gzclose OF((gzFile file));
 774 /*
 775      Flushes all pending output if necessary, closes the compressed file
 776    and deallocates all the (de)compression state. The return value is the zlib
 777    error number (see function gzerror below).
 778 */
 779
 780 extern const char * EXPORT gzerror OF((gzFile file, int *errnum));
 781 /*
 782      Returns the error message for the last error which occurred on the
 783    given compressed file. errnum is set to zlib error number. If an
 784    error occurred in the file system and not in the compression library,
 785    errnum is set to Z_ERRNO and the application may consult errno
 786    to get the exact error code.
 787 */
 788
 789                         /* checksum functions */
 790
 791 /*
 792      These functions are not related to compression but are exported
 793    anyway because they might be useful in applications using the
 794    compression library.
 795 */
 796
 797 extern uLong EXPORT adler32 OF((uLong adler, const Bytef *buf, uInt len));
 798
 799 /*
 800      Update a running Adler-32 checksum with the bytes buf[0..len-1] and
 801    return the updated checksum. If buf is NULL, this function returns
 802    the required initial value for the checksum.
 803    An Adler-32 checksum is almost as reliable as a CRC32 but can be computed
 804    much faster. Usage example:
 805
 806      uLong adler = adler32(0L, Z_NULL, 0);
 807
 808      while (read_buffer(buffer, length) != EOF) {
 809        adler = adler32(adler, buffer, length);
 810      }
 811      if (adler != original_adler) error();
 812 */
 813
 814 extern uLong EXPORT crc32   OF((uLong crc, const Bytef *buf, uInt len));
 815 /*
 816      Update a running crc with the bytes buf[0..len-1] and return the updated
 817    crc. If buf is NULL, this function returns the required initial value
 818    for the crc. Pre- and post-conditioning (one's complement) is performed
 819    within this function so it shouldn't be done by the application.
 820    Usage example:
 821
 822      uLong crc = crc32(0L, Z_NULL, 0);
 823
 824      while (read_buffer(buffer, length) != EOF) {
 825        crc = crc32(crc, buffer, length);
 826      }
 827      if (crc != original_crc) error();
 828 */
 829
 830
 831                         /* various hacks, don't look :) */
 832
 833 /* deflateInit and inflateInit are macros to allow checking the zlib version
 834  * and the compiler's view of z_stream:
 835  */
 836 extern int EXPORT deflateInit_ OF((z_streamp strm, int level,
 837                                    const char *version, int stream_size));
 838 extern int EXPORT inflateInit_ OF((z_streamp strm,
 839                                    const char *version, int stream_size));
 840 extern int EXPORT deflateInit2_ OF((z_streamp strm, int  level, int  method,
 841                                     int windowBits, int memLevel, int strategy,
 842                                     const char *version, int stream_size));
 843 extern int EXPORT inflateInit2_ OF((z_streamp strm, int  windowBits,
 844                                     const char *version, int stream_size));
 845 #define deflateInit(strm, level) \
 846         deflateInit_((strm), (level),       ZLIB_VERSION, sizeof(z_stream))
 847 #define inflateInit(strm) \
 848         inflateInit_((strm),                ZLIB_VERSION, sizeof(z_stream))
 849 #define deflateInit2(strm, level, method, windowBits, memLevel, strategy) \
 850         deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\
 851                       (strategy),           ZLIB_VERSION, sizeof(z_stream))
 852 #define inflateInit2(strm, windowBits) \
 853         inflateInit2_((strm), (windowBits), ZLIB_VERSION, sizeof(z_stream))
 854
 855
 856 #if !defined(_Z_UTIL_H) && !defined(NO_DUMMY_DECL)
 857     struct internal_state {int dummy;}; /* hack for buggy compilers */
 858 #endif
 859
 860 extern const char   * EXPORT zError           OF((int err));
 861 extern int            EXPORT inflateSyncPoint OF((z_streamp z));
 862 extern const uLongf * EXPORT get_crc_table    OF((void));
 863
 864 #ifdef __cplusplus
 865 }
 866 #endif
 867
 868 #endif /* _ZLIB_H */