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