diff options
| author | June McEnroe <june@causal.agency> | 2020-12-27 22:11:35 -0500 |
|---|---|---|
| committer | June McEnroe <june@causal.agency> | 2020-12-27 22:11:35 -0500 |
| commit | 98ea1a27fc5e0377b13213e009f0c236f5fe73b4 (patch) | |
| tree | 94c59aaaca157159510c1f81edba1d5e66cfdd64 /doc/zlib | |
| parent | Add "this commit" option to switch form (diff) | |
| parent | Replace Makefile with portable one (diff) | |
| download | src-98ea1a27fc5e0377b13213e009f0c236f5fe73b4.tar.gz src-98ea1a27fc5e0377b13213e009f0c236f5fe73b4.zip | |
Add 'doc/zlib/' from commit '38f010d3972db4262e7e0bcd7d6b9814f95d3538'
git-subtree-dir: doc/zlib git-subtree-mainline: db652695744cc54584296b54289166b4b21ac407 git-subtree-split: 38f010d3972db4262e7e0bcd7d6b9814f95d3538
Diffstat (limited to '')
59 files changed, 5932 insertions, 0 deletions
diff --git a/doc/zlib/Makefile b/doc/zlib/Makefile new file mode 100644 index 00000000..6cfd4a42 --- /dev/null +++ b/doc/zlib/Makefile @@ -0,0 +1,87 @@ +PREFIX ?= ~/.local +MANDIR ?= ${PREFIX}/share/man + +MAN += adler32.3 +MAN += adler32_combine.3 +MAN += compress.3 +MAN += compressBound.3 +MAN += crc32.3 +MAN += crc32_combine.3 +MAN += deflate.3 +MAN += deflateBound.3 +MAN += deflateCopy.3 +MAN += deflateEnd.3 +MAN += deflateGetDictionary.3 +MAN += deflateInit.3 +MAN += deflateInit2.3 +MAN += deflateParams.3 +MAN += deflatePending.3 +MAN += deflatePrime.3 +MAN += deflateReset.3 +MAN += deflateSetDictionary.3 +MAN += deflateSetHeader.3 +MAN += deflateTune.3 +MAN += gzbuffer.3 +MAN += gzclose.3 +MAN += gzdirect.3 +MAN += gzeof.3 +MAN += gzerror.3 +MAN += gzflush.3 +MAN += gzfread.3 +MAN += gzfwrite.3 +MAN += gzgetc.3 +MAN += gzgets.3 +MAN += gzoffset.3 +MAN += gzopen.3 +MAN += gzprintf.3 +MAN += gzputc.3 +MAN += gzputs.3 +MAN += gzread.3 +MAN += gzseek.3 +MAN += gzsetparams.3 +MAN += gzungetc.3 +MAN += gzwrite.3 +MAN += inflate.3 +MAN += inflateBack.3 +MAN += inflateBackEnd.3 +MAN += inflateBackInit.3 +MAN += inflateCopy.3 +MAN += inflateEnd.3 +MAN += inflateGetDictionary.3 +MAN += inflateGetHeader.3 +MAN += inflateInit.3 +MAN += inflateInit2.3 +MAN += inflateMark.3 +MAN += inflatePrime.3 +MAN += inflateReset.3 +MAN += inflateSetDictionary.3 +MAN += inflateSync.3 +MAN += uncompress.3 +MAN += zlibCompileFlags.3 +MAN += zlibVersion.3 + +MLINKS += adler32.3 adler32_z.3 +MLINKS += compress.3 compress2.3 +MLINKS += crc32.3 crc32_z.3 +MLINKS += gzclose.3 gzclose_r.3 +MLINKS += gzclose.3 gzclose_w.3 +MLINKS += gzerror.3 gzclearerr.3 +MLINKS += gzopen.3 gzdopen.3 +MLINKS += gzseek.3 gzrewind.3 +MLINKS += gzseek.3 gztell.3 +MLINKS += inflateReset.3 inflateReset2.3 +MLINKS += uncompress.3 uncompress2.3 + +lint: + mandoc -T lint ${MAN} | grep -v 'referenced manual not found' + +install: + install -d ${MANDIR}/man3 + install -m 644 ${MAN} ${MANDIR}/man3 + set -- ${MLINKS}; while [ -n "$$*" ]; do \ + ln -fs $$1 ${MANDIR}/man3/$$2; shift 2; done + +uninstall: + rm -f ${MAN:%=${MANDIR}/man3/%} + set -- ${MLINKS}; while [ -n "$$*" ]; do \ + rm -f ${MANDIR}/man3/$$2; shift 2; done diff --git a/doc/zlib/adler32.3 b/doc/zlib/adler32.3 new file mode 100644 index 00000000..d713d952 --- /dev/null +++ b/doc/zlib/adler32.3 @@ -0,0 +1,65 @@ +.Dd January 15, 2017 +.Dt ADLER32 3 +.Os +. +.Sh NAME +.Nm adler32 , +.Nm adler32_z +.Nd update Adler-32 checksum +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft uLong +.Fn adler32 "uLong adler" "const Bytef *buf" "uInt len" +.Ft uLong +.Fn adler32_z "uLong adler" "const Bytef *buf" "z_size_t len" +. +.Sh DESCRIPTION +Update a running Adler-32 checksum with the bytes +.Fa "buf[0..len-1]" +and return the updated checksum. +If +.Fa buf +is +.Dv Z_NULL , +this function returns +the required initial value for the checksum. +. +.Pp +An Adler-32 checksum is almost as reliable as a CRC-32 +but can be computed much faster. +. +.Pp +.Fn adler32_z +is the same as +.Fn adler32 , +but with a +.Vt size_t +length. +. +.Sh EXAMPLES +.Bd -literal -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 +. +.Sh SEE ALSO +.Xr adler32_combine 3 , +.Xr crc32 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/adler32_combine.3 b/doc/zlib/adler32_combine.3 new file mode 100644 index 00000000..861f235b --- /dev/null +++ b/doc/zlib/adler32_combine.3 @@ -0,0 +1,63 @@ +.Dd January 15, 2017 +.Dt ADLER32_COMBINE 3 +.Os +. +.Sh NAME +.Nm adler32_combine +.Nd combine Adler-32 checksums +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft uLong +.Fn adler32_combine "uLong adler1" "uLong adler2" "z_off_t len2" +. +.Sh DESCRIPTION +Combine two Adler-32 checksums into one. +For two sequences of bytes, +.Va seq1 +and +.Va seq2 +with lengths +.Va len1 +and +.Va len2 , +Adler-32 checksums were calculated for each, +.Va adler1 +and +.Va adler2 . +.Fn adler32_combine +returns the Adler-32 checksum of +.Va seq1 +and +.Va seq2 +concatenated, +requiring only +.Fa adler1 , +.Fa adler2 , +and +.Fa len2 . +Note that the +.Vt z_off_t +type +.Pq like Vt off_t +is a signed integer. +If +.Fa len2 +is negative, +the result has no meaning or utility. +. +.Sh SEE ALSO +.Xr adler32 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/compress.3 b/doc/zlib/compress.3 new file mode 100644 index 00000000..22b229ee --- /dev/null +++ b/doc/zlib/compress.3 @@ -0,0 +1,84 @@ +.Dd January 15, 2017 +.Dt COMPRESS 3 +.Os +. +.Sh NAME +.Nm compress , +.Nm compress2 +.Nd compress source buffer into destination buffer +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +. +.Ft int +.Fo compress +.Fa "Bytef *dest" +.Fa "uLongf *destLen" +.Fa "const Bytef *source" +.Fa "uLong sourceLen" +.Fc +. +.Ft int +.Fo compress2 +.Fa "Bytef *dest" +.Fa "uLongf *destLen" +.Fa "const Bytef *source" +.Fa "uLong sourceLen" +.Fa "int level" +.Fc +. +.Sh DESCRIPTION +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 the value returned by +.Fn compressBound sourceLen . +Upon exit, +.Fa destLen +is the actual size of the compressed data. +. +.Pp +.Fn compress +is equivalent to +.Fn compress2 +with a +.Fa level +parameter of +.Dv Z_DEFAULT_COMPRESSION . +. +.Sh RETURN VALUES +.Fn compress +and +.Fn compress2 +return +.Dv Z_OK +on success, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_BUF_ERROR +if there was not enough room in the output buffer, +.Dv Z_STREAM_ERROR +if the +.Fa level +parameter is invalid. +. +.Sh SEE ALSO +.Xr compressBound 3 , +.Xr deflateInit 3 , +.Xr uncompress 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/compressBound.3 b/doc/zlib/compressBound.3 new file mode 100644 index 00000000..5800e2ba --- /dev/null +++ b/doc/zlib/compressBound.3 @@ -0,0 +1,44 @@ +.Dd January 15, 2017 +.Dt COMPRESSBOUND 3 +.Os +. +.Sh NAME +.Nm compressBound +.Nd compressed size upper bound +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft uLong +.Fn compressBound "uLong sourceLen" +. +.Sh DESCRIPTION +.Fn compressBound +returns an upper bound on the compressed size after +.Xr compress 3 +or +.Xr compress2 3 +on +.Fa sourceLen +bytes. +It would be used before a +.Xr compress 3 +or +.Xr compress2 3 +call to allocate the destination buffer. +. +.Sh SEE ALSO +.Xr compress 3 , +.Xr deflateBound 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/crc32.3 b/doc/zlib/crc32.3 new file mode 100644 index 00000000..3c9cc8c4 --- /dev/null +++ b/doc/zlib/crc32.3 @@ -0,0 +1,66 @@ +.Dd January 15, 2017 +.Dt CRC32 3 +.Os +. +.Sh NAME +.Nm crc32 , +.Nm crc32_z +.Nd update CRC-32 checksum +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft uLong +.Fn crc32 "uLong crc" "const Bytef *buf" "uInt len" +.Ft uLong +.Fn crc32_z "uLong crc" "const Bytef *buf" "z_size_t len" +. +.Sh DESCRIPTION +Update a running CRC-32 with the bytes +.Fa "buf[0..len-1]" +and return the updated CRC-32. +If +.Fa buf +is +.Dv Z_NULL , +this function returns +the required initial value for the CRC. +Pre- and post-conditioning +(one's complement) +is performed within this function +so it shouldn't be done +by the application. +. +.Pp +.Fn crc32_z +is the same as +.Fn crc32 , +but with a +.Vt size_t +length. +. +.Sh EXAMPLES +.Bd -literal -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 +. +.Sh SEE ALSO +.Xr adler32 3 , +.Xr crc32_combine 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/crc32_combine.3 b/doc/zlib/crc32_combine.3 new file mode 100644 index 00000000..2f79f623 --- /dev/null +++ b/doc/zlib/crc32_combine.3 @@ -0,0 +1,54 @@ +.Dd January 15, 2017 +.Dt CRC32_COMBINE 3 +.Os +. +.Sh NAME +.Nm crc32_combine +.Nd combine CRC-32 checksums +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft uLong +.Fn crc32_combine "uLong crc1" "uLong crc2" "z_off_t len2" +. +.Sh DESCRIPTION +Combine two CRC-32 check values into one. +For two sequences of bytes, +.Va seq1 +and +.Va seq2 +with lengths +.Va len1 +and +.Va len2 , +CRC-32 check values were calculated for each, +.Va crc1 +and +.Va crc2 . +.Fn crc32_combine +returns the CRC-32 check value of +.Va seq1 +and +.Va seq2 +concatenated, +requiring only +.Fa crc1 , +.Fa crc2 , +and +.Fa len2 . +. +.Sh SEE ALSO +.Xr crc32 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflate.3 b/doc/zlib/deflate.3 new file mode 100644 index 00000000..7df313ee --- /dev/null +++ b/doc/zlib/deflate.3 @@ -0,0 +1,370 @@ +.Dd January 15, 2017 +.Dt DEFLATE 3 +.Os +. +.Sh NAME +.Nm deflate +.Nd deflate compression +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn deflate "z_streamp strm" "int flush" +. +.Sh DESCRIPTION +.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 +(reading input without producing any output) +except when forced the flush. +. +.Pp +The detailed semantics are as follows. +.Fn deflate +performs one or both of the following actions: +. +.Bl -dash +.It +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 of +.Fn deflate . +. +.It +Generate 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 flush frequently degrades the compression ratio, +so this parameter should be set only when necessary. +Some output may be provided even if +.Fa flush +is zero. +.El +. +.Pp +Before the call of +.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 +.Po +.Fa avail_out +== 0 +.Pc , +or after each call of +.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. +See +.Xr deflatePending 3 , +which can be used if desired to determine +whether or not there is more output in that case. +. +.Pp +Normally the parameter +.Fa flush +is set to +.Dv Z_NO_FLUSH , +which allows +.Fn deflate +to decide how much data to accumulate before producing output, +in order to maximize compression. +. +.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. +.Po +In particular +.Fa avail_in +is zero after the call if enough output space +has been provided before the call. +.Pc \& +Flushing may degrade compression for some compression algorithms +and so it should be used only when necessary. +This completes the current deflate block +and follows it with an empty stored block +that is three bits plus filler bits to the next byte, +followed by four bytes +(00 00 ff ff). +. +.Pp +If +.Fa flush +is set to +.Dv Z_PARTIAL_FLUSH , +all pending output is flushed to the output buffer, +but the output is not aligned to a byte boundary. +All of the input data so far will be available to the decompressor, +as for +.Dv Z_SYNC_FLUSH . +This completes the current deflate block +and follows it with an empty fixed codes block +that is 10 bits long. +This assures that enough bytes are output +in order for the decompressor to finish the block +before the empty fixed codes block. +. +.Pp +If +.Fa flush +is set to +.Dv Z_BLOCK , +a deflate block is completed and emitted, +as for +.Dv Z_SYNC_FLUSH , +but the output is not aligned on a byte boundary, +and up to seven bits of the current block +are held to be written as the next byte +after the next deflate block is completed. +In this case, +the decompressor may not be provided enough bits +at this point in order to complete decompression +of the data provided so far to the compressor. +It may need to wait for the next block to be emitted. +This is for advanced applications +that need to control the emission of deflate blocks. +. +.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 compression. +. +.Pp +If +.Fn deflate +returns with +.Fa avail_out +== 0, +this function must be called again +with the same value of the +.Fa flush +parameter +and more output space +.Po +updated +.Fa avail_out +.Pc , +until the flush is complete +.Po +.Fn deflate +returns with non-zero +.Fa avail_out +.Pc . +In the case of a +.Dv Z_FULL_FLUSH +or +.Dv Z_SYNC_FLUSH , +make sure that +.Fa avail_out +is greater than six +to avoid repeated flush markers +due to +.Fa avail_out +== 0 +on return. +. +.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 +or +.Dv Z_BUF_ERROR , +this function must be called again with +.Dv Z_FINISH +and more output space +.Pq 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 +.Xr deflateReset 3 +or +.Xr deflateEnd 3 . +. +.Pp +.Dv Z_FINISH +can be used in the first +.Fn deflate +call after +.Xr deflateInit 3 +if all the compression is to be done in a single step. +In order to complete in one call, +.Fa avail_out +must be at least the value returned by +.Xr deflateBound 3 . +Then +.Fn deflate +is guaranteed to return +.Dv Z_STREAM_END . +If not enough output space is provided, +.Fn deflate +will not return +.Dv Z_STREAM_END , +and it must be called again as described above. +. +.Pp +.Fn deflate +sets +.Fa strm->adler +to the Adler-32 checksum +of all input read so far +.Po +that is, +.Fa total_in +bytes +.Pc . +If a gzip stream is being generated, +then +.Fa strm->adler +will be the CRC-32 checksum of the input read so far. +See +.Xr deflateInit2 3 . +. +.Pp +.Fn deflate +may update +.Fa strm->data_type +if it can make a good guess +about the input data type +.Po +.Dv Z_BINARY +or +.Dv Z_TEXT +.Pc . +If in doubt, +the date is considered binary. +This field is only for information purposes +and does not affect the compression algorithm in any manner. +. +.Sh RETURN VALUES +.Fn deflate +returns +.Dv Z_OK +if some progress has been made +(more input processed or more output produced), +.Dv Z_STREAM_END +if all input has been consumed +and all output has been produced +.Po +only when +.Fa flush +is set to +.Dv Z_FINISH +.Pc , +.Dv Z_STREAM_ERROR +if the stream state was inconsistent +.Po +for example if +.Fa next_in +or +.Fa next_out +was +.Dv Z_NULL +or the state was inadvertently written over +by the application +.Pc , +or +.Dv Z_BUF_ERROR +if no progress is possible +.Po +for example +.Fa avail_in +or +.Fa avail_out +was zero +.Pc . +Note that +.Dv Z_BUF_ERROR +is not fatal, +and +.Fn deflate +can be called again with more input and more output space +to continue compressing. +. +.Sh SEE ALSO +.Xr deflateEnd 3 , +.Xr deflateInit 3 , +.Xr deflatePending 3 , +.Xr inflate 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflateBound.3 b/doc/zlib/deflateBound.3 new file mode 100644 index 00000000..63e80246 --- /dev/null +++ b/doc/zlib/deflateBound.3 @@ -0,0 +1,71 @@ +.Dd January 15, 2017 +.Dt DEFLATEBOUND 3 +.Os +. +.Sh NAME +.Nm deflateBound +.Nd compressed size upper bound +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft uLong +.Fn deflateBound "z_streamp strm" "uLong sourceLen" +. +.Sh DESCRIPTION +.Fn deflateBound +returns an upper bound +on the compressed size +after deflation of +.Fa sourceLen +bytes. +It must be called after +.Xr deflateInit 3 +or +.Xr deflateInit2 3 , +and after +.Xr deflateSetHeader 3 , +if used. +This would be used +to allocate an output buffer +for deflation in a single pass, +and so would be called before +.Xr deflate 3 . +If that first +.Fn deflate +call is provided the +.Fa sourceLen +input bytes, +an output buffer allocated +to the size returned by +.Fn deflateBound , +and the flush value +.Dv Z_FINISH , +then +.Fn deflate +is guaranteed to return +.Dv Z_STREAM_END . +Note that it is possible +for the compressed size +to be larger than the value returned by +.Fn deflateBound +if flush options other than +.Dv Z_FINISH +or +.Dv Z_NO_FLUSH +are used. +. +.Sh SEE ALSO +.Xr compressBound 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflateCopy.3 b/doc/zlib/deflateCopy.3 new file mode 100644 index 00000000..f30d6301 --- /dev/null +++ b/doc/zlib/deflateCopy.3 @@ -0,0 +1,66 @@ +.Dd January 15, 2017 +.Dt DEFLATECOPY 3 +.Os +. +.Sh NAME +.Nm deflateCopy +.Nd copy deflate stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn deflateCopy "z_streamp dest" "z_streamp source" +. +.Sh DESCRIPTION +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 +.Xr deflateEnd 3 . +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. +. +.Sh RETURN VALUES +.Fn deflateCopy +returns +.Dv Z_OK +if success, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +.Po +such as +.Fa zalloc +being +.Dv Z_NULL +.Pc . +.Fa msg +is left unchanged +in both source and destination. +. +.Sh SEE ALSO +.Xr deflateInit 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflateEnd.3 b/doc/zlib/deflateEnd.3 new file mode 100644 index 00000000..e24259a3 --- /dev/null +++ b/doc/zlib/deflateEnd.3 @@ -0,0 +1,50 @@ +.Dd January 15, 2017 +.Dt DEFLATEEND 3 +.Os +. +.Sh NAME +.Nm deflateEnd +.Nd free deflate stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn deflateEnd "z_streamp strm" +. +.Sh DESCRIPTION +All dynamically allocated data structures +for this stream are freed. +This function discards any unprocessed input +and does not flush any pending output. +. +.Sh RETURN VALUES +.Fn deflateEnd +returns +.Dv Z_OK +if success, +.Dv Z_STREAM_ERROR +if the stream state was inconsistent, +.Dv Z_DATA_ERROR +if the stream was freed prematurely +(some input or output was discarded). +In the error case, +.Fa msg +may be set but then points to a static string +(which must not be deallocated). +. +.Sh SEE ALSO +.Xr deflate 3 , +.Xr deflateInit 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflateGetDictionary.3 b/doc/zlib/deflateGetDictionary.3 new file mode 100644 index 00000000..403f6d10 --- /dev/null +++ b/doc/zlib/deflateGetDictionary.3 @@ -0,0 +1,79 @@ +.Dd January 15, 2017 +.Dt DEFLATEGETDICTIONARY 3 +.Os +. +.Sh NAME +.Nm deflateGetDictionary +.Nd deflate sliding dictionary +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fo deflateGetDictionary +.Fa "z_streamp strm" +.Fa "Bytef *dictionary" +.Fa "uInt *dictLength" +.Fc +. +.Sh DESCRIPTION +Returns the sliding dictionary +being maintained by deflate. +.Fa dictLength +is set to the number of bytes in the dictionary, +and that many bytes are copied to +.Fa dictionary . +.Fa dictionary +must have enough space, +where 32768 bytes is always enough. +If +.Fn deflateGetDictionary +is called with +.Fa dictionary +equal to +.Dv Z_NULL , +then only the dictionary length is returned, +and nothing is copied. +Similarly, +if +.Fa dictLength +is +.Dv Z_NULL , +then it is not set. +. +.Pp +.Fn deflateGetDictionary +may return a length less than the window size, +even when more than the window size in input +has been provided. +It may return up to 258 bytes less in that case, +due to how zlib's implementation of deflate +manages the sliding window and lookahead for matches, +where matches can be up to 258 bytes long. +If the application needs the last window-size bytes of input, +then that would need to be saved by the application +outside of zlib. +. +.Sh RETURN VALUES +.Fn deflateGetDictionary +returns +.Dv Z_OK +on success, +or +.Dv Z_STREAM_ERROR +if the stream state is inconsistent. +. +.Sh SEE ALSO +.Xr deflateSetDictionary 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflateInit.3 b/doc/zlib/deflateInit.3 new file mode 100644 index 00000000..a893dd91 --- /dev/null +++ b/doc/zlib/deflateInit.3 @@ -0,0 +1,178 @@ +.Dd January 15, 2017 +.Dt DEFLATEINIT 3 +.Os +. +.Sh NAME +.Nm deflateInit +.Nd initialize deflate stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +. +.Ft typedef voidpf +.Fo (*alloc_func) +.Fa "voidpf opaque" +.Fa "uInt items" +.Fa "uInt size" +.Fc +. +.Ft typedef void +.Fo (*free_func) +.Fa "voidpf opaque" +.Fa "voidpf address" +.Fc +. +.Bd -literal +typedef struct z_stream_s { + z_const Bytef *next_in; + uInt avail_in; + uLong total_in; + + Bytef *next_out; + uInt avail_out; + uLong total_out; + + z_const char *msg; + struct internal_state FAR *state; + + alloc_func zalloc; + free_func zfree; + voidpf opaque; + + int data_type; + uLong adler; + uLong reserved; +} z_stream; +.Ed +. +.Pp +.Vt typedef z_stream FAR *z_streamp; +. +.Ft int +.Fn deflateInit "z_streamp strm" "int level" +. +.Sh DESCRIPTION +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. +.Fn deflateInit +does not perform any compression: +this will be done by +.Xr deflate 3 . +. +.Pp +The compression +.Fa 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). +.Dv Z_DEFAULT_COMPRESSION +requests a default compromise between speed and compression +(currently equivalent to level 6). +. +.Pp +The fields of +.Vt z_stream +are as follows: +. +.Bl -tag -width "data_type" +.It Fa next_in +next input byte +.It Fa avail_in +number of bytes available at +.Fa next_in +.It Fa total_in +total number of input bytes read so far +.It Fa next_out +next output byte will go here +.It Fa avail_out +remaining free space at +.Fa next_out +.It Fa total_out +total number of bytes output so far +.It Fa msg +last error message, +.Dv NULL +if no error +.It Fa state +not visible by applications +.It Fa zalloc +used to allocate the internal state +.It Fa zfree +used to free the internal state +.It Fa opaque +private data object passed to +.Fa zalloc +and +.Fa zfree +.It data_type +best guess about the data type: +binary or text for +.Xr deflate 3 , +or the decoding state for +.Xr inflate 3 +.It adler +Adler-32 or CRC-32 value of the uncompressed data +.It reserved +reserved for future use +.El +. +.Sh RETURN VALUES +.Fn deflateInit +returns +.Dv Z_OK +if success, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if +.Fa level +is not a valid compression level, +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. +. +.Sh SEE ALSO +.Xr deflate 3 , +.Xr deflateCopy 3 , +.Xr deflateEnd 3 , +.Xr deflateInit2 3 , +.Xr deflatePrime 3 , +.Xr deflateReset 3 , +.Xr deflateSetDictionary 3 , +.Xr deflateTune 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflateInit2.3 b/doc/zlib/deflateInit2.3 new file mode 100644 index 00000000..6a581ef8 --- /dev/null +++ b/doc/zlib/deflateInit2.3 @@ -0,0 +1,227 @@ +.Dd January 15, 2017 +.Dt DEFLATEINIT2 3 +.Os +. +.Sh NAME +.Nm deflateInit2 +.Nd deflate compression options +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.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 +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. +. +.Sh SEE ALSO +.Xr deflate 3 , +.Xr deflateInit 3 , +.Xr deflateParams 3 , +.Xr deflateSetHeader 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflateParams.3 b/doc/zlib/deflateParams.3 new file mode 100644 index 00000000..8e770d4e --- /dev/null +++ b/doc/zlib/deflateParams.3 @@ -0,0 +1,123 @@ +.Dd January 15, 2017 +.Dt DEFLATEPARAMS 3 +.Os +. +.Sh NAME +.Nm deflateParams +.Nd update compression level and strategy +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn deflateParams "z_streamp strm" "int level" "int strategy" +. +.Sh DESCRIPTION +Dynamically update the compression level +and compression strategy. +The interpretation of +.Fa level +and +.Fa strategy +is as in +.Xr deflateInit2 3 . +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 approach +(which is a function of the level) +or the strategy is changed, +and if any input has been consumed +in a previous +.Xr deflate 3 +call, +then the input available so far is compressed +with the old level and strategy using +.Fn deflate strm Z_BLOCK . +There are three approaches +for the compression levels +0, 1..3, and 4..9 respectively. +The new level and strategy +will take effect at the next call of +.Xr deflate 3 . +. +.Pp +If a +.Fn deflate strm Z_BLOCK +is performed by +.Fn deflateParams , +and it does not have enough output space to complete, +then the parameter change will not take effect. +In this case, +.Fn deflateParams +can be called again +with the same parameters +and more output space +to try again. +. +.Pp +In order to assure a change in the parameters +on the first try, +the deflate stream should be flushed using +.Xr deflate 3 +with +.Dv Z_BLOCK +or other flush request until +.Fa strm.avail_out +is not zero, +before calling +.Fn deflateParams . +Then no more input data +should be provided before the +.Fn deflateParams +call. +If this is done, +the old level and strategy +will be applied +to the data compressed before +.Fn deflateParams , +and the new level and strategy +will be applied +to the data compressed after +.Fn deflateParams . +. +.Sh RETURN VALUES +.Fn deflateParams +returns +.Dv Z_OK +on success, +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +or if a parameter was invalid, +or +.Dv Z_BUF_ERROR +if there was not enough output space +to complete the compression +of the available input data +before a change in the strategy or approach. +Note that in the case of a +.Dv Z_BUF_ERROR , +the parameters are not changed. +A return value of +.Dv Z_BUF_ERROR +is not fatal, +in which case +.Fn deflateParams +can be retried +with more output space. +. +.Sh SEE ALSO +.Xr deflateInit2 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflatePending.3 b/doc/zlib/deflatePending.3 new file mode 100644 index 00000000..1ce40fc2 --- /dev/null +++ b/doc/zlib/deflatePending.3 @@ -0,0 +1,56 @@ +.Dd January 15, 2017 +.Dt DEFLATEPENDING 3 +.Os +. +.Sh NAME +.Nm deflatePending +.Nd pending deflate output +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn deflatePending "z_streamp strm" "unsigned *pending" "int *bits" +. +.Sh DESCRIPTION +.Fn deflatePending +returns the number of bytes and bits +of output that have been generated, +but not yet provided in the available output. +The bytes not provided would be due to +the available output space having been consumed. +The number of bits of output not provided +are between 0 and 7, +where they await more bits to join them +in order to fill out a full byte. +If +.Fa pending +or +.Fa bits +are +.Dv Z_NULL , +then those values are not set. +. +.Sh RETURN VALUES +.Fn deflatePending +returns +.Dv Z_OK +if success, +or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent. +. +.Sh SEE ALSO +.Xr deflate 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflatePrime.3 b/doc/zlib/deflatePrime.3 new file mode 100644 index 00000000..639e715a --- /dev/null +++ b/doc/zlib/deflatePrime.3 @@ -0,0 +1,64 @@ +.Dd January 15, 2017 +.Dt DEFLATEPRIME 3 +.Os +. +.Sh NAME +.Nm deflatePrime +.Nd insert bits in deflate stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn deflatePrime "z_streamp strm" "int bits" "int value" +. +.Sh DESCRIPTION +.Fn deflatePrime +inserts bits in the deflate output stream. +The intent is that this function +is used to start off the deflate output +with the bits leftover +from a previous deflate stream +when appending to it. +As such, +this function can only be used for raw deflate, +and must be used before the first +.Xr deflate 3 +call +after a +.Xr deflateInit2 3 +or +.Xr deflateReset 3 . +.Fa bits +must be less than or equal to 16, +and that many of the least significant bits of +.Fa value +will be inserted in the output. +. +.Sh RETURN VALUES +.Fn deflatePrime +returns +.Dv Z_OK +if success, +.Dv Z_BUF_ERROR +if there was not enough room +in the internal buffer +to insert the bits, +or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent. +. +.Sh SEE ALSO +.Xr deflateInit2 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflateReset.3 b/doc/zlib/deflateReset.3 new file mode 100644 index 00000000..7309ac15 --- /dev/null +++ b/doc/zlib/deflateReset.3 @@ -0,0 +1,57 @@ +.Dd January 15, 2017 +.Dt DEFLATERESET 3 +.Os +. +.Sh NAME +.Nm deflateReset +.Nd reset deflate stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn deflateReset "z_streamp strm" +. +.Sh DESCRIPTION +This function is equivalent to +.Xr deflateEnd 3 +followed by +.Xr deflateInit 3 , +but does not free and reallocate +the internal compression state. +The stream will leave the compression level +and any other attributes +that may have been set unchanged. +. +.Sh RETURN VALUES +.Fn deflateReset +returns +.Dv Z_OK +if success, +or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +.Po +such as +.Fa zalloc +or +.Fa state +being +.Dv Z_NULL +.Pc . +. +.Sh SEE ALSO +.Xr deflateEnd 3 , +.Xr deflateInit 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflateSetDictionary.3 b/doc/zlib/deflateSetDictionary.3 new file mode 100644 index 00000000..c2c9d7c2 --- /dev/null +++ b/doc/zlib/deflateSetDictionary.3 @@ -0,0 +1,142 @@ +.Dd January 15, 2017 +.Dt DEFLATESETDICTIONARY 3 +.Os +. +.Sh NAME +.Nm deflateSetDictionary +.Nd initialize compression dictionary +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fo deflateSetDictionary +.Fa "z_streamp strm" +.Fa "const Bytef *dictionary" +.Fa "uInt dictLength" +.Fc +. +.Sh DESCRIPTION +.Fn deflateSetDictionary +initializes the compression dictionary +from the given byte sequence +without producing any compressed output. +When using the zlib format, +this function must be called immediately after +.Xr deflateInit 3 , +.Xr deflateInit2 3 , +or +.Xr deflateReset 3 , +and before any call of +.Xr deflate 3 . +When doing raw deflate, +this function must be called +either before any call of +.Xr deflate 3 , +or immediately after the completion of a deflate block, +i.e. after all input has been consumed +and all output has been delivered +when using any of the flush options +.Dv Z_BLOCK , +.Dv Z_PARTIAL_FLUSH , +.Dv Z_SYNC_FLUSH , +or +.Dv Z_FULL_FLUSH . +The compressor and decompressor +must use exactly the same dictionary +.Po +see +.Xr inflateSetDictionary 3 +.Pc . +. +.Pp +The dictionary should consist of strings +(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 +.Xr deflateInit 3 +or +.Xr deflateInit2 3 , +a part of the dictionary may in effect be discarded, +for example if the dictionary is larger +than the window size provided in +.Xr deflateInit 3 +or +.Xr deflateInit2 3 . +Thus the strings most likely to be useful +should be put at the end of the dictionary, +not at the front. +In addition, +the current implementation of deflate +will use at most the window size minus 262 bytes +of the provided dictionary. +. +.Pp +Upon return of this function, +.Fa strm->adler +is set to the Adler-32 value +of the dictionary; +the decompressor may later use this value +to determine which dictionary has been used +by the compressor. +(The Adler-32 value applies to the whole dictionary +even if only a subset of the dictionary +is actually used by the compressor.) +If a raw deflate was requested, +then the Adler-32 value is not computed and +.Fa strm->adler +is not set. +. +.Pp +.Fn deflateSetDictionary +does not perform any compression: +this will be done by +.Xr deflate 3 . +. +.Sh RETURN VALUES +.Fn deflateSetDictionary +returns +.Dv Z_OK +if success, +or +.Dv Z_STREAM_ERROR +if a parameter is invalid +.Po +e.g. dictionary being +.Dv Z_NULL +.Pc +or the stream state is inconsistent +.Po +for example if +.Xr deflate 3 +has already been called for this stream +or if not at a block boundary +for raw deflate +.Pc . +. +.Sh SEE ALSO +.Xr deflateGetDictionary 3 , +.Xr inflateSetDictionary 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflateSetHeader.3 b/doc/zlib/deflateSetHeader.3 new file mode 100644 index 00000000..6fec645c --- /dev/null +++ b/doc/zlib/deflateSetHeader.3 @@ -0,0 +1,180 @@ +.Dd January 15, 2017 +.Dt DEFLATESETHEADER 3 +.Os +. +.Sh NAME +.Nm deflateSetHeader +.Nd set gzip header +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +. +.Bd -literal +typedef struct gz_header_s { + int text; + uLong time; + int xflags; + int os; + Bytef *extra; + uInt extra_len; + uInt extra_max; + Bytef *name; + uInt name_max; + Bytef *comment; + uInt comm_max; + int hcrc; + int done; +} gz_header; +.Ed +. +.Pp +.Vt typedef gz_header FAR *gz_headerp; +. +.Ft int +.Fn deflateSetHeader "z_streamp strm" "gz_headerp head" +. +.Sh DESCRIPTION +.Fn deflateSetHeader +provides gzip header information +for when a gzip stream +is requested by +.Xr deflateInit2 3 . +.Fn deflateSetHeader +may be called after +.Xr deflateInit2 3 +or +.Xr deflateReset 3 +and before the first call of +.Xr deflate 3 . +The +text, +time, +OS, +extra field, +name, +and comment +information in the provided +.Vt gz_header +structure +are written to the gzip header +.Po +.Fa xflag +is ignored \(em +the extra flags are set +according to the compression level +.Pc . +The caller must assure that, +if not +.Dv Z_NULL , +.Fa name +and +.Fa comment +are terminated with a zero byte, +and that if +.Fa extra +is not +.Dv Z_NULL , +that +.Fa extra_len +bytes are available there. +If +.Fa hcrc +is true, +a gzip header CRC is included. +Note that the current versions +of the command-line version of +.Xr gzip 1 +(up through version 1.3.x) +do not support header CRCs, +and will report that it is a +"multi-part gzip file" +and give up. +. +.Pp +If +.Fn deflateSetHeader +is not used, +the default gzip header has +text false, +the time set to zero, +and OS set to 255, +with no extra, name, or comment fields. +The gzip header is returned +to the default state by +.Xr deflateReset 3 . +. +.Pp +The fields of +.Vt gz_header +are as follows: +. +.Bl -tag -width "extra_len" +.It Fa text +true if compressed data believed to be text +.It Fa time +modification time +.It Fa xflags +extra flags +(not used when writing a gzip file) +.It Fa os +operating system +.It Fa extra +pointer to extra field or +.Dv Z_NULL +if none +.It Fa extra_len +extra field length +.Po +valid if +.Fa extra +!= +.Dv Z_NULL +.Pc +.It Fa extra_max +space at extra +(only when reading header) +.It Fa name +pointer to zero-terminated file name or +.Dv Z_NULL +.It Fa name_max +space at +.Fa name +(only when reading header) +.It Fa comment +pointer to zero-terminated comment or +.Dv Z_NULL +.It Fa comm_max +space at comment +(only when reading header) +.It Fa hcrc +true if there was or will be a header CRC +.It Fa done +true when done reading gzip header +(not used when writing a gzip file) +.El +. +.Sh RETURN VALUES +.Fn deflateSetHeader +returns +.Dv Z_OK +if success, +or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent. +. +.Sh SEE ALSO +.Xr gzip 1 , +.Xr deflateInit2 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/deflateTune.3 b/doc/zlib/deflateTune.3 new file mode 100644 index 00000000..7269dec0 --- /dev/null +++ b/doc/zlib/deflateTune.3 @@ -0,0 +1,70 @@ +.Dd January 15, 2017 +.Dt DEFLATETUNE 3 +.Os +. +.Sh NAME +.Nm deflateTune +.Nd fine tune compression parameters +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fo deflateTune +.Fa "z_streamp strm" +.Fa "int good_length" +.Fa "int max_lazy" +.Fa "int nice_length" +.Fa "int max_chain" +.Fc +. +.Sh DESCRIPTION +Fine tune deflate's internal compression parameters. +This should only be used +by someone who understands the algorithm +used by zlib's deflate +for searching for the best matching string, +and even then only by the most fanatic optimizer +trying to squeeze out the last compressed bit +for their specific input data. +Read the +.Pa deflate.c +source code for the meaning of the +.Fa max_lazy , +.Fa good_length , +.Fa nice_length , +and +.Fa max_chain +parameters. +. +.Pp +.Fn deflateTune +can be called after +.Xr deflateInit 3 +or +.Xr deflateInit2 3 . +. +.Sh RETURN VALUES +.Fn deflateTune +returns +.Dv Z_OK +on success, +or +.Dv Z_STREAM_ERROR +for an invalid deflate stream. +. +.Sh SEE ALSO +.Xr deflateInit 3 , +.Xr deflateInit2 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzbuffer.3 b/doc/zlib/gzbuffer.3 new file mode 100644 index 00000000..de7c706a --- /dev/null +++ b/doc/zlib/gzbuffer.3 @@ -0,0 +1,59 @@ +.Dd January 15, 2017 +.Dt GZBUFFER 3 +.Os +. +.Sh NAME +.Nm gzbuffer +.Nd set buffer size +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzbuffer "gzFile file" "unsigned size" +. +.Sh DESCRIPTION +Set the internal buffer size +used by this library's functions. +The default buffer size is 8192 bytes. +This function must be called after +.Xr gzopen 3 +or +.Xr gzdopen 3 , +and before any other calls +that read or write the file. +The buffer memory allocation +is always deferred to the first read or write. +Three times that size in buffer space is allocated. +A larger buffer size of, +for example, +64K or 128K bytes +will noticeably increase the speed +of decompression (reading). +. +.Pp +The new buffer size also affects +the maximum length for +.Xr gzprintf 3 . +. +.Sh RETURN VALUES +.Fn gzbuffer +returns 0 on success, +or -1 on failure, +such as being called too late. +. +.Sh SEE ALSO +.Xr gzopen 3 , +.Xr gzprintf 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzclose.3 b/doc/zlib/gzclose.3 new file mode 100644 index 00000000..77eae11e --- /dev/null +++ b/doc/zlib/gzclose.3 @@ -0,0 +1,97 @@ +.Dd January 15, 2017 +.Dt GZCLOSE 3 +.Os +. +.Sh NAME +.Nm gzclose , +.Nm gzclose_r , +.Nm gzclose_w +.Nd close compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzclose "gzFile file" +.Ft int +.Fn gzclose_r "gzFile file" +.Ft int +.Fn gzclose_w "gzFile file" +. +.Sh DESCRIPTION +Flushes all pending output if necessary, +closes the compressed file +and deallocates the (de)compression state. +Note that once +.Fa file +is closed, +you cannot call +.Xr gzerror 3 +with +.Fa file , +since its structures +have been deallocated. +.Fn gzclose +must not be called more than once +on the same file, +just as +.Xr free 3 +must not be called more than once +on the same allocation. +. +.Pp +.Fn gzclose_r +and +.Fn gzclose_w +are the same as +.Fn gzclose , +but +.Fn gzclose_r +is only for use when reading, +and +.Fn gzclose_w +is only for use when writing or appending. +The advantage to using these instead of +.Fn gzclose +is that they avoid linking in +zlib compression or decompression code +that is not used when only reading +or only writing respectively. +If +.Fn gzclose +is used, +then both compression and decompression code +will be included in the application +when linking to a static zlib library. +. +.Sh RETURN VALUES +.Fn gzclose +will return +.Dv Z_STREAM_ERROR +if +.Fa file +is not valid, +.Dv Z_ERRNO +on a file operator error, +.Dv Z_MEM_ERROR +if out of memory, +.Dv Z_BUF_ERROR +if the last read ended in the middle of a gzip stream, +or +.Dv Z_OK +on success. +. +.Sh SEE ALSO +.Xr gzopen 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzdirect.3 b/doc/zlib/gzdirect.3 new file mode 100644 index 00000000..8fa26aae --- /dev/null +++ b/doc/zlib/gzdirect.3 @@ -0,0 +1,85 @@ +.Dd January 15, 2017 +.Dt GZDIRECT 3 +.Os +. +.Sh NAME +.Nm gzdirect +.Nd check direct copy +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzdirect "gzFile file" +. +.Sh DESCRIPTION +Returns true (1) if +.Fa file +is being copied directly while reading, +or false (0) if +.Fa file +is a gzip stream being decompressed. +. +.Pp +If the input file is empty, +.Fn gzdirect +will return true, +since the input does not contain a gzip stream. +. +.Pp +If +.Fn gzdirect +is used immediately after +.Xr gzopen 3 +or +.Xr gzdopen 3 +it will cause buffers to be allocated +to allow reading the file +to determine if it is a gzip file. +Therefore if +.Xr gzbuffer 3 +is used, +it should be called before +.Fn gzdirect . +. +.Pp +When writing, +.Fn gzdirect +returns true (1) +if transparent writing was requested +.Po +.Dq wT +for the +.Xr gzopen 3 +mode +.Pc , +or false (0) otherwise. +.Po +Note: +.Fn gzdirect +is not needed when writing. +Transparent writing +must be explicitly requested, +so the application already knows the answer. +When linking statically, +using +.Fn gzdirect +will include all of the zlib code +for gzip file reading and decompression, +which may not be desired. +.Pc +. +.Sh SEE ALSO +.Xr gzopen 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzeof.3 b/doc/zlib/gzeof.3 new file mode 100644 index 00000000..26c415fe --- /dev/null +++ b/doc/zlib/gzeof.3 @@ -0,0 +1,63 @@ +.Dd January 15, 2017 +.Dt GZEOF 3 +.Os +. +.Sh NAME +.Nm gzeof +.Nd check end-of-file indicator +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzeof "gzFile file" +. +.Sh DESCRIPTION +Returns true (1) +if the end-of-file indicator +has been set while reading, +false (0) otherwise. +Note that the end-of-file indicator +is set only if the read +tried to go past the end of the input, +but came up short. +Therefore, +just like +.Xr feof 3 , +.Fn gzeof +may return false +even if there is no more data to read, +in the event that the last read request +was for the exact number of bytes +remaining in the input file. +This will happen if the input file size +is an exact multiple of the buffer size. +. +.Pp +If +.Fn gzeof +returns true, +then the read functions +will return no more data, +unless the end-of-file indicator +is reset by +.Xr gzclearerr 3 +and the input file +has grown since the previous +end of file was detected. +. +.Sh SEE ALSO +.Xr gzerror 3 , +.Xr gzread 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzerror.3 b/doc/zlib/gzerror.3 new file mode 100644 index 00000000..13dcddd4 --- /dev/null +++ b/doc/zlib/gzerror.3 @@ -0,0 +1,75 @@ +.Dd January 15, 2017 +.Dt GZERROR 3 +.Os +. +.Sh NAME +.Nm gzerror , +.Nm gzclearerr +.Nd check and reset compressed file error +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft const char * +.Fn gzerror "gzFile file" "int *errnum" +.Ft void +.Fn gzclearerr "gzFile file" +. +.Sh DESCRIPTION +.Fn gzerror +returns the error message for the last error +which occured on the given compressed file. +.Fa errnum +is set to the zlib 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 +.Va errno +to get the exact error code. +. +.Pp +The application must not modify the returned string. +Future calls to this function +may invalidate the previously returned string. +If +.Fa file +is closed, +then the string previously returned by +.Fn gzerror +will no longer be available. +. +.Pp +.Fn gzerror +should be used to distinguish errors from end-of-file +for those functions that do not distinguish those cases +in their return values. +. +.Pp +.Fn gzclearerr +clears the error and end-of-file for +.Fa file . +This is analogous to the +.Xr clearerr 3 +function in stdio. +This is useful for continuing to read a gzip file +that is being written concurrently. +. +.Sh SEE ALSO +.Xr gzeof 3 , +.Xr gzread 3 , +.Xr gzwrite 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzflush.3 b/doc/zlib/gzflush.3 new file mode 100644 index 00000000..b93c03e7 --- /dev/null +++ b/doc/zlib/gzflush.3 @@ -0,0 +1,73 @@ +.Dd January 15, 2017 +.Dt GZFLUSH 3 +.Os +. +.Sh NAME +.Nm gzflush +.Nd flush output to compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzflush "gzFile file" "int flush" +. +.Sh DESCRIPTION +Flushes all pending output +into the compressed file. +The parameter +.Fa flush +is as in the +.Xr deflate 3 +function. +.Fn gzflush +is only permitted when writing. +. +.Pp +If the +.Fa flush +parameter is +.Dv Z_FINISH , +the remaining data is written +and the gzip stream +is completed in the output. +If +.Xr gzwrite 3 +is called again, +a new gzip stream +will be started in the output. +.Xr gzread 3 +is able to read +such concatenated gzip streams. +. +.Pp +.Fn gzflush +should be called only when strictly necessary +because it will degrade compression +if called too often. +. +.Sh RETURN VALUES +The return value +is the zlib error number +.Po +see function +.Xr gzerror 3 +.Pc . +. +.Sh SEE ALSO +.Xr deflate 3 , +.Xr gzerror 3 , +.Xr gzread 3 , +.Xr gzwrite 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzfread.3 b/doc/zlib/gzfread.3 new file mode 100644 index 00000000..66231cc3 --- /dev/null +++ b/doc/zlib/gzfread.3 @@ -0,0 +1,107 @@ +.Dd January 15, 2017 +.Dt GZFREAD 3 +.Os +. +.Sh NAME +.Nm gzfread +.Nd read from compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft z_size_t +.Fn gzfread "voidp buf" "z_size_t size" "z_size_t nitems" "gzFile file" +. +.Sh DESCRIPTION +Read up to +.Fa nitems +of size +.Fa size +from +.Fa file +to +.Fa buf , +otherwise operating as +.Xr gzread 3 +does. +This duplicates the interface of stdio's +.Xr fread 3 , +with +.Vt size_t +request and return types. +If the library defines +.Vt size_t , +then +.Vt z_size_t +is identical to +.Vt size_t . +If not, +then +.Vt z_size_t +is an unsigned integer type +that can contain a pointer. +. +.Pp +In the event that the end of file is reached +and only a partial item is available at the end, +i.e. the remaining uncompressed data length +is not a multiple of +.Fa size , +then the file partial item +is nevertheless read into +.Fa buf +and the end-of-file flag is set. +The length of the partial item read +is not provided, +but could be inferred from the result of +.Xr gztell 3 . +This behavior is the same as the behavior of +.Xr fread 3 +implementations in common libraries, +but it prevents the direct use of +.Fn gzfread +to read a concurrently written file, +reseting and retrying on end-of-file, +when +.Fa size +is not 1. +. +.Sh RETURN VALUES +.Fn gzfread +returns the number of full items read of size +.Fa size , +or zero if the end of the file was reached +and a full item could not be read, +or if there was an error. +.Xr gzerror 3 +must be consulted if zero is returned +in order to determine if there was an error. +If the multiplication of +.Fa size +and +.Fa nitems +overflows, +i.e. the product does not fit in +.Vt z_size_t , +then nothing is read, +zero is returned, +and the error state is set to +.Dv Z_STREAM_ERROR . +. +.Sh SEE ALSO +.Xr gzeof 3 , +.Xr gzerror 3 , +.Xr gzopen 3 , +.Xr gzread 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzfwrite.3 b/doc/zlib/gzfwrite.3 new file mode 100644 index 00000000..38383a33 --- /dev/null +++ b/doc/zlib/gzfwrite.3 @@ -0,0 +1,75 @@ +.Dd January 15, 2017 +.Dt GZFWRITE 3 +.Os +. +.Sh NAME +.Nm gzfwrite +.Nd write to compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft z_size_t +.Fn gzfwrite "voidpc buf" "z_size_t size" "z_size_t nitems" "gzFile file" +. +.Sh DESCRIPTION +.Fn gzfwrite +writes +.Fa nitems +items of size +.Fa size +from +.Fa buf +to +.Fa file , +duplicating the interface of stdio's +.Xr fwrite 3 , +with +.Vt size_t +request and return types. +If the library defines +.Vt size_t , +then +.Vt z_size_t +is identical to +.Vt size_t . +If not, +then +.Vt z_size_t +is an unsigned integer type +that can contain a pointer. +. +.Sh RETURN VALUES +.Fn gzfwrite +returns the number of full items +written of size +.Fa size , +or zero if there was an error. +If the multiplication of +.Fa size +and +.Fa nitems +overflows, +i.e. the product does not fit in a +.Vt z_size_t , +then nothing is written, +zero is returned, +and the error state is set to +.Dv Z_STREAM_ERROR . +. +.Sh SEE ALSO +.Xr gzerror 3 , +.Xr gzopen 3 , +.Xr gzwrite 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzgetc.3 b/doc/zlib/gzgetc.3 new file mode 100644 index 00000000..93a90edd --- /dev/null +++ b/doc/zlib/gzgetc.3 @@ -0,0 +1,55 @@ +.Dd January 15, 2017 +.Dt GZGETC 3 +.Os +. +.Sh NAME +.Nm gzgetc +.Nd get character from compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzgetc "gzFile file" +. +.Sh DESCRIPTION +Reads one byte from the compressed file. +This is implemented as a macro for speed. +As such, +it does not do all of the checking +the other functions do. +I.e.\& +it does not check to see if +.Fa file +is +.Dv NULL , +nor whether the structure +.Fa file +points to has been clobbered or not. +. +.Sh RETURN VALUES +.Fn gzgetc +returns the byte +or -1 in case of +end of file +or error. +. +.Sh SEE ALSO +.Xr gzeof 3 , +.Xr gzerror 3 , +.Xr gzgets 3 , +.Xr gzopen 3 , +.Xr gzread 3 , +.Xr gzungetc 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzgets.3 b/doc/zlib/gzgets.3 new file mode 100644 index 00000000..2a329e9e --- /dev/null +++ b/doc/zlib/gzgets.3 @@ -0,0 +1,67 @@ +.Dd January 15, 2017 +.Dt GZGETS 3 +.Os +. +.Sh NAME +.Nm gzgets +.Nd read line from compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft char * +.Fn gzgets "gzFile file" "char *buf" "int len" +. +.Sh DESCRIPTION +Reads bytes from the compressed file +until +.Fa len-1 +characters are read, +or a newline character +is read and transferred to +.Fa buf , +or an end-of-file condition +is encountered. +If any characters are read or if +.Fa len +== 1, +the string is terminated +with a null character. +If no characters are read +due to an end-of-file or +.Fa len +< 1, +then the buffer is left untouched. +. +.Sh RETURN VALUES +.Fn gzgets +returns +.Fa buf +which is a null-terminated string, +or it returns +.Dv NULL +for end-of-file +or in case of error. +If there was an error, +the contents at +.Fa buf +are indeterminate. +. +.Sh SEE ALSO +.Xr gzeof 3 , +.Xr gzerror 3 , +.Xr gzgetc 3 , +.Xr gzopen 3 , +.Xr gzread 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzoffset.3 b/doc/zlib/gzoffset.3 new file mode 100644 index 00000000..cbb78a77 --- /dev/null +++ b/doc/zlib/gzoffset.3 @@ -0,0 +1,51 @@ +.Dd January 15, 2017 +.Dt GZOFFSET 3 +.Os +. +.Sh NAME +.Nm gzoffset +.Nd offset in compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft z_off_t +.Fn gzoffset "gzFile file" +. +.Sh DESCRIPTION +Returns the current offset +in the file being read or written. +This offset includes +the count of bytes +that precede the gzip stream, +for example when appending +or when using +.Xr gzdopen 3 +for reading. +When reading, +the offset does not include +as yet unused buffered input. +This information can be used +for a progress indicator. +. +.Sh RETURN VALUES +On error, +.Fn gzoffset +returns -1. +. +.Sh SEE ALSO +.Xr gzerror 3 , +.Xr gzopen 3 , +.Xr gzseek 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzopen.3 b/doc/zlib/gzopen.3 new file mode 100644 index 00000000..e3cb4cbd --- /dev/null +++ b/doc/zlib/gzopen.3 @@ -0,0 +1,261 @@ +.Dd January 15, 2017 +.Dt GZOPEN 3 +.Os +. +.Sh NAME +.Nm gzopen , +.Nm gzdopen +.Nd open gzip file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft gzFile +.Fn gzopen "const char *path" "const char *mode" +.Ft gzFile +.Fn gzdopen "int fd" "const char *mode" +. +.Sh DESCRIPTION +Opens a gzip (.gz) file +for reading or writing. +The +.Fa mode +parameter is as in +.Xr fopen 3 +.Po +.Dq rb +or +.Dq wb +.Pc +but can also include a compression level +.Pq Dq wb9 +or a strategy: +.Sq f +for filtered data as in +.Dq wb6f , +.Sq h +for Huffman-only compression as in +.Dq wb1h , +.Sq R +for run-length encoding as in +.Dq wb1R , +or +.Sq F +for fixed code compression as in +.Dq wb9F . +.Po +See the description of +.Xr deflateInit2 3 +for more information about the +.Fa strategy +parameter. +.Pc \& +.Sq T +will request transparent writing or appending +with no compression +and not using the gzip format. +. +.Pp +.Dq a +can be used instead of +.Dq w +to request that the gzip stream +that will be written +be appended to the file. +.Dq + +will result in an error, +since reading and writing +to the same gzip file +is not supported. +The addition of +.Dq x +when writing will create the file exclusively, +which fails if the file already exists. +On systems that support it, +the addition of +.Dq e +when reading or writing +will set the flag to close the file on an +.Xr execve 2 +call. +. +.Pp +These functions, +as well as +.Xr gzip 1 , +will read and decode +a sequence of gzip streams in a file. +The append function of +.Fn gzopen +can be used to create such a file. +.Po +Also see +.Xr gzflush 3 +for another way to do this. +.Pc \& +When appending, +.Fn gzopen +does not test whether the file begins with a gzip stream, +nor does it look for the end of the gzip streams +to begin appending. +.Fn gzopen +will simply append a gzip stream +to the existing file. +. +.Pp +.Fn gzopen +can be used to read a file which is not in gzip format; +in this case +.Xr gzread 3 +will directly read from the file without decompression. +When reading, +this will be detected automatically +by looking for the magic two-byte gzip header. +. +.Pp +.Fn gzdopen +associates at +.Vt gzFile +with the file descriptor +.Fa fd . +File descriptors +are obtained from calls like +.Xr open 2 , +.Xr dup 2 , +.Xr creat 2 , +.Xr pipe 2 +or +.Xr fileno 3 +.Po +if the file has been previously opened with +.Xr fopen 3 +.Pc . +The +.Fa mode +parameter is as in +.Fn gzopen . +. +.Pp +The next call of +.Xr gzclose 3 +on the returned +.Vt gzFile +will also close the file descriptor +.Fa fd , +just like +.Xr fclose 3 . +If you want to keep +.Fa fd +open, +use +.Li "fd = dup(fd_keep); gz = gzdopen(fd, mode)" . +The duplicated descriptor should be saved +to avoid a leak, +since +.Fn gzdopen +does not close +.Fa fd +if it fails. +If you are using +.Xr fileno 3 +to get the file descriptor from a +.Vt FILE * , +then you will have to use +.Xr dup 2 +to avoid double-closing +the file descriptor. +Both +.Xr gzclose 3 +and +.Xr flcose 3 +will close the associated file descriptor, +so they need to have different file descriptors. +. +.Sh RETURN VALUES +.Fn gzopen +and +.Fn gzdopen +return +.Dv NULL +if the file could not be opened, +if there was insufficient memory +to allocate the +.Vt gzFile +state, +or if an invalid +.Fa mode +was specified +.Po +an +.Sq r , +.Sq w , +or +.Sq a +was not provided, +or +.Sq + +was provided +.Pc , +or if +.Fa fd +is -1. +The file descriptor +is not used until the next +gz* read, write, seek, or close operation, +so +.Fn gzdopen +will not detect if +.Fa fd +is invalid +.Po +unless +.Fa fd +is -1 +.Pc . +.Va errno +can be checked +to determine if the reason +.Fn gzopen +failed was that the file +could not be opened. +. +.Sh ERRORS +The +.Fn gzopen +function may fail and set +.Va errno +for any of the errors specified +for the routine +.Xr fopen 3 . +. +.Sh SEE ALSO +.Xr deflateInit2 3 , +.Xr fopen 3 , +.Xr gzbuffer 3 , +.Xr gzclose 3 , +.Xr gzdirect 3 , +.Xr gzeof 3 , +.Xr gzerror 3 , +.Xr gzflush 3 , +.Xr gzgetc 3 , +.Xr gzgets 3 , +.Xr gzoffset 3 , +.Xr gzprintf 3 , +.Xr gzputc 3 , +.Xr gzputs 3 , +.Xr gzread 3 , +.Xr gzseek 3 , +.Xr gzsetparams 3 , +.Xr gzwrite 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzprintf.3 b/doc/zlib/gzprintf.3 new file mode 100644 index 00000000..26961f34 --- /dev/null +++ b/doc/zlib/gzprintf.3 @@ -0,0 +1,71 @@ +.Dd January 15, 2017 +.Dt GZPRINTF 3 +.Os +. +.Sh NAME +.Nm gzprintf +.Nd format output to compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzprintf "gzFile file" "const char *format" "..." +. +.Sh DESCRIPTION +Converts, formats, and writes the arguments +to the compressed file +under control of the format string, +as in +.Xr fprintf 3 . +. +.Sh RETURN VALUES +.Fn gzprintf +returns the number of +uncompressed bytes actually written, +or a negative zlib error code +in case of error. +The number of uncompressed bytes written +is limited to 8191, +or one less than the buffer size given to +.Xr gzbuffer 3 . +The caller should assure that +this limit is not exceeded. +If it is exceeded, +then +.Fn gzprintf +will return an error (0) +with nothing written. +In this case, +there may also be a buffer overflow +with unpredictable consequences, +which is possibly only if zlib +was compiled with the insecure functions +.Xr sprintf 3 +or +.Xr vsprintf 3 +because the secure +.Xr snprintf 3 +or +.Xr vsnprintf 3 +functions +were not available. +This can be determined using +.Xr zlibCompileFlags 3 . +. +.Sh SEE ALSO +.Xr fprintf 3 , +.Xr gzerror 3 , +.Xr gzopen 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzputc.3 b/doc/zlib/gzputc.3 new file mode 100644 index 00000000..161e5631 --- /dev/null +++ b/doc/zlib/gzputc.3 @@ -0,0 +1,43 @@ +.Dd January 15, 2017 +.Dt GZPUTC 3 +.Os +. +.Sh NAME +.Nm gzputc +.Nd write character to compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzputc "gzFile file" "int c" +. +.Sh DESCRIPTION +Writes +.Fa c , +converted to an +.Vt unsigned char , +into the compressed file. +. +.Sh RETURN VALUES +.Fn gzputc +returns the value that was written, +or -1 in case of error. +. +.Sh SEE ALSO +.Xr gzerror 3 , +.Xr gzopen 3 , +.Xr gzputs 3 , +.Xr gzwrite 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzputs.3 b/doc/zlib/gzputs.3 new file mode 100644 index 00000000..f5d1fd84 --- /dev/null +++ b/doc/zlib/gzputs.3 @@ -0,0 +1,41 @@ +.Dd January 15, 2017 +.Dt GZPUTS 3 +.Os +. +.Sh NAME +.Nm gzputs +.Nd write string to compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzputs "gzFile file" "const char *s" +. +.Sh DESCRIPTION +Writes the given null-terminated string +to the compressed file, +excluding the terminating null character. +. +.Sh RETURN VALUES +.Fn gzputs +returns the number of characters written, +or -1 in case of error. +. +.Sh SEE ALSO +.Xr gzerror 3 , +.Xr gzopen 3 , +.Xr gzputc 3 , +.Xr gzwrite 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzread.3 b/doc/zlib/gzread.3 new file mode 100644 index 00000000..84439eaa --- /dev/null +++ b/doc/zlib/gzread.3 @@ -0,0 +1,115 @@ +.Dd January 15, 2017 +.Dt GZREAD 3 +.Os +. +.Sh NAME +.Nm gzread +.Nd read from compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzread "gzFile file" "voidp buf" "unsigned len" +. +.Sh DESCRIPTION +Reads the given number of uncompressed bytes +from the compressed file. +If the input file +is not in gzip format, +.Fn gzread +copies the given number of bytes +into the buffer directly from the file. +. +.Pp +After reaching the end of a gzip stream +in the input, +.Fn gzread +will continue to read, +looking for another gzip stream. +Any number of gzip streams +may be concatenated in the input file, +and will all be decompressed by +.Fn gzread . +If something other than a gzip stream +is encountered after a gzip stream, +that remaining trailing garbage is ignored +(and no error is returned). +. +.Pp +.Fn gzread +can be used to read a gzip file +that is being concurrently written. +Upon reaching the end of the input, +.Fn gzread +will return with the available data. +If the error code returned by +.Xr gzerror 3 +is +.Dv Z_OK +or +.Dv Z_BUF_ERROR , +then +.Xr gzclearerr 3 +can be used +to clear the end of file indicator +in order to permit +.Fn gzread +to be tried again. +.Dv Z_OK +indicates that a gzip stream was completed +on the last +.Fn gzread . +.Dv Z_BUF_ERROR +indicates that the input file +ended in the middle of a gzip stream. +Note that +.Fn gzread +does not return -1 +in the event of an incomplete gzip stream. +This error is deferred until +.Xr gzclose 3 , +which will return +.Dv Z_BUF_ERROR +if the last +.Fn gzread +ended in the middle of a gzip stream. +Alternatively, +.Xr gzerror 3 +can be used before +.Xr gzclose 3 +to detect this case. +. +.Sh RETURN VALUES +.Fn gzread +returns the number of uncompressed bytes actually read, +less than +.Fa len +for end of file, +or -1 for error. +If +.Fa len +is too large to fit in an +.Vt int , +then nothing is read, +-1 is returned, +and the error state is set to +.Dv Z_STREAM_ERROR . +. +.Sh SEE ALSO +.Xr gzeof 3 , +.Xr gzerror 3 , +.Xr gzfread 3 , +.Xr gzopen 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzseek.3 b/doc/zlib/gzseek.3 new file mode 100644 index 00000000..cd85fd4c --- /dev/null +++ b/doc/zlib/gzseek.3 @@ -0,0 +1,108 @@ +.Dd January 15, 2017 +.Dt GZSEEK 3 +.Os +. +.Sh NAME +.Nm gzseek , +.Nm gzrewind , +.Nm gztell +.Nd seek compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.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" +. +.Sh DESCRIPTION +Sets the starting position +for the next +.Xr gzread 3 +or +.Xr gzwrite 3 +on the given compressed file. +The +.Fa offset +represents a number of bytes +in the uncompressed data stream. +The +.Fa 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 gzrewind +rewinds the given file. +This function is supported +only for reading. +. +.Pp +.Fn gzrewind file +is equivalent to +.Li (int) Ns Fn gzseek file 0L SEEK_SET . +. +.Pp +.Fn gztell +returns the starting position +for the next +.Xr gzread 3 +or +.Xr gzwrite 3 +on the given compressed file. +This position represents a number of bytes +in the uncompressed data stream, +and is zero when starting, +even if appending or reading +a gzip stream from the middle of a file using +.Xr gzdopen 3 . +. +.Pp +.Fn gztell file +is equivalent to +.Fn gzseek file 0L SEEK_CUR . +. +.Sh RETURN VALUES +.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. +. +.Sh SEE ALSO +.Xr gzerror 3 , +.Xr gzoffset 3 , +.Xr gzopen 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzsetparams.3 b/doc/zlib/gzsetparams.3 new file mode 100644 index 00000000..ff544d23 --- /dev/null +++ b/doc/zlib/gzsetparams.3 @@ -0,0 +1,51 @@ +.Dd January 15, 2017 +.Dt GZSETPARAMS 3 +.Os +. +.Sh NAME +.Nm gzsetparams +.Nd set compression level and strategy +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzsetparams "gzFile file" "int level" "int strategy" +. +.Sh DESCRIPTION +Dynamically update the compression level or strategy. +See the description of +.Xr deflateInit2 3 +for the meaning +of these parameters. +Previously provided data is flushed +before the parameter change. +. +.Sh RETURN VALUES +.Fn gzsetparams +returns +.Dv Z_OK +if success, +.Dv Z_STREAM_ERROR +if the file was not opened for writing, +.Dv Z_ERRNO +if there is an error writing the flushed data, +or +.Dv Z_MEM_ERROR +if there is a memory allocation error. +. +.Sh SEE ALSO +.Xr deflateInit2 3 , +.Xr gzopen 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzungetc.3 b/doc/zlib/gzungetc.3 new file mode 100644 index 00000000..90cdafc7 --- /dev/null +++ b/doc/zlib/gzungetc.3 @@ -0,0 +1,67 @@ +.Dd January 15, 2017 +.Dt GZUNGETC 3 +.Os +. +.Sh NAME +.Nm gzungetc +.Nd un-get character from compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzungetc "int c" "gzFile file" +. +.Sh DESCRIPTION +Push one character back onto the stream +to be read as the first character +on the next read. +At least one character of push-back +is allowed. +.Fn gzungetc +will fail if +.Fa c +is -1, +and may fail if a character +has been pushed +but not read yet. +If +.Fn gzungetc +is used immediately after +.Xr gzopen 3 +or +.Xr gzdopen 3 , +at least the output buffer size +of pushed characters is allowed. +.Po +See +.Xr gzbuffer 3 . +.Pc \& +The pushed character will be discarded +if the stream is repositioned with +.Xr gzseek 3 +or +.Xr gzrewind 3 . +. +.Sh RETURN VALUES +.Fn gzungetc +returns the character pushed, +or -1 on failure. +. +.Sh SEE ALSO +.Xr gzbuffer 3 , +.Xr gzerror 3 , +.Xr gzgetc 3 , +.Xr gzopen 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/gzwrite.3 b/doc/zlib/gzwrite.3 new file mode 100644 index 00000000..606d89f4 --- /dev/null +++ b/doc/zlib/gzwrite.3 @@ -0,0 +1,39 @@ +.Dd January 15, 2017 +.Dt GZWRITE 3 +.Os +. +.Sh NAME +.Nm gzwrite +.Nd write to compressed file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn gzwrite "gzFile file" "voidpc buf" "unsigned len" +. +.Sh DESCRIPTION +Writes the given number of uncompressed bytes +into the compressed file. +. +.Sh RETURN VALUES +.Fn gzwrite +returns the number of uncompressed bytes written +or 0 in case of error. +. +.Sh SEE ALSO +.Xr gzerror 3 , +.Xr gzfwrite 3 , +.Xr gzopen 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflate.3 b/doc/zlib/inflate.3 new file mode 100644 index 00000000..ca90c270 --- /dev/null +++ b/doc/zlib/inflate.3 @@ -0,0 +1,398 @@ +.Dd January 15, 2017 +.Dt INFLATE 3 +.Os +. +.Sh NAME +.Nm inflate +.Nd deflate decompression +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn inflate "z_streamp strm" "int flush" +. +.Sh DESCRIPTION +.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 +(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: +. +.Bl -dash +.It +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), +then +.Fa next_in +and +.Fa avail_in +are updated accordingly, +and processing will resume at this point +for the next call of +.Fn inflate . +. +.It +Generate 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 +.Po +see below about the +.Fa flush +parameter +.Pc . +.El +. +.Pp +Before the call of +.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 +.Fa next_* +and +.Fa avail_* +values accordingly. +If the caller of +.Fn inflate +does not provide both available input +and available output space, +it is possible that there will be no progress made. +The application can consume the uncompressed output +when it wants, +for example when the output buffer is full +.Po +.Fa avail_out +== 0 +.Pc , +or after each call of +.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 +The +.Fa flush +parameter of +.Fn inflate +can be +.Dv Z_NO_FLUSH , +.Dv Z_SYNC_FLUSH , +.Dv Z_FINISH , +.Dv Z_BLOCK , +or +.Dv Z_TREES . +.Dv Z_SYNC_FLUSH +requests that +.Fn inflate +flush as much output as possible +to the output buffer. +.Dv Z_BLOCK +requests that +.Fn inflate +stop if and when it gets to the next deflate block boundary. +When decoding the zlib or gzip format, +this will cause +.Fn inflate +to return immediately after the header +and before the first block. +When doing a raw inflate, +.Fn inflate +will go ahead and process the first block, +and will return when it gets to the end of that block, +or when it runs out of data. +. +.Pp +The +.Dv Z_BLOCK +option assists in appending to +or combining deflate streams. +To assist in this, +on return +.Fn inflate +always sets +.Fa strm->data_type +to the number of unused bits +in the last byte taken from +.Fa strm->next_in , +plus 64 if +.Fn inflate +is currently decoding the last block in the deflate stream, +plus 128 if +.Fn inflate +returned immediately after decoding an end-of-block code +or decoding the complete header up to +just before the first byte of the deflate stream. +The end-of-block will not be indicated +until all of the uncompressed data +from that block has been written to +.Fa strm->next_out . +The number of unused bits may in general be greater than seven, +except when bit 7 of +.Fa data_type +is set, +in which case the number of unused bits +will be less than eight. +.Fa data_type +is set as noted here every time +.Fn inflate +returns for all flush options, +and so can be used to determine +the amount of currently consumed input in bits. +. +.Pp +The +.Dv Z_TREES +option behaves as +.Dv Z_BLOCK +does, +but it also returns +when the end of each deflate block header is reached, +before any actual data in that block is decoded. +This allows the caller to determine +the length of the deflate block header +for later use in random access +within a deflate block. +256 is added to the value of +.Fa strm->data_type +when +.Fn inflate +returns immediately after reaching +the end of the deflate block header. +. +.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 +.Po +a single call of +.Fn inflate +.Pc , +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 of +the uncompressed data for the operation to complete. +(The size of the uncompressed data +may have been saved by the compressor for this purpose.) +The use of +.Dv Z_FINISH +is not required to perform inflation in one step. +However it may be used to inform +.Fn inflate +that a faster approach can be used for the single +.Fn inflate +call. +.Dv Z_FINISH also informs +.Fn inflate +to not maintain a sliding window +if the stream completes, +which reduces +.Fn inflate Ap s +memory footprint. +If the stream does not complete, +either because not all of the stream is provided +or not enough output space is provided, +then a sliding window will be allocated and +.Fn inflate +can be called again to continue the operation as if +.Dv Z_NO_FLUSH +had been used. +. +.Pp +In this implementation, +.Fn inflate +always flushes as much output as possible +to the output buffer, +and always uses the faster approach +on the first call. +So the effects of the +.Fa flush +parameter in this implementation +are on the return value of +.Fn inflate +as noted below, +when +.Fn inflate +returns early when +.Dv Z_BLOCK +or +.Dv Z_TREES +is used, +and when +.Fn inflate +avoids the allocation of memory +for a sliding window when +.Dv Z_FINISH +is used. +. +.Pp +If a preset dictionary is needed after this call +.Po +see +.Xr inflateSetDictionary 3 +.Pc , +.Fn inflate +sets +.Fa strm->adler +to the Adler-32 checksum of the dictionary +chosen by the compressor +and returns +.Dv Z_NEED_DICT ; +otherwise it sets +.Fa strm->adler +to the Adler-32 checksum +of all output produced so far +.Po +that is, +.Fa total_out +bytes +.Pc +and returns +.Dv Z_OK , +.Dv Z_STREAM_END +or an error code +as described in +.Sx RETURN VALUES . +At the end of the stream, +.Fn inflate +checks that its computed Adler-32 checksum +is equal to that saved by the compressor +and returns +.Dv Z_STREAM_END +only if the checksum is correct. +. +.Pp +.Fn inflate +can decompress and check +either zlib-wrapped or gzip-wrapped +deflate data. +The header type is detected automatically, +if requested when initializing with +.Xr inflateInit2 3 . +Any information contained in the gzip header +is not retained unless +.Xr inflateGetHeader 3 +is used. +When processing gzip-wrapped deflate data, +.Fa strm->adler32 +is set to the CRC-32 +of the output produced so far. +The CRC-32 is checked against the gzip trailer, +as is the uncompressed length, +modulo 2^32. +. +.Sh RETURN VALUES +.Fn inflate +returns +.Dv Z_OK +if some progress has been made +(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 +.Po +input stream not conforming to the zlib format +or incorrect check value, +in which case +.Fa strm->msg +points to a string with a more specific error +.Pc , +.Dv Z_STREAM_ERROR +if the stream structure was inconsistent +.Po +for example +.Fa next_in +or +.Fa next_out +was +.Dv Z_NULL , +or the state was inadvertently written over +by the application +.Pc , +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_BUF_ERROR +if no progress was possible +or if there was not enough room +in the output buffer when +.Dv Z_FINISH +is used. +Note that +.Dv Z_BUF_ERROR +is not fatal, +and +.Fn inflate +can be called again with more input +and more output space +to continue decompressing. +If +.Dv Z_DATA_ERROR +is returned, +the application may then call +.Xr inflateSync 3 +to look for a good compression block +if a partial recovery of the data +is to be attempted. +. +.Sh SEE ALSO +.Xr deflate 3 , +.Xr inflateBack 3 , +.Xr inflateEnd 3 , +.Xr inflateInit 3 , +.Xr inflateMark 3 , +.Xr inflateSync 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateBack.3 b/doc/zlib/inflateBack.3 new file mode 100644 index 00000000..59d5f8cb --- /dev/null +++ b/doc/zlib/inflateBack.3 @@ -0,0 +1,285 @@ +.Dd January 15, 2017 +.Dt INFLATEBACK 3 +.Os +. +.Sh NAME +.Nm inflateBack +.Nd inflate call-back interface +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +. +.Ft typedef unsigned +.Fo (*in_func) +.Fa "void FAR *" +.Fa "z_const unsigned char FAR * FAR *" +.Fc +. +.Ft typedef int +.Fo (*out_func) +.Fa "void FAR *" +.Fa "unsigned char FAR *" +.Fa "unsigned" +.Fc +. +.Ft int +.Fo inflateBack +.Fa "z_streamp strm" +.Fa "in_func in" +.Fa "void FAR *in_desc" +.Fa "out_func out" +.Fa "void FAR *out_desc" +.Fc +. +.Sh DESCRIPTION +.Fn inflateBack +does a raw inflate +with a single call +using a call-back interface +for input and output. +This is potentially more efficient than +.Xr inflate 3 +for file I/O applications, +in that it avoids copying between the output +and the sliding window +by simply making the window itself the output buffer. +.Xr inflate 3 +can be faster on modern CPUs +when used with large buffers. +.Fn inflateBack +trusts the application to not change +the output buffer passed by the output function, +at least until +.Fn inflateBack +returns. +. +.Pp +.Xr inflateBackInit 3 +must be called first +to allocate the internal state +and to initialize the state +with the user-provided window buffer. +.Fn inflateBack +may then be used multiple times +to inflate a complete, +raw deflate stream +with each call. +.Xr inflateBackEnd 3 +is then called to free the allocated state. +. +.Pp +A raw deflate stream +is one with no zlib or gzip header or trailer. +This routine would normally be used +in a utility that reads zip or gzip files +and write out uncompressed files. +The utility would decode the header +and process the trailer on its own, +hence this routine expects only +the raw deflate stream to decompress. +This is different from the default behaviour of +.Xr inflate 3 , +which expects a zlib header and trailer +around the deflate stream. +. +.Pp +.Fn inflateBack +uses two subroutines +supplied by the caller +that are then called by +.Fn inflateBack +for input and output. +.Fn inflateBack +calls those routines +until it reads a complete deflate stream +and writes out all of the uncompressed data, +or until it encounters an error. +The function's parameters and return types +are defined above in the +.Vt in_func +and +.Vt out_func +typedefs. +.Fn inflateBack +will call +.Fn in in_desc &buf +which should return +the number of bytes of provided input, +and a pointer to that input in +.Fa buf . +If there is no input available, +.Fn in +must return zero \(em +.Fa buf +is ignored in that case \(em +and +.Fn inflateBack +will return a buffer error. +.Fn inflateBack +will call +.Fn out out_desc buf len +to write the uncompressed data +.Fa buf[0..len-1] . +.Fn out +should return zero on success, +or non-zero on failure. +If +.Fn out +returns non-zero, +.Fn inflateBack +will return with an error. +Neither +.Fn in +nor +.Fn out +are permitted to change +the contents of the window provided to +.Xr inflateBackInit 3 , +which is also the buffer that +.Fn out +uses to write from. +The length written by +.Fn out +will be at most the window size. +Any non-zero amount of input +may be provided by +.Fn in . +. +.Pp +For convenience, +.Fn inflateBack +can be provided input on the first call +by setting +.Fa strm->next_in +and +.Fa strm->avail_in . +If that input is exhausted, +then +.Fn in +will be called. +Therefore +.Fa strm->next_in +must be initialized before calling +.Fn inflateBack . +If +.Fa strm->next_in +is +.Dv Z_NULL , +then +.Fn in +will be called immediately for input. +If +.Fa strm->next_in +is not +.Dv Z_NULL , +then +.Fa strm->avail_in +must also be initialized, +and then if +.Fa strm->avail_in +is not zero, +input will initially be taken from +.Fa "strm->next_in[0 .. strm->avail_in - 1]" . +. +.Pp +The +.Fa in_desc +and +.Fa out_desc +parameters of +.Fn inflateBack +is passed as the first parameter of +.Fn in +and +.Fn out +respectively when they are called. +These descriptors can be optionally used +to pass any information that the caller-supplied +.Fn in +and +.Fn out +functions need to do their job. +. +.Sh RETURN VALUES +On return, +.Fn inflateBack +will set +.Fa strm->next_in +and +.Fa strm->avail_in +to pass back any unused input +that was provided by the last +.Fn in +call. +The return values of +.Fn inflateBack +can be +.Dv Z_STREAM_END +on success, +.Dv Z_BUF_ERROR +if +.Fn in +or +.Fn out +returned an error, +.Dv Z_DATA_ERROR +if there was a format error +in the deflate stream +.Po +in which case +.Fa strm->msg +is set to indicate the nature of the error +.Pc , +or +.Dv Z_STREAM_ERROR +if the stream was not properly initialized. +In the case of +.Dv Z_BUF_ERROR , +an input or output error can be distinguished using +.Fa strm->next_in +which will be +.Dv Z_NULL +only if +.Fn in +returned an error. +If +.Fa strm->next_in +is not +.Dv Z_NULL , +then the +.Dv Z_BUF_ERROR +was due to +.Fn out +returning non-zero. +.Po +.Fn in +will always be called before +.Fn out , +so +.Fa strm->next_in +is assured to be defined if +.Fa out +returns non-zero. +.Pc \& +Note that +.Fn inflateBack +cannot return +.Dv Z_OK . +. +.Sh SEE ALSO +.Xr inflate 3 , +.Xr inflateBackEnd 3 , +.Xr inflateBackInit 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateBackEnd.3 b/doc/zlib/inflateBackEnd.3 new file mode 100644 index 00000000..eeb88636 --- /dev/null +++ b/doc/zlib/inflateBackEnd.3 @@ -0,0 +1,43 @@ +.Dd January 15, 2017 +.Dt INFLATEBACKEND 3 +.Os +. +.Sh NAME +.Nm inflateBackEnd +.Nd free inflateBack stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn inflateBackEnd "z_streamp strm" +. +.Sh DESCRIPTION +All memory allocated by +.Xr inflateBackInit 3 +is freed. +. +.Sh RETURN VALUES +.Fn inflateBackEnd +returns +.Dv Z_OK +on success, +or +.Dv Z_STREAM_ERROR +if the stream state was inconsistent. +. +.Sh SEE ALSO +.Xr inflateBack 3 , +.Xr inflateBackInit 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateBackInit.3 b/doc/zlib/inflateBackInit.3 new file mode 100644 index 00000000..483edda5 --- /dev/null +++ b/doc/zlib/inflateBackInit.3 @@ -0,0 +1,84 @@ +.Dd January 15, 2017 +.Dt INFLATEBACKINIT 3 +.Os +. +.Sh NAME +.Nm inflateBackInit +.Nd initialize inflateBack stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fo inflateBackInit +.Fa "z_streamp strm" +.Fa "int windowBits" +.Fa "unsigned char FAR *window" +.Fc +. +.Sh DESCRIPTION +Initialize the internal stream state +for decompression using +.Xr inflateBack 3 +calls. +The fields +.Fa zalloc , +.Fa zfree +and +.Fa opaque +in +.Fa strm +must be initialized before the call. +If +.Fa zalloc +and +.Fa zfree +are +.Dv Z_NULL , +then the default +library-derived memory allocation routines are used. +.Fa windowBits +is the base two logarithm of the window size, +in the range 8..15. +.Fa window +is a caller supplied buffer of that size. +Except for special applications +where it is assured that deflate +was used with small window sizes, +.Fa windowBits +must be 15 +and a 32K byte +.Fa window +must be supplied +to be able to decompress general deflate streams. +. +.Sh RETURN VALUES +.Fn inflateBackInit +will return +.Dv Z_OK +on success, +.Dv Z_STREAM_ERROR +if any of the parameters are invalid, +.Dv Z_MEM_ERROR +if the internal state could not be allocated, +or +.Dv Z_VERSION_ERROR +if the version of the library +does not match the version of the header file. +. +.Sh SEE ALSO +.Xr inflateBack 3 , +.Xr inflateBackEnd 3 , +.Xr inflateInit 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateCopy.3 b/doc/zlib/inflateCopy.3 new file mode 100644 index 00000000..53b30edf --- /dev/null +++ b/doc/zlib/inflateCopy.3 @@ -0,0 +1,59 @@ +.Dd January 15, 2017 +.Dt INFLATECOPY 3 +.Os +. +.Sh NAME +.Nm inflateCopy +.Nd copy inflate stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn inflateCopy "z_streamp dest" "z_streamp source" +. +.Sh DESCRIPTION +Sets the destination stream +as a complete copy of the source stream. +. +.Pp +This function can be useful +when randomly accessing a large stream. +The first pass through the stream +can periodically record the inflate state, +allowing restarting inflate at those points +when randomly accessing the stream. +. +.Sh RETURN VALUES +.Fn inflateCopy +returns +.Dv Z_OK +if success, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +.Po +such as +.Fa zalloc +being +.Dv Z_NULL +.Pc . +.Fa msg +is left unchanged +in both source and destination. +. +.Sh SEE ALSO +.Xr inflateInit 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateEnd.3 b/doc/zlib/inflateEnd.3 new file mode 100644 index 00000000..9b18226b --- /dev/null +++ b/doc/zlib/inflateEnd.3 @@ -0,0 +1,44 @@ +.Dd January 15, 2017 +.Dt INFLATEEND 3 +.Os +. +.Sh NAME +.Nm inflateEnd +.Nd free inflate stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn inflateEnd "z_streamp strm" +. +.Sh DESCRIPTION +All dynamically allocated data structures +for this stream are feed. +This function discards any unprocessed input +and does not flush any pending output. +. +.Sh RETURN VALUES +.Fn inflateEnd +returns +.Dv Z_OK +if success, +or +.Dv Z_STREAM_ERROR +if the stream state was inconsistent. +. +.Sh SEE ALSO +.Xr inflate 3 , +.Xr inflateInit 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateGetDictionary.3 b/doc/zlib/inflateGetDictionary.3 new file mode 100644 index 00000000..e70ee736 --- /dev/null +++ b/doc/zlib/inflateGetDictionary.3 @@ -0,0 +1,69 @@ +.Dd January 15, 2017 +.Dt INFLATEGETDICTIONARY 3 +.Os +. +.Sh NAME +.Nm inflateGetDictionary +.Nd inflate sliding dictionary +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fo inflateGetDictionary +.Fa "z_streamp strm" +.Fa "Bytef *dictionary" +.Fa "uInt *dictLength" +.Fc +. +.Sh DESCRIPTION +Returns the sliding dictionary +being maintained by +.Xr inflate 3 . +.Fa dictLength +is set to the number of bytes +in the dictionary, +and that many bytes are copied to +.Fa dictionary . +.Fa dictionary +must have enough space, +where 32768 bytes is always enough. +If +.Fn inflateGetDictionary +is called with +.Fa dictionary +equal to +.Dv Z_NULL , +then only the dictionary length is returned, +and nothing is copied. +Similarly, +if +.Fa dictLength +is +.Dv Z_NULL , +then it is not set. +. +.Sh RETURN VALUES +.Fn inflateGetDictionary +returns +.Dv Z_OK +on success, +or +.Dv Z_STREAM_ERROR +if the stream state is inconsistent. +. +.Sh SEE ALSO +.Xr deflateSetDictionary 3 , +.Xr inflateSetDictionary 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateGetHeader.3 b/doc/zlib/inflateGetHeader.3 new file mode 100644 index 00000000..f77670f2 --- /dev/null +++ b/doc/zlib/inflateGetHeader.3 @@ -0,0 +1,170 @@ +.Dd January 15, 2017 +.Dt INFLATEGETHEADER 3 +.Os +. +.Sh NAME +.Nm inflateGetHeader +.Nd get gzip header +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn inflateGetHeader "z_streamp strm" "gz_headerp head" +. +.Sh DESCRIPTION +.Fn inflateGetHeader +requests that gzip header information +be stored in the provided +.Vt gz_header +structure. +.Fn inflateGetHeader +may be called after +.Xr inflateInit2 3 +or +.Xr inflateReset 3 , +and before the first call of +.Xr inflate 3 . +As +.Xr inflate 3 +processes the gzip stream, +.Fa head->done +is zero until the header is completed, +at which time +.Fa head->done +is set to one. +If a zlib stream is being decoded, +then +.Fa head->done +is set to -1 to indicate that +there will be no gzip header information forthcoming. +Note that +.Dv Z_BLOCK +or +.Dv Z_TREES +can be used to force +.Xr inflate 3 +to return immediately after +header processing is complete +and before any actual data is decompressed. +. +.Pp +The +.Fa text , +.Fa time , +.Fa xflags , +and +.Fa os +fields are filled in with the gzip header contents. +.Fa hcrc +is set to true if there is a header CRC. +.Po +The header CRC was valid if +.Fa done +is set to one. +.Pc \& +If +.Fa extra +is not +.Dv Z_NULL , +then +.Fa extra_max +contains the maximum number of bytes to write to +.Fa extra . +Once +.Fa done +is true, +.Fa extra_len +contains the actual extra field length, +and +.Fa extra +contains the extra field, +or that field truncated if +.Fa extra_max +is less than +.Fa extra_len . +If +.Fa name +is not +.Dv Z_NULL , +then up to +.Fa name_max +characters are written there, +terminated with a zero +unless the length is greater than +.Fa name_max . +If +.Fa comment +is not +.Dv Z_NULL , +then up to +.Fa comm_max +characters are written there, +terminated with a zero +unless the length is greater than +.Fa comm_max . +When any of +.Fa extra , +.Fa name , +or +.Fa comment +are not +.Dv Z_NULL +and the respective field +is not present in the header, +then that field is set to +.Dv Z_NULL +to signal its absence. +This allows the use of +.Xr deflateSetHeader 3 +with the returned structure +to duplicate the header. +However if those fields are set to allocated memory, +then the application will need to +save those pointers elsewhere +so that they can be eventually feed. +. +.Pp +If +.Fn inflateGetHeader +is not used, +then the header information is simply discarded. +The header is always checked for validity, +including the header CRC if present. +.Xr inflateReset 3 +will reset the process to discard the header information. +The application would need to call +.Fn inflateGetHeader +again to retrieve the header from the next gzip stream. +. +.Pp +The +.Vt gz_headerp +type is documented in +.Xr deflateSetHeader 3 . +. +.Sh RETURN VALUES +.Fn inflateGetHeader +returns +.Dv Z_OK +if success, +or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent. +. +.Sh SEE ALSO +.Xr gzip 1 , +.Xr deflateSetHeader 3 , +.Xr inflateInit2 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateInit.3 b/doc/zlib/inflateInit.3 new file mode 100644 index 00000000..186b058a --- /dev/null +++ b/doc/zlib/inflateInit.3 @@ -0,0 +1,101 @@ +.Dd January 15, 2017 +.Dt INFLATEINIT 3 +.Os +. +.Sh NAME +.Nm inflateInit +.Nd initialize inflate stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn inflateInit "z_streamp strm" +. +.Sh DESCRIPTION +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. +In the current version of +.Fn inflateInit , +the provided input is not read or consumed. +The allocation of a sliding window +will be deferred to the first call of +.Xr inflate 3 +(if the decompression does not complete on the first call). +If +.Fa zalloc +and +.Fa zfree +are set to +.Dv Z_NULL , +.Fn inflateInit +updates them to use default allocation functions. +. +.Pp +.Fn inflateInit +does not perform any decompression. +Actual decompression will be done by +.Xr inflate 3 . +So +.Fa next_in , +.Fa avail_in , +.Fa next_out +and +.Fa avail_out +are unused and unchanged. +The current implementation of +.Fn inflateInit +does not process any header information \(em +that is deferred until +.Xr inflate 3 +is called. +. +.Pp +The +.Vt z_streamp +type is documented in +.Xr deflateInit 3 . +. +.Sh RETURN VALUES +.Fn inflateInit +returns +.Dv Z_OK +if success, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_VERSION_ERROR +if the zlib library version +is incompatible with the version assumed by the caller, +or +.Dv Z_STREAM_ERROR +if the parameters are invalid, +such as a null pointer to the structure. +.Fa msg +is set to null if there is no error message. +. +.Sh SEE ALSO +.Xr inflate 3 , +.Xr inflateBackInit 3 , +.Xr inflateCopy 3 , +.Xr inflateEnd 3 , +.Xr inflateInit2 3 , +.Xr inflateSetDictionary 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateInit2.3 b/doc/zlib/inflateInit2.3 new file mode 100644 index 00000000..a630f12a --- /dev/null +++ b/doc/zlib/inflateInit2.3 @@ -0,0 +1,181 @@ +.Dd January 15, 2017 +.Dt INFLATEINIT2 3 +.Os +. +.Sh NAME +.Nm inflateInit2 +.Nd inflate compression options +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn inflateInit2 "z_streamp strm" "int windowBits" +. +.Sh DESCRIPTION +This is another version of +.Xr inflateInit 3 +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 +(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 +.Xr inflateInit 3 +is used instead. +.Fa windowBits +must be greater than or equal to the +.Fa windowBits +value provided to +.Xr deflateInit2 3 +while compressing, +or it must be equal to 15 if +.Xr deflateInit2 3 +was not used. +If a compressed stream with a larger window size +is given as input, +.Xr inflate 3 +will return with the error code +.Dv Z_DATA_ERROR +instead of trying to allocate a larger window. +. +.Pp +.Fa windowBits +can also be zero +to request that +.Xr inflate 3 +use the window size +in the zlib header +of the compressed stream. +. +.Pp +.Fa windowBits +can also be -8..-15 +for raw inflate. +In this case, +.Fa -windowBits +determines the window size. +.Xr inflate 3 +will then process raw deflate data, +not looking for a zlib or gzip header, +not generating a check value, +and not looking for any check values +for comparison at the end of the stream. +This is for use with other formats +that use the deflate compressed data format +such as zip. +Those formats provide their own check values. +If a custom format is developed +using the raw deflate format for compressed data, +it is recommended that a check value +such as an Adler-32 or a CRC-32 +be applied to the uncompressed data +as is done in the zlib, gzip and zip formats. +For most applications, +the zlib format should be used as is. +Note that comments above on the use in +.Xr deflateInit2 3 +applies to the magnitude of +.Fa windowBits . +. +.Pp +.Fa windowBits +can also be greater than 15 +for optional gzip decoding. +Add 32 to +.Fa windowBits +to enable zlib and gzip decoding +with automatic header detection, +or add 16 to decode only the gzip format +.Po +the zlib format will return a +.Dv Z_DATA_ERROR +.Pc . +If a gzip stream is being decoded, +.Fa strm->adler +is a CRC-32 instead of an Adler-32. +Unlike the +.Xr gunzip 1 +utility and +.Xr gzread 3 , +.Xr inflate 3 +will not automatically decode +concatenated gzip streams. +.Xr inflate 3 +will return +.Dv Z_STREAM_END +at the end of the gzip stream. +The state would need to be reset +to continue decoding a subsequent gzip stream. +. +.Pp +.Fn inflateInit2 +does not perform any decompression +apart from possibly reading the zlib header if present: +actual decompression will be done by +.Xr inflate 3 . +.Po +So +.Fa next_in +and +.Fa avail_in +may be modified, +but +.Fa next_out +and +.Fa avail_out +are unused and unchanged. +.Pc \& +The current implementation of +.Fn inflateInit2 +does not process any header information \(em +that is deferred until +.Xr inflate 3 +is called. +. +.Sh RETURN VALUES +.Fn inflateInit2 +returns +.Dv Z_OK +if success, +.Dv Z_MEM_ERROR +if there was not enough memory, +.Dv Z_VERSION_ERROR +if the zlib library version +is incompatible with the version assumed by the caller, +or +.Dv Z_STREAM_ERROR +if the parameters are invalid, +such as a null pointer to the structure. +.Fa msg +is set to null if there is no error message. +. +.Sh SEE ALSO +.Xr deflateInit2 3 , +.Xr inflateInit 3 , +.Xr inflatePrime 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateMark.3 b/doc/zlib/inflateMark.3 new file mode 100644 index 00000000..2d15993d --- /dev/null +++ b/doc/zlib/inflateMark.3 @@ -0,0 +1,88 @@ +.Dd January 15, 2017 +.Dt INFLATEMARK 3 +.Os +. +.Sh NAME +.Nm inflateMark +.Nd mark location for random access +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft long +.Fn inflateMark "z_streamp strm" +. +.Sh DESCRIPTION +This function returns two values, +one in the lower 16 bits of the return value, +and the other in the remaining upper bits, +obtained by shifting the return value down 16 bits. +If the upper value is -1 +and the lower value is zero, +then +.Xr inflate 3 +is currently decoding information outside of a block. +If the upper value is -1 +and the lower value is non-zero, +then +.Xr inflate 3 +is in the middle of a stored block, +with the lower value equaling +the number of bytes from the input remaining to copy. +If the upper value is not -1, +then it is the number of bits +back from the current bit position +in the input of the code +(literal of length/distance pair) +currently being processed. +In that case the lower value +is the number of bytes +already emitted for that code. +. +.Pp +A code is being processed if +.Xr inflate 3 +is waiting for more input to complete +decoding of the code, +or if it has completed decoding +but is waiting for more output space +to write the literal or match data. +. +.Pp +.Fn inflateMark +is used to mark locations in the input data +for random access, +which may be at bit positions, +and to note those cases where +the output of a code may span boundaries +of random access blocks. +The current location in the input stream +can be determined from +.Fa avail_in +and +.Fa data_type +as noted in the description for the +.Dv Z_BLOCK +.Fa flush +parameter for +.Xr inflate 3 . +. +.Sh RETURN VALUES +.Fn inflateMark +returns the value noted above, +or -65536 if the provided source stream state was inconsistent. +. +.Sh SEE ALSO +.Xr inflate 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflatePrime.3 b/doc/zlib/inflatePrime.3 new file mode 100644 index 00000000..c89dc2c5 --- /dev/null +++ b/doc/zlib/inflatePrime.3 @@ -0,0 +1,73 @@ +.Dd January 15, 2017 +.Dt INFLATEPRIME 3 +.Os +. +.Sh NAME +.Nm inflatePrime +.Nd insert bits in inflate stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn inflatePrime "z_streamp strm" "int bits" "int value" +. +.Sh DESCRIPTION +This function inserts bits +in the inflate input stream. +The intent is that this function +is used to start inflating +at a bit position +in the middle of a byte. +The provided bits will be used +before any bytes are used from +.Fa next_in . +This function should only be used with raw inflate, +and should be used before the first +.Xr inflate 3 +call after +.Xr inflateInit2 3 +or +.Xr inflateReset 3 . +.Fa bits +must be less than or equal to 16, +and that many of the least significant bits of +.Fa value +will be inserted in the input. +. +.Pp +If +.Fa bits +is negative, +then the input stream bit buffer is emptied. +Then +.Fn inflatePrime +can be called again +to put bits in the buffer. +This is used to clear out bits leftover +after feeding inflate a block description +prior to feeding inflate codes. +. +.Sh RETURN VALUES +.Fn inflatePrime +returns +.Dv Z_OK +if success, +or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent. +. +.Sh SEE ALSO +.Xr inflateInit2 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateReset.3 b/doc/zlib/inflateReset.3 new file mode 100644 index 00000000..a8d2e219 --- /dev/null +++ b/doc/zlib/inflateReset.3 @@ -0,0 +1,81 @@ +.Dd January 15, 2017 +.Dt INFLATERESET 3 +.Os +. +.Sh NAME +.Nm inflateReset , +.Nm inflateReset2 +.Nd reset inflate stream +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn inflateReset "z_streamp strm" +.Ft int +.Fn inflateReset2 "z_streamp strm" "int windowBits" +. +.Sh DESCRIPTION +This function is equivalent to +.Xr inflateEnd 3 +followed by +.Xr inflateInit 3 , +but does not free and reallocate +the internal decompression state. +The stream will keep attributes +that may have been set by +.Xr inflateInit2 3 . +. +.Pp +.Fn inflateReset2 +is the same as +.Fn inflateReset , +but it also permits changing +the wrap and window size requests. +The +.Fa windowBits +parameter is interpreted the same as it is for +.Xr inflateInit2 3 . +If the window size is changed, +then the memory allocated for the window is freed, +and the window will be reallocated by +.Xr inflate 3 +if needed. +. +.Sh RETURN VALUES +.Fn inflateReset +and +.Fn inflateReset2 +return +.Dv Z_OK +if success, +or +.Dv Z_STREAM_ERROR +if the source stream state was inconsistent +.Po +such as +.Fa zalloc +or +.Fa state +being +.Dv Z_NULL +.Pc , +or if the +.Fa windowBits +parameter is invalid. +. +.Sh SEE ALSO +.Xr inflateEnd 3 , +.Xr inflateInit 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateSetDictionary.3 b/doc/zlib/inflateSetDictionary.3 new file mode 100644 index 00000000..0e3c60c7 --- /dev/null +++ b/doc/zlib/inflateSetDictionary.3 @@ -0,0 +1,85 @@ +.Dd January 15, 2017 +.Dt INFLATESETDICTIONARY 3 +.Os +. +.Sh NAME +.Nm inflateSetDictionary +.Nd initialize decompression dictionary +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fo inflateSetDictionary +.Fa "z_streamp strm" +.Fa "const Bytef *dictionary" +.Fa "uInt dictLength" +.Fc +. +.Sh DESCRIPTION +Initializes the decompression dictionary +from the given uncompressed byte sequence. +This function must be called +immediately after a call of +.Xr inflate 3 , +if that call returned +.Dv Z_NEED_DICT . +The dictionary chosen by the compressor +can be determined from the Adler-32 value +returned by that call of +.Xr inflate 3 . +The compressor and decompressor +must use exactly the same dictionary +.Po +see +.Xr deflateSetDictionary 3 +.Pc . +For raw inflate, +this function can be called at any time +to set the dictionary. +If the provided dictionary +is smaller than the window +and there is already data in the window, +then the provided dictionary +will amend what's there. +The application must insure that the dictionary +that was used for compression is provided. +. +.Pp +.Fn inflateSetDictionary +does not perform any decompression: +this will be done by subsequent calls of +.Xr inflate 3 . +. +.Sh RETURN VALUES +.Fn inflateSetDictionary +returns +.Dv Z_OK +if success, +.Dv Z_STREAM_ERROR +if a parameter is invalid +.Po +e.g. dictionary being +.Dv Z_NULL +.Pc +or the stream state is inconsistent, +.Dv Z_DATA_ERROR +if the given dictionary +doesn't match the expected one +(incorrect Adler-32 value). +. +.Sh SEE ALSO +.Xr deflateGetDictionary 3 , +.Xr inflateGetDictionary 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/inflateSync.3 b/doc/zlib/inflateSync.3 new file mode 100644 index 00000000..35264ddd --- /dev/null +++ b/doc/zlib/inflateSync.3 @@ -0,0 +1,72 @@ +.Dd January 15, 2017 +.Dt INFLATESYNC 3 +.Os +. +.Sh NAME +.Nm inflateSync +.Nd skip invalid data +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft int +.Fn inflateSync "z_streamp strm" +. +.Sh DESCRIPTION +Skips invalid compressed data +until a possible full flush point +.Po +see +.Xr deflate 3 +for the description of +.Dv Z_FULL_FLUSH +.Pc +can be found, +or until all available input is skipped. +No output is provided. +. +.Pp +.Fn inflateSync +searches for a 00 00 FF FF pattern +in the compressed data. +All full flush points have this pattern, +but not all occurrences of this pattern +are full flush points. +. +.Sh RETURN VALUES +.Fn inflateSync +returns +.Dv Z_OK +if a possible 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 the end of the input data. +. +.Sh SEE ALSO +.Xr deflate 3 , +.Xr inflate 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/uncompress.3 b/doc/zlib/uncompress.3 new file mode 100644 index 00000000..d951da9b --- /dev/null +++ b/doc/zlib/uncompress.3 @@ -0,0 +1,92 @@ +.Dd January 15, 2017 +.Dt UNCOMPRESS 3 +.Os +. +.Sh NAME +.Nm uncompress , +.Nm uncompress2 +.Nd decompress source buffer into destination buffer +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +. +.Ft int +.Fo uncompress +.Fa "Bytef *dest" +.Fa "uLongf *destLen" +.Fa "const Bytef *source" +.Fa "uLong sourceLen" +.Fc +. +.Ft int +.Fo uncompress2 +.Fa "Bytef *dest" +.Fa "uLongf *destLen" +.Fa "const Bytef *source" +.Fa "uLong *sourceLen" +.Fc +. +.Sh DESCRIPTION +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. +.Po +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. +.Pc \& +Upon exit, +.Fa destLen +is the actual size of the uncompressed data. +. +.Pp +.Fn uncompress2 +is the same as +.Fn uncompress , +except that +.Fa sourceLen +is a pointer, +where the length of the source is +.Fa *sourceLen . +On return, +.Fa *sourceLen +is the number of source bytes consumed. +. +.Sh RETURN VALUES +.Fn uncompress +returns +.Dv Z_OK +if success, +.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 or incomplete. +In the case where there is not enough room, +.Fn uncompress +will fill the output buffer +with the uncompressed data up to that point. +. +.Sh SEE ALSO +.Xr compress 3 , +.Xr inflate 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/zlibCompileFlags.3 b/doc/zlib/zlibCompileFlags.3 new file mode 100644 index 00000000..465195c2 --- /dev/null +++ b/doc/zlib/zlibCompileFlags.3 @@ -0,0 +1,163 @@ +.Dd January 15, 2017 +.Dt ZLIBCOMPILEFLAGS 3 +.Os +. +.Sh NAME +.Nm zlibCompileFlags +.Nd zlib compile-time options +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft uLong +.Fn zlibCompileFlags void +. +.Sh DESCRIPTION +Return flags indicating compile-time options. +. +.Ss Type sizes +Two bits each, +00 = 16 bits, +01 = 32 bits, +10 = 64 bits, +11 = other. +. +.Pp +.Bl -tag -width Ds -compact +.It 1.0 +size of +.Vt uInt +.It 3.2 +size of +.Vt uLong +.It 5.4 +size of +.Vt voidpf +(pointer) +.It 7.6 +size of +.Vt z_off_t +.El +. +.Ss Compiler, assembler, and debug options +.Bl -tag -width Ds -compact +.It 8 +.Dv ZLIB_DEBUG +.It 9 +.Dv ASMV +or +.Dv ASMINF +\(em +use ASM code +.It 10 +.Dv ZLIB_WINAPI +\(em +exported functions use the WINAPI calling convention +.It 11 +0 (reserved) +.El +. +.Ss One-time table building +Smaller code, +but not thread-safe if true. +. +.Pp +.Bl -tag -width Ds -compact +.It 12 +.Dv BUILDFIXED +\(em +build static block decoding tables when needed +.It 13 +.Dv DYNAMIC_CRC_TABLE +\(em +build CRC calculation tables when needed +.It 14,15 +0 (reserved) +.El +. +.Ss Library content +Indicates missing functionality. +. +.Pp +.Bl -tag -width Ds -compact +.It 16 +.Dv NO_GZCOMPRESS +\(em +gz* functions cannot compress +(to avoid linking deflate code when not needed) +.It 17 +.Dv NO_GZIP +\(em +.Xr deflate 3 +can't write gzip streams, +and +.Xr inflate 3 +can't detect and decode gzip streams +(to avoid linking crc code) +.It 18-19 +0 (reserved) +.El +. +.Ss Operation variations +Changes in library functionality. +. +.Pp +.Bl -tag -width Ds -compact +.It 20 +.Dv PKZIP_BUG_WORKAROUND +\(em +slightly more permissive +.Xr inflate 3 +.It 21 +.Dv FASTEST +\(em +deflate algorithm with only one, +lowest compression level +.It 22,23 +0 (reserved) +.El +. +.Ss sprintf variant used by gzprintf +Zero is best. +. +.Pp +.Bl -tag -width Ds -compact +.It 24 +0 = vs*, +1 = s* +\(em +1 means limited to 20 arguments after the format +.It 25 +0 = *nprintf, +1 = *printf +\(em +1 means +.Xr gzprintf 3 +not secure! +.It 26 +0 = returns value, +1 = void +\(em +1 means inferred string length returned +.El +. +.Ss Remainder +.Bl -tag -width Ds -compact +.It 27-31 +0 (reserved) +.El +. +.Sh SEE ALSO +.Xr zlibVersion 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu diff --git a/doc/zlib/zlibVersion.3 b/doc/zlib/zlibVersion.3 new file mode 100644 index 00000000..35a9854b --- /dev/null +++ b/doc/zlib/zlibVersion.3 @@ -0,0 +1,45 @@ +.Dd January 15, 2017 +.Dt ZLIBVERSION 3 +.Os +. +.Sh NAME +.Nm zlibVersion +.Nd check zlib version +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Fd #define ZLIB_VERSION \(dq1.2.11\(dq +.Ft "const char *" +.Fn zlibVersion void +. +.Sh DESCRIPTION +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 +.In zlib.h +header file used by the application. +This check is automatically made by +.Xr deflateInit 3 +and +.Xr inflateInit 3 . +. +.Sh SEE ALSO +.Xr zlibCompileFlags 3 +. +.Sh HISTORY +This manual page was converted from +.In zlib.h +to mdoc format by +.An C. McEnroe Aq Mt june@causal.agency . +. +.Sh AUTHORS +.An Jean-loup Gailly Aq Mt jloup@gzip.org +.An Mark Adler Aq Mt madler@alumni.caltech.edu |