diff options
Diffstat (limited to 'lib/libz/zlib.3')
| -rw-r--r-- | lib/libz/zlib.3 | 1776 |
1 files changed, 1776 insertions, 0 deletions
diff --git a/lib/libz/zlib.3 b/lib/libz/zlib.3 new file mode 100644 index 00000000000..5978c834382 --- /dev/null +++ b/lib/libz/zlib.3 @@ -0,0 +1,1776 @@ +.\" $OpenBSD: zlib.3,v 1.1 2003/09/25 09:12:09 jmc Exp $ +.\" +.\" Copyright (C) 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 commercial applications, and to alter it and redistribute it +.\" freely, subject to the following restrictions: +.\" +.\" 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 documentation would be +.\" appreciated but is not required. +.\" Altered source versions must be plainly marked as such, and must not be +.\" misrepresented as being the original software. +.\" This notice may not be removed or altered from any source distribution. +.\" +.\" Converted to mdoc format for the OpenBSD project +.\" by Jason McIntyre <jmc@openbsd.org> +.\" +.Dd September 17, 2003 +.Dt ZLIB 3 +.Os +.Sh NAME +.Nm zlib +.Nd general purpose compression library +.Sh SYNOPSIS +.Fd "#include <zlib.h>" +.Pp +Basic functions +.Pp +.Ft const char * +.Fn zlibVersion "void" +.Ft int +.Fn deflateInit "z_streamp strm" "int level" +.Ft int +.Fn deflate "z_streamp strm" "int flush" +.Ft int +.Fn deflateEnd "z_streamp strm" +.Ft int +.Fn inflateInit "z_streamp strm" +.Ft int +.Fn inflate "z_streamp strm" "int flush" +.Ft int +.Fn inflateEnd "z_streamp strm" +.Pp +Advanced functions +.Pp +.Ft int +.Fn deflateInit2 "z_streamp strm" "int level" "int method" "int windowBits" "int memLevel" "int strategy" +.Ft int +.Fn deflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" +.Ft int +.Fn deflateCopy "z_streamp dest" "z_streamp source" +.Ft int +.Fn deflateReset "z_streamp strm" +.Ft int +.Fn deflateParams "z_streamp strm" "int level" "int strategy" +.Ft int +.Fn inflateInit2 "z_streamp strm" "int windowBits" +.Ft int +.Fn inflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" +.Ft int +.Fn inflateSync "z_streamp strm" +.Ft int +.Fn inflateReset "z_streamp strm" +.Pp +Utility functions +.Pp +.Fd typedef voidp gzFile; +.Pp +.Ft int +.Fn compress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" +.Ft int +.Fn compress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" "int level" +.Ft int +.Fn uncompress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" +.Ft gzFile +.Fn gzopen "const char *path" "const char *mode" +.Ft gzFile +.Fn gzdopen "int fd" "const char *mode" +.Ft int +.Fn gzsetparams "gzFile file" "int level" "int strategy" +.Ft int +.Fn gzread "gzFile file" "voidp buf" "unsigned len" +.Ft int +.Fn gzwrite "gzFile file" "const voidp buf" "unsigned len" +.Ft int +.Fn gzprintf "gzFile file" "const char *format" "..." +.Ft int +.Fn gzputs "gzFile file" "const char *s" +.Ft char * +.Fn gzgets "gzFile file" "char *buf" "int len" +.Ft int +.Fn gzputc "gzFile file" "int c" +.Ft int +.Fn gzgetc "gzFile file" +.Ft int +.Fn gzflush "gzFile file" "int flush" +.Ft z_off_t +.Fn gzseek "gzFile file" "z_off_t offset" "int whence" +.Ft int +.Fn gzrewind "gzFile file" +.Ft z_off_t +.Fn gztell "gzFile file" +.Ft int +.Fn gzeof "gzFile file" +.Ft int +.Fn gzclose "gzFile file" +.Ft const char * +.Fn gzerror "gzFile file" "int *errnum" +.Pp +Checksum functions +.Pp +.Ft uLong +.Fn adler32 "uLong adler" "const Bytef *buf" "uInt len" +.Ft uLong +.Fn crc32 "uLong crc" "const Bytef *buf" "uInt len" +.Sh DESCRIPTION +This manual page describes the +.Nm +general purpose compression library, version 1.1.4. +.Pp +The +.Nm +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 +.Pq deflation +but other algorithms will be added later and will have the same +stream interface. +.Pp +Compression can be done in a single step if the buffers are large enough +.Pq for example if an input file is mmap'ed , +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 +.Pq providing more output space +before each call. +.Pp +The library also supports reading and writing files in +.Xr gzip 1 +.Pq .gz +format with an interface similar to that of +.Xr stdio 3 . +.Pp +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 input. +.Pp +The functions within the library are divided into the following sections: +.Pp +.Bl -dash -offset indent -compact +.It +Basic functions +.It +Advanced functions +.It +Utility functions +.It +Checksum functions +.El +.Sh BASIC FUNCTIONS +.Bl -tag -width Ds +.It Xo +.Fa const char * +.Fn zlibVersion "void" ; +.Xc +.Pp +The application can compare +.Fn zlibVersion +and +.Dv ZLIB_VERSION +for consistency. +If the first character differs, the library code actually used is +not compatible with the +.Aq Pa zlib.h +header file used by the application. +This check is automatically made by +.Fn deflateInit +and +.Fn inflateInit . +.It Xo +.Fa int +.Fn deflateInit "z_streamp strm" "int level" ; +.Xc +.Pp +The +.Fn deflateInit +function initializes the internal stream state for compression. +The fields +.Fa zalloc , +.Fa zfree , +and +.Fa opaque +must be initialized before by the caller. +If +.Fa zalloc +and +.Fa zfree +are set to +.Dv Z_NULL , +.Fn deflateInit +updates them to use default allocation functions. +.Pp +The compression level must be +.Dv Z_DEFAULT_COMPRESSION , +or between 0 and 9: +1 gives best speed, 9 gives best compression, 0 gives no compression at all +(the input data is simply copied a block at a time). +.Pp +.Dv Z_DEFAULT_COMPRESSION +requests a default compromise between speed and compression +.Pq currently equivalent to level 6 . +.Pp +.Fn deflateInit +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if level is not a valid compression level, +.Dv Z_VERSION_ERROR +if the +.Nm +library version +.Pq zlib_version +is incompatible with the version assumed by the caller +.Pq ZLIB_VERSION . +.Fa msg +is set to null if there is no error message. +.Fn deflateInit +does not perform any compression: this will be done by +.Fn deflate . +.It Xo +.Fa int +.Fn deflate "z_streamp strm" "int flush" ; +.Xc +.Pp +.Fn deflate +compresses as much data as possible, and stops when the input +buffer becomes empty or the output buffer becomes full. +It may introduce some output latency +.Pq reading input without producing any output +except when forced to flush. +.Pp +The detailed semantics are as follows. +.Fn deflate +performs one or both of the following actions: +.Pp +Compress more input starting at +.Fa next_in +and update +.Fa next_in +and +.Fa avail_in +accordingly. +If not all input can be processed +(because there is not enough room in the output buffer), +.Fa next_in +and +.Fa avail_in +are updated and processing will resume at this point for the next call to +.Fn deflate . +.Pp +Provide more output starting at +.Fa next_out +and update +.Fa next_out +and +.Fa avail_out +accordingly. +This action is forced if the parameter +.Fa flush +is non-zero. +Forcing +.Fa flush +frequently degrades the compression ratio, +so this parameter should be set only when necessary +.Pq in interactive applications . +Some output may be provided even if +.Fa flush +is not set. +.Pp +Before the call to +.Fn deflate , +the application should ensure that at least +one of the actions is possible, by providing more input and/or consuming +more output, and updating +.Fa avail_in +or +.Fa avail_out +accordingly; +.Fa avail_out +should never be zero before the call. +The application can consume the compressed output when it wants, +for example when the output buffer is full +.Pq avail_out == 0 , +or after each call to +.Fn deflate . +If +.Fn deflate +returns +.Dv Z_OK +and with zero +.Fa avail_out , +it must be called again after making room in the +output buffer because there might be more output pending. +.Pp +If the parameter +.Fa flush +is set to +.Dv Z_SYNC_FLUSH , +all pending output is flushed to the output buffer and the output +is aligned on a byte boundary, so that the decompressor can get all +input data available so far. +(In particular, +.Fa avail_in +is zero after the call if enough output space +has been provided before the call.) +Flushing may degrade compression for some compression algorithms +and so it should be used only when necessary. +.Pp +If +.Fa flush +is set to +.Dv Z_FULL_FLUSH , +all output is flushed as with +.Dv Z_SYNC_FLUSH , +and the compression state is reset so that decompression can restart from this +point if previous compressed data has been damaged or if random access +is desired. +Using +.Dv Z_FULL_FLUSH +too often can seriously degrade the compression. +.Pp +If +.Fn deflate +returns with avail_out == 0, this function must be called again +with the same value of the flush parameter and more output space +(updated +.Fa avail_out ) , +until the flush is complete +.Pf ( Fn deflate +returns with non-zero +.Fa avail_out ) . +.Pp +If the parameter +.Fa flush +is set to +.Dv Z_FINISH , +pending input is processed, pending output is flushed and +.Fn deflate +returns with +.Dv Z_STREAM_END +if there was enough output space; if +.Fn deflate +returns with +.Dv Z_OK , +this function must be called again with +.Dv Z_FINISH +and more output space +(updated +.Fa avail_out +but no more input data, until it returns with +.Dv Z_STREAM_END +or an error. +After +.Fn deflate +has returned +.Dv Z_STREAM_END , +the only possible operations on the stream are +.Fn deflateReset +or +.Fn deflateEnd . +.Pp +.Dv Z_FINISH +can be used immediately after +.Fn deflateInit +if all the compression is to be done in a single step. +In this case, +.Fa avail_out +must be at least 0.1% larger than +.Fa avail_in +plus 12 bytes. +If +.Fn deflate +does not return +.Dv Z_STREAM_END , +then it must be called again as described above. +.Pp +.Fn deflate +sets strm->adler to the adler32 checksum of all input read so far +(that is, +.Fa total_in +bytes). +.Pp +.Fn deflate +may update +.Fa data_type +if it can make a good guess about the input data type +.Pq Z_ASCII or Z_BINARY . +If in doubt, the data is considered binary. +This field is only for information purposes and does not affect +the compression algorithm in any manner. +.Pp +.Fn deflate +returns +.Dv Z_OK +if some progress has been made +.Pq more input processed or more output produced , +.Dv Z_STREAM_END +if all input has been consumed and all output has been produced +(only when +.Fa flush +is set to +.Dv Z_FINISH ) , +.Dv Z_STREAM_ERROR +if the stream state was inconsistent +(for example, if +.Fa next_in +or +.Fa next_out +was +.Dv NULL ) , +.Dv Z_BUF_ERROR +if no progress is possible +(for example, +.Fa avail_in +or +.Fa avail_out +was zero). +.It Xo +.Fa int +.Fn deflateEnd "z_streamp strm" ; +.Xc +.Pp +All dynamically allocated data structures for this stream are freed. +This function discards any unprocessed input and does not flush any +pending output. +.Pp +.Fn deflateEnd +returns +.Dv Z_OK +if successful, +.Dv Z_STREAM_ERROR +if the stream state was inconsistent, +.Dv Z_DATA_ERROR +if the stream was freed prematurely +.Pq some input or output was discarded . +In the error case, +.Fa msg +may be set but then points to a static string +.Pq which must not be deallocated . +.It Xo +.Fa int +.Fn inflateInit "z_streamp strm" ; +.Xc +The +.Fn inflateInit +function initializes the internal stream state for decompression. +The fields +.Fa next_in , +.Fa avail_in , +.Fa zalloc , +.Fa zfree , +and +.Fa opaque +must be initialized before by the caller. +If +.Fa next_in +is not +.Dv Z_NULL +and +.Fa avail_in +is large enough +.Pq the exact value depends on the compression method , +.Fn inflateInit +determines the compression method from the +.Nm +header and allocates all data structures accordingly; +otherwise the allocation will be deferred to the first call to +.Fn inflate . +If +.Fa zalloc +and +.Fa zfree +are set to +.Dv Z_NULL , +.Fn inflateInit +updates them to use default allocation functions. +.Pp +.Fn inflateInit +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_VERSION_ERROR +if the +.Nm +library version is incompatible with the version assumed by the caller. +.Fa msg +is set to null if there is no error message. +.Fn inflateInit +does not perform any decompression apart from reading the +.Nm +header if present: this will be done by +.Fn inflate . +(So +.Fa next_in +and +.Fa avail_in +may be modified, +but +.Fa next_out +and +.Fa avail_out +are unchanged.) +.It Xo +.Fa int +.Fn inflate "z_streamp strm" "int flush" ; +.Xc +.Fn inflate +decompresses as much data as possible, and stops when the input +buffer becomes empty or the output buffer becomes full. +It may introduce some output latency +.Pq reading input without producing any output +except when forced to flush. +.Pp +The detailed semantics are as follows. +.Fn inflate +performs one or both of the following actions: +.Pp +Decompress more input starting at +.Fa next_in +and update +.Fa next_in +and +.Fa avail_in +accordingly. +If not all input can be processed +(because there is not enough room in the output buffer), +.Fa next_in +is updated and processing will resume at this point for the next call to +.Fn inflate . +.Pp +Provide more output starting at +.Fa next_out +and update +.Fa next_out +and +.Fa avail_out +accordingly. +.Fn inflate +provides as much output as possible, +until there is no more input data or no more space in the output buffer +.Pq see below about the flush parameter . +.Pp +Before the call to +.Fn inflate , +the application should ensure that at least one of the actions is possible, +by providing more input and/or consuming more output, +and updating the next_* and avail_* values accordingly. +The application can consume the uncompressed output when it wants, +for example when the output buffer is full (avail_out == 0), +or after each call to +.Fn inflate . +If +.Fn inflate +returns +.Dv Z_OK +and with zero +.Fa avail_out , +it must be called again after making room +in the output buffer because there might be more output pending. +.Pp +If the parameter +.Fa flush +is set to +.Dv Z_SYNC_FLUSH , +.Fn inflate +flushes as much output as possible to the output buffer. +The flushing behavior of +.Fn inflate +is not specified for values of the flush parameter other than +.Dv Z_SYNC_FLUSH +and +.Dv Z_FINISH , +but the current implementation actually flushes as much output +as possible anyway. +.Pp +.Fn inflate +should normally be called until it returns +.Dv Z_STREAM_END +or an error. +However if all decompression is to be performed in a single step +.Pq a single call to inflate , +the parameter +.Fa flush +should be set to +.Dv Z_FINISH . +In this case all pending input is processed and all pending output is flushed; +.Fa avail_out +must be large enough to hold all the uncompressed data. +(The size of the uncompressed data may have been saved +by the compressor for this purpose.) +The next operation on this stream must be +.Fn inflateEnd +to deallocate the decompression state. +The use of +.Dv Z_FINISH +is never required, but can be used to inform +.Fn inflate +that a faster routine may be used for the single +.Fn inflate +call. +.Pp +If a preset dictionary is needed at this point (see +.Fn inflateSetDictionary +below), +.Fn inflate +sets strm->adler to the adler32 checksum of the dictionary +chosen by the compressor and returns +.Dv Z_NEED_DICT ; +otherwise it sets strm->adler to the adler32 checksum of all output produced +so far +(that is, +.Fa total_out +bytes) +and returns +.Dv Z_OK , +.Dv Z_STREAM_END , +or an error code as described below. +At the end of the stream, +.Fn inflate +checks that its computed adler32 checksum is equal to that saved by the +compressor and returns +.Dv Z_STREAM_END +only if the checksum is correct. +.Pp +.Fn inflate +returns +.Dv Z_OK +if some progress has been made +.Pq more input processed or more output produced , +.Dv Z_STREAM_END +if the end of the compressed data has been reached and all uncompressed output +has been produced, +.Dv Z_NEED_DICT +if a preset dictionary is needed at this point, +.Dv Z_DATA_ERROR +if the input data was corrupted (input stream not conforming to the +.Nm +format or incorrect adler32 checksum), +.Dv Z_STREAM_ERROR +if the stream structure was inconsistent +(for example, if +.Fa next_in +or +.Fa next_out +was +.Dv NULL ) , +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_BUF_ERROR +if no progress is possible or if there was not enough room in the output buffer +when +.Dv Z_FINISH +is used. +In the +.Dv Z_DATA_ERROR +case, the application may then call +.Fn inflateSync +to look for a good compression block. +.It Xo +.Fa int +.Fn inflateEnd "z_streamp strm" ; +.Xc +All dynamically allocated data structures for this stream are freed. +This function discards any unprocessed input and does not flush any +pending output. +.Pp +.Fn inflateEnd +returns +.Dv Z_OK +if successful, or +.Dv Z_STREAM_ERROR +if the stream state was inconsistent. +In the error case, +.Fa msg +may be set but then points to a static string +.Pq which must not be deallocated . +.El +.Sh ADVANCED FUNCTIONS +The following functions are needed only in some special applications. +.Bl -tag -width Ds +.It Xo +.Fa int +.Fn deflateInit2 "z_streamp strm" "int level" "int method" "int windowBits" "int memLevel" "int strategy" ; +.Xc +.Pp +This is another version of +.Fn deflateInit +with more compression options. +The fields +.Fa next_in , +.Fa zalloc , +.Fa zfree , +and +.Fa opaque +must be initialized before by the caller. +.Pp +The +.Fa method +parameter is the compression method. +It must be +.Dv Z_DEFLATED +in this version of the library. +.Pp +The +.Fa windowBits +parameter is the base two logarithm of the window size +.Pq the size of the history buffer . +It should be in the range 8..15 for this version of the library. +Larger values of this parameter result in better compression +at the expense of memory usage. +The default value is 15 if +.Fn deflateInit +is used instead. +.Pp +The +.Fa memLevel +parameter specifies how much memory should be allocated +for the internal compression state. +memLevel=1 uses minimum memory but is slow and reduces compression ratio; +memLevel=9 uses maximum memory for optimal speed. +The default value is 8. +See +.Aq Pa zconf.h +for total memory usage as a function of +.Fa windowBits +and +.Fa memLevel . +.Pp +The +.Fa strategy +parameter is used to tune the compression algorithm. +Use the value +.Dv Z_DEFAULT_STRATEGY +for normal data; +.Dv Z_FILTERED +for data produced by a filter +.Pq or predictor ; +or +.Dv Z_HUFFMAN_ONLY +to force Huffman encoding only +.Pq no string match . +Filtered data consists mostly of small values with a +somewhat random distribution. +In this case, the compression algorithm is tuned to compress them better. +The effect of +.Dv Z_FILTERED +is to force more Huffman coding and less string matching; +it is somewhat intermediate between +.Dv Z_DEFAULT +and +.Dv Z_HUFFMAN_ONLY . +The +.Fa strategy +parameter only affects the compression ratio but not the correctness of the +compressed output, even if it is not set appropriately. +.Pp +.Fn deflateInit2 +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if a parameter is invalid +.Pq such as an invalid method . +.Fa msg +is set to null if there is no error message. +.Fn deflateInit2 +does not perform any compression: this will be done by +.Fn deflate . +.It Xo +.Fa int +.Fn deflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" ; +.Xc +.Pp +Initializes the compression dictionary from the given byte sequence +without producing any compressed output. +This function must be called immediately after +.Fn deflateInit , +.Fn deflateInit2 , +or +.Fn deflateReset , +before any call to +.Fn deflate . +The compressor and decompressor must use exactly the same dictionary +(see +.Fn inflateSetDictionary ) . +.Pp +The dictionary should consist of strings +.Pq byte sequences +that are likely to be encountered later in the data to be compressed, +with the most commonly used strings preferably put towards +the end of the dictionary. +Using a dictionary is most useful when the data to be compressed is short +and can be predicted with good accuracy; +the data can then be compressed better than with the default empty dictionary. +.Pp +Depending on the size of the compression data structures selected by +.Fn deflateInit +or +.Fn deflateInit2 , +a part of the dictionary may in effect be discarded, +for example if the dictionary is larger than the window size in +.Fn deflate +or +.Fn deflate2 . +Thus the strings most likely to be useful should be +put at the end of the dictionary, not at the front. +.Pp +Upon return of this function, strm->adler is set to the Adler32 value +of the dictionary; the decompressor may later use this value to determine +which dictionary has been used by the compressor. +(The Adler32 value applies to the whole dictionary even if only a subset +of the dictionary is actually used by the compressor.) +.Pp +.Fn deflateSetDictionary +returns +.Dv Z_OK +if successful, +or +.Dv Z_STREAM_ERROR +if a parameter is invalid +.Pq such as NULL dictionary +or the stream state is inconsistent +(for example if +.Fn deflate +has already been called for this stream or if the compression method is bsort). +.Fn deflateSetDictionary +does not perform any compression: this will be done by +.Fn deflate . +.It Xo +.Fa int +.Fn deflateCopy "z_streamp dest" "z_streamp source" ; +.Xc +.Pp +The +.Fn deflateCopy +function sets the destination stream as a complete copy of the source stream. +.Pp +This function can be useful when several compression strategies will be +tried, for example when there are several ways of pre-processing the input +data with a filter. +The streams that will be discarded should then be freed by calling +.Fn deflateEnd . +Note that +.Fn deflateCopy +duplicates the internal compression state which can be quite large, +so this strategy is slow and can consume lots of memory. +.Pp +.Fn deflateCopy +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +(such as +.Fa zalloc +being NULL). +.Fa msg +is left unchanged in both source and destination. +.It Xo +.Fa int +.Fn deflateReset "z_streamp strm" ; +.Xc +.Pp +This function is equivalent to +.Fn deflateEnd +followed by +.Fn deflateInit , +but does not free and reallocate all the internal compression state. +The stream will keep the same compression level and any other attributes +that may have been set by +.Fn deflateInit2 . +.Pp +.Fn deflateReset +returns +.Dv Z_OK +if successful, or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +(such as +.Fa zalloc +or +.Fa state +being NULL). +.It Xo +.Fa int +.Fn deflateParams "z_streamp strm" "int level" "int strategy" ; +.Xc +.Pp +The +.Fn deflateParams +function dynamically updates the compression level and compression strategy. +The interpretation of level and strategy is as in +.Fn deflateInit2 . +This can be used to switch between compression and straight copy +of the input data, or to switch to a different kind of input data +requiring a different strategy. +If the compression level is changed, the input available so far +is compressed with the old level +.Pq and may be flushed ; +the new level will take effect only at the next call to +.Fn deflate . +.Pp +Before the call to +.Fn deflateParams , +the stream state must be set as for a call to +.Fn deflate , +since the currently available input may have to be compressed and flushed. +In particular, strm->avail_out must be non-zero. +.Pp +.Fn deflateParams +returns +.Dv Z_OK +if successful, +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent or if a parameter was invalid, or +.Dv Z_BUF_ERROR +if strm->avail_out was zero. +.It Xo +.Fa int +.Fn inflateInit2 "z_streamp strm" "int windowBits" ; +.Xc +.Pp +This is another version of +.Fn inflateInit +with an extra parameter. +The fields +.Fa next_in , +.Fa avail_in , +.Fa zalloc , +.Fa zfree , +and +.Fa opaque +must be initialized before by the caller. +.Pp +The +.Fa windowBits +parameter is the base two logarithm of the maximum window size +.Pq the size of the history buffer . +It should be in the range 8..15 for this version of the library. +The default value is 15 if +.Fn inflateInit +is used instead. +If a compressed stream with a larger window size is given as input, +.Fn inflate +will return with the error code +.Dv Z_DATA_ERROR +instead of trying to allocate a larger window. +.Pp +.Fn inflateInit2 +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if a parameter is invalid +(such as a negative +.Fa memLevel ) . +.Fa msg +is set to null if there is no error message. +.Fn inflateInit2 +does not perform any decompression apart from reading the +.Nm +header if present: this will be done by +.Fn inflate . +(So +.Fa next_in +and +.Fa avail_in +may be modified, but +.Fa next_out +and +.Fa avail_out +are unchanged.) +.It Xo +.Fa int +.Fn inflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength" ; +.Xc +.Pp +Initializes the decompression dictionary from the given uncompressed byte +sequence. +This function must be called immediately after a call to +.Fn inflate +if this call returned +.Dv Z_NEED_DICT . +The dictionary chosen by the compressor can be determined from the +Adler32 value returned by this call to +.Fn inflate . +The compressor and decompressor must use exactly the same dictionary +(see +.Fn deflateSetDictionary ) . +.Pp +.Fn inflateSetDictionary +returns +.Dv Z_OK +if successful, +.Dv Z_STREAM_ERROR +if a parameter is invalid +.Pq such as NULL dictionary +or the stream state is inconsistent, +.Dv Z_DATA_ERROR +if the given dictionary doesn't match the expected one +.Pq incorrect Adler32 value . +.Fn inflateSetDictionary +does not perform any decompression: this will be done by subsequent calls of +.Fn inflate . +.It Xo +.Fa int +.Fn inflateSync "z_streamp strm" ; +.Xc +.Pp +Skips invalid compressed data until a full flush point +(see above the description of +.Fn deflate +with +.Dv Z_FULL_FLUSH ) +can be found, or until all available input is skipped. +No output is provided. +.Pp +.Fn inflateSync +returns +.Dv Z_OK +if a full flush point has been found, +.Dv Z_BUF_ERROR +if no more input was provided, +.Dv Z_DATA_ERROR +if no flush point has been found, or +.Dv Z_STREAM_ERROR +if the stream structure was inconsistent. +In the success case, the application may save the current value of +.Fa total_in +which indicates where valid compressed data was found. +In the error case, the application may repeatedly call +.Fn inflateSync , +providing more input each time, until success or end of the input data. +.It Xo +.Fa int +.Fn inflateReset "z_streamp strm" ; +.Xc +.Pp +This function is equivalent to +.Fn inflateEnd +followed by +.Fn inflateInit , +but does not free and reallocate all the internal decompression state. +The stream will keep attributes that may have been set by +.Fn inflateInit2 . +.Pp +.Fn inflateReset +returns +.Dv Z_OK +if successful, or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +(such as +.Fa zalloc +or +.Fa state +being NULL). +.El +.Sh 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 can easily be modified +if you need special options. +.Bl -tag -width Ds +.It Xo +.Fa int +.Fn compress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" ; +.Xc +.Pp +The +.Fn compress +function compresses the source buffer into the destination buffer. +.Fa sourceLen +is the byte length of the source buffer. +Upon entry, +.Fa destLen +is the total size of the destination buffer, +which must be at least 0.1% larger than +.Fa sourceLen +plus 12 bytes. +Upon exit, +.Fa destLen +is the actual size of the compressed buffer. +This function can be used to compress a whole file at once if the +input file is mmap'ed. +.Pp +.Fn compress +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, or +.Dv Z_BUF_ERROR +if there was not enough room in the output buffer. +.It Xo +.Fa int +.Fn compress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" "int level" ; +.Xc +.Pp +The +.Fn compress2 +function compresses the source buffer into the destination buffer. +The +.Fa level +parameter has the same meaning as in +.Fn deflateInit . +.Fa sourceLen +is the byte length of the source buffer. +Upon entry, +.Fa destLen +is the total size of the destination buffer, +which must be at least 0.1% larger than +.Fa sourceLen +plus 12 bytes. +Upon exit, +.Fa destLen +is the actual size of the compressed buffer. +.Pp +.Fn compress2 +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_BUF_ERROR +if there was not enough room in the output buffer, or +.Dv Z_STREAM_ERROR +if the level parameter is invalid. +.It Xo +.Fa int +.Fn uncompress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" ; +.Xc +.Pp +The +.Fn uncompress +function decompresses the source buffer into the destination buffer. +.Fa sourceLen +is the byte length of the source buffer. +Upon entry, +.Fa destLen +is the total size of the destination buffer, +which must be large enough to hold the entire uncompressed data. +(The size of the uncompressed 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, +.Fa destLen +is the actual size of the compressed buffer. +This function can be used to decompress a whole file at once if the +input file is mmap'ed. +.Pp +.Fn uncompress +returns +.Dv Z_OK +if successful, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_BUF_ERROR +if there was not enough room in the output buffer, or +.Dv Z_DATA_ERROR +if the input data was corrupted. +.It Xo +.Fa gzFile +.Fn gzopen "const char *path" "const char *mode" ; +.Xc +.Pp +The +.Fn gzopen +function opens a gzip +.Pq .gz +file for reading or writing. +The mode parameter is as in +.Xr fopen 3 +.Pq \&"rb\&" or \&"wb\&" +but can also include a compression level +.Pq "wb9" +or a strategy: +.Sq f +for filtered data, as in +.Qq wb6f ; +.Sq h +for Huffman only compression, as in +.Qq wb1h . +(See the description of +.Fn deflateInit2 +for more information about the strategy parameter.) +.Pp +.Fn gzopen +can be used to read a file which is not in gzip format; +in this case +.Fn gzread +will directly read from the file without decompression. +.Pp +.Fn gzopen +returns +.Dv 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 distinguish the two cases (if errno is zero, the +.Nm +error is +.Dv Z_MEM_ERROR ) . +.It Xo +.Fa gzFile +.Fn gzdopen "int fd" "const char *mode" ; +.Xc +.Pp +The +.Fn gzdopen +function associates a gzFile with the file descriptor +.Fa fd . +File descriptors are obtained from calls like +.Xr open 2 , +.Xr dup 2 , +.Xr creat 3 , +.Xr pipe 2 , +or +.Xr fileno 3 +(if the file has been previously opened with +.Xr fopen 3 ) . +The +.Fa mode +parameter is as in +.Fn gzopen . +.Pp +The next call to +.Fn 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). +.Pp +.Fn gzdopen +returns +.Dv NULL +if there was insufficient memory to allocate the (de)compression state. +.It Xo +.Fa int +.Fn gzsetparams "gzFile file" "int level" "int strategy" ; +.Xc +.Pp +The +.Fn gzsetparams +function dynamically updates the compression level or strategy. +See the description of +.Fn deflateInit2 +for the meaning of these parameters. +.Pp +.Fn gzsetparams +returns +.Dv Z_OK +if successful, or +.Dv Z_STREAM_ERROR +if the file was not opened for writing. +.It Xo +.Fa int +.Fn gzread "gzFile file" "voidp buf" "unsigned len" ; +.Xc +.Pp +The +.Fn gzread +function reads the given number of uncompressed bytes from the compressed file. +If the input file was not in gzip format, +.Fn gzread +copies the given number of bytes into the buffer. +.Pp +.Fn gzread +returns the number of uncompressed bytes actually read +(0 for end of file, \-1 for error). +.It Xo +.Fa int +.Fn gzwrite "gzFile file" "const voidp buf" "unsigned len" ; +.Xc +.Pp +The +.Fn gzwrite +function writes the given number of uncompressed bytes into the compressed file. +.Fn gzwrite +returns the number of uncompressed bytes actually written +.Pq 0 in case of error . +.It Xo +.Fa int +.Fn gzprintf "gzFile file" "const char *format" "..." ; +.Xc +.Pp +The +.Fn gzprintf +function converts, formats, and writes the args to the compressed file +under control of the format string, as in +.Xr fprintf 3 . +.Fn gzprintf +returns the number of uncompressed bytes actually written +.Pq 0 in case of error . +.It Xo +.Fa int +.Fn gzputs "gzFile file" "const char *s" ; +.Xc +.Pp +The +.Fn gzputs +function writes the given null-terminated string to the compressed file, +excluding the terminating null character. +.Pp +.Fn gzputs +returns the number of characters written, or \-1 in case of error. +.It Xo +.Fa char * +.Fn gzgets "gzFile file" "char *buf" "int len" ; +.Xc +.Pp +The +.Fn gzgets +function reads bytes from the compressed file until len\-1 characters are read, +or a newline character is read and transferred to +.Fa buf , +or an end-of-file condition is encountered. +The string is then terminated with a null character. +.Pp +.Fn gzgets +returns +.Fa buf , +or +.Dv Z_NULL +in case of error. +.It Xo +.Fa int +.Fn gzputc "gzFile file" "int c" ; +.Xc +.Pp +The +.Fn gzputc +function writes +.Fa c , +converted to an unsigned char, into the compressed file. +.Fn gzputc +returns the value that was written, or \-1 in case of error. +.It Xo +.Fa int +.Fn gzgetc "gzFile file" ; +.Xc +.Pp +The +.Fn gzgetc +function reads one byte from the compressed file. +.Fn gzgetc +returns this byte or \-1 in case of end of file or error. +.It Xo +.Fa int +.Fn gzflush "gzFile file" "int flush" ; +.Xc +.Pp +The +.Fn gzflush +function flushes all pending output into the compressed file. +The parameter +.Fa flush +is as in the +.Fn deflate +function. +The return value is the +.Nm +error number (see function +.Fn gzerror +below). +.Fn gzflush +returns +.Dv Z_OK +if the flush parameter is +.Dv Z_FINISH +and all output could be flushed. +.Pp +.Fn gzflush +should be called only when strictly necessary because it can +degrade compression. +.It Xo +.Fa z_off_t +.Fn gzseek "gzFile file" "z_off_t offset" "int whence" ; +.Xc +.Pp +Sets the starting position for the next +.Fn gzread +or +.Fn gzwrite +on the given compressed file. +The offset represents a number of bytes in the uncompressed data stream. +The whence parameter is defined as in +.Xr lseek 2 ; +the value +.Dv SEEK_END +is not supported. +.Pp +If the file is opened for reading, this function is emulated but can be +extremely slow. +If the file is opened for writing, only forward seeks are supported; +.Fn gzseek +then compresses a sequence of zeroes up to the new starting position. +.Pp +.Fn gzseek +returns the resulting offset location as measured in bytes from +the beginning of the uncompressed stream, or \-1 in case of error, +in particular if the file is opened for writing and the new starting position +would be before the current position. +.It Xo +.Fa int +.Fn gzrewind "gzFile file" ; +.Xc +.Pp +The +.Fn gzrewind +function rewinds the given +.Fa file . +This function is supported only for reading. +.Pp +gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET). +.It Xo +.Fa z_off_t +.Fn gztell "gzFile file" ; +.Xc +.Pp +The +.Fn gztell +function returns the starting position for the next +.Fn gzread +or +.Fn gzwrite +on the given compressed file. +This position represents a number of bytes in the uncompressed data stream. +.Pp +gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR). +.It Xo +.Fa int +.Fn gzeof "gzFile file" ; +.Xc +.Pp +The +.Fn gzeof +function returns 1 when +.Dv EOF +has previously been detected reading the given input stream, otherwise zero. +.It Xo +.Fa int +.Fn gzclose "gzFile file" ; +.Xc +.Pp +The +.Fn gzclose +function flushes all pending output if necessary, closes the compressed file +and deallocates all the (de)compression state. +The return value is the +.Nm +error number (see function +.Fn gzerror +below). +.It Xo +.Fa const char * +.Fn gzerror "gzFile file" "int *errnum" ; +.Xc +.Pp +The +.Fn gzerror +function returns the error message for the last error which occurred on the +given compressed +.Fa file . +.Fa errnum +is set to the +.Nm +error number. +If an error occurred in the file system and not in the compression library, +.Fa errnum +is set to +.Dv Z_ERRNO +and the application may consult errno to get the exact error code. +.El +.Sh CHECKSUM FUNCTIONS +These functions are not related to compression but are exported +anyway because they might be useful in applications using the +compression library. +.Bl -tag -width Ds +.It Xo +.Fa uLong +.Fn adler32 "uLong adler" "const Bytef *buf" "uInt len" ; +.Xc +The +.Fn adler32 +function updates a running Adler-32 checksum with the bytes buf[0..len-1] +and returns the updated checksum. +If +.Fa buf +is +.Dv NULL , +this function returns the required initial value for the checksum. +.Pp +An Adler-32 checksum is almost as reliable as a CRC32 but can be computed +much faster. +Usage example: +.Bd -unfilled -offset indent +uLong adler = adler32(0L, Z_NULL, 0); + +while (read_buffer(buffer, length) != EOF) { +adler = adler32(adler, buffer, length); +} +if (adler != original_adler) error(); +.Ed +.It Xo +.Fa uLong +.Fn crc32 "uLong crc" "const Bytef *buf" "uInt len" ; +.Xc +The +.Fn crc32 +function updates a running CRC with the bytes buf[0..len-1] +and returns the updated CRC. +If +.Fa buf +is +.Dv NULL , +this function returns the required initial value for the CRC. +Pre- and post-conditioning +.Pq one's complement +is performed within this function so it shouldn't be done by the application. +Usage example: +.Bd -unfilled -offset indent +uLong crc = crc32(0L, Z_NULL, 0); + +while (read_buffer(buffer, length) != EOF) { +crc = crc32(crc, buffer, length); +} +if (crc != original_crc) error(); +.Ed +.El +.Sh STRUCTURES +.Bd -unfilled +struct internal_state; + +typedef struct z_stream_s { + Bytef *next_in; /* next input byte */ + uInt avail_in; /* number of bytes available at next_in */ + uLong total_in; /* total nb of input bytes read so far */ + + Bytef *next_out; /* next output byte should be put there */ + uInt avail_out; /* remaining free space at next_out */ + uLong total_out; /* total nb of bytes output so far */ + + char *msg; /* last error message, NULL if no error */ + struct internal_state FAR *state; /* not visible by applications */ + + alloc_func zalloc; /* used to allocate the internal state */ + free_func zfree; /* used to free the internal state */ + voidpf opaque; /* private data object passed to zalloc and zfree*/ + + int data_type; /*best guess about the data type: ascii or binary*/ + uLong adler; /* adler32 value of the uncompressed data */ + uLong reserved; /* reserved for future use */ +} z_stream; + +typedef z_stream FAR * z_streamp; +.Ed +.Pp +The application must update +.Fa next_in +and +.Fa avail_in +when +.Fa avail_in +has dropped to zero. +It must update +.Fa next_out +and +.Fa avail_out +when +.Fa avail_out +has dropped to zero. +The application must initialize +.Fa zalloc , +.Fa zfree , +and +.Fa opaque +before calling the init function. +All other fields are set by the compression library +and must not be updated by the application. +.Pp +The +.Fa opaque +value provided by the application will be passed as the first +parameter for calls to +.Fn zalloc +and +.Fn zfree . +This can be useful for custom memory management. +The compression library attaches no meaning to the +.Fa opaque +value. +.Pp +.Fa zalloc +must return +.Dv Z_NULL +if there is not enough memory for the object. +If +.Nm +is used in a multi-threaded application, +.Fa zalloc +and +.Fa zfree +must be thread safe. +.Pp +On 16-bit systems, the functions +.Fa zalloc +and +.Fa zfree +must be able to allocate exactly 65536 bytes, +but will not be required to allocate more than this if the symbol MAXSEG_64K +is defined (see +.Aq Pa zconf.h ) . +.Pp +WARNING: On MSDOS, pointers returned by +.Fa zalloc +for objects of exactly 65536 bytes *must* have their offset normalized to zero. +The default allocation function provided by this library ensures this (see +.Pa zutil.c ) . +To reduce memory requirements and avoid any allocation of 64K objects, +at the expense of compression ratio, +compile the library with -DMAX_WBITS=14 (see +.Aq Pa zconf.h ) . +.Pp +The fields +.Fa total_in +and +.Fa total_out +can be used for statistics or progress reports. +After compression, +.Fa total_in +holds the total size of the uncompressed data and may be saved for use +in the decompressor +(particularly if the decompressor wants to decompress everything +in a single step). +.Sh CONSTANTS +.Bd -unfilled +#define Z_NO_FLUSH 0 +#define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */ +#define Z_SYNC_FLUSH 2 +#define Z_FULL_FLUSH 3 +#define Z_FINISH 4 +/* Allowed flush values; see deflate() below for details */ + +#define Z_OK 0 +#define Z_STREAM_END 1 +#define Z_NEED_DICT 2 +#define Z_ERRNO (-1) +#define Z_STREAM_ERROR (-2) +#define Z_DATA_ERROR (-3) +#define Z_MEM_ERROR (-4) +#define Z_BUF_ERROR (-5) +#define Z_VERSION_ERROR (-6) +/* Return codes for the compression/decompression functions. + * Negative values are errors, + * positive values are used for special but normal events. + */ + +#define Z_NO_COMPRESSION 0 +#define Z_BEST_SPEED 1 +#define Z_BEST_COMPRESSION 9 +#define Z_DEFAULT_COMPRESSION (-1) +/* compression levels */ + +#define Z_FILTERED 1 +#define Z_HUFFMAN_ONLY 2 +#define Z_DEFAULT_STRATEGY 0 +/* compression strategy; see deflateInit2() below for details */ + +#define Z_BINARY 0 +#define Z_ASCII 1 +#define Z_UNKNOWN 2 +/* Possible values of the data_type field */ + +#define Z_DEFLATED 8 +/* The deflate compression method + * (the only one supported in this version) +*/ + +#define Z_NULL 0 /* for initializing zalloc, zfree, opaque */ + +#define zlib_version zlibVersion() +/* for compatibility with versions < 1.0.2 */ +.Ed +.Sh VARIOUS HACKS +deflateInit and inflateInit are macros to allow checking the +.Nm +version and the compiler's view of +.Fa z_stream . +.Bl -tag -width Ds +.It Xo +.Fa int +.Fn deflateInit_ "z_stream strm" "int level" "const char *version" "int stream_size" ; +.Xc +.It Xo +.Fa int +.Fn inflateInit_ "z_stream strm" "const char *version" "int stream_size" ; +.Xc +.It Xo +.Fa int +.Fo deflateInit2_ +.Fa "z_stream strm" +.Fa "int level" +.Fa "int method" +.Fa "int windowBits" +.Fa "int memLevel" +.Fa "int strategy" +.Fa "const char *version" +.Fa "int stream_size" +.Fc +.Xc +.It Xo +.Fa int +.Fn inflateInit2_ "z_stream strm" "int windowBits" "const char *version" "int stream_size" ; +.Xc +.It Xo +.Fa const char * +.Fn zError "int err" ; +.Xc +.It Xo +.Fa int +.Fn inflateSyncPoint "z_streamp z" ; +.Xc +.It Xo +.Fa const uLongf * +.Fn "get_crc_table" "void" ; +.Xc +.El +.Sh SEE ALSO +.Bl -tag -width 12n -compact +.It RFC 1950 +ZLIB Compressed Data Format Specification. +.It RFC 1951 +DEFLATE Compressed Data Format Specification. +.It RFC 1952 +GZIP File Format Specification. +.El +.Pp +.Pa http://ftp.cdrom.com/pub/infozip/zlib/ +.Sh HISTORY +This manual page is based on an HTML version of +.Aq Pa zlib.h +converted by +.An piaip Aq piaip@csie.ntu.edu.tw +and was converted to mdoc format by the OpenBSD project. +.Sh AUTHORS +.An Jean-loup Gailly Aq jloup@gzip.org +.An Mark Adler Aq madler@alumni.caltech.edu |