From 470523cdad6c92d3b88a82f5e476cd4a4c61bcd2 Mon Sep 17 00:00:00 2001 From: "C. McEnroe" Date: Thu, 8 Nov 2018 21:40:50 -0500 Subject: Convert zlib.h comments to mdoc --- inflateBack.3 | 285 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 285 insertions(+) create mode 100644 inflateBack.3 (limited to 'inflateBack.3') diff --git a/inflateBack.3 b/inflateBack.3 new file mode 100644 index 00000000..59d5f8cb --- /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 -- cgit 1.4.1