deps/libchdr/deps/zlib-1.3.1/examples/zlib_how.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2   "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   6 <title>zlib Usage Example</title>
   7 <!--  Copyright (c) 2004-2023 Mark Adler.  -->
   8 </head>
   9 <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#00A000">
  10 <h2 align="center"> zlib Usage Example </h2>
  11 We often get questions about how the <tt>deflate()</tt> and <tt>inflate()</tt> functions should be used.
  12 Users wonder when they should provide more input, when they should use more output,
  13 what to do with a <tt>Z_BUF_ERROR</tt>, how to make sure the process terminates properly, and
  14 so on.  So for those who have read <tt>zlib.h</tt> (a few times), and
  15 would like further edification, below is an annotated example in C of simple routines to compress and decompress
  16 from an input file to an output file using <tt>deflate()</tt> and <tt>inflate()</tt> respectively.  The
  17 annotations are interspersed between lines of the code.  So please read between the lines.
  18 We hope this helps explain some of the intricacies of <em>zlib</em>.
  19 <p>
  20 Without further ado, here is the program <a href="zpipe.c"><tt>zpipe.c</tt></a>:
  21 <pre><b>
  22 /* zpipe.c: example of proper use of zlib's inflate() and deflate()
  23    Not copyrighted -- provided to the public domain
  24    Version 1.4  11 December 2005  Mark Adler */
  25
  26 /* Version history:
  27    1.0  30 Oct 2004  First version
  28    1.1   8 Nov 2004  Add void casting for unused return values
  29                      Use switch statement for inflate() return values
  30    1.2   9 Nov 2004  Add assertions to document zlib guarantees
  31    1.3   6 Apr 2005  Remove incorrect assertion in inf()
  32    1.4  11 Dec 2005  Add hack to avoid MSDOS end-of-line conversions
  33                      Avoid some compiler warnings for input and output buffers
  34  */
  35 </b></pre><!-- -->
  36 We now include the header files for the required definitions.  From
  37 <tt>stdio.h</tt> we use <tt>fopen()</tt>, <tt>fread()</tt>, <tt>fwrite()</tt>,
  38 <tt>feof()</tt>, <tt>ferror()</tt>, and <tt>fclose()</tt> for file i/o, and
  39 <tt>fputs()</tt> for error messages.  From <tt>string.h</tt> we use
  40 <tt>strcmp()</tt> for command line argument processing.
  41 From <tt>assert.h</tt> we use the <tt>assert()</tt> macro.
  42 From <tt>zlib.h</tt>
  43 we use the basic compression functions <tt>deflateInit()</tt>,
  44 <tt>deflate()</tt>, and <tt>deflateEnd()</tt>, and the basic decompression
  45 functions <tt>inflateInit()</tt>, <tt>inflate()</tt>, and
  46 <tt>inflateEnd()</tt>.
  47 <pre><b>
  48 #include &lt;stdio.h&gt;
  49 #include &lt;string.h&gt;
  50 #include &lt;assert.h&gt;
  51 #include "zlib.h"
  52 </b></pre><!-- -->
  53 This is an ugly hack required to avoid corruption of the input and output data on
  54 Windows/MS-DOS systems.  Without this, those systems would assume that the input and output
  55 files are text, and try to convert the end-of-line characters from one standard to
  56 another.  That would corrupt binary data, and in particular would render the compressed data unusable.
  57 This sets the input and output to binary which suppresses the end-of-line conversions.
  58 <tt>SET_BINARY_MODE()</tt> will be used later on <tt>stdin</tt> and <tt>stdout</tt>, at the beginning of <tt>main()</tt>.
  59 <pre><b>
  60 #if defined(MSDOS) || defined(OS2) || defined(WIN32) || defined(__CYGWIN__)
  61 #  include &lt;fcntl.h&gt;
  62 #  include &lt;io.h&gt;
  63 #  define SET_BINARY_MODE(file) setmode(fileno(file), O_BINARY)
  64 #else
  65 #  define SET_BINARY_MODE(file)
  66 #endif
  67 </b></pre><!-- -->
  68 <tt>CHUNK</tt> is simply the buffer size for feeding data to and pulling data
  69 from the <em>zlib</em> routines.  Larger buffer sizes would be more efficient,
  70 especially for <tt>inflate()</tt>.  If the memory is available, buffers sizes
  71 on the order of 128K or 256K bytes should be used.
  72 <pre><b>
  73 #define CHUNK 16384
  74 </b></pre><!-- -->
  75 The <tt>def()</tt> routine compresses data from an input file to an output file.  The output data
  76 will be in the <em>zlib</em> format, which is different from the <em>gzip</em> or <em>zip</em>
  77 formats.  The <em>zlib</em> format has a very small header of only two bytes to identify it as
  78 a <em>zlib</em> stream and to provide decoding information, and a four-byte trailer with a fast
  79 check value to verify the integrity of the uncompressed data after decoding.
  80 <pre><b>
  81 /* Compress from file source to file dest until EOF on source.
  82    def() returns Z_OK on success, Z_MEM_ERROR if memory could not be
  83    allocated for processing, Z_STREAM_ERROR if an invalid compression
  84    level is supplied, Z_VERSION_ERROR if the version of zlib.h and the
  85    version of the library linked do not match, or Z_ERRNO if there is
  86    an error reading or writing the files. */
  87 int def(FILE *source, FILE *dest, int level)
  88 {
  89 </b></pre>
  90 Here are the local variables for <tt>def()</tt>.  <tt>ret</tt> will be used for <em>zlib</em>
  91 return codes.  <tt>flush</tt> will keep track of the current flushing state for <tt>deflate()</tt>,
  92 which is either no flushing, or flush to completion after the end of the input file is reached.
  93 <tt>have</tt> is the amount of data returned from <tt>deflate()</tt>.  The <tt>strm</tt> structure
  94 is used to pass information to and from the <em>zlib</em> routines, and to maintain the
  95 <tt>deflate()</tt> state.  <tt>in</tt> and <tt>out</tt> are the input and output buffers for
  96 <tt>deflate()</tt>.
  97 <pre><b>
  98     int ret, flush;
  99     unsigned have;
 100     z_stream strm;
 101     unsigned char in[CHUNK];
 102     unsigned char out[CHUNK];
 103 </b></pre><!-- -->
 104 The first thing we do is to initialize the <em>zlib</em> state for compression using
 105 <tt>deflateInit()</tt>.  This must be done before the first use of <tt>deflate()</tt>.
 106 The <tt>zalloc</tt>, <tt>zfree</tt>, and <tt>opaque</tt> fields in the <tt>strm</tt>
 107 structure must be initialized before calling <tt>deflateInit()</tt>.  Here they are
 108 set to the <em>zlib</em> constant <tt>Z_NULL</tt> to request that <em>zlib</em> use
 109 the default memory allocation routines.  An application may also choose to provide
 110 custom memory allocation routines here.  <tt>deflateInit()</tt> will allocate on the
 111 order of 256K bytes for the internal state.
 112 (See <a href="zlib_tech.html"><em>zlib Technical Details</em></a>.)
 113 <p>
 114 <tt>deflateInit()</tt> is called with a pointer to the structure to be initialized and
 115 the compression level, which is an integer in the range of -1 to 9.  Lower compression
 116 levels result in faster execution, but less compression.  Higher levels result in
 117 greater compression, but slower execution.  The <em>zlib</em> constant Z_DEFAULT_COMPRESSION,
 118 equal to -1,
 119 provides a good compromise between compression and speed and is equivalent to level 6.
 120 Level 0 actually does no compression at all, and in fact expands the data slightly to produce
 121 the <em>zlib</em> format (it is not a byte-for-byte copy of the input).
 122 More advanced applications of <em>zlib</em>
 123 may use <tt>deflateInit2()</tt> here instead.  Such an application may want to reduce how
 124 much memory will be used, at some price in compression.  Or it may need to request a
 125 <em>gzip</em> header and trailer instead of a <em>zlib</em> header and trailer, or raw
 126 encoding with no header or trailer at all.
 127 <p>
 128 We must check the return value of <tt>deflateInit()</tt> against the <em>zlib</em> constant
 129 <tt>Z_OK</tt> to make sure that it was able to
 130 allocate memory for the internal state, and that the provided arguments were valid.
 131 <tt>deflateInit()</tt> will also check that the version of <em>zlib</em> that the <tt>zlib.h</tt>
 132 file came from matches the version of <em>zlib</em> actually linked with the program.  This
 133 is especially important for environments in which <em>zlib</em> is a shared library.
 134 <p>
 135 Note that an application can initialize multiple, independent <em>zlib</em> streams, which can
 136 operate in parallel.  The state information maintained in the structure allows the <em>zlib</em>
 137 routines to be reentrant.
 138 <pre><b>
 139     /* allocate deflate state */
 140     strm.zalloc = Z_NULL;
 141     strm.zfree = Z_NULL;
 142     strm.opaque = Z_NULL;
 143     ret = deflateInit(&amp;strm, level);
 144     if (ret != Z_OK)
 145         return ret;
 146 </b></pre><!-- -->
 147 With the pleasantries out of the way, now we can get down to business.  The outer <tt>do</tt>-loop
 148 reads all of the input file and exits at the bottom of the loop once end-of-file is reached.
 149 This loop contains the only call of <tt>deflate()</tt>.  So we must make sure that all of the
 150 input data has been processed and that all of the output data has been generated and consumed
 151 before we fall out of the loop at the bottom.
 152 <pre><b>
 153     /* compress until end of file */
 154     do {
 155 </b></pre>
 156 We start off by reading data from the input file.  The number of bytes read is put directly
 157 into <tt>avail_in</tt>, and a pointer to those bytes is put into <tt>next_in</tt>.  We also
 158 check to see if end-of-file on the input has been reached using feof().
 159 If we are at the end of file, then <tt>flush</tt> is set to the
 160 <em>zlib</em> constant <tt>Z_FINISH</tt>, which is later passed to <tt>deflate()</tt> to
 161 indicate that this is the last chunk of input data to compress.
 162 If we are not yet at the end of the input, then the <em>zlib</em>
 163 constant <tt>Z_NO_FLUSH</tt> will be passed to <tt>deflate</tt> to indicate that we are still
 164 in the middle of the uncompressed data.
 165 <p>
 166 If there is an error in reading from the input file, the process is aborted with
 167 <tt>deflateEnd()</tt> being called to free the allocated <em>zlib</em> state before returning
 168 the error.  We wouldn't want a memory leak, now would we?  <tt>deflateEnd()</tt> can be called
 169 at any time after the state has been initialized.  Once that's done, <tt>deflateInit()</tt> (or
 170 <tt>deflateInit2()</tt>) would have to be called to start a new compression process.  There is
 171 no point here in checking the <tt>deflateEnd()</tt> return code.  The deallocation can't fail.
 172 <pre><b>
 173         strm.avail_in = fread(in, 1, CHUNK, source);
 174         if (ferror(source)) {
 175             (void)deflateEnd(&amp;strm);
 176             return Z_ERRNO;
 177         }
 178         flush = feof(source) ? Z_FINISH : Z_NO_FLUSH;
 179         strm.next_in = in;
 180 </b></pre><!-- -->
 181 The inner <tt>do</tt>-loop passes our chunk of input data to <tt>deflate()</tt>, and then
 182 keeps calling <tt>deflate()</tt> until it is done producing output.  Once there is no more
 183 new output, <tt>deflate()</tt> is guaranteed to have consumed all of the input, i.e.,
 184 <tt>avail_in</tt> will be zero.
 185 <pre><b>
 186         /* run deflate() on input until output buffer not full, finish
 187            compression if all of source has been read in */
 188         do {
 189 </b></pre>
 190 Output space is provided to <tt>deflate()</tt> by setting <tt>avail_out</tt> to the number
 191 of available output bytes and <tt>next_out</tt> to a pointer to that space.
 192 <pre><b>
 193             strm.avail_out = CHUNK;
 194             strm.next_out = out;
 195 </b></pre>
 196 Now we call the compression engine itself, <tt>deflate()</tt>.  It takes as many of the
 197 <tt>avail_in</tt> bytes at <tt>next_in</tt> as it can process, and writes as many as
 198 <tt>avail_out</tt> bytes to <tt>next_out</tt>.  Those counters and pointers are then
 199 updated past the input data consumed and the output data written.  It is the amount of
 200 output space available that may limit how much input is consumed.
 201 Hence the inner loop to make sure that
 202 all of the input is consumed by providing more output space each time.  Since <tt>avail_in</tt>
 203 and <tt>next_in</tt> are updated by <tt>deflate()</tt>, we don't have to mess with those
 204 between <tt>deflate()</tt> calls until it's all used up.
 205 <p>
 206 The parameters to <tt>deflate()</tt> are a pointer to the <tt>strm</tt> structure containing
 207 the input and output information and the internal compression engine state, and a parameter
 208 indicating whether and how to flush data to the output.  Normally <tt>deflate</tt> will consume
 209 several K bytes of input data before producing any output (except for the header), in order
 210 to accumulate statistics on the data for optimum compression.  It will then put out a burst of
 211 compressed data, and proceed to consume more input before the next burst.  Eventually,
 212 <tt>deflate()</tt>
 213 must be told to terminate the stream, complete the compression with provided input data, and
 214 write out the trailer check value.  <tt>deflate()</tt> will continue to compress normally as long
 215 as the flush parameter is <tt>Z_NO_FLUSH</tt>.  Once the <tt>Z_FINISH</tt> parameter is provided,
 216 <tt>deflate()</tt> will begin to complete the compressed output stream.  However depending on how
 217 much output space is provided, <tt>deflate()</tt> may have to be called several times until it
 218 has provided the complete compressed stream, even after it has consumed all of the input.  The flush
 219 parameter must continue to be <tt>Z_FINISH</tt> for those subsequent calls.
 220 <p>
 221 There are other values of the flush parameter that are used in more advanced applications.  You can
 222 force <tt>deflate()</tt> to produce a burst of output that encodes all of the input data provided
 223 so far, even if it wouldn't have otherwise, for example to control data latency on a link with
 224 compressed data.  You can also ask that <tt>deflate()</tt> do that as well as erase any history up to
 225 that point so that what follows can be decompressed independently, for example for random access
 226 applications.  Both requests will degrade compression by an amount depending on how often such
 227 requests are made.
 228 <p>
 229 <tt>deflate()</tt> has a return value that can indicate errors, yet we do not check it here.  Why
 230 not?  Well, it turns out that <tt>deflate()</tt> can do no wrong here.  Let's go through
 231 <tt>deflate()</tt>'s return values and dispense with them one by one.  The possible values are
 232 <tt>Z_OK</tt>, <tt>Z_STREAM_END</tt>, <tt>Z_STREAM_ERROR</tt>, or <tt>Z_BUF_ERROR</tt>.  <tt>Z_OK</tt>
 233 is, well, ok.  <tt>Z_STREAM_END</tt> is also ok and will be returned for the last call of
 234 <tt>deflate()</tt>.  This is already guaranteed by calling <tt>deflate()</tt> with <tt>Z_FINISH</tt>
 235 until it has no more output.  <tt>Z_STREAM_ERROR</tt> is only possible if the stream is not
 236 initialized properly, but we did initialize it properly.  There is no harm in checking for
 237 <tt>Z_STREAM_ERROR</tt> here, for example to check for the possibility that some
 238 other part of the application inadvertently clobbered the memory containing the <em>zlib</em> state.
 239 <tt>Z_BUF_ERROR</tt> will be explained further below, but
 240 suffice it to say that this is simply an indication that <tt>deflate()</tt> could not consume
 241 more input or produce more output.  <tt>deflate()</tt> can be called again with more output space
 242 or more available input, which it will be in this code.
 243 <pre><b>
 244             ret = deflate(&amp;strm, flush);    /* no bad return value */
 245             assert(ret != Z_STREAM_ERROR);  /* state not clobbered */
 246 </b></pre>
 247 Now we compute how much output <tt>deflate()</tt> provided on the last call, which is the
 248 difference between how much space was provided before the call, and how much output space
 249 is still available after the call.  Then that data, if any, is written to the output file.
 250 We can then reuse the output buffer for the next call of <tt>deflate()</tt>.  Again if there
 251 is a file i/o error, we call <tt>deflateEnd()</tt> before returning to avoid a memory leak.
 252 <pre><b>
 253             have = CHUNK - strm.avail_out;
 254             if (fwrite(out, 1, have, dest) != have || ferror(dest)) {
 255                 (void)deflateEnd(&amp;strm);
 256                 return Z_ERRNO;
 257             }
 258 </b></pre>
 259 The inner <tt>do</tt>-loop is repeated until the last <tt>deflate()</tt> call fails to fill the
 260 provided output buffer.  Then we know that <tt>deflate()</tt> has done as much as it can with
 261 the provided input, and that all of that input has been consumed.  We can then fall out of this
 262 loop and reuse the input buffer.
 263 <p>
 264 The way we tell that <tt>deflate()</tt> has no more output is by seeing that it did not fill
 265 the output buffer, leaving <tt>avail_out</tt> greater than zero.  However suppose that
 266 <tt>deflate()</tt> has no more output, but just so happened to exactly fill the output buffer!
 267 <tt>avail_out</tt> is zero, and we can't tell that <tt>deflate()</tt> has done all it can.
 268 As far as we know, <tt>deflate()</tt>
 269 has more output for us.  So we call it again.  But now <tt>deflate()</tt> produces no output
 270 at all, and <tt>avail_out</tt> remains unchanged as <tt>CHUNK</tt>.  That <tt>deflate()</tt> call
 271 wasn't able to do anything, either consume input or produce output, and so it returns
 272 <tt>Z_BUF_ERROR</tt>.  (See, I told you I'd cover this later.)  However this is not a problem at
 273 all.  Now we finally have the desired indication that <tt>deflate()</tt> is really done,
 274 and so we drop out of the inner loop to provide more input to <tt>deflate()</tt>.
 275 <p>
 276 With <tt>flush</tt> set to <tt>Z_FINISH</tt>, this final set of <tt>deflate()</tt> calls will
 277 complete the output stream.  Once that is done, subsequent calls of <tt>deflate()</tt> would return
 278 <tt>Z_STREAM_ERROR</tt> if the flush parameter is not <tt>Z_FINISH</tt>, and do no more processing
 279 until the state is reinitialized.
 280 <p>
 281 Some applications of <em>zlib</em> have two loops that call <tt>deflate()</tt>
 282 instead of the single inner loop we have here.  The first loop would call
 283 without flushing and feed all of the data to <tt>deflate()</tt>.  The second loop would call
 284 <tt>deflate()</tt> with no more
 285 data and the <tt>Z_FINISH</tt> parameter to complete the process.  As you can see from this
 286 example, that can be avoided by simply keeping track of the current flush state.
 287 <pre><b>
 288         } while (strm.avail_out == 0);
 289         assert(strm.avail_in == 0);     /* all input will be used */
 290 </b></pre><!-- -->
 291 Now we check to see if we have already processed all of the input file.  That information was
 292 saved in the <tt>flush</tt> variable, so we see if that was set to <tt>Z_FINISH</tt>.  If so,
 293 then we're done and we fall out of the outer loop.  We're guaranteed to get <tt>Z_STREAM_END</tt>
 294 from the last <tt>deflate()</tt> call, since we ran it until the last chunk of input was
 295 consumed and all of the output was generated.
 296 <pre><b>
 297         /* done when last data in file processed */
 298     } while (flush != Z_FINISH);
 299     assert(ret == Z_STREAM_END);        /* stream will be complete */
 300 </b></pre><!-- -->
 301 The process is complete, but we still need to deallocate the state to avoid a memory leak
 302 (or rather more like a memory hemorrhage if you didn't do this).  Then
 303 finally we can return with a happy return value.
 304 <pre><b>
 305     /* clean up and return */
 306     (void)deflateEnd(&amp;strm);
 307     return Z_OK;
 308 }
 309 </b></pre><!-- -->
 310 Now we do the same thing for decompression in the <tt>inf()</tt> routine. <tt>inf()</tt>
 311 decompresses what is hopefully a valid <em>zlib</em> stream from the input file and writes the
 312 uncompressed data to the output file.  Much of the discussion above for <tt>def()</tt>
 313 applies to <tt>inf()</tt> as well, so the discussion here will focus on the differences between
 314 the two.
 315 <pre><b>
 316 /* Decompress from file source to file dest until stream ends or EOF.
 317    inf() returns Z_OK on success, Z_MEM_ERROR if memory could not be
 318    allocated for processing, Z_DATA_ERROR if the deflate data is
 319    invalid or incomplete, Z_VERSION_ERROR if the version of zlib.h and
 320    the version of the library linked do not match, or Z_ERRNO if there
 321    is an error reading or writing the files. */
 322 int inf(FILE *source, FILE *dest)
 323 {
 324 </b></pre>
 325 The local variables have the same functionality as they do for <tt>def()</tt>.  The
 326 only difference is that there is no <tt>flush</tt> variable, since <tt>inflate()</tt>
 327 can tell from the <em>zlib</em> stream itself when the stream is complete.
 328 <pre><b>
 329     int ret;
 330     unsigned have;
 331     z_stream strm;
 332     unsigned char in[CHUNK];
 333     unsigned char out[CHUNK];
 334 </b></pre><!-- -->
 335 The initialization of the state is the same, except that there is no compression level,
 336 of course, and two more elements of the structure are initialized.  <tt>avail_in</tt>
 337 and <tt>next_in</tt> must be initialized before calling <tt>inflateInit()</tt>.  This
 338 is because the application has the option to provide the start of the zlib stream in
 339 order for <tt>inflateInit()</tt> to have access to information about the compression
 340 method to aid in memory allocation.  In the current implementation of <em>zlib</em>
 341 (up through versions 1.2.x), the method-dependent memory allocations are deferred to the first call of
 342 <tt>inflate()</tt> anyway.  However those fields must be initialized since later versions
 343 of <em>zlib</em> that provide more compression methods may take advantage of this interface.
 344 In any case, no decompression is performed by <tt>inflateInit()</tt>, so the
 345 <tt>avail_out</tt> and <tt>next_out</tt> fields do not need to be initialized before calling.
 346 <p>
 347 Here <tt>avail_in</tt> is set to zero and <tt>next_in</tt> is set to <tt>Z_NULL</tt> to
 348 indicate that no input data is being provided.
 349 <pre><b>
 350     /* allocate inflate state */
 351     strm.zalloc = Z_NULL;
 352     strm.zfree = Z_NULL;
 353     strm.opaque = Z_NULL;
 354     strm.avail_in = 0;
 355     strm.next_in = Z_NULL;
 356     ret = inflateInit(&amp;strm);
 357     if (ret != Z_OK)
 358         return ret;
 359 </b></pre><!-- -->
 360 The outer <tt>do</tt>-loop decompresses input until <tt>inflate()</tt> indicates
 361 that it has reached the end of the compressed data and has produced all of the uncompressed
 362 output.  This is in contrast to <tt>def()</tt> which processes all of the input file.
 363 If end-of-file is reached before the compressed data self-terminates, then the compressed
 364 data is incomplete and an error is returned.
 365 <pre><b>
 366     /* decompress until deflate stream ends or end of file */
 367     do {
 368 </b></pre>
 369 We read input data and set the <tt>strm</tt> structure accordingly.  If we've reached the
 370 end of the input file, then we leave the outer loop and report an error, since the
 371 compressed data is incomplete.  Note that we may read more data than is eventually consumed
 372 by <tt>inflate()</tt>, if the input file continues past the <em>zlib</em> stream.
 373 For applications where <em>zlib</em> streams are embedded in other data, this routine would
 374 need to be modified to return the unused data, or at least indicate how much of the input
 375 data was not used, so the application would know where to pick up after the <em>zlib</em> stream.
 376 <pre><b>
 377         strm.avail_in = fread(in, 1, CHUNK, source);
 378         if (ferror(source)) {
 379             (void)inflateEnd(&amp;strm);
 380             return Z_ERRNO;
 381         }
 382         if (strm.avail_in == 0)
 383             break;
 384         strm.next_in = in;
 385 </b></pre><!-- -->
 386 The inner <tt>do</tt>-loop has the same function it did in <tt>def()</tt>, which is to
 387 keep calling <tt>inflate()</tt> until has generated all of the output it can with the
 388 provided input.
 389 <pre><b>
 390         /* run inflate() on input until output buffer not full */
 391         do {
 392 </b></pre>
 393 Just like in <tt>def()</tt>, the same output space is provided for each call of <tt>inflate()</tt>.
 394 <pre><b>
 395             strm.avail_out = CHUNK;
 396             strm.next_out = out;
 397 </b></pre>
 398 Now we run the decompression engine itself.  There is no need to adjust the flush parameter, since
 399 the <em>zlib</em> format is self-terminating. The main difference here is that there are
 400 return values that we need to pay attention to.  <tt>Z_DATA_ERROR</tt>
 401 indicates that <tt>inflate()</tt> detected an error in the <em>zlib</em> compressed data format,
 402 which means that either the data is not a <em>zlib</em> stream to begin with, or that the data was
 403 corrupted somewhere along the way since it was compressed.  The other error to be processed is
 404 <tt>Z_MEM_ERROR</tt>, which can occur since memory allocation is deferred until <tt>inflate()</tt>
 405 needs it, unlike <tt>deflate()</tt>, whose memory is allocated at the start by <tt>deflateInit()</tt>.
 406 <p>
 407 Advanced applications may use
 408 <tt>deflateSetDictionary()</tt> to prime <tt>deflate()</tt> with a set of likely data to improve the
 409 first 32K or so of compression.  This is noted in the <em>zlib</em> header, so <tt>inflate()</tt>
 410 requests that that dictionary be provided before it can start to decompress.  Without the dictionary,
 411 correct decompression is not possible.  For this routine, we have no idea what the dictionary is,
 412 so the <tt>Z_NEED_DICT</tt> indication is converted to a <tt>Z_DATA_ERROR</tt>.
 413 <p>
 414 <tt>inflate()</tt> can also return <tt>Z_STREAM_ERROR</tt>, which should not be possible here,
 415 but could be checked for as noted above for <tt>def()</tt>.  <tt>Z_BUF_ERROR</tt> does not need to be
 416 checked for here, for the same reasons noted for <tt>def()</tt>.  <tt>Z_STREAM_END</tt> will be
 417 checked for later.
 418 <pre><b>
 419             ret = inflate(&amp;strm, Z_NO_FLUSH);
 420             assert(ret != Z_STREAM_ERROR);  /* state not clobbered */
 421             switch (ret) {
 422             case Z_NEED_DICT:
 423                 ret = Z_DATA_ERROR;     /* and fall through */
 424             case Z_DATA_ERROR:
 425             case Z_MEM_ERROR:
 426                 (void)inflateEnd(&amp;strm);
 427                 return ret;
 428             }
 429 </b></pre>
 430 The output of <tt>inflate()</tt> is handled identically to that of <tt>deflate()</tt>.
 431 <pre><b>
 432             have = CHUNK - strm.avail_out;
 433             if (fwrite(out, 1, have, dest) != have || ferror(dest)) {
 434                 (void)inflateEnd(&amp;strm);
 435                 return Z_ERRNO;
 436             }
 437 </b></pre>
 438 The inner <tt>do</tt>-loop ends when <tt>inflate()</tt> has no more output as indicated
 439 by not filling the output buffer, just as for <tt>deflate()</tt>.  In this case, we cannot
 440 assert that <tt>strm.avail_in</tt> will be zero, since the deflate stream may end before the file
 441 does.
 442 <pre><b>
 443         } while (strm.avail_out == 0);
 444 </b></pre><!-- -->
 445 The outer <tt>do</tt>-loop ends when <tt>inflate()</tt> reports that it has reached the
 446 end of the input <em>zlib</em> stream, has completed the decompression and integrity
 447 check, and has provided all of the output.  This is indicated by the <tt>inflate()</tt>
 448 return value <tt>Z_STREAM_END</tt>.  The inner loop is guaranteed to leave <tt>ret</tt>
 449 equal to <tt>Z_STREAM_END</tt> if the last chunk of the input file read contained the end
 450 of the <em>zlib</em> stream.  So if the return value is not <tt>Z_STREAM_END</tt>, the
 451 loop continues to read more input.
 452 <pre><b>
 453         /* done when inflate() says it's done */
 454     } while (ret != Z_STREAM_END);
 455 </b></pre><!-- -->
 456 At this point, decompression successfully completed, or we broke out of the loop due to no
 457 more data being available from the input file.  If the last <tt>inflate()</tt> return value
 458 is not <tt>Z_STREAM_END</tt>, then the <em>zlib</em> stream was incomplete and a data error
 459 is returned.  Otherwise, we return with a happy return value.  Of course, <tt>inflateEnd()</tt>
 460 is called first to avoid a memory leak.
 461 <pre><b>
 462     /* clean up and return */
 463     (void)inflateEnd(&amp;strm);
 464     return ret == Z_STREAM_END ? Z_OK : Z_DATA_ERROR;
 465 }
 466 </b></pre><!-- -->
 467 That ends the routines that directly use <em>zlib</em>.  The following routines make this
 468 a command-line program by running data through the above routines from <tt>stdin</tt> to
 469 <tt>stdout</tt>, and handling any errors reported by <tt>def()</tt> or <tt>inf()</tt>.
 470 <p>
 471 <tt>zerr()</tt> is used to interpret the possible error codes from <tt>def()</tt>
 472 and <tt>inf()</tt>, as detailed in their comments above, and print out an error message.
 473 Note that these are only a subset of the possible return values from <tt>deflate()</tt>
 474 and <tt>inflate()</tt>.
 475 <pre><b>
 476 /* report a zlib or i/o error */
 477 void zerr(int ret)
 478 {
 479     fputs("zpipe: ", stderr);
 480     switch (ret) {
 481     case Z_ERRNO:
 482         if (ferror(stdin))
 483             fputs("error reading stdin\n", stderr);
 484         if (ferror(stdout))
 485             fputs("error writing stdout\n", stderr);
 486         break;
 487     case Z_STREAM_ERROR:
 488         fputs("invalid compression level\n", stderr);
 489         break;
 490     case Z_DATA_ERROR:
 491         fputs("invalid or incomplete deflate data\n", stderr);
 492         break;
 493     case Z_MEM_ERROR:
 494         fputs("out of memory\n", stderr);
 495         break;
 496     case Z_VERSION_ERROR:
 497         fputs("zlib version mismatch!\n", stderr);
 498     }
 499 }
 500 </b></pre><!-- -->
 501 Here is the <tt>main()</tt> routine used to test <tt>def()</tt> and <tt>inf()</tt>.  The
 502 <tt>zpipe</tt> command is simply a compression pipe from <tt>stdin</tt> to <tt>stdout</tt>, if
 503 no arguments are given, or it is a decompression pipe if <tt>zpipe -d</tt> is used.  If any other
 504 arguments are provided, no compression or decompression is performed.  Instead a usage
 505 message is displayed.  Examples are <tt>zpipe < foo.txt > foo.txt.z</tt> to compress, and
 506 <tt>zpipe -d < foo.txt.z > foo.txt</tt> to decompress.
 507 <pre><b>
 508 /* compress or decompress from stdin to stdout */
 509 int main(int argc, char **argv)
 510 {
 511     int ret;
 512
 513     /* avoid end-of-line conversions */
 514     SET_BINARY_MODE(stdin);
 515     SET_BINARY_MODE(stdout);
 516
 517     /* do compression if no arguments */
 518     if (argc == 1) {
 519         ret = def(stdin, stdout, Z_DEFAULT_COMPRESSION);
 520         if (ret != Z_OK)
 521             zerr(ret);
 522         return ret;
 523     }
 524
 525     /* do decompression if -d specified */
 526     else if (argc == 2 &amp;&amp; strcmp(argv[1], "-d") == 0) {
 527         ret = inf(stdin, stdout);
 528         if (ret != Z_OK)
 529             zerr(ret);
 530         return ret;
 531     }
 532
 533     /* otherwise, report usage */
 534     else {
 535         fputs("zpipe usage: zpipe [-d] &lt; source &gt; dest\n", stderr);
 536         return 1;
 537     }
 538 }
 539 </b></pre>
 540 <hr>
 541 <i>Last modified 24 January 2023<br>
 542 Copyright &#169; 2004-2023 Mark Adler</i><br>
 543 <a rel="license" href="http://creativecommons.org/licenses/by-nd/4.0/">
 544 <img alt="Creative Commons License" style="border-width:0"
 545 src="https://i.creativecommons.org/l/by-nd/4.0/88x31.png"></a>
 546 <a rel="license" href="http://creativecommons.org/licenses/by-nd/4.0/">
 547 Creative Commons Attribution-NoDerivatives 4.0 International License</a>.
 548 </body>
 549 </html>