Add inflate.3

4 files changed, 469 insertions, 0 deletions

diff --git a/Makefile b/Makefile
index 68863a8..080484e 100644
--- a/Makefile
+++ b/Makefile
@@ -2,6 +2,7 @@ MAN += adler32.3
 MAN += compress.3
 MAN += crc32.3
 MAN += deflate.3
+MAN += inflate.3
 MAN += uncompress.3
 MAN += zlibCompileFlags.3
 MAN += zlibVersion.3
@@ -14,6 +15,8 @@ MLINKS += crc32.3 crc32_combine.3
 MLINKS += crc32.3 crc32_z.3
 MLINKS += deflate.3 deflateEnd.3
 MLINKS += deflate.3 deflateInit.3
+MLINKS += inflate.3 inflateEnd.3
+MLINKS += inflate.3 inflateInit.3
 MLINKS += uncompress.3 uncompress2.3
 
 .include <bsd.lib.mk>
diff --git a/inflate.3 b/inflate.3
new file mode 100644
index 0000000..4bd06de
--- /dev/null
+++ b/inflate.3
@@ -0,0 +1,464 @@
+.Dd November 9, 2018
+.Dt INFLATE 3
+.Os
+.
+.Sh NAME
+.Nm inflate ,
+.Nm inflateInit ,
+.Nm inflateEnd
+.Nd deflate decompression
+.
+.Sh LIBRARY
+.Lb libz
+.
+.Sh SYNOPSIS
+.In zlib.h
+.Ft int
+.Fn inflateInit "z_streamp strm"
+.Ft int
+.Fn inflate "z_streamp strm" "int flush"
+.Ft int
+.Fn inflateEnd "z_streamp strm"
+.
+.Sh DESCRIPTION
+.Fn inflateInit
+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
+.Fn inflate
+(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
+.Fn inflate .
+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
+.Fn inflate
+is called.
+.
+.Pp
+.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.
+.
+.Pp
+.Fn inflateEnd
+causes all dynamically allocated data structures
+for this stream to be feed.
+This function discards any unprocessed input
+and does not flush any pending output.
+.
+.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.
+.
+.Pp
+.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.
+.
+.Pp
+.Fn inflateEnd
+returns
+.Dv Z_OK
+if success,
+or
+.Dv Z_STREAM_ERROR
+if the stream state was inconsistent.
diff --git a/inflateEnd.3 b/inflateEnd.3
new file mode 120000
index 0000000..a4ababe
--- /dev/null
+++ b/inflateEnd.3
@@ -0,0 +1 @@
+inflate.3
\ No newline at end of file
diff --git a/inflateInit.3 b/inflateInit.3
new file mode 120000
index 0000000..a4ababe
--- /dev/null
+++ b/inflateInit.3
@@ -0,0 +1 @@
+inflate.3
\ No newline at end of file