.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