Add deflateParams.3

1 files changed, 109 insertions, 0 deletions

diff --git a/deflateParams.3 b/deflateParams.3
new file mode 100644
index 0000000..31a5911
--- /dev/null
+++ b/deflateParams.3
@@ -0,0 +1,109 @@
+.Dd November 10, 2018
+.Dt DEFLATEPARAMS 3
+.Os
+.
+.Sh NAME
+.Nm deflateParams
+.Nd update compression level and strategy
+.
+.Sh LIBRARY
+.Lb libz
+.
+.Sh SYNOPSIS
+.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.