1275793eaSopenharmony_ci<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2275793eaSopenharmony_ci  "http://www.w3.org/TR/html4/loose.dtd">
3275793eaSopenharmony_ci<html>
4275793eaSopenharmony_ci<head>
5275793eaSopenharmony_ci<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6275793eaSopenharmony_ci<title>zlib Usage Example</title>
7275793eaSopenharmony_ci<!--  Copyright (c) 2004-2023 Mark Adler.  -->
8275793eaSopenharmony_ci</head>
9275793eaSopenharmony_ci<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#00A000">
10275793eaSopenharmony_ci<h2 align="center"> zlib Usage Example </h2>
11275793eaSopenharmony_ciWe often get questions about how the <tt>deflate()</tt> and <tt>inflate()</tt> functions should be used.
12275793eaSopenharmony_ciUsers wonder when they should provide more input, when they should use more output,
13275793eaSopenharmony_ciwhat to do with a <tt>Z_BUF_ERROR</tt>, how to make sure the process terminates properly, and
14275793eaSopenharmony_ciso on.  So for those who have read <tt>zlib.h</tt> (a few times), and
15275793eaSopenharmony_ciwould like further edification, below is an annotated example in C of simple routines to compress and decompress
16275793eaSopenharmony_cifrom an input file to an output file using <tt>deflate()</tt> and <tt>inflate()</tt> respectively.  The
17275793eaSopenharmony_ciannotations are interspersed between lines of the code.  So please read between the lines.
18275793eaSopenharmony_ciWe hope this helps explain some of the intricacies of <em>zlib</em>.
19275793eaSopenharmony_ci<p>
20275793eaSopenharmony_ciWithout further ado, here is the program <a href="zpipe.c"><tt>zpipe.c</tt></a>:
21275793eaSopenharmony_ci<pre><b>
22275793eaSopenharmony_ci/* zpipe.c: example of proper use of zlib's inflate() and deflate()
23275793eaSopenharmony_ci   Not copyrighted -- provided to the public domain
24275793eaSopenharmony_ci   Version 1.4  11 December 2005  Mark Adler */
25275793eaSopenharmony_ci
26275793eaSopenharmony_ci/* Version history:
27275793eaSopenharmony_ci   1.0  30 Oct 2004  First version
28275793eaSopenharmony_ci   1.1   8 Nov 2004  Add void casting for unused return values
29275793eaSopenharmony_ci                     Use switch statement for inflate() return values
30275793eaSopenharmony_ci   1.2   9 Nov 2004  Add assertions to document zlib guarantees
31275793eaSopenharmony_ci   1.3   6 Apr 2005  Remove incorrect assertion in inf()
32275793eaSopenharmony_ci   1.4  11 Dec 2005  Add hack to avoid MSDOS end-of-line conversions
33275793eaSopenharmony_ci                     Avoid some compiler warnings for input and output buffers
34275793eaSopenharmony_ci */
35275793eaSopenharmony_ci</b></pre><!-- -->
36275793eaSopenharmony_ciWe now include the header files for the required definitions.  From
37275793eaSopenharmony_ci<tt>stdio.h</tt> we use <tt>fopen()</tt>, <tt>fread()</tt>, <tt>fwrite()</tt>,
38275793eaSopenharmony_ci<tt>feof()</tt>, <tt>ferror()</tt>, and <tt>fclose()</tt> for file i/o, and
39275793eaSopenharmony_ci<tt>fputs()</tt> for error messages.  From <tt>string.h</tt> we use
40275793eaSopenharmony_ci<tt>strcmp()</tt> for command line argument processing.
41275793eaSopenharmony_ciFrom <tt>assert.h</tt> we use the <tt>assert()</tt> macro.
42275793eaSopenharmony_ciFrom <tt>zlib.h</tt>
43275793eaSopenharmony_ciwe use the basic compression functions <tt>deflateInit()</tt>,
44275793eaSopenharmony_ci<tt>deflate()</tt>, and <tt>deflateEnd()</tt>, and the basic decompression
45275793eaSopenharmony_cifunctions <tt>inflateInit()</tt>, <tt>inflate()</tt>, and
46275793eaSopenharmony_ci<tt>inflateEnd()</tt>.
47275793eaSopenharmony_ci<pre><b>
48275793eaSopenharmony_ci#include &lt;stdio.h&gt;
49275793eaSopenharmony_ci#include &lt;string.h&gt;
50275793eaSopenharmony_ci#include &lt;assert.h&gt;
51275793eaSopenharmony_ci#include "zlib.h"
52275793eaSopenharmony_ci</b></pre><!-- -->
53275793eaSopenharmony_ciThis is an ugly hack required to avoid corruption of the input and output data on
54275793eaSopenharmony_ciWindows/MS-DOS systems.  Without this, those systems would assume that the input and output
55275793eaSopenharmony_cifiles are text, and try to convert the end-of-line characters from one standard to
56275793eaSopenharmony_cianother.  That would corrupt binary data, and in particular would render the compressed data unusable.
57275793eaSopenharmony_ciThis sets the input and output to binary which suppresses the end-of-line conversions.
58275793eaSopenharmony_ci<tt>SET_BINARY_MODE()</tt> will be used later on <tt>stdin</tt> and <tt>stdout</tt>, at the beginning of <tt>main()</tt>.
59275793eaSopenharmony_ci<pre><b>
60275793eaSopenharmony_ci#if defined(MSDOS) || defined(OS2) || defined(WIN32) || defined(__CYGWIN__)
61275793eaSopenharmony_ci#  include &lt;fcntl.h&gt;
62275793eaSopenharmony_ci#  include &lt;io.h&gt;
63275793eaSopenharmony_ci#  define SET_BINARY_MODE(file) setmode(fileno(file), O_BINARY)
64275793eaSopenharmony_ci#else
65275793eaSopenharmony_ci#  define SET_BINARY_MODE(file)
66275793eaSopenharmony_ci#endif
67275793eaSopenharmony_ci</b></pre><!-- -->
68275793eaSopenharmony_ci<tt>CHUNK</tt> is simply the buffer size for feeding data to and pulling data
69275793eaSopenharmony_cifrom the <em>zlib</em> routines.  Larger buffer sizes would be more efficient,
70275793eaSopenharmony_ciespecially for <tt>inflate()</tt>.  If the memory is available, buffers sizes
71275793eaSopenharmony_cion the order of 128K or 256K bytes should be used.
72275793eaSopenharmony_ci<pre><b>
73275793eaSopenharmony_ci#define CHUNK 16384
74275793eaSopenharmony_ci</b></pre><!-- -->
75275793eaSopenharmony_ciThe <tt>def()</tt> routine compresses data from an input file to an output file.  The output data
76275793eaSopenharmony_ciwill be in the <em>zlib</em> format, which is different from the <em>gzip</em> or <em>zip</em>
77275793eaSopenharmony_ciformats.  The <em>zlib</em> format has a very small header of only two bytes to identify it as
78275793eaSopenharmony_cia <em>zlib</em> stream and to provide decoding information, and a four-byte trailer with a fast
79275793eaSopenharmony_cicheck value to verify the integrity of the uncompressed data after decoding.
80275793eaSopenharmony_ci<pre><b>
81275793eaSopenharmony_ci/* Compress from file source to file dest until EOF on source.
82275793eaSopenharmony_ci   def() returns Z_OK on success, Z_MEM_ERROR if memory could not be
83275793eaSopenharmony_ci   allocated for processing, Z_STREAM_ERROR if an invalid compression
84275793eaSopenharmony_ci   level is supplied, Z_VERSION_ERROR if the version of zlib.h and the
85275793eaSopenharmony_ci   version of the library linked do not match, or Z_ERRNO if there is
86275793eaSopenharmony_ci   an error reading or writing the files. */
87275793eaSopenharmony_ciint def(FILE *source, FILE *dest, int level)
88275793eaSopenharmony_ci{
89275793eaSopenharmony_ci</b></pre>
90275793eaSopenharmony_ciHere are the local variables for <tt>def()</tt>.  <tt>ret</tt> will be used for <em>zlib</em>
91275793eaSopenharmony_cireturn codes.  <tt>flush</tt> will keep track of the current flushing state for <tt>deflate()</tt>,
92275793eaSopenharmony_ciwhich is either no flushing, or flush to completion after the end of the input file is reached.
93275793eaSopenharmony_ci<tt>have</tt> is the amount of data returned from <tt>deflate()</tt>.  The <tt>strm</tt> structure
94275793eaSopenharmony_ciis used to pass information to and from the <em>zlib</em> routines, and to maintain the
95275793eaSopenharmony_ci<tt>deflate()</tt> state.  <tt>in</tt> and <tt>out</tt> are the input and output buffers for
96275793eaSopenharmony_ci<tt>deflate()</tt>.
97275793eaSopenharmony_ci<pre><b>
98275793eaSopenharmony_ci    int ret, flush;
99275793eaSopenharmony_ci    unsigned have;
100275793eaSopenharmony_ci    z_stream strm;
101275793eaSopenharmony_ci    unsigned char in[CHUNK];
102275793eaSopenharmony_ci    unsigned char out[CHUNK];
103275793eaSopenharmony_ci</b></pre><!-- -->
104275793eaSopenharmony_ciThe first thing we do is to initialize the <em>zlib</em> state for compression using
105275793eaSopenharmony_ci<tt>deflateInit()</tt>.  This must be done before the first use of <tt>deflate()</tt>.
106275793eaSopenharmony_ciThe <tt>zalloc</tt>, <tt>zfree</tt>, and <tt>opaque</tt> fields in the <tt>strm</tt>
107275793eaSopenharmony_cistructure must be initialized before calling <tt>deflateInit()</tt>.  Here they are
108275793eaSopenharmony_ciset to the <em>zlib</em> constant <tt>Z_NULL</tt> to request that <em>zlib</em> use
109275793eaSopenharmony_cithe default memory allocation routines.  An application may also choose to provide
110275793eaSopenharmony_cicustom memory allocation routines here.  <tt>deflateInit()</tt> will allocate on the
111275793eaSopenharmony_ciorder of 256K bytes for the internal state.
112275793eaSopenharmony_ci(See <a href="zlib_tech.html"><em>zlib Technical Details</em></a>.)
113275793eaSopenharmony_ci<p>
114275793eaSopenharmony_ci<tt>deflateInit()</tt> is called with a pointer to the structure to be initialized and
115275793eaSopenharmony_cithe compression level, which is an integer in the range of -1 to 9.  Lower compression
116275793eaSopenharmony_cilevels result in faster execution, but less compression.  Higher levels result in
117275793eaSopenharmony_cigreater compression, but slower execution.  The <em>zlib</em> constant Z_DEFAULT_COMPRESSION,
118275793eaSopenharmony_ciequal to -1,
119275793eaSopenharmony_ciprovides a good compromise between compression and speed and is equivalent to level 6.
120275793eaSopenharmony_ciLevel 0 actually does no compression at all, and in fact expands the data slightly to produce
121275793eaSopenharmony_cithe <em>zlib</em> format (it is not a byte-for-byte copy of the input).
122275793eaSopenharmony_ciMore advanced applications of <em>zlib</em>
123275793eaSopenharmony_cimay use <tt>deflateInit2()</tt> here instead.  Such an application may want to reduce how
124275793eaSopenharmony_cimuch memory will be used, at some price in compression.  Or it may need to request a
125275793eaSopenharmony_ci<em>gzip</em> header and trailer instead of a <em>zlib</em> header and trailer, or raw
126275793eaSopenharmony_ciencoding with no header or trailer at all.
127275793eaSopenharmony_ci<p>
128275793eaSopenharmony_ciWe must check the return value of <tt>deflateInit()</tt> against the <em>zlib</em> constant
129275793eaSopenharmony_ci<tt>Z_OK</tt> to make sure that it was able to
130275793eaSopenharmony_ciallocate memory for the internal state, and that the provided arguments were valid.
131275793eaSopenharmony_ci<tt>deflateInit()</tt> will also check that the version of <em>zlib</em> that the <tt>zlib.h</tt>
132275793eaSopenharmony_cifile came from matches the version of <em>zlib</em> actually linked with the program.  This
133275793eaSopenharmony_ciis especially important for environments in which <em>zlib</em> is a shared library.
134275793eaSopenharmony_ci<p>
135275793eaSopenharmony_ciNote that an application can initialize multiple, independent <em>zlib</em> streams, which can
136275793eaSopenharmony_cioperate in parallel.  The state information maintained in the structure allows the <em>zlib</em>
137275793eaSopenharmony_ciroutines to be reentrant.
138275793eaSopenharmony_ci<pre><b>
139275793eaSopenharmony_ci    /* allocate deflate state */
140275793eaSopenharmony_ci    strm.zalloc = Z_NULL;
141275793eaSopenharmony_ci    strm.zfree = Z_NULL;
142275793eaSopenharmony_ci    strm.opaque = Z_NULL;
143275793eaSopenharmony_ci    ret = deflateInit(&amp;strm, level);
144275793eaSopenharmony_ci    if (ret != Z_OK)
145275793eaSopenharmony_ci        return ret;
146275793eaSopenharmony_ci</b></pre><!-- -->
147275793eaSopenharmony_ciWith the pleasantries out of the way, now we can get down to business.  The outer <tt>do</tt>-loop
148275793eaSopenharmony_cireads all of the input file and exits at the bottom of the loop once end-of-file is reached.
149275793eaSopenharmony_ciThis loop contains the only call of <tt>deflate()</tt>.  So we must make sure that all of the
150275793eaSopenharmony_ciinput data has been processed and that all of the output data has been generated and consumed
151275793eaSopenharmony_cibefore we fall out of the loop at the bottom.
152275793eaSopenharmony_ci<pre><b>
153275793eaSopenharmony_ci    /* compress until end of file */
154275793eaSopenharmony_ci    do {
155275793eaSopenharmony_ci</b></pre>
156275793eaSopenharmony_ciWe start off by reading data from the input file.  The number of bytes read is put directly
157275793eaSopenharmony_ciinto <tt>avail_in</tt>, and a pointer to those bytes is put into <tt>next_in</tt>.  We also
158275793eaSopenharmony_cicheck to see if end-of-file on the input has been reached using feof().
159275793eaSopenharmony_ciIf we are at the end of file, then <tt>flush</tt> is set to the
160275793eaSopenharmony_ci<em>zlib</em> constant <tt>Z_FINISH</tt>, which is later passed to <tt>deflate()</tt> to
161275793eaSopenharmony_ciindicate that this is the last chunk of input data to compress.
162275793eaSopenharmony_ciIf we are not yet at the end of the input, then the <em>zlib</em>
163275793eaSopenharmony_ciconstant <tt>Z_NO_FLUSH</tt> will be passed to <tt>deflate</tt> to indicate that we are still
164275793eaSopenharmony_ciin the middle of the uncompressed data.
165275793eaSopenharmony_ci<p>
166275793eaSopenharmony_ciIf there is an error in reading from the input file, the process is aborted with
167275793eaSopenharmony_ci<tt>deflateEnd()</tt> being called to free the allocated <em>zlib</em> state before returning
168275793eaSopenharmony_cithe error.  We wouldn't want a memory leak, now would we?  <tt>deflateEnd()</tt> can be called
169275793eaSopenharmony_ciat any time after the state has been initialized.  Once that's done, <tt>deflateInit()</tt> (or
170275793eaSopenharmony_ci<tt>deflateInit2()</tt>) would have to be called to start a new compression process.  There is
171275793eaSopenharmony_cino point here in checking the <tt>deflateEnd()</tt> return code.  The deallocation can't fail.
172275793eaSopenharmony_ci<pre><b>
173275793eaSopenharmony_ci        strm.avail_in = fread(in, 1, CHUNK, source);
174275793eaSopenharmony_ci        if (ferror(source)) {
175275793eaSopenharmony_ci            (void)deflateEnd(&amp;strm);
176275793eaSopenharmony_ci            return Z_ERRNO;
177275793eaSopenharmony_ci        }
178275793eaSopenharmony_ci        flush = feof(source) ? Z_FINISH : Z_NO_FLUSH;
179275793eaSopenharmony_ci        strm.next_in = in;
180275793eaSopenharmony_ci</b></pre><!-- -->
181275793eaSopenharmony_ciThe inner <tt>do</tt>-loop passes our chunk of input data to <tt>deflate()</tt>, and then
182275793eaSopenharmony_cikeeps calling <tt>deflate()</tt> until it is done producing output.  Once there is no more
183275793eaSopenharmony_cinew output, <tt>deflate()</tt> is guaranteed to have consumed all of the input, i.e.,
184275793eaSopenharmony_ci<tt>avail_in</tt> will be zero.
185275793eaSopenharmony_ci<pre><b>
186275793eaSopenharmony_ci        /* run deflate() on input until output buffer not full, finish
187275793eaSopenharmony_ci           compression if all of source has been read in */
188275793eaSopenharmony_ci        do {
189275793eaSopenharmony_ci</b></pre>
190275793eaSopenharmony_ciOutput space is provided to <tt>deflate()</tt> by setting <tt>avail_out</tt> to the number
191275793eaSopenharmony_ciof available output bytes and <tt>next_out</tt> to a pointer to that space.
192275793eaSopenharmony_ci<pre><b>
193275793eaSopenharmony_ci            strm.avail_out = CHUNK;
194275793eaSopenharmony_ci            strm.next_out = out;
195275793eaSopenharmony_ci</b></pre>
196275793eaSopenharmony_ciNow we call the compression engine itself, <tt>deflate()</tt>.  It takes as many of the
197275793eaSopenharmony_ci<tt>avail_in</tt> bytes at <tt>next_in</tt> as it can process, and writes as many as
198275793eaSopenharmony_ci<tt>avail_out</tt> bytes to <tt>next_out</tt>.  Those counters and pointers are then
199275793eaSopenharmony_ciupdated past the input data consumed and the output data written.  It is the amount of
200275793eaSopenharmony_cioutput space available that may limit how much input is consumed.
201275793eaSopenharmony_ciHence the inner loop to make sure that
202275793eaSopenharmony_ciall of the input is consumed by providing more output space each time.  Since <tt>avail_in</tt>
203275793eaSopenharmony_ciand <tt>next_in</tt> are updated by <tt>deflate()</tt>, we don't have to mess with those
204275793eaSopenharmony_cibetween <tt>deflate()</tt> calls until it's all used up.
205275793eaSopenharmony_ci<p>
206275793eaSopenharmony_ciThe parameters to <tt>deflate()</tt> are a pointer to the <tt>strm</tt> structure containing
207275793eaSopenharmony_cithe input and output information and the internal compression engine state, and a parameter
208275793eaSopenharmony_ciindicating whether and how to flush data to the output.  Normally <tt>deflate</tt> will consume
209275793eaSopenharmony_ciseveral K bytes of input data before producing any output (except for the header), in order
210275793eaSopenharmony_cito accumulate statistics on the data for optimum compression.  It will then put out a burst of
211275793eaSopenharmony_cicompressed data, and proceed to consume more input before the next burst.  Eventually,
212275793eaSopenharmony_ci<tt>deflate()</tt>
213275793eaSopenharmony_cimust be told to terminate the stream, complete the compression with provided input data, and
214275793eaSopenharmony_ciwrite out the trailer check value.  <tt>deflate()</tt> will continue to compress normally as long
215275793eaSopenharmony_cias the flush parameter is <tt>Z_NO_FLUSH</tt>.  Once the <tt>Z_FINISH</tt> parameter is provided,
216275793eaSopenharmony_ci<tt>deflate()</tt> will begin to complete the compressed output stream.  However depending on how
217275793eaSopenharmony_cimuch output space is provided, <tt>deflate()</tt> may have to be called several times until it
218275793eaSopenharmony_cihas provided the complete compressed stream, even after it has consumed all of the input.  The flush
219275793eaSopenharmony_ciparameter must continue to be <tt>Z_FINISH</tt> for those subsequent calls.
220275793eaSopenharmony_ci<p>
221275793eaSopenharmony_ciThere are other values of the flush parameter that are used in more advanced applications.  You can
222275793eaSopenharmony_ciforce <tt>deflate()</tt> to produce a burst of output that encodes all of the input data provided
223275793eaSopenharmony_ciso far, even if it wouldn't have otherwise, for example to control data latency on a link with
224275793eaSopenharmony_cicompressed data.  You can also ask that <tt>deflate()</tt> do that as well as erase any history up to
225275793eaSopenharmony_cithat point so that what follows can be decompressed independently, for example for random access
226275793eaSopenharmony_ciapplications.  Both requests will degrade compression by an amount depending on how often such
227275793eaSopenharmony_cirequests are made.
228275793eaSopenharmony_ci<p>
229275793eaSopenharmony_ci<tt>deflate()</tt> has a return value that can indicate errors, yet we do not check it here.  Why
230275793eaSopenharmony_cinot?  Well, it turns out that <tt>deflate()</tt> can do no wrong here.  Let's go through
231275793eaSopenharmony_ci<tt>deflate()</tt>'s return values and dispense with them one by one.  The possible values are
232275793eaSopenharmony_ci<tt>Z_OK</tt>, <tt>Z_STREAM_END</tt>, <tt>Z_STREAM_ERROR</tt>, or <tt>Z_BUF_ERROR</tt>.  <tt>Z_OK</tt>
233275793eaSopenharmony_ciis, well, ok.  <tt>Z_STREAM_END</tt> is also ok and will be returned for the last call of
234275793eaSopenharmony_ci<tt>deflate()</tt>.  This is already guaranteed by calling <tt>deflate()</tt> with <tt>Z_FINISH</tt>
235275793eaSopenharmony_ciuntil it has no more output.  <tt>Z_STREAM_ERROR</tt> is only possible if the stream is not
236275793eaSopenharmony_ciinitialized properly, but we did initialize it properly.  There is no harm in checking for
237275793eaSopenharmony_ci<tt>Z_STREAM_ERROR</tt> here, for example to check for the possibility that some
238275793eaSopenharmony_ciother part of the application inadvertently clobbered the memory containing the <em>zlib</em> state.
239275793eaSopenharmony_ci<tt>Z_BUF_ERROR</tt> will be explained further below, but
240275793eaSopenharmony_cisuffice it to say that this is simply an indication that <tt>deflate()</tt> could not consume
241275793eaSopenharmony_cimore input or produce more output.  <tt>deflate()</tt> can be called again with more output space
242275793eaSopenharmony_cior more available input, which it will be in this code.
243275793eaSopenharmony_ci<pre><b>
244275793eaSopenharmony_ci            ret = deflate(&amp;strm, flush);    /* no bad return value */
245275793eaSopenharmony_ci            assert(ret != Z_STREAM_ERROR);  /* state not clobbered */
246275793eaSopenharmony_ci</b></pre>
247275793eaSopenharmony_ciNow we compute how much output <tt>deflate()</tt> provided on the last call, which is the
248275793eaSopenharmony_cidifference between how much space was provided before the call, and how much output space
249275793eaSopenharmony_ciis still available after the call.  Then that data, if any, is written to the output file.
250275793eaSopenharmony_ciWe can then reuse the output buffer for the next call of <tt>deflate()</tt>.  Again if there
251275793eaSopenharmony_ciis a file i/o error, we call <tt>deflateEnd()</tt> before returning to avoid a memory leak.
252275793eaSopenharmony_ci<pre><b>
253275793eaSopenharmony_ci            have = CHUNK - strm.avail_out;
254275793eaSopenharmony_ci            if (fwrite(out, 1, have, dest) != have || ferror(dest)) {
255275793eaSopenharmony_ci                (void)deflateEnd(&amp;strm);
256275793eaSopenharmony_ci                return Z_ERRNO;
257275793eaSopenharmony_ci            }
258275793eaSopenharmony_ci</b></pre>
259275793eaSopenharmony_ciThe inner <tt>do</tt>-loop is repeated until the last <tt>deflate()</tt> call fails to fill the
260275793eaSopenharmony_ciprovided output buffer.  Then we know that <tt>deflate()</tt> has done as much as it can with
261275793eaSopenharmony_cithe provided input, and that all of that input has been consumed.  We can then fall out of this
262275793eaSopenharmony_ciloop and reuse the input buffer.
263275793eaSopenharmony_ci<p>
264275793eaSopenharmony_ciThe way we tell that <tt>deflate()</tt> has no more output is by seeing that it did not fill
265275793eaSopenharmony_cithe output buffer, leaving <tt>avail_out</tt> greater than zero.  However suppose that
266275793eaSopenharmony_ci<tt>deflate()</tt> has no more output, but just so happened to exactly fill the output buffer!
267275793eaSopenharmony_ci<tt>avail_out</tt> is zero, and we can't tell that <tt>deflate()</tt> has done all it can.
268275793eaSopenharmony_ciAs far as we know, <tt>deflate()</tt>
269275793eaSopenharmony_cihas more output for us.  So we call it again.  But now <tt>deflate()</tt> produces no output
270275793eaSopenharmony_ciat all, and <tt>avail_out</tt> remains unchanged as <tt>CHUNK</tt>.  That <tt>deflate()</tt> call
271275793eaSopenharmony_ciwasn't able to do anything, either consume input or produce output, and so it returns
272275793eaSopenharmony_ci<tt>Z_BUF_ERROR</tt>.  (See, I told you I'd cover this later.)  However this is not a problem at
273275793eaSopenharmony_ciall.  Now we finally have the desired indication that <tt>deflate()</tt> is really done,
274275793eaSopenharmony_ciand so we drop out of the inner loop to provide more input to <tt>deflate()</tt>.
275275793eaSopenharmony_ci<p>
276275793eaSopenharmony_ciWith <tt>flush</tt> set to <tt>Z_FINISH</tt>, this final set of <tt>deflate()</tt> calls will
277275793eaSopenharmony_cicomplete the output stream.  Once that is done, subsequent calls of <tt>deflate()</tt> would return
278275793eaSopenharmony_ci<tt>Z_STREAM_ERROR</tt> if the flush parameter is not <tt>Z_FINISH</tt>, and do no more processing
279275793eaSopenharmony_ciuntil the state is reinitialized.
280275793eaSopenharmony_ci<p>
281275793eaSopenharmony_ciSome applications of <em>zlib</em> have two loops that call <tt>deflate()</tt>
282275793eaSopenharmony_ciinstead of the single inner loop we have here.  The first loop would call
283275793eaSopenharmony_ciwithout flushing and feed all of the data to <tt>deflate()</tt>.  The second loop would call
284275793eaSopenharmony_ci<tt>deflate()</tt> with no more
285275793eaSopenharmony_cidata and the <tt>Z_FINISH</tt> parameter to complete the process.  As you can see from this
286275793eaSopenharmony_ciexample, that can be avoided by simply keeping track of the current flush state.
287275793eaSopenharmony_ci<pre><b>
288275793eaSopenharmony_ci        } while (strm.avail_out == 0);
289275793eaSopenharmony_ci        assert(strm.avail_in == 0);     /* all input will be used */
290275793eaSopenharmony_ci</b></pre><!-- -->
291275793eaSopenharmony_ciNow we check to see if we have already processed all of the input file.  That information was
292275793eaSopenharmony_cisaved in the <tt>flush</tt> variable, so we see if that was set to <tt>Z_FINISH</tt>.  If so,
293275793eaSopenharmony_cithen we're done and we fall out of the outer loop.  We're guaranteed to get <tt>Z_STREAM_END</tt>
294275793eaSopenharmony_cifrom the last <tt>deflate()</tt> call, since we ran it until the last chunk of input was
295275793eaSopenharmony_ciconsumed and all of the output was generated.
296275793eaSopenharmony_ci<pre><b>
297275793eaSopenharmony_ci        /* done when last data in file processed */
298275793eaSopenharmony_ci    } while (flush != Z_FINISH);
299275793eaSopenharmony_ci    assert(ret == Z_STREAM_END);        /* stream will be complete */
300275793eaSopenharmony_ci</b></pre><!-- -->
301275793eaSopenharmony_ciThe process is complete, but we still need to deallocate the state to avoid a memory leak
302275793eaSopenharmony_ci(or rather more like a memory hemorrhage if you didn't do this).  Then
303275793eaSopenharmony_cifinally we can return with a happy return value.
304275793eaSopenharmony_ci<pre><b>
305275793eaSopenharmony_ci    /* clean up and return */
306275793eaSopenharmony_ci    (void)deflateEnd(&amp;strm);
307275793eaSopenharmony_ci    return Z_OK;
308275793eaSopenharmony_ci}
309275793eaSopenharmony_ci</b></pre><!-- -->
310275793eaSopenharmony_ciNow we do the same thing for decompression in the <tt>inf()</tt> routine. <tt>inf()</tt>
311275793eaSopenharmony_cidecompresses what is hopefully a valid <em>zlib</em> stream from the input file and writes the
312275793eaSopenharmony_ciuncompressed data to the output file.  Much of the discussion above for <tt>def()</tt>
313275793eaSopenharmony_ciapplies to <tt>inf()</tt> as well, so the discussion here will focus on the differences between
314275793eaSopenharmony_cithe two.
315275793eaSopenharmony_ci<pre><b>
316275793eaSopenharmony_ci/* Decompress from file source to file dest until stream ends or EOF.
317275793eaSopenharmony_ci   inf() returns Z_OK on success, Z_MEM_ERROR if memory could not be
318275793eaSopenharmony_ci   allocated for processing, Z_DATA_ERROR if the deflate data is
319275793eaSopenharmony_ci   invalid or incomplete, Z_VERSION_ERROR if the version of zlib.h and
320275793eaSopenharmony_ci   the version of the library linked do not match, or Z_ERRNO if there
321275793eaSopenharmony_ci   is an error reading or writing the files. */
322275793eaSopenharmony_ciint inf(FILE *source, FILE *dest)
323275793eaSopenharmony_ci{
324275793eaSopenharmony_ci</b></pre>
325275793eaSopenharmony_ciThe local variables have the same functionality as they do for <tt>def()</tt>.  The
326275793eaSopenharmony_cionly difference is that there is no <tt>flush</tt> variable, since <tt>inflate()</tt>
327275793eaSopenharmony_cican tell from the <em>zlib</em> stream itself when the stream is complete.
328275793eaSopenharmony_ci<pre><b>
329275793eaSopenharmony_ci    int ret;
330275793eaSopenharmony_ci    unsigned have;
331275793eaSopenharmony_ci    z_stream strm;
332275793eaSopenharmony_ci    unsigned char in[CHUNK];
333275793eaSopenharmony_ci    unsigned char out[CHUNK];
334275793eaSopenharmony_ci</b></pre><!-- -->
335275793eaSopenharmony_ciThe initialization of the state is the same, except that there is no compression level,
336275793eaSopenharmony_ciof course, and two more elements of the structure are initialized.  <tt>avail_in</tt>
337275793eaSopenharmony_ciand <tt>next_in</tt> must be initialized before calling <tt>inflateInit()</tt>.  This
338275793eaSopenharmony_ciis because the application has the option to provide the start of the zlib stream in
339275793eaSopenharmony_ciorder for <tt>inflateInit()</tt> to have access to information about the compression
340275793eaSopenharmony_cimethod to aid in memory allocation.  In the current implementation of <em>zlib</em>
341275793eaSopenharmony_ci(up through versions 1.2.x), the method-dependent memory allocations are deferred to the first call of
342275793eaSopenharmony_ci<tt>inflate()</tt> anyway.  However those fields must be initialized since later versions
343275793eaSopenharmony_ciof <em>zlib</em> that provide more compression methods may take advantage of this interface.
344275793eaSopenharmony_ciIn any case, no decompression is performed by <tt>inflateInit()</tt>, so the
345275793eaSopenharmony_ci<tt>avail_out</tt> and <tt>next_out</tt> fields do not need to be initialized before calling.
346275793eaSopenharmony_ci<p>
347275793eaSopenharmony_ciHere <tt>avail_in</tt> is set to zero and <tt>next_in</tt> is set to <tt>Z_NULL</tt> to
348275793eaSopenharmony_ciindicate that no input data is being provided.
349275793eaSopenharmony_ci<pre><b>
350275793eaSopenharmony_ci    /* allocate inflate state */
351275793eaSopenharmony_ci    strm.zalloc = Z_NULL;
352275793eaSopenharmony_ci    strm.zfree = Z_NULL;
353275793eaSopenharmony_ci    strm.opaque = Z_NULL;
354275793eaSopenharmony_ci    strm.avail_in = 0;
355275793eaSopenharmony_ci    strm.next_in = Z_NULL;
356275793eaSopenharmony_ci    ret = inflateInit(&amp;strm);
357275793eaSopenharmony_ci    if (ret != Z_OK)
358275793eaSopenharmony_ci        return ret;
359275793eaSopenharmony_ci</b></pre><!-- -->
360275793eaSopenharmony_ciThe outer <tt>do</tt>-loop decompresses input until <tt>inflate()</tt> indicates
361275793eaSopenharmony_cithat it has reached the end of the compressed data and has produced all of the uncompressed
362275793eaSopenharmony_cioutput.  This is in contrast to <tt>def()</tt> which processes all of the input file.
363275793eaSopenharmony_ciIf end-of-file is reached before the compressed data self-terminates, then the compressed
364275793eaSopenharmony_cidata is incomplete and an error is returned.
365275793eaSopenharmony_ci<pre><b>
366275793eaSopenharmony_ci    /* decompress until deflate stream ends or end of file */
367275793eaSopenharmony_ci    do {
368275793eaSopenharmony_ci</b></pre>
369275793eaSopenharmony_ciWe read input data and set the <tt>strm</tt> structure accordingly.  If we've reached the
370275793eaSopenharmony_ciend of the input file, then we leave the outer loop and report an error, since the
371275793eaSopenharmony_cicompressed data is incomplete.  Note that we may read more data than is eventually consumed
372275793eaSopenharmony_ciby <tt>inflate()</tt>, if the input file continues past the <em>zlib</em> stream.
373275793eaSopenharmony_ciFor applications where <em>zlib</em> streams are embedded in other data, this routine would
374275793eaSopenharmony_cineed to be modified to return the unused data, or at least indicate how much of the input
375275793eaSopenharmony_cidata was not used, so the application would know where to pick up after the <em>zlib</em> stream.
376275793eaSopenharmony_ci<pre><b>
377275793eaSopenharmony_ci        strm.avail_in = fread(in, 1, CHUNK, source);
378275793eaSopenharmony_ci        if (ferror(source)) {
379275793eaSopenharmony_ci            (void)inflateEnd(&amp;strm);
380275793eaSopenharmony_ci            return Z_ERRNO;
381275793eaSopenharmony_ci        }
382275793eaSopenharmony_ci        if (strm.avail_in == 0)
383275793eaSopenharmony_ci            break;
384275793eaSopenharmony_ci        strm.next_in = in;
385275793eaSopenharmony_ci</b></pre><!-- -->
386275793eaSopenharmony_ciThe inner <tt>do</tt>-loop has the same function it did in <tt>def()</tt>, which is to
387275793eaSopenharmony_cikeep calling <tt>inflate()</tt> until has generated all of the output it can with the
388275793eaSopenharmony_ciprovided input.
389275793eaSopenharmony_ci<pre><b>
390275793eaSopenharmony_ci        /* run inflate() on input until output buffer not full */
391275793eaSopenharmony_ci        do {
392275793eaSopenharmony_ci</b></pre>
393275793eaSopenharmony_ciJust like in <tt>def()</tt>, the same output space is provided for each call of <tt>inflate()</tt>.
394275793eaSopenharmony_ci<pre><b>
395275793eaSopenharmony_ci            strm.avail_out = CHUNK;
396275793eaSopenharmony_ci            strm.next_out = out;
397275793eaSopenharmony_ci</b></pre>
398275793eaSopenharmony_ciNow we run the decompression engine itself.  There is no need to adjust the flush parameter, since
399275793eaSopenharmony_cithe <em>zlib</em> format is self-terminating. The main difference here is that there are
400275793eaSopenharmony_cireturn values that we need to pay attention to.  <tt>Z_DATA_ERROR</tt>
401275793eaSopenharmony_ciindicates that <tt>inflate()</tt> detected an error in the <em>zlib</em> compressed data format,
402275793eaSopenharmony_ciwhich means that either the data is not a <em>zlib</em> stream to begin with, or that the data was
403275793eaSopenharmony_cicorrupted somewhere along the way since it was compressed.  The other error to be processed is
404275793eaSopenharmony_ci<tt>Z_MEM_ERROR</tt>, which can occur since memory allocation is deferred until <tt>inflate()</tt>
405275793eaSopenharmony_cineeds it, unlike <tt>deflate()</tt>, whose memory is allocated at the start by <tt>deflateInit()</tt>.
406275793eaSopenharmony_ci<p>
407275793eaSopenharmony_ciAdvanced applications may use
408275793eaSopenharmony_ci<tt>deflateSetDictionary()</tt> to prime <tt>deflate()</tt> with a set of likely data to improve the
409275793eaSopenharmony_cifirst 32K or so of compression.  This is noted in the <em>zlib</em> header, so <tt>inflate()</tt>
410275793eaSopenharmony_cirequests that that dictionary be provided before it can start to decompress.  Without the dictionary,
411275793eaSopenharmony_cicorrect decompression is not possible.  For this routine, we have no idea what the dictionary is,
412275793eaSopenharmony_ciso the <tt>Z_NEED_DICT</tt> indication is converted to a <tt>Z_DATA_ERROR</tt>.
413275793eaSopenharmony_ci<p>
414275793eaSopenharmony_ci<tt>inflate()</tt> can also return <tt>Z_STREAM_ERROR</tt>, which should not be possible here,
415275793eaSopenharmony_cibut could be checked for as noted above for <tt>def()</tt>.  <tt>Z_BUF_ERROR</tt> does not need to be
416275793eaSopenharmony_cichecked for here, for the same reasons noted for <tt>def()</tt>.  <tt>Z_STREAM_END</tt> will be
417275793eaSopenharmony_cichecked for later.
418275793eaSopenharmony_ci<pre><b>
419275793eaSopenharmony_ci            ret = inflate(&amp;strm, Z_NO_FLUSH);
420275793eaSopenharmony_ci            assert(ret != Z_STREAM_ERROR);  /* state not clobbered */
421275793eaSopenharmony_ci            switch (ret) {
422275793eaSopenharmony_ci            case Z_NEED_DICT:
423275793eaSopenharmony_ci                ret = Z_DATA_ERROR;     /* and fall through */
424275793eaSopenharmony_ci            case Z_DATA_ERROR:
425275793eaSopenharmony_ci            case Z_MEM_ERROR:
426275793eaSopenharmony_ci                (void)inflateEnd(&amp;strm);
427275793eaSopenharmony_ci                return ret;
428275793eaSopenharmony_ci            }
429275793eaSopenharmony_ci</b></pre>
430275793eaSopenharmony_ciThe output of <tt>inflate()</tt> is handled identically to that of <tt>deflate()</tt>.
431275793eaSopenharmony_ci<pre><b>
432275793eaSopenharmony_ci            have = CHUNK - strm.avail_out;
433275793eaSopenharmony_ci            if (fwrite(out, 1, have, dest) != have || ferror(dest)) {
434275793eaSopenharmony_ci                (void)inflateEnd(&amp;strm);
435275793eaSopenharmony_ci                return Z_ERRNO;
436275793eaSopenharmony_ci            }
437275793eaSopenharmony_ci</b></pre>
438275793eaSopenharmony_ciThe inner <tt>do</tt>-loop ends when <tt>inflate()</tt> has no more output as indicated
439275793eaSopenharmony_ciby not filling the output buffer, just as for <tt>deflate()</tt>.  In this case, we cannot
440275793eaSopenharmony_ciassert that <tt>strm.avail_in</tt> will be zero, since the deflate stream may end before the file
441275793eaSopenharmony_cidoes.
442275793eaSopenharmony_ci<pre><b>
443275793eaSopenharmony_ci        } while (strm.avail_out == 0);
444275793eaSopenharmony_ci</b></pre><!-- -->
445275793eaSopenharmony_ciThe outer <tt>do</tt>-loop ends when <tt>inflate()</tt> reports that it has reached the
446275793eaSopenharmony_ciend of the input <em>zlib</em> stream, has completed the decompression and integrity
447275793eaSopenharmony_cicheck, and has provided all of the output.  This is indicated by the <tt>inflate()</tt>
448275793eaSopenharmony_cireturn value <tt>Z_STREAM_END</tt>.  The inner loop is guaranteed to leave <tt>ret</tt>
449275793eaSopenharmony_ciequal to <tt>Z_STREAM_END</tt> if the last chunk of the input file read contained the end
450275793eaSopenharmony_ciof the <em>zlib</em> stream.  So if the return value is not <tt>Z_STREAM_END</tt>, the
451275793eaSopenharmony_ciloop continues to read more input.
452275793eaSopenharmony_ci<pre><b>
453275793eaSopenharmony_ci        /* done when inflate() says it's done */
454275793eaSopenharmony_ci    } while (ret != Z_STREAM_END);
455275793eaSopenharmony_ci</b></pre><!-- -->
456275793eaSopenharmony_ciAt this point, decompression successfully completed, or we broke out of the loop due to no
457275793eaSopenharmony_cimore data being available from the input file.  If the last <tt>inflate()</tt> return value
458275793eaSopenharmony_ciis not <tt>Z_STREAM_END</tt>, then the <em>zlib</em> stream was incomplete and a data error
459275793eaSopenharmony_ciis returned.  Otherwise, we return with a happy return value.  Of course, <tt>inflateEnd()</tt>
460275793eaSopenharmony_ciis called first to avoid a memory leak.
461275793eaSopenharmony_ci<pre><b>
462275793eaSopenharmony_ci    /* clean up and return */
463275793eaSopenharmony_ci    (void)inflateEnd(&amp;strm);
464275793eaSopenharmony_ci    return ret == Z_STREAM_END ? Z_OK : Z_DATA_ERROR;
465275793eaSopenharmony_ci}
466275793eaSopenharmony_ci</b></pre><!-- -->
467275793eaSopenharmony_ciThat ends the routines that directly use <em>zlib</em>.  The following routines make this
468275793eaSopenharmony_cia command-line program by running data through the above routines from <tt>stdin</tt> to
469275793eaSopenharmony_ci<tt>stdout</tt>, and handling any errors reported by <tt>def()</tt> or <tt>inf()</tt>.
470275793eaSopenharmony_ci<p>
471275793eaSopenharmony_ci<tt>zerr()</tt> is used to interpret the possible error codes from <tt>def()</tt>
472275793eaSopenharmony_ciand <tt>inf()</tt>, as detailed in their comments above, and print out an error message.
473275793eaSopenharmony_ciNote that these are only a subset of the possible return values from <tt>deflate()</tt>
474275793eaSopenharmony_ciand <tt>inflate()</tt>.
475275793eaSopenharmony_ci<pre><b>
476275793eaSopenharmony_ci/* report a zlib or i/o error */
477275793eaSopenharmony_civoid zerr(int ret)
478275793eaSopenharmony_ci{
479275793eaSopenharmony_ci    fputs("zpipe: ", stderr);
480275793eaSopenharmony_ci    switch (ret) {
481275793eaSopenharmony_ci    case Z_ERRNO:
482275793eaSopenharmony_ci        if (ferror(stdin))
483275793eaSopenharmony_ci            fputs("error reading stdin\n", stderr);
484275793eaSopenharmony_ci        if (ferror(stdout))
485275793eaSopenharmony_ci            fputs("error writing stdout\n", stderr);
486275793eaSopenharmony_ci        break;
487275793eaSopenharmony_ci    case Z_STREAM_ERROR:
488275793eaSopenharmony_ci        fputs("invalid compression level\n", stderr);
489275793eaSopenharmony_ci        break;
490275793eaSopenharmony_ci    case Z_DATA_ERROR:
491275793eaSopenharmony_ci        fputs("invalid or incomplete deflate data\n", stderr);
492275793eaSopenharmony_ci        break;
493275793eaSopenharmony_ci    case Z_MEM_ERROR:
494275793eaSopenharmony_ci        fputs("out of memory\n", stderr);
495275793eaSopenharmony_ci        break;
496275793eaSopenharmony_ci    case Z_VERSION_ERROR:
497275793eaSopenharmony_ci        fputs("zlib version mismatch!\n", stderr);
498275793eaSopenharmony_ci    }
499275793eaSopenharmony_ci}
500275793eaSopenharmony_ci</b></pre><!-- -->
501275793eaSopenharmony_ciHere is the <tt>main()</tt> routine used to test <tt>def()</tt> and <tt>inf()</tt>.  The
502275793eaSopenharmony_ci<tt>zpipe</tt> command is simply a compression pipe from <tt>stdin</tt> to <tt>stdout</tt>, if
503275793eaSopenharmony_cino arguments are given, or it is a decompression pipe if <tt>zpipe -d</tt> is used.  If any other
504275793eaSopenharmony_ciarguments are provided, no compression or decompression is performed.  Instead a usage
505275793eaSopenharmony_cimessage is displayed.  Examples are <tt>zpipe < foo.txt > foo.txt.z</tt> to compress, and
506275793eaSopenharmony_ci<tt>zpipe -d < foo.txt.z > foo.txt</tt> to decompress.
507275793eaSopenharmony_ci<pre><b>
508275793eaSopenharmony_ci/* compress or decompress from stdin to stdout */
509275793eaSopenharmony_ciint main(int argc, char **argv)
510275793eaSopenharmony_ci{
511275793eaSopenharmony_ci    int ret;
512275793eaSopenharmony_ci
513275793eaSopenharmony_ci    /* avoid end-of-line conversions */
514275793eaSopenharmony_ci    SET_BINARY_MODE(stdin);
515275793eaSopenharmony_ci    SET_BINARY_MODE(stdout);
516275793eaSopenharmony_ci
517275793eaSopenharmony_ci    /* do compression if no arguments */
518275793eaSopenharmony_ci    if (argc == 1) {
519275793eaSopenharmony_ci        ret = def(stdin, stdout, Z_DEFAULT_COMPRESSION);
520275793eaSopenharmony_ci        if (ret != Z_OK)
521275793eaSopenharmony_ci            zerr(ret);
522275793eaSopenharmony_ci        return ret;
523275793eaSopenharmony_ci    }
524275793eaSopenharmony_ci
525275793eaSopenharmony_ci    /* do decompression if -d specified */
526275793eaSopenharmony_ci    else if (argc == 2 &amp;&amp; strcmp(argv[1], "-d") == 0) {
527275793eaSopenharmony_ci        ret = inf(stdin, stdout);
528275793eaSopenharmony_ci        if (ret != Z_OK)
529275793eaSopenharmony_ci            zerr(ret);
530275793eaSopenharmony_ci        return ret;
531275793eaSopenharmony_ci    }
532275793eaSopenharmony_ci
533275793eaSopenharmony_ci    /* otherwise, report usage */
534275793eaSopenharmony_ci    else {
535275793eaSopenharmony_ci        fputs("zpipe usage: zpipe [-d] &lt; source &gt; dest\n", stderr);
536275793eaSopenharmony_ci        return 1;
537275793eaSopenharmony_ci    }
538275793eaSopenharmony_ci}
539275793eaSopenharmony_ci</b></pre>
540275793eaSopenharmony_ci<hr>
541275793eaSopenharmony_ci<i>Last modified 24 January 2023<br>
542275793eaSopenharmony_ciCopyright &#169; 2004-2023 Mark Adler</i><br>
543275793eaSopenharmony_ci<a rel="license" href="http://creativecommons.org/licenses/by-nd/4.0/">
544275793eaSopenharmony_ci<img alt="Creative Commons License" style="border-width:0"
545275793eaSopenharmony_cisrc="https://i.creativecommons.org/l/by-nd/4.0/88x31.png"></a>
546275793eaSopenharmony_ci<a rel="license" href="http://creativecommons.org/licenses/by-nd/4.0/">
547275793eaSopenharmony_ciCreative Commons Attribution-NoDerivatives 4.0 International License</a>.
548275793eaSopenharmony_ci</body>
549275793eaSopenharmony_ci</html>
550