zlib 114 Manual.docx

1、zlib 114 Manualzlib 1.1.4 Manual ContentsI. Prologue II. Introduction III. Utility functions IV. Basic functions V. Advanced functions VI. Constants VII. struct z_stream_s VIII. Checksum functions IX. Misc Prologue zlib general purpose compression library version 1.1.4, March 11th, 2002 Copyright (C

2、) 1995-2002 Jean-loup Gailly and Mark Adler This software is provided as-is, without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including com

3、mercial applications, and to alter it and redistribute it freely, subject to the following restrictions: 1. The origin of this software must not be misrepresented ; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product docume

4、ntation would be appreciated but is not required. 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution. Jean-loup Gailly jloupgzip.org Mark Adler madleralumn

5、i.caltech.edu The data format used by the zlib library is described by RFCs (Request for Comments) 1950 to 1952 in the files ftp:/ (zlib format), rfc1951.txt (deflate format) and rfc1952.txt (gzip format). This manual is converted from zlib.h by piaip Visit for the official zlib web page. Introducti

6、on The zlib compression library provides in-memory compression and decompression functions, including integrity checks of the uncompressed data. This version of the library supports only one compression method (deflation) but other algorithms will be added later and will have the same stream interfa

7、ce. Compression can be done in a single step if the buffers are large enough (for example if an input file is mmaped), or can be done by repeated calls of the compression function. In the latter case, the application must provide more input and/or consume the output (providing more output space) bef

8、ore each call. The library also supports reading and writing files in gzip (.gz) format with an interface similar to that of stdio. The library does not install any signal handler. The decoder checks the consistency of the compressed data, so the library should never crash even in case of corrupted

9、input. Utility functions The following utility functions are implemented on top of the basic stream-oriented functions. To simplify the interface, some default options are assumed (compression level and memory usage, standard memory allocation functions). The source code of these utility functions c

10、an easily be modified if you need special options. Function list int compress (Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen); int compress2 (Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen, int level); int uncompress (Bytef *dest, uLongf *destLen, const Bytef

11、 *source, uLong sourceLen); typedef voidp gzFile; gzFile gzopen (const char *path, const char *mode); gzFile gzdopen (int fd, const char *mode); int gzsetparams (gzFile file, int level, int strategy); int gzread (gzFile file, voidp buf, unsigned len); int gzwrite (gzFile file, const voidp buf, unsig

12、ned len); int VA gzprintf (gzFile file, const char *format, .); int gzputs (gzFile file, const char *s); char * gzgets (gzFile file, char *buf, int len); int gzputc (gzFile file, int c); int gzgetc (gzFile file); int gzflush (gzFile file, int flush); z_off_t gzseek (gzFile file, z_off_t offset, int

13、whence); z_off_t gztell (gzFile file); int gzrewind (gzFile file); int gzeof (gzFile file); int gzclose (gzFile file); const char * gzerror (gzFile file, int *errnum); Function description int compress (Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen); Compresses the source buffer

14、 into the destination buffer. sourceLen is the byte length of the source buffer. Upon entry, destLen is the total size of the destination buffer, which must be at least 0.1% larger than sourceLen plus 12 bytes. Upon exit, destLen is the actual size of the compressed buffer. This function can be used

15、 to compress a whole file at once if the input file is mmaped. compress returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if there was not enough room in the output buffer. int compress2 (Bytef *dest, uLongf *destLen, const Bytef *source, uLong sourceLen, int level); C

16、ompresses the source buffer into the destination buffer. The level parameter has the same meaning as in deflateInit. sourceLen is the byte length of the source buffer. Upon entry, destLen is the total size of the destination buffer, which must be at least 0.1% larger than sourceLen plus 12 bytes. Up

17、on exit, destLen is the actual size of the compressed buffer. compress2 returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if there was not enough room in the output buffer, Z_STREAM_ERROR if the level parameter is invalid. int uncompress (Bytef *dest, uLongf *destLen,

18、const Bytef *source, uLong sourceLen); Decompresses the source buffer into the destination buffer. sourceLen is the byte length of the source buffer. Upon entry, destLen is the total size of the destination buffer, which must be large enough to hold the entire uncompressed data. (The size of the unc

19、ompressed data must have been saved previously by the compressor and transmitted to the decompressor by some mechanism outside the scope of this compression library.) Upon exit, destLen is the actual size of the compressed buffer. This function can be used to decompress a whole file at once if the i

20、nput file is mmaped. uncompress returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if there was not enough room in the output buffer, or Z_DATA_ERROR if the input data was corrupted. typedef voidp gzFile; gzFile gzopen (const char *path, const char *mode); Opens a gzip

21、(.gz) file for reading or writing. The mode parameter is as in fopen (rb or wb) but can also include a compression level (wb9) or a strategy: f for filtered data as in wb6f, h for Huffman only compression as in wb1h. (See the description of deflateInit2 for more information about the strategy parame

22、ter.) gzopen can be used to read a file which is not in gzip format ; in this case gzread will directly read from the file without decompression. gzopen returns NULL if the file could not be opened or if there was insufficient memory to allocate the (de)compression state ; errno can be checked to di

23、stinguish the two cases (if errno is zero, the zlib error is Z_MEM_ERROR). gzFile gzdopen (int fd, const char *mode); gzdopen() associates a gzFile with the file descriptor fd. File descriptors are obtained from calls like open, dup, creat, pipe or fileno (in the file has been previously opened with

24、 fopen). The mode parameter is as in gzopen. The next call of gzclose on the returned gzFile will also close the file descriptor fd, just like fclose(fdopen(fd), mode) closes the file descriptor fd. If you want to keep fd open, use gzdopen(dup(fd), mode). gzdopen returns NULL if there was insufficie

25、nt memory to allocate the (de)compression state. int gzsetparams (gzFile file, int level, int strategy); Dynamically update the compression level or strategy. See the description of deflateInit2 for the meaning of these parameters. gzsetparams returns Z_OK if success, or Z_STREAM_ERROR if the file w

26、as not opened for writing. int gzread (gzFile file, voidp buf, unsigned len); Reads the given number of uncompressed bytes from the compressed file. If the input file was not in gzip format, gzread copies the given number of bytes into the buffer. gzread returns the number of uncompressed bytes actu

27、ally read (0 for end of file, -1 for error). int gzwrite (gzFile file, const voidp buf, unsigned len); Writes the given number of uncompressed bytes into the compressed file. gzwrite returns the number of uncompressed bytes actually written (0 in case of error). int VA gzprintf (gzFile file, const c

28、har *format, .); Converts, formats, and writes the args to the compressed file under control of the format string, as in fprintf. gzprintf returns the number of uncompressed bytes actually written (0 in case of error). int gzputs (gzFile file, const char *s); Writes the given null-terminated string

29、to the compressed file, excluding the terminating null character. gzputs returns the number of characters written, or -1 in case of error. char * gzgets (gzFile file, char *buf, int len); Reads bytes from the compressed file until len-1 characters are read, or a newline character is read and transfe

30、rred to buf, or an end-of-file condition is encountered. The string is then terminated with a null character. gzgets returns buf, or Z_NULL in case of error. int gzputc (gzFile file, int c); Writes c, converted to an unsigned char, into the compressed file. gzputc returns the value that was written,

31、 or -1 in case of error. int gzgetc (gzFile file); Reads one byte from the compressed file. gzgetc returns this byte or -1 in case of end of file or error. int gzflush (gzFile file, int flush); Flushes all pending output into the compressed file. The parameter flush is as in the deflate() function.

32、The return value is the zlib error number (see function gzerror below). gzflush returns Z_OK if the flush parameter is Z_FINISH and all output could be flushed. gzflush should be called only when strictly necessary because it can degrade compression. z_off_t gzseek (gzFile file, z_off_t offset, int whence); Sets the starting position for the next gzread