4
zlib general purpose compression library version 1.1.4
7
<body bgcolor="White" text="Black" vlink="Red" alink="Navy" link="Red">
8
<!-- background="zlibbg.gif" -->
10
<h1> zlib 1.1.4 Manual </h1>
12
<a name="Contents"><h2>Contents</h2>
14
<li> <a href="#Prologue">Prologue</a>
15
<li> <a href="#Introduction">Introduction</a>
16
<li> <a href="#Utility functions">Utility functions</a>
17
<li> <a href="#Basic functions">Basic functions</a>
18
<li> <a href="#Advanced functions">Advanced functions</a>
19
<li> <a href="#Constants">Constants</a>
20
<li> <a href="#struct z_stream_s">struct z_stream_s</a>
21
<li> <a href="#Checksum functions">Checksum functions</a>
22
<li> <a href="#Misc">Misc</a>
25
<a name="Prologue"><h2> Prologue </h2>
26
'zlib' general purpose compression library version 1.1.4, March 11th, 2002
28
Copyright (C) 1995-2002 Jean-loup Gailly and Mark Adler
30
This software is provided 'as-is', without any express or implied
31
warranty. In no event will the authors be held liable for any damages
32
arising from the use of this software.
34
Permission is granted to anyone to use this software for any purpose,
35
including commercial applications, and to alter it and redistribute it
36
freely, subject to the following restrictions:
38
<li> The origin of this software must not be misrepresented ; you must not
39
claim that you wrote the original software. If you use this software
40
in a product, an acknowledgment in the product documentation would be
41
appreciated but is not required.
42
<li> Altered source versions must be plainly marked as such, and must not be
43
misrepresented as being the original software.
44
<li> This notice may not be removed or altered from any source distribution.
49
<dd><a href="mailto:jloup@gzip.org">jloup@gzip.org</a>
51
<dd><a href="mailto:madler@alumni.caltech.edu">madler@alumni.caltech.edu</a>
54
The data format used by the zlib library is described by RFCs (Request for
55
Comments) 1950 to 1952 in the files
56
<a href="ftp://ds.internic.net/rfc/rfc1950.txt">
57
ftp://ds.internic.net/rfc/rfc1950.txt </a>
59
<a href="ftp://ds.internic.net/rfc/rfc1951.txt">
61
(<a href="#deflate">deflate</a> format) and
62
<a href="ftp://ds.internic.net/rfc/rfc1952.txt">
66
This manual is converted from zlib.h by
67
<a href="mailto:piaip@csie.ntu.edu.tw"> piaip </a>
69
Visit <a href="http://ftp.cdrom.com/pub/infozip/zlib/">
70
http://ftp.cdrom.com/pub/infozip/zlib/</a>
71
for the official zlib web page.
75
<a name="Introduction"><h2> Introduction </h2>
76
The 'zlib' compression library provides in-memory compression and
77
decompression functions, including integrity checks of the uncompressed
78
data. This version of the library supports only one compression method
79
(deflation) but other algorithms will be added later and will have the same
83
Compression can be done in a single step if the buffers are large
84
enough (for example if an input file is mmap'ed), or can be done by
85
repeated calls of the compression function. In the latter case, the
86
application must provide more input and/or consume the output
87
(providing more output space) before each call.
90
The library also supports reading and writing files in gzip (.gz) format
91
with an interface similar to that of stdio.
94
The library does not install any signal handler. The decoder checks
95
the consistency of the compressed data, so the library should never
96
crash even in case of corrupted input.
100
<a name="Utility functions"><h2> Utility functions </h2>
101
The following utility functions are implemented on top of the
102
<a href="#Basic functions">basic stream-oriented functions</a>.
103
To simplify the interface, some
104
default options are assumed (compression level and memory usage,
105
standard memory allocation functions). The source code of these
106
utility functions can easily be modified if you need special options.
107
<h3> Function list </h3>
109
<li> int <a href="#compress">compress</a> (Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen);
110
<li> int <a href="#compress2">compress2</a> (Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen, int level);
111
<li> int <a href="#uncompress">uncompress</a> (Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen);
112
<li> typedef voidp gzFile;
113
<li> gzFile <a href="#gzopen">gzopen</a> (const char *path, const char *mode);
114
<li> gzFile <a href="#gzdopen">gzdopen</a> (int fd, const char *mode);
115
<li> int <a href="#gzsetparams">gzsetparams</a> (gzFile file, int level, int strategy);
116
<li> int <a href="#gzread">gzread</a> (gzFile file, voidp buf, unsigned len);
117
<li> int <a href="#gzwrite">gzwrite</a> (gzFile file, const voidp buf, unsigned len);
118
<li> int VA <a href="#gzprintf">gzprintf</a> (gzFile file, const char *format, ...);
119
<li> int <a href="#gzputs">gzputs</a> (gzFile file, const char *s);
120
<li> char * <a href="#gzgets">gzgets</a> (gzFile file, char *buf, int len);
121
<li> int <a href="#gzputc">gzputc</a> (gzFile file, int c);
122
<li> int <a href="#gzgetc">gzgetc</a> (gzFile file);
123
<li> int <a href="#gzflush">gzflush</a> (gzFile file, int flush);
124
<li> z_off_t <a href="#gzseek">gzseek</a> (gzFile file, z_off_t offset, int whence);
125
<li> z_off_t <a href="#gztell">gztell</a> (gzFile file);
126
<li> int <a href="#gzrewind">gzrewind</a> (gzFile file);
127
<li> int <a href="#gzeof">gzeof</a> (gzFile file);
128
<li> int <a href="#gzclose">gzclose</a> (gzFile file);
129
<li> const char * <a href="#gzerror">gzerror</a> (gzFile file, int *errnum);
131
<h3> Function description </h3>
133
<font color="Blue"><dt> int <a name="compress">compress</a> (Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen);</font>
135
Compresses the source buffer into the destination buffer. sourceLen is
136
the byte length of the source buffer. Upon entry, destLen is the total
137
size of the destination buffer, which must be at least 0.1% larger than
138
sourceLen plus 12 bytes. Upon exit, destLen is the actual size of the
139
compressed buffer.<p>
140
This function can be used to <a href="#compress">compress</a> a whole file at once if the
141
input file is mmap'ed.<p>
142
<a href="#compress">compress</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_MEM_ERROR">Z_MEM_ERROR</a> if there was not
143
enough memory, <a href="#Z_BUF_ERROR">Z_BUF_ERROR</a> if there was not enough room in the output
146
<font color="Blue"><dt> int <a name="compress2">compress2</a> (Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen, int level);</font>
148
Compresses the source buffer into the destination buffer. The level
149
parameter has the same meaning as in <a href="#deflateInit">deflateInit</a>. sourceLen is the byte
150
length of the source buffer. Upon entry, destLen is the total size of the
151
destination buffer, which must be at least 0.1% larger than sourceLen plus
152
12 bytes. Upon exit, destLen is the actual size of the compressed buffer.
155
<a href="#compress2">compress2</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_MEM_ERROR">Z_MEM_ERROR</a> if there was not enough
156
memory, <a href="#Z_BUF_ERROR">Z_BUF_ERROR</a> if there was not enough room in the output buffer,
157
<a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if the level parameter is invalid.
160
<font color="Blue"><dt> int <a name="uncompress">uncompress</a> (Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen);</font>
162
Decompresses the source buffer into the destination buffer. sourceLen is
163
the byte length of the source buffer. Upon entry, destLen is the total
164
size of the destination buffer, which must be large enough to hold the
165
entire uncompressed data. (The size of the uncompressed data must have
166
been saved previously by the compressor and transmitted to the decompressor
167
by some mechanism outside the scope of this compression library.)
168
Upon exit, destLen is the actual size of the compressed buffer. <p>
169
This function can be used to decompress a whole file at once if the
170
input file is mmap'ed.
173
<a href="#uncompress">uncompress</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_MEM_ERROR">Z_MEM_ERROR</a> if there was not
174
enough memory, <a href="#Z_BUF_ERROR">Z_BUF_ERROR</a> if there was not enough room in the output
175
buffer, or <a href="#Z_DATA_ERROR">Z_DATA_ERROR</a> if the input data was corrupted.
178
<dt> typedef voidp gzFile;
181
<font color="Blue"><dt> gzFile <a name="gzopen">gzopen</a> (const char *path, const char *mode);</font>
183
Opens a gzip (.gz) file for reading or writing. The mode parameter
184
is as in fopen ("rb" or "wb") but can also include a compression level
185
("wb9") or a strategy: 'f' for filtered data as in "wb6f", 'h' for
186
Huffman only compression as in "wb1h". (See the description
187
of <a href="#deflateInit2">deflateInit2</a> for more information about the strategy parameter.)
190
<a href="#gzopen">gzopen</a> can be used to read a file which is not in gzip format ; in this
191
case <a href="#gzread">gzread</a> will directly read from the file without decompression.
194
<a href="#gzopen">gzopen</a> returns NULL if the file could not be opened or if there was
195
insufficient memory to allocate the (de)compression <a href="#state">state</a> ; errno
196
can be checked to distinguish the two cases (if errno is zero, the
197
zlib error is <a href="#Z_MEM_ERROR">Z_MEM_ERROR</a>).
200
<font color="Blue"><dt> gzFile <a name="gzdopen">gzdopen</a> (int fd, const char *mode);</font>
202
<a href="#gzdopen">gzdopen</a>() associates a gzFile with the file descriptor fd. File
203
descriptors are obtained from calls like open, dup, creat, pipe or
204
fileno (in the file has been previously opened with fopen).
205
The mode parameter is as in <a href="#gzopen">gzopen</a>.
207
The next call of <a href="#gzclose">gzclose</a> on the returned gzFile will also close the
208
file descriptor fd, just like fclose(fdopen(fd), mode) closes the file
209
descriptor fd. If you want to keep fd open, use <a href="#gzdopen">gzdopen</a>(dup(fd), mode).
211
<a href="#gzdopen">gzdopen</a> returns NULL if there was insufficient memory to allocate
212
the (de)compression <a href="#state">state</a>.
215
<font color="Blue"><dt> int <a name="gzsetparams">gzsetparams</a> (gzFile file, int level, int strategy);</font>
217
Dynamically update the compression level or strategy. See the description
218
of <a href="#deflateInit2">deflateInit2</a> for the meaning of these parameters.
220
<a href="#gzsetparams">gzsetparams</a> returns <a href="#Z_OK">Z_OK</a> if success, or <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if the file was not
224
<font color="Blue"><dt> int <a name="gzread">gzread</a> (gzFile file, voidp buf, unsigned len);</font>
226
Reads the given number of uncompressed bytes from the compressed file.
227
If the input file was not in gzip format, <a href="#gzread">gzread</a> copies the given number
228
of bytes into the buffer.
230
<a href="#gzread">gzread</a> returns the number of uncompressed bytes actually read (0 for
231
end of file, -1 for error).
234
<font color="Blue"><dt> int <a name="gzwrite">gzwrite</a> (gzFile file, const voidp buf, unsigned len);</font>
236
Writes the given number of uncompressed bytes into the compressed file.
237
<a href="#gzwrite">gzwrite</a> returns the number of uncompressed bytes actually written
238
(0 in case of error).
241
<font color="Blue"><dt> int VA <a name="gzprintf">gzprintf</a> (gzFile file, const char *format, ...);</font>
243
Converts, formats, and writes the args to the compressed file under
244
control of the format string, as in fprintf. <a href="#gzprintf">gzprintf</a> returns the number of
245
uncompressed bytes actually written (0 in case of error).
248
<font color="Blue"><dt> int <a name="gzputs">gzputs</a> (gzFile file, const char *s);</font>
250
Writes the given null-terminated string to the compressed file, excluding
251
the terminating null character.
253
<a href="#gzputs">gzputs</a> returns the number of characters written, or -1 in case of error.
256
<font color="Blue"><dt> char * <a name="gzgets">gzgets</a> (gzFile file, char *buf, int len);</font>
258
Reads bytes from the compressed file until len-1 characters are read, or
259
a newline character is read and transferred to buf, or an end-of-file
260
condition is encountered. The string is then terminated with a null
263
<a href="#gzgets">gzgets</a> returns buf, or <a href="#Z_NULL">Z_NULL</a> in case of error.
266
<font color="Blue"><dt> int <a name="gzputc">gzputc</a> (gzFile file, int c);</font>
268
Writes c, converted to an unsigned char, into the compressed file.
269
<a href="#gzputc">gzputc</a> returns the value that was written, or -1 in case of error.
272
<font color="Blue"><dt> int <a name="gzgetc">gzgetc</a> (gzFile file);</font>
274
Reads one byte from the compressed file. <a href="#gzgetc">gzgetc</a> returns this byte
275
or -1 in case of end of file or error.
278
<font color="Blue"><dt> int <a name="gzflush">gzflush</a> (gzFile file, int flush);</font>
280
Flushes all pending output into the compressed file. The parameter
281
flush is as in the <a href="#deflate">deflate</a>() function. The return value is the zlib
282
error number (see function <a href="#gzerror">gzerror</a> below). <a href="#gzflush">gzflush</a> returns <a href="#Z_OK">Z_OK</a> if
283
the flush parameter is <a href="#Z_FINISH">Z_FINISH</a> and all output could be flushed.
285
<a href="#gzflush">gzflush</a> should be called only when strictly necessary because it can
289
<font color="Blue"><dt> z_off_t <a name="gzseek">gzseek</a> (gzFile file, z_off_t offset, int whence);</font>
291
Sets the starting position for the next <a href="#gzread">gzread</a> or <a href="#gzwrite">gzwrite</a> on the
292
given compressed file. The offset represents a number of bytes in the
293
uncompressed data stream. The whence parameter is defined as in lseek(2);
294
the value SEEK_END is not supported.
296
If the file is opened for reading, this function is emulated but can be
297
extremely slow. If the file is opened for writing, only forward seeks are
298
supported ; <a href="#gzseek">gzseek</a> then compresses a sequence of zeroes up to the new
301
<a href="#gzseek">gzseek</a> returns the resulting offset location as measured in bytes from
302
the beginning of the uncompressed stream, or -1 in case of error, in
303
particular if the file is opened for writing and the new starting position
304
would be before the current position.
307
<font color="Blue"><dt> int <a name="gzrewind">gzrewind</a> (gzFile file);</font>
309
Rewinds the given file. This function is supported only for reading.
311
<a href="#gzrewind">gzrewind</a>(file) is equivalent to (int)<a href="#gzseek">gzseek</a>(file, 0L, SEEK_SET)
314
<font color="Blue"><dt> z_off_t <a name="gztell">gztell</a> (gzFile file);</font>
316
Returns the starting position for the next <a href="#gzread">gzread</a> or <a href="#gzwrite">gzwrite</a> on the
317
given compressed file. This position represents a number of bytes in the
318
uncompressed data stream.
321
<a href="#gztell">gztell</a>(file) is equivalent to <a href="#gzseek">gzseek</a>(file, 0L, SEEK_CUR)
324
<font color="Blue"><dt> int <a name="gzeof">gzeof</a> (gzFile file);</font>
326
Returns 1 when EOF has previously been detected reading the given
327
input stream, otherwise zero.
330
<font color="Blue"><dt> int <a name="gzclose">gzclose</a> (gzFile file);</font>
332
Flushes all pending output if necessary, closes the compressed file
333
and deallocates all the (de)compression <a href="#state">state</a>. The return value is the zlib
334
error number (see function <a href="#gzerror">gzerror</a> below).
337
<font color="Blue"><dt> const char * <a name="gzerror">gzerror</a> (gzFile file, int *errnum);</font>
339
Returns the error message for the last error which occurred on the
340
given compressed file. errnum is set to zlib error number. If an
341
error occurred in the file system and not in the compression library,
342
errnum is set to <a href="#Z_ERRNO">Z_ERRNO</a> and the application may consult errno
343
to get the exact error code.
347
<a name="Basic functions"><h2> Basic functions </h2>
348
<h3> Function list </h3>
350
<li> const char * <a href="#zlibVersion">zlibVersion</a> (void);
351
<li> int <a href="#deflateInit">deflateInit</a> (<a href="#z_streamp">z_streamp</a> strm, int level);
352
<li> int <a href="#deflate">deflate</a> (<a href="#z_streamp">z_streamp</a> strm, int flush);
353
<li> int <a href="#deflateEnd">deflateEnd</a> (<a href="#z_streamp">z_streamp</a> strm);
354
<li> int <a href="#inflateInit">inflateInit</a> (<a href="#z_streamp">z_streamp</a> strm);
355
<li> int <a href="#inflate">inflate</a> (<a href="#z_streamp">z_streamp</a> strm, int flush);
356
<li> int <a href="#inflateEnd">inflateEnd</a> (<a href="#z_streamp">z_streamp</a> strm);
359
<h3> Function description </h3>
361
<font color="Blue"><dt> const char * <a name="zlibVersion">zlibVersion</a> (void);</font>
362
<dd> The application can compare <a href="#zlibVersion">zlibVersion</a> and ZLIB_VERSION for consistency.
363
If the first character differs, the library code actually used is
364
not compatible with the zlib.h header file used by the application.
365
This check is automatically made by <a href="#deflateInit">deflateInit</a> and <a href="#inflateInit">inflateInit</a>.
368
<font color="Blue"><dt> int <a name="deflateInit">deflateInit</a> (<a href="#z_streamp">z_streamp</a> strm, int level);</font>
370
Initializes the internal stream <a href="#state">state</a> for compression. The fields
371
<a href="#zalloc">zalloc</a>, <a href="#zfree">zfree</a> and <a href="#opaque">opaque</a> must be initialized before by the caller.
372
If <a href="#zalloc">zalloc</a> and <a href="#zfree">zfree</a> are set to <a href="#Z_NULL">Z_NULL</a>, <a href="#deflateInit">deflateInit</a> updates them to
373
use default allocation functions.
376
The compression level must be <a href="#Z_DEFAULT_COMPRESSION">Z_DEFAULT_COMPRESSION</a>, or between 0 and 9:
377
1 gives best speed, 9 gives best compression, 0 gives no compression at
378
all (the input data is simply copied a block at a time).
381
<a href="#Z_DEFAULT_COMPRESSION">Z_DEFAULT_COMPRESSION</a> requests a default compromise between speed and
382
compression (currently equivalent to level 6).
385
<a href="#deflateInit">deflateInit</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_MEM_ERROR">Z_MEM_ERROR</a> if there was not
386
enough memory, <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if level is not a valid compression level,
387
<a href="#Z_VERSION_ERROR">Z_VERSION_ERROR</a> if the zlib library version (<a href="#zlib_version">zlib_version</a>) is incompatible
388
with the version assumed by the caller (ZLIB_VERSION).
389
<a href="#msg">msg</a> is set to null if there is no error message. <a href="#deflateInit">deflateInit</a> does not
390
perform any compression: this will be done by <a href="#deflate">deflate</a>().
393
<font color="Blue"><dt> int <a name="deflate">deflate</a> (<a href="#z_streamp">z_streamp</a> strm, int flush);</font>
395
<a href="#deflate">deflate</a> compresses as much data as possible, and stops when the input
396
buffer becomes empty or the output buffer becomes full. It may introduce some
397
output latency (reading input without producing any output) except when
400
The detailed semantics are as follows. <a href="#deflate">deflate</a> performs one or both of the
404
<li> Compress more input starting at <a href="#next_in">next_in</a> and update <a href="#next_in">next_in</a> and <a href="#avail_in">avail_in</a>
405
accordingly. If not all input can be processed (because there is not
406
enough room in the output buffer), <a href="#next_in">next_in</a> and <a href="#avail_in">avail_in</a> are updated and
407
processing will resume at this point for the next call of <a href="#deflate">deflate</a>().
410
Provide more output starting at <a href="#next_out">next_out</a> and update <a href="#next_out">next_out</a> and <a href="#avail_out">avail_out</a>
411
accordingly. This action is forced if the parameter flush is non zero.
412
Forcing flush frequently degrades the compression ratio, so this parameter
413
should be set only when necessary (in interactive applications).
414
Some output may be provided even if flush is not set.
417
Before the call of <a href="#deflate">deflate</a>(), the application should ensure that at least
418
one of the actions is possible, by providing more input and/or consuming
419
more output, and updating <a href="#avail_in">avail_in</a> or <a href="#avail_out">avail_out</a> accordingly ; <a href="#avail_out">avail_out</a>
420
should never be zero before the call. The application can consume the
421
compressed output when it wants, for example when the output buffer is full
422
(<a href="#avail_out">avail_out</a> == 0), or after each call of <a href="#deflate">deflate</a>(). If <a href="#deflate">deflate</a> returns <a href="#Z_OK">Z_OK</a>
423
and with zero <a href="#avail_out">avail_out</a>, it must be called again after making room in the
424
output buffer because there might be more output pending.
427
If the parameter flush is set to <a href="#Z_SYNC_FLUSH">Z_SYNC_FLUSH</a>, all pending output is
428
flushed to the output buffer and the output is aligned on a byte boundary, so
429
that the decompressor can get all input data available so far. (In particular
430
<a href="#avail_in">avail_in</a> is zero after the call if enough output space has been provided
431
before the call.) Flushing may degrade compression for some compression
432
algorithms and so it should be used only when necessary.
435
If flush is set to <a href="#Z_FULL_FLUSH">Z_FULL_FLUSH</a>, all output is flushed as with
436
<a href="#Z_SYNC_FLUSH">Z_SYNC_FLUSH</a>, and the compression <a href="#state">state</a> is reset so that decompression can
437
restart from this point if previous compressed data has been damaged or if
438
random access is desired. Using <a href="#Z_FULL_FLUSH">Z_FULL_FLUSH</a> too often can seriously degrade
442
If <a href="#deflate">deflate</a> returns with <a href="#avail_out">avail_out</a> == 0, this function must be called again
443
with the same value of the flush parameter and more output space (updated
444
<a href="#avail_out">avail_out</a>), until the flush is complete (<a href="#deflate">deflate</a> returns with non-zero
445
<a href="#avail_out">avail_out</a>).
448
If the parameter flush is set to <a href="#Z_FINISH">Z_FINISH</a>, pending input is processed,
449
pending output is flushed and <a href="#deflate">deflate</a> returns with <a href="#Z_STREAM_END">Z_STREAM_END</a> if there
450
was enough output space ; if <a href="#deflate">deflate</a> returns with <a href="#Z_OK">Z_OK</a>, this function must be
451
called again with <a href="#Z_FINISH">Z_FINISH</a> and more output space (updated <a href="#avail_out">avail_out</a>) but no
452
more input data, until it returns with <a href="#Z_STREAM_END">Z_STREAM_END</a> or an error. After
453
<a href="#deflate">deflate</a> has returned <a href="#Z_STREAM_END">Z_STREAM_END</a>, the only possible operations on the
454
stream are <a href="#deflateReset">deflateReset</a> or <a href="#deflateEnd">deflateEnd</a>.
457
<a href="#Z_FINISH">Z_FINISH</a> can be used immediately after <a href="#deflateInit">deflateInit</a> if all the compression
458
is to be done in a single step. In this case, <a href="#avail_out">avail_out</a> must be at least
459
0.1% larger than <a href="#avail_in">avail_in</a> plus 12 bytes. If <a href="#deflate">deflate</a> does not return
460
<a href="#Z_STREAM_END">Z_STREAM_END</a>, then it must be called again as described above.
463
<a href="#deflate">deflate</a>() sets strm-> <a href="#adler">adler</a> to the <a href="#adler32">adler32</a> checksum of all input read
464
so far (that is, <a href="#total_in">total_in</a> bytes).
467
<a href="#deflate">deflate</a>() may update <a href="#data_type">data_type</a> if it can make a good guess about
468
the input data type (<a href="#Z_ASCII">Z_ASCII</a> or <a href="#Z_BINARY">Z_BINARY</a>). In doubt, the data is considered
469
binary. This field is only for information purposes and does not affect
470
the compression algorithm in any manner.
473
<a href="#deflate">deflate</a>() returns <a href="#Z_OK">Z_OK</a> if some progress has been made (more input
474
processed or more output produced), <a href="#Z_STREAM_END">Z_STREAM_END</a> if all input has been
475
consumed and all output has been produced (only when flush is set to
476
<a href="#Z_FINISH">Z_FINISH</a>), <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if the stream <a href="#state">state</a> was inconsistent (for example
477
if <a href="#next_in">next_in</a> or <a href="#next_out">next_out</a> was NULL), <a href="#Z_BUF_ERROR">Z_BUF_ERROR</a> if no progress is possible
478
(for example <a href="#avail_in">avail_in</a> or <a href="#avail_out">avail_out</a> was zero).
481
<font color="Blue"><dt> int <a name="deflateEnd">deflateEnd</a> (<a href="#z_streamp">z_streamp</a> strm);</font>
483
All dynamically allocated data structures for this stream are freed.
484
This function discards any unprocessed input and does not flush any
488
<a href="#deflateEnd">deflateEnd</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if the
489
stream <a href="#state">state</a> was inconsistent, <a href="#Z_DATA_ERROR">Z_DATA_ERROR</a> if the stream was freed
490
prematurely (some input or output was discarded). In the error case,
491
<a href="#msg">msg</a> may be set but then points to a static string (which must not be
495
<font color="Blue"><dt> int <a name="inflateInit">inflateInit</a> (<a href="#z_streamp">z_streamp</a> strm);</font>
497
Initializes the internal stream <a href="#state">state</a> for decompression. The fields
498
<a href="#next_in">next_in</a>, <a href="#avail_in">avail_in</a>, <a href="#zalloc">zalloc</a>, <a href="#zfree">zfree</a> and <a href="#opaque">opaque</a> must be initialized before by
499
the caller. If <a href="#next_in">next_in</a> is not <a href="#Z_NULL">Z_NULL</a> and <a href="#avail_in">avail_in</a> is large enough (the exact
500
value depends on the compression method), <a href="#inflateInit">inflateInit</a> determines the
501
compression method from the zlib header and allocates all data structures
502
accordingly ; otherwise the allocation will be deferred to the first call of
503
<a href="#inflate">inflate</a>. If <a href="#zalloc">zalloc</a> and <a href="#zfree">zfree</a> are set to <a href="#Z_NULL">Z_NULL</a>, <a href="#inflateInit">inflateInit</a> updates them to
504
use default allocation functions.
507
<a href="#inflateInit">inflateInit</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_MEM_ERROR">Z_MEM_ERROR</a> if there was not enough
508
memory, <a href="#Z_VERSION_ERROR">Z_VERSION_ERROR</a> if the zlib library version is incompatible with the
509
version assumed by the caller. <a href="#msg">msg</a> is set to null if there is no error
510
message. <a href="#inflateInit">inflateInit</a> does not perform any decompression apart from reading
511
the zlib header if present: this will be done by <a href="#inflate">inflate</a>(). (So <a href="#next_in">next_in</a> and
512
<a href="#avail_in">avail_in</a> may be modified, but <a href="#next_out">next_out</a> and <a href="#avail_out">avail_out</a> are unchanged.)
515
<font color="Blue"><dt> int <a name="inflate">inflate</a> (<a href="#z_streamp">z_streamp</a> strm, int flush);</font>
517
<a href="#inflate">inflate</a> decompresses as much data as possible, and stops when the input
518
buffer becomes empty or the output buffer becomes full. It may some
519
introduce some output latency (reading input without producing any output)
520
except when forced to flush.
523
The detailed semantics are as follows. <a href="#inflate">inflate</a> performs one or both of the
527
<li> Decompress more input starting at <a href="#next_in">next_in</a> and update <a href="#next_in">next_in</a> and <a href="#avail_in">avail_in</a>
528
accordingly. If not all input can be processed (because there is not
529
enough room in the output buffer), <a href="#next_in">next_in</a> is updated and processing
530
will resume at this point for the next call of <a href="#inflate">inflate</a>().
532
<li> Provide more output starting at <a href="#next_out">next_out</a> and update <a href="#next_out">next_out</a> and
533
<a href="#avail_out">avail_out</a> accordingly. <a href="#inflate">inflate</a>() provides as much output as possible,
534
until there is no more input data or no more space in the output buffer
535
(see below about the flush parameter).
538
Before the call of <a href="#inflate">inflate</a>(), the application should ensure that at least
539
one of the actions is possible, by providing more input and/or consuming
540
more output, and updating the next_* and avail_* values accordingly.
541
The application can consume the uncompressed output when it wants, for
542
example when the output buffer is full (<a href="#avail_out">avail_out</a> == 0), or after each
543
call of <a href="#inflate">inflate</a>(). If <a href="#inflate">inflate</a> returns <a href="#Z_OK">Z_OK</a> and with zero <a href="#avail_out">avail_out</a>, it
544
must be called again after making room in the output buffer because there
545
might be more output pending.
548
If the parameter flush is set to <a href="#Z_SYNC_FLUSH">Z_SYNC_FLUSH</a>, <a href="#inflate">inflate</a> flushes as much
549
output as possible to the output buffer. The flushing behavior of <a href="#inflate">inflate</a> is
550
not specified for values of the flush parameter other than <a href="#Z_SYNC_FLUSH">Z_SYNC_FLUSH</a>
551
and <a href="#Z_FINISH">Z_FINISH</a>, but the current implementation actually flushes as much output
555
<a href="#inflate">inflate</a>() should normally be called until it returns <a href="#Z_STREAM_END">Z_STREAM_END</a> or an
556
error. However if all decompression is to be performed in a single step
557
(a single call of <a href="#inflate">inflate</a>), the parameter flush should be set to
558
<a href="#Z_FINISH">Z_FINISH</a>. In this case all pending input is processed and all pending
559
output is flushed ; <a href="#avail_out">avail_out</a> must be large enough to hold all the
560
uncompressed data. (The size of the uncompressed data may have been saved
561
by the compressor for this purpose.) The next operation on this stream must
562
be <a href="#inflateEnd">inflateEnd</a> to deallocate the decompression <a href="#state">state</a>. The use of <a href="#Z_FINISH">Z_FINISH</a>
563
is never required, but can be used to inform <a href="#inflate">inflate</a> that a faster routine
564
may be used for the single <a href="#inflate">inflate</a>() call.
567
If a preset dictionary is needed at this point (see <a href="#inflateSetDictionary">inflateSetDictionary</a>
568
below), <a href="#inflate">inflate</a> sets strm-<a href="#adler">adler</a> to the <a href="#adler32">adler32</a> checksum of the
569
dictionary chosen by the compressor and returns <a href="#Z_NEED_DICT">Z_NEED_DICT</a> ; otherwise
570
it sets strm-> <a href="#adler">adler</a> to the <a href="#adler32">adler32</a> checksum of all output produced
571
so far (that is, <a href="#total_out">total_out</a> bytes) and returns <a href="#Z_OK">Z_OK</a>, <a href="#Z_STREAM_END">Z_STREAM_END</a> or
572
an error code as described below. At the end of the stream, <a href="#inflate">inflate</a>()
573
checks that its computed <a href="#adler32">adler32</a> checksum is equal to that saved by the
574
compressor and returns <a href="#Z_STREAM_END">Z_STREAM_END</a> only if the checksum is correct.
577
<a href="#inflate">inflate</a>() returns <a href="#Z_OK">Z_OK</a> if some progress has been made (more input processed
578
or more output produced), <a href="#Z_STREAM_END">Z_STREAM_END</a> if the end of the compressed data has
579
been reached and all uncompressed output has been produced, <a href="#Z_NEED_DICT">Z_NEED_DICT</a> if a
580
preset dictionary is needed at this point, <a href="#Z_DATA_ERROR">Z_DATA_ERROR</a> if the input data was
581
corrupted (input stream not conforming to the zlib format or incorrect
582
<a href="#adler32">adler32</a> checksum), <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if the stream structure was inconsistent
583
(for example if <a href="#next_in">next_in</a> or <a href="#next_out">next_out</a> was NULL), <a href="#Z_MEM_ERROR">Z_MEM_ERROR</a> if there was not
584
enough memory, <a href="#Z_BUF_ERROR">Z_BUF_ERROR</a> if no progress is possible or if there was not
585
enough room in the output buffer when <a href="#Z_FINISH">Z_FINISH</a> is used. In the <a href="#Z_DATA_ERROR">Z_DATA_ERROR</a>
586
case, the application may then call <a href="#inflateSync">inflateSync</a> to look for a good
590
<font color="Blue"><dt> int <a name="inflateEnd">inflateEnd</a> (<a href="#z_streamp">z_streamp</a> strm);</font>
592
All dynamically allocated data structures for this stream are freed.
593
This function discards any unprocessed input and does not flush any
597
<a href="#inflateEnd">inflateEnd</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if the stream <a href="#state">state</a>
598
was inconsistent. In the error case, <a href="#msg">msg</a> may be set but then points to a
599
static string (which must not be deallocated).
602
<a name="Advanced functions"><h2> Advanced functions </h2>
603
The following functions are needed only in some special applications.
604
<h3> Function list </h3>
606
<li> int <a href="#deflateInit2">deflateInit2</a> (<a href="#z_streamp">z_streamp</a> strm,
607
<li> int <a href="#deflateSetDictionary">deflateSetDictionary</a> (<a href="#z_streamp">z_streamp</a> strm, const Bytef *dictionary, uInt dictLength);
608
<li> int <a href="#deflateCopy">deflateCopy</a> (<a href="#z_streamp">z_streamp</a> dest, <a href="#z_streamp">z_streamp</a> source);
609
<li> int <a href="#deflateReset">deflateReset</a> (<a href="#z_streamp">z_streamp</a> strm);
610
<li> int <a href="#deflateParams">deflateParams</a> (<a href="#z_streamp">z_streamp</a> strm, int level, int strategy);
611
<li> int <a href="#inflateInit2">inflateInit2</a> (<a href="#z_streamp">z_streamp</a> strm, int windowBits);
612
<li> int <a href="#inflateSetDictionary">inflateSetDictionary</a> (<a href="#z_streamp">z_streamp</a> strm, const Bytef *dictionary, uInt dictLength);
613
<li> int <a href="#inflateSync">inflateSync</a> (<a href="#z_streamp">z_streamp</a> strm);
614
<li> int <a href="#inflateReset">inflateReset</a> (<a href="#z_streamp">z_streamp</a> strm);
617
<h3> Function description </h3>
619
<font color="Blue"><dt> int <a name="deflateInit2">deflateInit2</a> (<a href="#z_streamp">z_streamp</a> strm, int level, int method, int windowBits, int memLevel, int strategy);</font>
621
<dd> This is another version of <a href="#deflateInit">deflateInit</a> with more compression options. The
622
fields <a href="#next_in">next_in</a>, <a href="#zalloc">zalloc</a>, <a href="#zfree">zfree</a> and <a href="#opaque">opaque</a> must be initialized before by
625
The method parameter is the compression method. It must be <a href="#Z_DEFLATED">Z_DEFLATED</a> in
626
this version of the library.<p>
628
The windowBits parameter is the base two logarithm of the window size
629
(the size of the history buffer). It should be in the range 8..15 for this
630
version of the library. Larger values of this parameter result in better
631
compression at the expense of memory usage. The default value is 15 if
632
<a href="#deflateInit">deflateInit</a> is used instead.<p>
634
The memLevel parameter specifies how much memory should be allocated
635
for the internal compression <a href="#state">state</a>. memLevel=1 uses minimum memory but
636
is slow and reduces compression ratio ; memLevel=9 uses maximum memory
637
for optimal speed. The default value is 8. See zconf.h for total memory
638
usage as a function of windowBits and memLevel.<p>
640
The strategy parameter is used to tune the compression algorithm. Use the
641
value <a href="#Z_DEFAULT_STRATEGY">Z_DEFAULT_STRATEGY</a> for normal data, <a href="#Z_FILTERED">Z_FILTERED</a> for data produced by a
642
filter (or predictor), or <a href="#Z_HUFFMAN_ONLY">Z_HUFFMAN_ONLY</a> to force Huffman encoding only (no
643
string match). Filtered data consists mostly of small values with a
644
somewhat random distribution. In this case, the compression algorithm is
645
tuned to <a href="#compress">compress</a> them better. The effect of <a href="#Z_FILTERED">Z_FILTERED</a> is to force more
646
Huffman coding and less string matching ; it is somewhat intermediate
647
between Z_DEFAULT and <a href="#Z_HUFFMAN_ONLY">Z_HUFFMAN_ONLY</a>. The strategy parameter only affects
648
the compression ratio but not the correctness of the compressed output even
649
if it is not set appropriately.<p>
651
<a href="#deflateInit2">deflateInit2</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_MEM_ERROR">Z_MEM_ERROR</a> if there was not enough
652
memory, <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if a parameter is invalid (such as an invalid
653
method). <a href="#msg">msg</a> is set to null if there is no error message. <a href="#deflateInit2">deflateInit2</a> does
654
not perform any compression: this will be done by <a href="#deflate">deflate</a>().<p>
656
<font color="Blue"><dt> int <a name="deflateSetDictionary">deflateSetDictionary</a> (<a href="#z_streamp">z_streamp</a> strm, const Bytef *dictionary, uInt dictLength);</font>
658
Initializes the compression dictionary from the given byte sequence
659
without producing any compressed output. This function must be called
660
immediately after <a href="#deflateInit">deflateInit</a>, <a href="#deflateInit2">deflateInit2</a> or <a href="#deflateReset">deflateReset</a>, before any
661
call of <a href="#deflate">deflate</a>. The compressor and decompressor must use exactly the same
662
dictionary (see <a href="#inflateSetDictionary">inflateSetDictionary</a>).<p>
664
The dictionary should consist of strings (byte sequences) that are likely
665
to be encountered later in the data to be compressed, with the most commonly
666
used strings preferably put towards the end of the dictionary. Using a
667
dictionary is most useful when the data to be compressed is short and can be
668
predicted with good accuracy ; the data can then be compressed better than
669
with the default empty dictionary.<p>
671
Depending on the size of the compression data structures selected by
672
<a href="#deflateInit">deflateInit</a> or <a href="#deflateInit2">deflateInit2</a>, a part of the dictionary may in effect be
673
discarded, for example if the dictionary is larger than the window size in
674
<a href="#deflate">deflate</a> or deflate2. Thus the strings most likely to be useful should be
675
put at the end of the dictionary, not at the front.<p>
677
Upon return of this function, strm-> <a href="#adler">adler</a> is set to the Adler32 value
678
of the dictionary ; the decompressor may later use this value to determine
679
which dictionary has been used by the compressor. (The Adler32 value
680
applies to the whole dictionary even if only a subset of the dictionary is
681
actually used by the compressor.)<p>
683
<a href="#deflateSetDictionary">deflateSetDictionary</a> returns <a href="#Z_OK">Z_OK</a> if success, or <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if a
684
parameter is invalid (such as NULL dictionary) or the stream <a href="#state">state</a> is
685
inconsistent (for example if <a href="#deflate">deflate</a> has already been called for this stream
686
or if the compression method is bsort). <a href="#deflateSetDictionary">deflateSetDictionary</a> does not
687
perform any compression: this will be done by <a href="#deflate">deflate</a>().<p>
689
<font color="Blue"><dt> int <a name="deflateCopy">deflateCopy</a> (<a href="#z_streamp">z_streamp</a> dest, <a href="#z_streamp">z_streamp</a> source);</font>
691
Sets the destination stream as a complete copy of the source stream.<p>
693
This function can be useful when several compression strategies will be
694
tried, for example when there are several ways of pre-processing the input
695
data with a filter. The streams that will be discarded should then be freed
696
by calling <a href="#deflateEnd">deflateEnd</a>. Note that <a href="#deflateCopy">deflateCopy</a> duplicates the internal
697
compression <a href="#state">state</a> which can be quite large, so this strategy is slow and
698
can consume lots of memory.<p>
700
<a href="#deflateCopy">deflateCopy</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_MEM_ERROR">Z_MEM_ERROR</a> if there was not
701
enough memory, <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if the source stream <a href="#state">state</a> was inconsistent
702
(such as <a href="#zalloc">zalloc</a> being NULL). <a href="#msg">msg</a> is left unchanged in both source and
705
<font color="Blue"><dt> int <a name="deflateReset">deflateReset</a> (<a href="#z_streamp">z_streamp</a> strm);</font>
706
<dd> This function is equivalent to <a href="#deflateEnd">deflateEnd</a> followed by <a href="#deflateInit">deflateInit</a>,
707
but does not free and reallocate all the internal compression <a href="#state">state</a>.
708
The stream will keep the same compression level and any other attributes
709
that may have been set by <a href="#deflateInit2">deflateInit2</a>.<p>
711
<a href="#deflateReset">deflateReset</a> returns <a href="#Z_OK">Z_OK</a> if success, or <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if the source
712
stream <a href="#state">state</a> was inconsistent (such as <a href="#zalloc">zalloc</a> or <a href="#state">state</a> being NULL).<p>
714
<font color="Blue"><dt> int <a name="deflateParams">deflateParams</a> (<a href="#z_streamp">z_streamp</a> strm, int level, int strategy);</font>
716
Dynamically update the compression level and compression strategy. The
717
interpretation of level and strategy is as in <a href="#deflateInit2">deflateInit2</a>. This can be
718
used to switch between compression and straight copy of the input data, or
719
to switch to a different kind of input data requiring a different
720
strategy. If the compression level is changed, the input available so far
721
is compressed with the old level (and may be flushed); the new level will
722
take effect only at the next call of <a href="#deflate">deflate</a>().<p>
724
Before the call of <a href="#deflateParams">deflateParams</a>, the stream <a href="#state">state</a> must be set as for
725
a call of <a href="#deflate">deflate</a>(), since the currently available input may have to
726
be compressed and flushed. In particular, strm-> <a href="#avail_out">avail_out</a> must be
729
<a href="#deflateParams">deflateParams</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if the source
730
stream <a href="#state">state</a> was inconsistent or if a parameter was invalid, <a href="#Z_BUF_ERROR">Z_BUF_ERROR</a>
731
if strm->avail_out was zero.<p>
733
<font color="Blue"><dt> int <a name="inflateInit2">inflateInit2</a> (<a href="#z_streamp">z_streamp</a> strm, int windowBits);</font>
735
<dd> This is another version of <a href="#inflateInit">inflateInit</a> with an extra parameter. The
736
fields <a href="#next_in">next_in</a>, <a href="#avail_in">avail_in</a>, <a href="#zalloc">zalloc</a>, <a href="#zfree">zfree</a> and <a href="#opaque">opaque</a> must be initialized
737
before by the caller.<p>
739
The windowBits parameter is the base two logarithm of the maximum window
740
size (the size of the history buffer). It should be in the range 8..15 for
741
this version of the library. The default value is 15 if <a href="#inflateInit">inflateInit</a> is used
742
instead. If a compressed stream with a larger window size is given as
743
input, <a href="#inflate">inflate</a>() will return with the error code <a href="#Z_DATA_ERROR">Z_DATA_ERROR</a> instead of
744
trying to allocate a larger window.<p>
746
<a href="#inflateInit2">inflateInit2</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_MEM_ERROR">Z_MEM_ERROR</a> if there was not enough
747
memory, <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if a parameter is invalid (such as a negative
748
memLevel). <a href="#msg">msg</a> is set to null if there is no error message. <a href="#inflateInit2">inflateInit2</a>
749
does not perform any decompression apart from reading the zlib header if
750
present: this will be done by <a href="#inflate">inflate</a>(). (So <a href="#next_in">next_in</a> and <a href="#avail_in">avail_in</a> may be
751
modified, but <a href="#next_out">next_out</a> and <a href="#avail_out">avail_out</a> are unchanged.)<p>
753
<font color="Blue"><dt> int <a name="inflateSetDictionary">inflateSetDictionary</a> (<a href="#z_streamp">z_streamp</a> strm, const Bytef *dictionary, uInt dictLength);</font>
755
Initializes the decompression dictionary from the given uncompressed byte
756
sequence. This function must be called immediately after a call of <a href="#inflate">inflate</a>
757
if this call returned <a href="#Z_NEED_DICT">Z_NEED_DICT</a>. The dictionary chosen by the compressor
758
can be determined from the Adler32 value returned by this call of
759
<a href="#inflate">inflate</a>. The compressor and decompressor must use exactly the same
760
dictionary (see <a href="#deflateSetDictionary">deflateSetDictionary</a>).<p>
762
<a href="#inflateSetDictionary">inflateSetDictionary</a> returns <a href="#Z_OK">Z_OK</a> if success, <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if a
763
parameter is invalid (such as NULL dictionary) or the stream <a href="#state">state</a> is
764
inconsistent, <a href="#Z_DATA_ERROR">Z_DATA_ERROR</a> if the given dictionary doesn't match the
765
expected one (incorrect Adler32 value). <a href="#inflateSetDictionary">inflateSetDictionary</a> does not
766
perform any decompression: this will be done by subsequent calls of
767
<a href="#inflate">inflate</a>().<p>
769
<font color="Blue"><dt> int <a name="inflateSync">inflateSync</a> (<a href="#z_streamp">z_streamp</a> strm);</font>
771
<dd> Skips invalid compressed data until a full flush point (see above the
772
description of <a href="#deflate">deflate</a> with <a href="#Z_FULL_FLUSH">Z_FULL_FLUSH</a>) can be found, or until all
773
available input is skipped. No output is provided.<p>
775
<a href="#inflateSync">inflateSync</a> returns <a href="#Z_OK">Z_OK</a> if a full flush point has been found, <a href="#Z_BUF_ERROR">Z_BUF_ERROR</a>
776
if no more input was provided, <a href="#Z_DATA_ERROR">Z_DATA_ERROR</a> if no flush point has been found,
777
or <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if the stream structure was inconsistent. In the success
778
case, the application may save the current current value of <a href="#total_in">total_in</a> which
779
indicates where valid compressed data was found. In the error case, the
780
application may repeatedly call <a href="#inflateSync">inflateSync</a>, providing more input each time,
781
until success or end of the input data.<p>
783
<font color="Blue"><dt> int <a name="inflateReset">inflateReset</a> (<a href="#z_streamp">z_streamp</a> strm);</font>
785
This function is equivalent to <a href="#inflateEnd">inflateEnd</a> followed by <a href="#inflateInit">inflateInit</a>,
786
but does not free and reallocate all the internal decompression <a href="#state">state</a>.
787
The stream will keep attributes that may have been set by <a href="#inflateInit2">inflateInit2</a>.
790
<a href="#inflateReset">inflateReset</a> returns <a href="#Z_OK">Z_OK</a> if success, or <a href="#Z_STREAM_ERROR">Z_STREAM_ERROR</a> if the source
791
stream <a href="#state">state</a> was inconsistent (such as <a href="#zalloc">zalloc</a> or <a href="#state">state</a> being NULL).
796
<a name="Checksum functions"><h2> Checksum functions </h2>
797
These functions are not related to compression but are exported
798
anyway because they might be useful in applications using the
800
<h3> Function list </h3>
802
<li> uLong <a href="#adler32">adler32</a> (uLong <a href="#adler">adler</a>, const Bytef *buf, uInt len);
803
<li> uLong <a href="#crc32">crc32</a> (uLong crc, const Bytef *buf, uInt len);
805
<h3> Function description </h3>
807
<font color="Blue"><dt> uLong <a name="adler32">adler32</a> (uLong <a href="#adler">adler</a>, const Bytef *buf, uInt len);</font>
809
Update a running Adler-32 checksum with the bytes buf[0..len-1] and
810
return the updated checksum. If buf is NULL, this function returns
811
the required initial value for the checksum.
813
An Adler-32 checksum is almost as reliable as a CRC32 but can be computed
814
much faster. Usage example:
817
uLong <a href="#adler">adler</a> = <a href="#adler32">adler32</a>(0L, <a href="#Z_NULL">Z_NULL</a>, 0);
819
while (read_buffer(buffer, length) != EOF) {
820
<a href="#adler">adler</a> = <a href="#adler32">adler32</a>(<a href="#adler">adler</a>, buffer, length);
822
if (<a href="#adler">adler</a> != original_adler) error();
825
<font color="Blue"><dt> uLong <a name="crc32">crc32</a> (uLong crc, const Bytef *buf, uInt len);</font>
827
Update a running crc with the bytes buf[0..len-1] and return the updated
828
crc. If buf is NULL, this function returns the required initial value
829
for the crc. Pre- and post-conditioning (one's complement) is performed
830
within this function so it shouldn't be done by the application.
834
uLong crc = <a href="#crc32">crc32</a>(0L, <a href="#Z_NULL">Z_NULL</a>, 0);
836
while (read_buffer(buffer, length) != EOF) {
837
crc = <a href="#crc32">crc32</a>(crc, buffer, length);
839
if (crc != original_crc) error();
843
<a name="struct z_stream_s"><h2> struct z_stream_s </h2>
845
<a name="z_stream_s">
847
typedef struct z_stream_s {
848
Bytef *<a name="next_in">next_in</a>; /* next input byte */
849
uInt <a name="avail_in">avail_in</a>; /* number of bytes available at <a href="#next_in">next_in</a> */
850
uLong <a name="total_in">total_in</a>; /* total nb of input bytes read so far */
852
Bytef *<a name="next_out">next_out</a>; /* next output byte should be put there */
853
uInt <a name="avail_out">avail_out</a>; /* remaining free space at <a href="#next_out">next_out</a> */
854
uLong <a name="total_out">total_out</a>; /* total nb of bytes output so far */
856
char *<a name="msg">msg</a>; /* last error message, NULL if no error */
857
struct internal_state FAR *<a name="state">state</a>; /* not visible by applications */
859
alloc_func <a name="zalloc">zalloc</a>; /* used to allocate the internal <a href="#state">state</a> */
860
free_func <a name="zfree">zfree</a>; /* used to free the internal <a href="#state">state</a> */
861
voidpf <a name="opaque">opaque</a>; /* private data object passed to <a href="#zalloc">zalloc</a> and <a href="#zfree">zfree</a> */
863
int <a name="data_type">data_type</a>; /* best guess about the data type: ascii or binary */
864
uLong <a name="adler">adler</a>; /* <a href="#adler32">adler32</a> value of the uncompressed data */
865
uLong <a name="reserved">reserved</a>; /* <a href="#reserved">reserved</a> for future use */
866
} <a href="#z_stream_s">z_stream</a> ;
868
typedef <a href="#z_stream_s">z_stream</a> FAR * <a name="z_streamp">z_streamp</a>; �
871
The application must update <a href="#next_in">next_in</a> and <a href="#avail_in">avail_in</a> when <a href="#avail_in">avail_in</a> has
872
dropped to zero. It must update <a href="#next_out">next_out</a> and <a href="#avail_out">avail_out</a> when <a href="#avail_out">avail_out</a>
873
has dropped to zero. The application must initialize <a href="#zalloc">zalloc</a>, <a href="#zfree">zfree</a> and
874
<a href="#opaque">opaque</a> before calling the init function. All other fields are set by the
875
compression library and must not be updated by the application. <p>
877
The <a href="#opaque">opaque</a> value provided by the application will be passed as the first
878
parameter for calls of <a href="#zalloc">zalloc</a> and <a href="#zfree">zfree</a>. This can be useful for custom
879
memory management. The compression library attaches no meaning to the
880
<a href="#opaque">opaque</a> value. <p>
882
<a href="#zalloc">zalloc</a> must return <a href="#Z_NULL">Z_NULL</a> if there is not enough memory for the object.
883
If zlib is used in a multi-threaded application, <a href="#zalloc">zalloc</a> and <a href="#zfree">zfree</a> must be
886
On 16-bit systems, the functions <a href="#zalloc">zalloc</a> and <a href="#zfree">zfree</a> must be able to allocate
887
exactly 65536 bytes, but will not be required to allocate more than this
888
if the symbol MAXSEG_64K is defined (see zconf.h). WARNING: On MSDOS,
889
pointers returned by <a href="#zalloc">zalloc</a> for objects of exactly 65536 bytes *must*
890
have their offset normalized to zero. The default allocation function
891
provided by this library ensures this (see zutil.c). To reduce memory
892
requirements and avoid any allocation of 64K objects, at the expense of
893
compression ratio, compile the library with -DMAX_WBITS=14 (see zconf.h).
896
The fields <a href="#total_in">total_in</a> and <a href="#total_out">total_out</a> can be used for statistics or
897
progress reports. After compression, <a href="#total_in">total_in</a> holds the total size of
898
the uncompressed data and may be saved for use in the decompressor
899
(particularly if the decompressor wants to decompress everything in
903
<a name="Constants"><h2> Constants </h2>
906
#define <a name="Z_NO_FLUSH">Z_NO_FLUSH</a> 0
907
#define <a name="Z_PARTIAL_FLUSH">Z_PARTIAL_FLUSH</a> 1
908
/* will be removed, use <a href="#Z_SYNC_FLUSH">Z_SYNC_FLUSH</a> instead */
909
#define <a name="Z_SYNC_FLUSH">Z_SYNC_FLUSH</a> 2
910
#define <a name="Z_FULL_FLUSH">Z_FULL_FLUSH</a> 3
911
#define <a name="Z_FINISH">Z_FINISH</a> 4
912
/* Allowed flush values ; see <a href="#deflate">deflate</a>() below for details */
914
#define <a name="Z_OK">Z_OK</a> 0
915
#define <a name="Z_STREAM_END">Z_STREAM_END</a> 1
916
#define <a name="Z_NEED_DICT">Z_NEED_DICT</a> 2
917
#define <a name="Z_ERRNO">Z_ERRNO</a> (-1)
918
#define <a name="Z_STREAM_ERROR">Z_STREAM_ERROR</a> (-2)
919
#define <a name="Z_DATA_ERROR">Z_DATA_ERROR</a> (-3)
920
#define <a name="Z_MEM_ERROR">Z_MEM_ERROR</a> (-4)
921
#define <a name="Z_BUF_ERROR">Z_BUF_ERROR</a> (-5)
922
#define <a name="Z_VERSION_ERROR">Z_VERSION_ERROR</a> (-6)
923
/* Return codes for the compression/decompression functions. Negative
924
* values are errors, positive values are used for special but normal events.
927
#define <a name="Z_NO_COMPRESSION">Z_NO_COMPRESSION</a> 0
928
#define <a name="Z_BEST_SPEED">Z_BEST_SPEED</a> 1
929
#define <a name="Z_BEST_COMPRESSION">Z_BEST_COMPRESSION</a> 9
930
#define <a name="Z_DEFAULT_COMPRESSION">Z_DEFAULT_COMPRESSION</a> (-1)
931
/* compression levels */
933
#define <a name="Z_FILTERED">Z_FILTERED</a> 1
934
#define <a name="Z_HUFFMAN_ONLY">Z_HUFFMAN_ONLY</a> 2
935
#define <a name="Z_DEFAULT_STRATEGY">Z_DEFAULT_STRATEGY</a> 0
936
/* compression strategy ; see <a href="#deflateInit2">deflateInit2</a>() below for details */
938
#define <a name="Z_BINARY">Z_BINARY</a> 0
939
#define <a name="Z_ASCII">Z_ASCII</a> 1
940
#define <a name="Z_UNKNOWN">Z_UNKNOWN</a> 2
941
/* Possible values of the <a href="#data_type">data_type</a> field */
943
#define <a name="Z_DEFLATED">Z_DEFLATED</a> 8
944
/* The <a href="#deflate">deflate</a> compression method (the only one supported in this version) */
946
#define <a name="Z_NULL">Z_NULL</a> 0 /* for initializing <a href="#zalloc">zalloc</a>, <a href="#zfree">zfree</a>, <a href="#opaque">opaque</a> */
948
#define <a name="zlib_version">zlib_version</a> <a href="#zlibVersion">zlibVersion</a>()
949
/* for compatibility with versions less than 1.0.2 */
954
<a name="Misc"><h2> Misc </h2>
955
<a href="#deflateInit">deflateInit</a> and <a href="#inflateInit">inflateInit</a> are macros to allow checking the zlib version
956
and the compiler's view of <a href="#z_stream_s">z_stream</a>.
960
<font color="Blue"><dt> const char * <a name="zError">zError</a> (int err);</font>
961
<font color="Blue"><dt> int <a name="inflateSyncPoint">inflateSyncPoint</a> (<a href="#z_streamp">z_streamp</a> z);</font>
962
<font color="Blue"><dt> const uLongf * <a name="get_crc_table">get_crc_table</a> (void);</font>
966
Last update: Wed Oct 13 20:42:34 1999<br>
967
piapi@csie.ntu.edu.tw
added
removed
lib/zlib/old/zlib.html
