diff options
Diffstat (limited to '')
| -rw-r--r-- | deflateParams.3 | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/deflateParams.3 b/deflateParams.3 new file mode 100644 index 0000000..8e770d4 --- /dev/null +++ b/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 |