Convert zlib.h comments to mdoc

1 files changed, 285 insertions, 0 deletions

diff --git a/inflateBack.3 b/inflateBack.3
new file mode 100644
index 0000000..59d5f8c
--- /dev/null
+++ b/inflateBack.3
@@ -0,0 +1,285 @@
+.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 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