path: root/doc/zlib/inflateBack.3

.Dd January 15, 2017
.Dt INFLATEBACK 3
.Os
.
.Sh NAME
.Nm inflateBack
.Nd inflate call-back interface
.
.Sh LIBRARY
.Lb libz
.
.Sh SYNOPSIS
.In zlib.h
.
.Ft typedef unsigned
.Fo (*in_func)
.Fa "void FAR *"
.Fa "z_const unsigned char FAR * FAR *"
.Fc
.
.Ft typedef int
.Fo (*out_func)
.Fa "void FAR *"
.Fa "unsigned char FAR *"
.Fa "unsigned"
.Fc
.
.Ft int
.Fo inflateBack
.Fa "z_streamp strm"
.Fa "in_func in"
.Fa "void FAR *in_desc"
.Fa "out_func out"
.Fa "void FAR *out_desc"
.Fc
.
.Sh DESCRIPTION
.Fn inflateBack
does a raw inflate
with a single call
using a call-back interface
for input and output.
This is potentially more efficient than
.Xr inflate 3
for file I/O applications,
in that it avoids copying between the output
and the sliding window
by simply making the window itself the output buffer.
.Xr inflate 3
can be faster on modern CPUs
when used with large buffers.
.Fn inflateBack
trusts the application to not change
the output buffer passed by the output function,
at least until
.Fn inflateBack
returns.
.
.Pp
.Xr inflateBackInit 3
must be called first
to allocate the internal state
and to initialize the state
with the user-provided window buffer.
.Fn inflateBack
may then be used multiple times
to inflate a complete,
raw deflate stream
with each call.
.Xr inflateBackEnd 3
is then called to free the allocated state.
.
.Pp
A raw deflate stream
is one with no zlib or gzip header or trailer.
This routine would normally be used
in a utility that reads zip or gzip files
and write out uncompressed files.
The utility would decode the header
and process the trailer on its own,
hence this routine expects only
the raw deflate stream to decompress.
This is different from the default behaviour of
.Xr inflate 3 ,
which expects a zlib header and trailer
around the deflate stream.
.
.Pp
.Fn inflateBack
uses two subroutines
supplied by the caller
that are then called by
.Fn inflateBack
for input and output.
.Fn inflateBack
calls those routines
until it reads a complete deflate stream
and writes out all of the uncompressed data,
or until it encounters an error.
The function's parameters and return types
are defined above in the
.Vt in_func
and
.Vt out_func
typedefs.
.Fn inflateBack
will call
.Fn in in_desc &buf
which should return
the number of bytes of provided input,
and a pointer to that input in
.Fa buf .
If there is no input available,
.Fn in
must return zero \(em
.Fa buf
is ignored in that case \(em
and
.Fn inflateBack
will return a buffer error.
.Fn inflateBack
will call
.Fn out out_desc buf len
to write the uncompressed data
.Fa buf[0..len-1] .
.Fn out
should return zero on success,
or non-zero on failure.
If
.Fn out
returns non-zero,
.Fn inflateBack
will return with an error.
Neither
.Fn in
nor
.Fn out
are permitted to change
the contents of the window provided to
.Xr inflateBackInit 3 ,
which is also the buffer that
.Fn out
uses to write from.
The length written by
.Fn out
will be at most the window size.
Any non-zero amount of input
may be provided by
.Fn in .
.
.Pp
For convenience,
.Fn inflateBack
can be provided input on the first call
by setting
.Fa strm->next_in
and
.Fa strm->avail_in .
If that input is exhausted,
then
.Fn in
will be called.
Therefore
.Fa strm->next_in
must be initialized before calling
.Fn inflateBack .
If
.Fa strm->next_in
is
.Dv Z_NULL ,
then
.Fn in
will be called immediately for input.
If
.Fa strm->next_in
is not
.Dv Z_NULL ,
then
.Fa strm->avail_in
must also be initialized,
and then if
.Fa strm->avail_in
is not zero,
input will initially be taken from
.Fa "strm->next_in[0 .. strm->avail_in - 1]" .
.
.Pp
The
.Fa in_desc
and
.Fa out_desc
parameters of
.Fn inflateBack
is passed as the first parameter of
.Fn in
and
.Fn out
respectively when they are called.
These descriptors can be optionally used
to pass any information that the caller-supplied
.Fn in
and
.Fn out
functions need to do their job.
.
.Sh RETURN VALUES
On return,
.Fn inflateBack
will set
.Fa strm->next_in
and
.Fa strm->avail_in
to pass back any unused input
that was provided by the last
.Fn in
call.
The return values of
.Fn inflateBack
can be
.Dv Z_STREAM_END
on success,
.Dv Z_BUF_ERROR
if
.Fn in
or
.Fn out
returned an error,
.Dv Z_DATA_ERROR
if there was a format error
in the deflate stream
.Po
in which case
.Fa strm->msg
is set to indicate the nature of the error
.Pc ,
or
.Dv Z_STREAM_ERROR
if the stream was not properly initialized.
In the case of
.Dv Z_BUF_ERROR ,
an input or output error can be distinguished using
.Fa strm->next_in
which will be
.Dv Z_NULL
only if
.Fn in
returned an error.
If
.Fa strm->next_in
is not
.Dv Z_NULL ,
then the
.Dv Z_BUF_ERROR
was due to
.Fn out
returning non-zero.
.Po
.Fn in
will always be called before
.Fn out ,
so
.Fa strm->next_in
is assured to be defined if
.Fa out
returns non-zero.
.Pc \&
Note that
.Fn inflateBack
cannot return
.Dv Z_OK .
.
.Sh SEE ALSO
.Xr inflate 3 ,
.Xr inflateBackEnd 3 ,
.Xr inflateBackInit 3
.
.Sh HISTORY
This manual page was converted from
.In zlib.h
to mdoc format by
.An June 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