Add 'doc/zlib/' from commit '38f010d3972db4262e7e0bcd7d6b9814f95d3538'

git-subtree-dir: doc/zlib
git-subtree-mainline: db652695744cc54584296b54289166b4b21ac407
git-subtree-split: 38f010d3972db4262e7e0bcd7d6b9814f95d3538

1 files changed, 123 insertions, 0 deletions

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