diff options
Diffstat (limited to 'zlib.h')
-rw-r--r-- | zlib.h | 363 |
1 files changed, 218 insertions, 145 deletions
@@ -1,5 +1,5 @@ | |||
1 | /* zlib.h -- interface of the 'zlib' general purpose compression library | 1 | /* zlib.h -- interface of the 'zlib' general purpose compression library |
2 | version 1.0.5, Jan 3rd, 1998. | 2 | version 1.0.7, Jan 20th, 1998 |
3 | 3 | ||
4 | Copyright (C) 1995-1998 Jean-loup Gailly and Mark Adler | 4 | Copyright (C) 1995-1998 Jean-loup Gailly and Mark Adler |
5 | 5 | ||
@@ -20,7 +20,7 @@ | |||
20 | 3. This notice may not be removed or altered from any source distribution. | 20 | 3. This notice may not be removed or altered from any source distribution. |
21 | 21 | ||
22 | Jean-loup Gailly Mark Adler | 22 | Jean-loup Gailly Mark Adler |
23 | gzip@prep.ai.mit.edu madler@alumni.caltech.edu | 23 | jloup@gzip.org madler@alumni.caltech.edu |
24 | 24 | ||
25 | 25 | ||
26 | The data format used by the zlib library is described by RFCs (Request for | 26 | The data format used by the zlib library is described by RFCs (Request for |
@@ -37,30 +37,27 @@ extern "C" { | |||
37 | 37 | ||
38 | #include "zconf.h" | 38 | #include "zconf.h" |
39 | 39 | ||
40 | #define ZLIB_VERSION "1.0.5" | 40 | #define ZLIB_VERSION "1.0.7" |
41 | 41 | ||
42 | /* | 42 | /* |
43 | The 'zlib' compression library provides in-memory compression and | 43 | The 'zlib' compression library provides in-memory compression and |
44 | decompression functions, including integrity checks of the uncompressed | 44 | decompression functions, including integrity checks of the uncompressed |
45 | data. This version of the library supports only one compression method | 45 | data. This version of the library supports only one compression method |
46 | (deflation) but other algorithms may be added later and will have the same | 46 | (deflation) but other algorithms will be added later and will have the same |
47 | stream interface. | 47 | stream interface. |
48 | 48 | ||
49 | For compression the application must provide the output buffer and | ||
50 | may optionally provide the input buffer for optimization. For decompression, | ||
51 | the application must provide the input buffer and may optionally provide | ||
52 | the output buffer for optimization. | ||
53 | |||
54 | Compression can be done in a single step if the buffers are large | 49 | Compression can be done in a single step if the buffers are large |
55 | enough (for example if an input file is mmap'ed), or can be done by | 50 | enough (for example if an input file is mmap'ed), or can be done by |
56 | repeated calls of the compression function. In the latter case, the | 51 | repeated calls of the compression function. In the latter case, the |
57 | application must provide more input and/or consume the output | 52 | application must provide more input and/or consume the output |
58 | (providing more output space) before each call. | 53 | (providing more output space) before each call. |
59 | 54 | ||
60 | The library does not install any signal handler. It is recommended to | 55 | The library also supports reading and writing files in gzip (.gz) format |
61 | add at least a handler for SIGSEGV when decompressing; the library checks | 56 | with an interface similar to that of stdio. |
62 | the consistency of the input data whenever possible but may go nuts | 57 | |
63 | for some forms of corrupted input. | 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. | ||
64 | */ | 61 | */ |
65 | 62 | ||
66 | typedef voidpf (*alloc_func) OF((voidpf opaque, uInt items, uInt size)); | 63 | typedef voidpf (*alloc_func) OF((voidpf opaque, uInt items, uInt size)); |
@@ -123,7 +120,7 @@ typedef z_stream FAR *z_streamp; | |||
123 | /* constants */ | 120 | /* constants */ |
124 | 121 | ||
125 | #define Z_NO_FLUSH 0 | 122 | #define Z_NO_FLUSH 0 |
126 | #define Z_PARTIAL_FLUSH 1 | 123 | #define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */ |
127 | #define Z_SYNC_FLUSH 2 | 124 | #define Z_SYNC_FLUSH 2 |
128 | #define Z_FULL_FLUSH 3 | 125 | #define Z_FULL_FLUSH 3 |
129 | #define Z_FINISH 4 | 126 | #define Z_FINISH 4 |
@@ -200,7 +197,13 @@ extern int EXPORT deflateInit OF((z_streamp strm, int level)); | |||
200 | 197 | ||
201 | extern int EXPORT deflate OF((z_streamp strm, int flush)); | 198 | extern int EXPORT deflate OF((z_streamp strm, int flush)); |
202 | /* | 199 | /* |
203 | Performs one or both of the following actions: | 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: | ||
204 | 207 | ||
205 | - Compress more input starting at next_in and update next_in and avail_in | 208 | - Compress more input starting at next_in and update next_in and avail_in |
206 | accordingly. If not all input can be processed (because there is not | 209 | accordingly. If not all input can be processed (because there is not |
@@ -222,24 +225,23 @@ extern int EXPORT deflate OF((z_streamp strm, int flush)); | |||
222 | and with zero avail_out, it must be called again after making room in the | 225 | and with zero avail_out, it must be called again after making room in the |
223 | output buffer because there might be more output pending. | 226 | output buffer because there might be more output pending. |
224 | 227 | ||
225 | If the parameter flush is set to Z_PARTIAL_FLUSH, the current compression | 228 | If the parameter flush is set to Z_SYNC_FLUSH, all pending output is |
226 | block is terminated and flushed to the output buffer so that the | 229 | flushed to the output buffer and the output is aligned on a byte boundary, so |
227 | decompressor can get all input data available so far. For method 9, a future | 230 | that the decompressor can get all input data available so far. (In particular |
228 | variant on method 8, the current block will be flushed but not terminated. | 231 | avail_in is zero after the call if enough output space has been provided |
229 | Z_SYNC_FLUSH has the same effect as partial flush except that the compressed | 232 | before the call.) Flushing may degrade compression for some compression |
230 | output is byte aligned (the compressor can clear its internal bit buffer) | 233 | algorithms and so it should be used only when necessary. |
231 | and the current block is always terminated; this can be useful if the | 234 | |
232 | compressor has to be restarted from scratch after an interruption (in which | 235 | If flush is set to Z_FULL_FLUSH, all output is flushed as with |
233 | case the internal state of the compressor may be lost). | 236 | Z_SYNC_FLUSH, and the compression state is reset so that decompression can |
234 | If flush is set to Z_FULL_FLUSH, the compression block is terminated, a | 237 | restart from this point if previous compressed data has been damaged or if |
235 | special marker is output and the compression dictionary is discarded; this | 238 | random access is desired. Using Z_FULL_FLUSH too often can seriously degrade |
236 | is useful to allow the decompressor to synchronize if one compressed block | 239 | the compression. |
237 | has been damaged (see inflateSync below). Flushing degrades compression and | 240 | |
238 | so should be used only when necessary. Using Z_FULL_FLUSH too often can | 241 | If deflate returns with avail_out == 0, this function must be called again |
239 | seriously degrade the compression. If deflate returns with avail_out == 0, | 242 | with the same value of the flush parameter and more output space (updated |
240 | this function must be called again with the same value of the flush | 243 | avail_out), until the flush is complete (deflate returns with non-zero |
241 | parameter and more output space (updated avail_out), until the flush is | 244 | avail_out). |
242 | complete (deflate returns with non-zero avail_out). | ||
243 | 245 | ||
244 | If the parameter flush is set to Z_FINISH, pending input is processed, | 246 | If the parameter flush is set to Z_FINISH, pending input is processed, |
245 | pending output is flushed and deflate returns with Z_STREAM_END if there | 247 | pending output is flushed and deflate returns with Z_STREAM_END if there |
@@ -254,6 +256,9 @@ extern int EXPORT deflate OF((z_streamp strm, int flush)); | |||
254 | 0.1% larger than avail_in plus 12 bytes. If deflate does not return | 256 | 0.1% larger than avail_in plus 12 bytes. If deflate does not return |
255 | Z_STREAM_END, then it must be called again as described above. | 257 | Z_STREAM_END, then it must be called again as described above. |
256 | 258 | ||
259 | deflate() sets strm->adler to the adler32 checksum of all input read | ||
260 | so far (that is, total_in bytes). | ||
261 | |||
257 | deflate() may update data_type if it can make a good guess about | 262 | deflate() may update data_type if it can make a good guess about |
258 | the input data type (Z_ASCII or Z_BINARY). In doubt, the data is considered | 263 | the input data type (Z_ASCII or Z_BINARY). In doubt, the data is considered |
259 | binary. This field is only for information purposes and does not affect | 264 | binary. This field is only for information purposes and does not affect |
@@ -285,21 +290,32 @@ extern int EXPORT deflateEnd OF((z_streamp strm)); | |||
285 | extern int EXPORT inflateInit OF((z_streamp strm)); | 290 | extern int EXPORT inflateInit OF((z_streamp strm)); |
286 | 291 | ||
287 | Initializes the internal stream state for decompression. The fields | 292 | Initializes the internal stream state for decompression. The fields |
288 | zalloc, zfree and opaque must be initialized before by the caller. If | 293 | next_in, avail_in, zalloc, zfree and opaque must be initialized before by |
289 | zalloc and zfree are set to Z_NULL, inflateInit updates them to use default | 294 | the caller. If next_in is not Z_NULL and avail_in is large enough (the exact |
290 | allocation functions. | 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. | ||
291 | 300 | ||
292 | inflateInit returns Z_OK if success, Z_MEM_ERROR if there was not | 301 | inflateInit returns Z_OK if success, Z_MEM_ERROR if there was not enough |
293 | enough memory, Z_VERSION_ERROR if the zlib library version is incompatible | 302 | memory, Z_VERSION_ERROR if the zlib library version is incompatible with the |
294 | with the version assumed by the caller. msg is set to null if there is no | 303 | version assumed by the caller. msg is set to null if there is no error |
295 | error message. inflateInit does not perform any decompression: this will be | 304 | message. inflateInit does not perform any decompression apart from reading |
296 | done by inflate(). | 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.) | ||
297 | */ | 307 | */ |
298 | 308 | ||
299 | 309 | ||
300 | extern int EXPORT inflate OF((z_streamp strm, int flush)); | 310 | extern int EXPORT inflate OF((z_streamp strm, int flush)); |
301 | /* | 311 | /* |
302 | Performs one or both of the following actions: | 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: | ||
303 | 319 | ||
304 | - Decompress more input starting at next_in and update next_in and avail_in | 320 | - Decompress more input starting at next_in and update next_in and avail_in |
305 | accordingly. If not all input can be processed (because there is not | 321 | accordingly. If not all input can be processed (because there is not |
@@ -320,9 +336,9 @@ extern int EXPORT inflate OF((z_streamp strm, int flush)); | |||
320 | must be called again after making room in the output buffer because there | 336 | must be called again after making room in the output buffer because there |
321 | might be more output pending. | 337 | might be more output pending. |
322 | 338 | ||
323 | If the parameter flush is set to Z_PARTIAL_FLUSH, inflate flushes as much | 339 | If the parameter flush is set to Z_SYNC_FLUSH, inflate flushes as much |
324 | output as possible to the output buffer. The flushing behavior of inflate is | 340 | output as possible to the output buffer. The flushing behavior of inflate is |
325 | not specified for values of the flush parameter other than Z_PARTIAL_FLUSH | 341 | not specified for values of the flush parameter other than Z_SYNC_FLUSH |
326 | and Z_FINISH, but the current implementation actually flushes as much output | 342 | and Z_FINISH, but the current implementation actually flushes as much output |
327 | as possible anyway. | 343 | as possible anyway. |
328 | 344 | ||
@@ -337,18 +353,26 @@ extern int EXPORT inflate OF((z_streamp strm, int flush)); | |||
337 | is never required, but can be used to inform inflate that a faster routine | 353 | is never required, but can be used to inform inflate that a faster routine |
338 | may be used for the single inflate() call. | 354 | may be used for the single inflate() call. |
339 | 355 | ||
340 | inflate() returns Z_OK if some progress has been made (more input | 356 | If a preset dictionary is needed at this point (see inflateSetDictionary |
341 | processed or more output produced), Z_STREAM_END if the end of the | 357 | below), inflate sets strm-adler to the adler32 checksum of the |
342 | compressed data has been reached and all uncompressed output has been | 358 | dictionary chosen by the compressor and returns Z_NEED_DICT; otherwise |
343 | produced, Z_NEED_DICT if a preset dictionary is needed at this point (see | 359 | it sets strm->adler to the adler32 checksum of all output produced |
344 | inflateSetDictionary below), Z_DATA_ERROR if the input data was corrupted, | 360 | so far (that is, total_out bytes) and returns Z_OK, Z_STREAM_END or |
345 | Z_STREAM_ERROR if the stream structure was inconsistent (for example if | 361 | an error code as described below. At the end of the stream, inflate() |
346 | next_in or next_out was NULL), Z_MEM_ERROR if there was not enough memory, | 362 | checks that its computed adler32 checksum is equal to that saved by the |
347 | Z_BUF_ERROR if no progress is possible or if there was not enough room in | 363 | compressor and returns Z_STREAM_END only if the checksum is correct. |
348 | the output buffer when Z_FINISH is used. In the Z_DATA_ERROR case, the | 364 | |
349 | application may then call inflateSync to look for a good compression block. | 365 | inflate() returns Z_OK if some progress has been made (more input processed |
350 | In the Z_NEED_DICT case, strm->adler is set to the Adler32 value of the | 366 | or more output produced), Z_STREAM_END if the end of the compressed data has |
351 | dictionary chosen by the compressor. | 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. | ||
352 | */ | 376 | */ |
353 | 377 | ||
354 | 378 | ||
@@ -382,14 +406,13 @@ extern int EXPORT deflateInit2 OF((z_streamp strm, | |||
382 | the caller. | 406 | the caller. |
383 | 407 | ||
384 | The method parameter is the compression method. It must be Z_DEFLATED in | 408 | The method parameter is the compression method. It must be Z_DEFLATED in |
385 | this version of the library. (Method 9 will allow a 64K history buffer and | 409 | this version of the library. |
386 | partial block flushes.) | ||
387 | 410 | ||
388 | The windowBits parameter is the base two logarithm of the window size | 411 | The windowBits parameter is the base two logarithm of the window size |
389 | (the size of the history buffer). It should be in the range 8..15 for this | 412 | (the size of the history buffer). It should be in the range 8..15 for this |
390 | version of the library (the value 16 will be allowed for method 9). Larger | 413 | version of the library. Larger values of this parameter result in better |
391 | values of this parameter result in better compression at the expense of | 414 | compression at the expense of memory usage. The default value is 15 if |
392 | memory usage. The default value is 15 if deflateInit is used instead. | 415 | deflateInit is used instead. |
393 | 416 | ||
394 | The memLevel parameter specifies how much memory should be allocated | 417 | The memLevel parameter specifies how much memory should be allocated |
395 | for the internal compression state. memLevel=1 uses minimum memory but | 418 | for the internal compression state. memLevel=1 uses minimum memory but |
@@ -408,42 +431,35 @@ extern int EXPORT deflateInit2 OF((z_streamp strm, | |||
408 | the compression ratio but not the correctness of the compressed output even | 431 | the compression ratio but not the correctness of the compressed output even |
409 | if it is not set appropriately. | 432 | if it is not set appropriately. |
410 | 433 | ||
411 | If next_in is not null, the library will use this buffer to hold also | 434 | deflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough |
412 | some history information; the buffer must either hold the entire input | 435 | memory, Z_STREAM_ERROR if a parameter is invalid (such as an invalid |
413 | data, or have at least 1<<(windowBits+1) bytes and be writable. If next_in | 436 | method). msg is set to null if there is no error message. deflateInit2 does |
414 | is null, the library will allocate its own history buffer (and leave next_in | 437 | not perform any compression: this will be done by deflate(). |
415 | null). next_out need not be provided here but must be provided by the | ||
416 | application for the next call of deflate(). | ||
417 | |||
418 | If the history buffer is provided by the application, next_in must | ||
419 | must never be changed by the application since the compressor maintains | ||
420 | information inside this buffer from call to call; the application | ||
421 | must provide more input only by increasing avail_in. next_in is always | ||
422 | reset by the library in this case. | ||
423 | |||
424 | deflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was | ||
425 | not enough memory, Z_STREAM_ERROR if a parameter is invalid (such as | ||
426 | an invalid method). msg is set to null if there is no error message. | ||
427 | deflateInit2 does not perform any compression: this will be done by | ||
428 | deflate(). | ||
429 | */ | 438 | */ |
430 | 439 | ||
431 | extern int EXPORT deflateSetDictionary OF((z_streamp strm, | 440 | extern int EXPORT deflateSetDictionary OF((z_streamp strm, |
432 | const Bytef *dictionary, | 441 | const Bytef *dictionary, |
433 | uInt dictLength)); | 442 | uInt dictLength)); |
434 | /* | 443 | /* |
435 | Initializes the compression dictionary (history buffer) from the given | 444 | Initializes the compression dictionary from the given byte sequence |
436 | byte sequence without producing any compressed output. This function must | 445 | without producing any compressed output. This function must be called |
437 | be called immediately after deflateInit or deflateInit2, before any call | 446 | immediately after deflateInit or deflateInit2, before any call of |
438 | of deflate. The compressor and decompressor must use exactly the same | 447 | deflate. The compressor and decompressor must use exactly the same |
439 | dictionary (see inflateSetDictionary). | 448 | dictionary (see inflateSetDictionary). |
449 | |||
440 | The dictionary should consist of strings (byte sequences) that are likely | 450 | The dictionary should consist of strings (byte sequences) that are likely |
441 | to be encountered later in the data to be compressed, with the most commonly | 451 | to be encountered later in the data to be compressed, with the most commonly |
442 | used strings preferably put towards the end of the dictionary. Using a | 452 | used strings preferably put towards the end of the dictionary. Using a |
443 | dictionary is most useful when the data to be compressed is short and | 453 | dictionary is most useful when the data to be compressed is short and can be |
444 | can be predicted with good accuracy; the data can then be compressed better | 454 | predicted with good accuracy; the data can then be compressed better than |
445 | than with the default empty dictionary. In this version of the library, | 455 | with the default empty dictionary. |
446 | only the last 32K bytes of the dictionary are used. | 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 | |||
447 | Upon return of this function, strm->adler is set to the Adler32 value | 463 | Upon return of this function, strm->adler is set to the Adler32 value |
448 | of the dictionary; the decompressor may later use this value to determine | 464 | of the dictionary; the decompressor may later use this value to determine |
449 | which dictionary has been used by the compressor. (The Adler32 value | 465 | which dictionary has been used by the compressor. (The Adler32 value |
@@ -451,21 +467,16 @@ extern int EXPORT deflateSetDictionary OF((z_streamp strm, | |||
451 | actually used by the compressor.) | 467 | actually used by the compressor.) |
452 | 468 | ||
453 | deflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a | 469 | deflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a |
454 | parameter is invalid (such as NULL dictionary) or the stream state | 470 | parameter is invalid (such as NULL dictionary) or the stream state is |
455 | is inconsistent (for example if deflate has already been called for this | 471 | inconsistent (for example if deflate has already been called for this stream |
456 | stream). deflateSetDictionary does not perform any compression: this will | 472 | or if the compression method is bsort). deflateSetDictionary does not |
457 | be done by deflate(). | 473 | perform any compression: this will be done by deflate(). |
458 | */ | 474 | */ |
459 | 475 | ||
460 | extern int EXPORT deflateCopy OF((z_streamp dest, | 476 | extern int EXPORT deflateCopy OF((z_streamp dest, |
461 | z_streamp source)); | 477 | z_streamp source)); |
462 | /* | 478 | /* |
463 | Sets the destination stream as a complete copy of the source stream. If | 479 | Sets the destination stream as a complete copy of the source stream. |
464 | the source stream is using an application-supplied history buffer, a new | ||
465 | buffer is allocated for the destination stream. The compressed output | ||
466 | buffer is always application-supplied. It's the responsibility of the | ||
467 | application to provide the correct values of next_out and avail_out for the | ||
468 | next call of deflate. | ||
469 | 480 | ||
470 | This function can be useful when several compression strategies will be | 481 | This function can be useful when several compression strategies will be |
471 | tried, for example when there are several ways of pre-processing the input | 482 | tried, for example when there are several ways of pre-processing the input |
@@ -493,12 +504,13 @@ extern int EXPORT deflateReset OF((z_streamp strm)); | |||
493 | 504 | ||
494 | extern int EXPORT deflateParams OF((z_streamp strm, int level, int strategy)); | 505 | extern int EXPORT deflateParams OF((z_streamp strm, int level, int strategy)); |
495 | /* | 506 | /* |
496 | Dynamically update the compression level and compression strategy. | 507 | Dynamically update the compression level and compression strategy. The |
497 | This can be used to switch between compression and straight copy of | 508 | interpretation of level and strategy is as in deflateInit2. This can be |
498 | the input data, or to switch to a different kind of input data requiring | 509 | used to switch between compression and straight copy of the input data, or |
499 | a different strategy. If the compression level is changed, the input | 510 | to switch to a different kind of input data requiring a different |
500 | available so far is compressed with the old level (and may be flushed); | 511 | strategy. If the compression level is changed, the input available so far |
501 | the new level will take effect only at the next call of deflate(). | 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(). | ||
502 | 514 | ||
503 | Before the call of deflateParams, the stream state must be set as for | 515 | Before the call of deflateParams, the stream state must be set as for |
504 | a call of deflate(), since the currently available input may have to | 516 | a call of deflate(), since the currently available input may have to |
@@ -513,46 +525,34 @@ extern int EXPORT deflateParams OF((z_streamp strm, int level, int strategy)); | |||
513 | extern int EXPORT inflateInit2 OF((z_streamp strm, | 525 | extern int EXPORT inflateInit2 OF((z_streamp strm, |
514 | int windowBits)); | 526 | int windowBits)); |
515 | 527 | ||
516 | This is another version of inflateInit with more compression options. The | 528 | This is another version of inflateInit with an extra parameter. The |
517 | fields next_out, zalloc, zfree and opaque must be initialized before by | 529 | fields next_in, avail_in, zalloc, zfree and opaque must be initialized |
518 | the caller. | 530 | before by the caller. |
519 | 531 | ||
520 | The windowBits parameter is the base two logarithm of the maximum window | 532 | The windowBits parameter is the base two logarithm of the maximum window |
521 | size (the size of the history buffer). It should be in the range 8..15 for | 533 | size (the size of the history buffer). It should be in the range 8..15 for |
522 | this version of the library (the value 16 will be allowed soon). The | 534 | this version of the library. The default value is 15 if inflateInit is used |
523 | default value is 15 if inflateInit is used instead. If a compressed stream | 535 | instead. If a compressed stream with a larger window size is given as |
524 | with a larger window size is given as input, inflate() will return with | 536 | input, inflate() will return with the error code Z_DATA_ERROR instead of |
525 | the error code Z_DATA_ERROR instead of trying to allocate a larger window. | 537 | trying to allocate a larger window. |
526 | 538 | ||
527 | If next_out is not null, the library will use this buffer for the history | 539 | inflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough |
528 | buffer; the buffer must either be large enough to hold the entire output | 540 | memory, Z_STREAM_ERROR if a parameter is invalid (such as a negative |
529 | data, or have at least 1<<windowBits bytes. If next_out is null, the | 541 | memLevel). msg is set to null if there is no error message. inflateInit2 |
530 | library will allocate its own buffer (and leave next_out null). next_in | 542 | does not perform any decompression apart from reading the zlib header if |
531 | need not be provided here but must be provided by the application for the | 543 | present: this will be done by inflate(). (So next_in and avail_in may be |
532 | next call of inflate(). | 544 | modified, but next_out and avail_out are unchanged.) |
533 | |||
534 | If the history buffer is provided by the application, next_out must | ||
535 | never be changed by the application since the decompressor maintains | ||
536 | history information inside this buffer from call to call; the application | ||
537 | can only reset next_out to the beginning of the history buffer when | ||
538 | avail_out is zero and all output has been consumed. | ||
539 | |||
540 | inflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was | ||
541 | not enough memory, Z_STREAM_ERROR if a parameter is invalid (such as | ||
542 | windowBits < 8). msg is set to null if there is no error message. | ||
543 | inflateInit2 does not perform any decompression: this will be done by | ||
544 | inflate(). | ||
545 | */ | 545 | */ |
546 | 546 | ||
547 | extern int EXPORT inflateSetDictionary OF((z_streamp strm, | 547 | extern int EXPORT inflateSetDictionary OF((z_streamp strm, |
548 | const Bytef *dictionary, | 548 | const Bytef *dictionary, |
549 | uInt dictLength)); | 549 | uInt dictLength)); |
550 | /* | 550 | /* |
551 | Initializes the decompression dictionary (history buffer) from the given | 551 | Initializes the decompression dictionary from the given uncompressed byte |
552 | uncompressed byte sequence. This function must be called immediately after | 552 | sequence. This function must be called immediately after a call of inflate |
553 | a call of inflate if this call returned Z_NEED_DICT. The dictionary chosen | 553 | if this call returned Z_NEED_DICT. The dictionary chosen by the compressor |
554 | by the compressor can be determined from the Adler32 value returned by this | 554 | can be determined from the Adler32 value returned by this call of |
555 | call of inflate. The compressor and decompressor must use exactly the same | 555 | inflate. The compressor and decompressor must use exactly the same |
556 | dictionary (see deflateSetDictionary). | 556 | dictionary (see deflateSetDictionary). |
557 | 557 | ||
558 | inflateSetDictionary returns Z_OK if success, Z_STREAM_ERROR if a | 558 | inflateSetDictionary returns Z_OK if success, Z_STREAM_ERROR if a |
@@ -565,12 +565,12 @@ extern int EXPORT inflateSetDictionary OF((z_streamp strm, | |||
565 | 565 | ||
566 | extern int EXPORT inflateSync OF((z_streamp strm)); | 566 | extern int EXPORT inflateSync OF((z_streamp strm)); |
567 | /* | 567 | /* |
568 | Skips invalid compressed data until the special marker (see deflate() | 568 | Skips invalid compressed data until a full flush point (see above the |
569 | above) can be found, or until all available input is skipped. No output | 569 | description of deflate with Z_FULL_FLUSH) can be found, or until all |
570 | is provided. | 570 | available input is skipped. No output is provided. |
571 | 571 | ||
572 | inflateSync returns Z_OK if the special marker has been found, Z_BUF_ERROR | 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 marker has been found, | 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 | 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 | 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 | 576 | indicates where valid compressed data was found. In the error case, the |
@@ -594,7 +594,7 @@ extern int EXPORT inflateReset OF((z_streamp strm)); | |||
594 | /* | 594 | /* |
595 | The following utility functions are implemented on top of the | 595 | The following utility functions are implemented on top of the |
596 | basic stream-oriented functions. To simplify the interface, some | 596 | basic stream-oriented functions. To simplify the interface, some |
597 | default options are assumed (compression level, window size, | 597 | default options are assumed (compression level and memory usage, |
598 | standard memory allocation functions). The source code of these | 598 | standard memory allocation functions). The source code of these |
599 | utility functions can easily be modified if you need special options. | 599 | utility functions can easily be modified if you need special options. |
600 | */ | 600 | */ |
@@ -639,13 +639,17 @@ extern gzFile EXPORT gzopen OF((const char *path, const char *mode)); | |||
639 | /* | 639 | /* |
640 | Opens a gzip (.gz) file for reading or writing. The mode parameter | 640 | Opens a gzip (.gz) file for reading or writing. The mode parameter |
641 | is as in fopen ("rb" or "wb") but can also include a compression level | 641 | is as in fopen ("rb" or "wb") but can also include a compression level |
642 | ("wb9"). gzopen can be used to read a file which is not in gzip format; | 642 | ("wb9") or a strategy: 'f' for filtered data as in "wb6f", 'h' for |
643 | in this case gzread will directly read from the file without decompression. | 643 | Huffman only compression as in "wb1h". (See the description |
644 | of deflateInit2 for more information about the strategy parameter.) | ||
645 | |||
646 | gzopen can be used to read a file which is not in gzip format; in this | ||
647 | case gzread will directly read from the file without decompression. | ||
648 | |||
644 | gzopen returns NULL if the file could not be opened or if there was | 649 | gzopen returns NULL if the file could not be opened or if there was |
645 | insufficient memory to allocate the (de)compression state; errno | 650 | insufficient memory to allocate the (de)compression state; errno |
646 | can be checked to distinguish the two cases (if errno is zero, the | 651 | can be checked to distinguish the two cases (if errno is zero, the |
647 | zlib error is Z_MEM_ERROR). | 652 | zlib error is Z_MEM_ERROR). */ |
648 | */ | ||
649 | 653 | ||
650 | extern gzFile EXPORT gzdopen OF((int fd, const char *mode)); | 654 | extern gzFile EXPORT gzdopen OF((int fd, const char *mode)); |
651 | /* | 655 | /* |
@@ -660,6 +664,14 @@ extern gzFile EXPORT gzdopen OF((int fd, const char *mode)); | |||
660 | the (de)compression state. | 664 | the (de)compression state. |
661 | */ | 665 | */ |
662 | 666 | ||
667 | extern int EXPORT gzsetparams OF((gzFile file, int level, int strategy)); | ||
668 | /* | ||
669 | Dynamically update the compression level or strategy. See the description | ||
670 | of deflateInit2 for the meaning of these parameters. | ||
671 | gzsetparams returns Z_OK if success, or Z_STREAM_ERROR if the file was not | ||
672 | opened for writing. | ||
673 | */ | ||
674 | |||
663 | extern int EXPORT gzread OF((gzFile file, voidp buf, unsigned len)); | 675 | extern int EXPORT gzread OF((gzFile file, voidp buf, unsigned len)); |
664 | /* | 676 | /* |
665 | Reads the given number of uncompressed bytes from the compressed file. | 677 | Reads the given number of uncompressed bytes from the compressed file. |
@@ -675,6 +687,25 @@ extern int EXPORT gzwrite OF((gzFile file, const voidp buf, unsigned len)); | |||
675 | (0 in case of error). | 687 | (0 in case of error). |
676 | */ | 688 | */ |
677 | 689 | ||
690 | extern int EXPORTVA gzprintf OF((gzFile file, const char *format, ...)); | ||
691 | /* | ||
692 | Converts, formats, and writes the args to the compressed file under | ||
693 | control of the format string, as in fprintf. gzprintf returns the number of | ||
694 | uncompressed bytes actually written (0 in case of error). | ||
695 | */ | ||
696 | |||
697 | extern int EXPORT gzputc OF((gzFile file, int c)); | ||
698 | /* | ||
699 | Writes c, converted to an unsigned char, into the compressed file. | ||
700 | gzputc returns the value that was written, or -1 in case of error. | ||
701 | */ | ||
702 | |||
703 | extern int EXPORT gzgetc OF((gzFile file)); | ||
704 | /* | ||
705 | Reads one byte from the compressed file. gzgetc returns this byte | ||
706 | or -1 in case of end of file or error. | ||
707 | */ | ||
708 | |||
678 | extern int EXPORT gzflush OF((gzFile file, int flush)); | 709 | extern int EXPORT gzflush OF((gzFile file, int flush)); |
679 | /* | 710 | /* |
680 | Flushes all pending output into the compressed file. The parameter | 711 | Flushes all pending output into the compressed file. The parameter |
@@ -685,6 +716,45 @@ extern int EXPORT gzflush OF((gzFile file, int flush)); | |||
685 | degrade compression. | 716 | degrade compression. |
686 | */ | 717 | */ |
687 | 718 | ||
719 | extern z_off_t EXPORT gzseek OF((gzFile file, z_off_t offset, int whence)); | ||
720 | /* | ||
721 | Sets the starting position for the next gzread or gzwrite on the given | ||
722 | compressed file. The offset represents a number of bytes in the | ||
723 | uncompressed data stream. The whence parameter is defined as in lseek(2); | ||
724 | the value SEEK_END is not supported. | ||
725 | If the file is opened for reading, this function is emulated but can be | ||
726 | extremely slow. If the file is opened for writing, only forward seeks are | ||
727 | supported; gzseek then compresses a sequence of zeroes up to the new | ||
728 | starting position. | ||
729 | |||
730 | gzseek returns the resulting offset location as measured in bytes from | ||
731 | the beginning of the uncompressed stream, or -1 in case of error, in | ||
732 | particular if the file is opened for writing and the new starting position | ||
733 | would be before the current position. | ||
734 | */ | ||
735 | |||
736 | extern int EXPORT gzrewind OF((gzFile file)); | ||
737 | /* | ||
738 | Rewinds the given file. This function is supported only for reading. | ||
739 | |||
740 | gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET) | ||
741 | */ | ||
742 | |||
743 | extern z_off_t EXPORT gztell OF((gzFile file)); | ||
744 | /* | ||
745 | Returns the starting position for the next gzread or gzwrite on the | ||
746 | given compressed file. This position represents a number of bytes in the | ||
747 | uncompressed data stream. | ||
748 | |||
749 | gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR) | ||
750 | */ | ||
751 | |||
752 | extern int EXPORT gzeof OF((gzFile file)); | ||
753 | /* | ||
754 | Returns 1 when EOF has previously been detected reading the given | ||
755 | input stream, otherwise zero. | ||
756 | */ | ||
757 | |||
688 | extern int EXPORT gzclose OF((gzFile file)); | 758 | extern int EXPORT gzclose OF((gzFile file)); |
689 | /* | 759 | /* |
690 | Flushes all pending output if necessary, closes the compressed file | 760 | Flushes all pending output if necessary, closes the compressed file |
@@ -767,11 +837,14 @@ extern int EXPORT inflateInit2_ OF((z_streamp strm, int windowBits, | |||
767 | #define inflateInit2(strm, windowBits) \ | 837 | #define inflateInit2(strm, windowBits) \ |
768 | inflateInit2_((strm), (windowBits), ZLIB_VERSION, sizeof(z_stream)) | 838 | inflateInit2_((strm), (windowBits), ZLIB_VERSION, sizeof(z_stream)) |
769 | 839 | ||
840 | |||
770 | #if !defined(_Z_UTIL_H) && !defined(NO_DUMMY_DECL) | 841 | #if !defined(_Z_UTIL_H) && !defined(NO_DUMMY_DECL) |
771 | struct internal_state {int dummy;}; /* hack for buggy compilers */ | 842 | struct internal_state {int dummy;}; /* hack for buggy compilers */ |
772 | #endif | 843 | #endif |
773 | 844 | ||
774 | uLongf *get_crc_table OF((void)); /* can be used by asm versions of crc32() */ | 845 | extern const char * EXPORT zError OF((int err)); |
846 | extern int EXPORT inflateSyncPoint OF((z_streamp z)); | ||
847 | extern uLongf * EXPORT get_crc_table OF((void)); | ||
775 | 848 | ||
776 | #ifdef __cplusplus | 849 | #ifdef __cplusplus |
777 | } | 850 | } |