diff options
| -rw-r--r-- | Makefile | 1 | ||||
| -rw-r--r-- | deflateInit2.3 | 217 |
2 files changed, 218 insertions, 0 deletions
diff --git a/Makefile b/Makefile index 080484e..fca5f07 100644 --- a/Makefile +++ b/Makefile @@ -2,6 +2,7 @@ MAN += adler32.3 MAN += compress.3 MAN += crc32.3 MAN += deflate.3 +MAN += deflateInit2.3 MAN += inflate.3 MAN += uncompress.3 MAN += zlibCompileFlags.3 diff --git a/deflateInit2.3 b/deflateInit2.3 new file mode 100644 index 0000000..5cdf1fc --- /dev/null +++ b/deflateInit2.3 @@ -0,0 +1,217 @@ +.Dd November 10, 2018 +.Dt DEFLATEINIT2 3 +.Os +. +.Sh NAME +.Nm deflateInit2 +.Nd deflate compression options +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.Ft int +.Fo deflateInit2 +.Fa "z_streamp strm" +.Fa "int level" +.Fa "int method" +.Fa "int windowBits" +.Fa "int memLevel" +.Fa "int strategy" +.Fc +. +.Sh DESCRIPTION +See +.Xr deflate 3 +for a description of the +.Vt z_streamp +type. +. +.Pp +This is another version of +.Xr deflateInit 3 +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 +(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 +.Xr deflateInit 3 +is used instead. +. +.Pp +For the current implementation of +.Xr deflate 3 , +a +.Fa windowBits +value of 8 +(a window size of 256 bytes) +is not supported. +As a result, +a request for 8 +will result in 9 +(a 512-byte window). +In that case, +providing 8 to +.Xr inflateInit2 3 +will result in an error +when the zlib header with 9 +is checked against the initialization of +.Xr inflate 3 . +The remedy is to not use 8 with +.Fn deflateInit2 +with this initialization, +or at least in that case use 9 with +.Xr inflateInit2 3 . +. +.Pp +.Fa windowBits +can also be -8..-15 for raw deflate. +In this case, +.Fa -windowBits +determines the window size. +.Xr deflate 3 +will then generate raw deflate data +with no zlib header or trailer, +and will not compute a check value. +. +.Pp +.Fa windowBits +can also be greater than 15 +for optional gzip encoding. +Add 16 to +.Fa windowBits +to write a simple gzip header and trailer +around the compressed data +instead of a zlib wrapper. +The gzip header will have +no file name, +no extra data, +no comment, +no modification time (set to zero), +no header CRC, +and the operating system will be set +to the appropriate value, +if the operating system was determined at compile time. +If a gzip stream is being written, +.Fa strm->adler +is a CRC-32 instead of an Adler-32. +. +.Pp +For raw deflate or gzip encoding, +a request for a 256-byte window +is rejected as invalid, +since only the zlib header provides +a means of transmitting the window size +to the decompressor. +. +.Pp +The +.Fa memLevel +parameter specifies how much memory should be allocated +for the internal compression state. +.Fa memLevel=1 +uses minimum memory +but is slow and reduces compression ratio; +.Fa memLevel=9 +uses maximum memory for optimal speed. +The default value is 8. +See +.In 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 +(or predictor), +.Dv Z_HUFFMAN_ONLY +to force Huffman encoding only +(no string match), +or +.Dv Z_RLE +to limit match distances to one +(run-length encoding). +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_STRATEGY +and +.Dv Z_HUFFMAN_ONLY. +.Dv Z_RLE +is designed to be almost as fast as +.Dv Z_HUFFMAN_ONLY , +but give better compression for PNG image data. +The +.Fa strategy +parameter only affects the compression ratio +but not the correctness of the compressed output +even if it is not set appropriately. +.Dv Z_FIXED +prevents the use of dynamic Huffman codes, +allowing for a simpler decoder +for special applications. +. +.Pp +.Fn deflateInit2 +does not perform any compression: +this will be done by +.Xr deflate 3 . +. +.Sh RETURN VALUES +.Fn deflateInit2 +returns +.Dv Z_OK +if success, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if any parameter is invalid +(such as invalid method), +or +.Dv Z_VERSION_ERROR +if the zlib library version +.Pq Xr zlibVersion 3 +is incompatible with the version assumed by the caller +.Pq Dv ZLIB_VERSION . +.Fa msg +is set to null if there is no error message. |