zlib_how.html revision 1.1.1.2 
11.1Schristos<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
21.1Schristos  "http://www.w3.org/TR/REC-html40/loose.dtd">
31.1Schristos<html>
41.1Schristos<head>
51.1Schristos<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
61.1Schristos<title>zlib Usage Example</title>
71.1.1.2Schristos<!--  Copyright (c) 2004, 2005 Mark Adler.  -->
81.1Schristos</head>
91.1Schristos<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#00A000">
101.1Schristos<h2 align="center"> zlib Usage Example </h2>
111.1SchristosWe often get questions about how the <tt>deflate()</tt> and <tt>inflate()</tt> functions should be used.
121.1SchristosUsers wonder when they should provide more input, when they should use more output,
131.1Schristoswhat to do with a <tt>Z_BUF_ERROR</tt>, how to make sure the process terminates properly, and
141.1Schristosso on.  So for those who have read <tt>zlib.h</tt> (a few times), and
151.1Schristoswould like further edification, below is an annotated example in C of simple routines to compress and decompress
161.1Schristosfrom an input file to an output file using <tt>deflate()</tt> and <tt>inflate()</tt> respectively.  The
171.1Schristosannotations are interspersed between lines of the code.  So please read between the lines.
181.1SchristosWe hope this helps explain some of the intricacies of <em>zlib</em>.
191.1Schristos<p>
201.1SchristosWithout further adieu, here is the program <a href="zpipe.c"><tt>zpipe.c</tt></a>:
211.1Schristos<pre><b>
221.1Schristos/* zpipe.c: example of proper use of zlib's inflate() and deflate()
231.1Schristos   Not copyrighted -- provided to the public domain
241.1.1.2Schristos   Version 1.4  11 December 2005  Mark Adler */
251.1Schristos
261.1Schristos/* Version history:
271.1Schristos   1.0  30 Oct 2004  First version
281.1Schristos   1.1   8 Nov 2004  Add void casting for unused return values
291.1Schristos                     Use switch statement for inflate() return values
301.1Schristos   1.2   9 Nov 2004  Add assertions to document zlib guarantees
311.1.1.2Schristos   1.3   6 Apr 2005  Remove incorrect assertion in inf()
321.1.1.2Schristos   1.4  11 Dec 2005  Add hack to avoid MSDOS end-of-line conversions
331.1.1.2Schristos                     Avoid some compiler warnings for input and output buffers
341.1Schristos */
351.1Schristos</b></pre><!-- -->
361.1SchristosWe now include the header files for the required definitions.  From
371.1Schristos<tt>stdio.h</tt> we use <tt>fopen()</tt>, <tt>fread()</tt>, <tt>fwrite()</tt>,
381.1Schristos<tt>feof()</tt>, <tt>ferror()</tt>, and <tt>fclose()</tt> for file i/o, and
391.1Schristos<tt>fputs()</tt> for error messages.  From <tt>string.h</tt> we use
401.1Schristos<tt>strcmp()</tt> for command line argument processing.
411.1SchristosFrom <tt>assert.h</tt> we use the <tt>assert()</tt> macro.
421.1SchristosFrom <tt>zlib.h</tt>
431.1Schristoswe use the basic compression functions <tt>deflateInit()</tt>,
441.1Schristos<tt>deflate()</tt>, and <tt>deflateEnd()</tt>, and the basic decompression
451.1Schristosfunctions <tt>inflateInit()</tt>, <tt>inflate()</tt>, and
461.1Schristos<tt>inflateEnd()</tt>.
471.1Schristos<pre><b>
481.1Schristos#include &lt;stdio.h&gt;
491.1Schristos#include &lt;string.h&gt;
501.1Schristos#include &lt;assert.h&gt;
511.1Schristos#include "zlib.h"
521.1Schristos</b></pre><!-- -->
531.1.1.2SchristosThis is an ugly hack required to avoid corruption of the input and output data on
541.1.1.2SchristosWindows/MS-DOS systems.  Without this, those systems would assume that the input and output
551.1.1.2Schristosfiles are text, and try to convert the end-of-line characters from one standard to
561.1.1.2Schristosanother.  That would corrupt binary data, and in particular would render the compressed data unusable.
571.1.1.2SchristosThis sets the input and output to binary which suppresses the end-of-line conversions.
581.1.1.2Schristos<tt>SET_BINARY_MODE()</tt> will be used later on <tt>stdin</tt> and <tt>stdout</tt>, at the beginning of <tt>main()</tt>.
591.1.1.2Schristos<pre><b>
601.1.1.2Schristos#if defined(MSDOS) || defined(OS2) || defined(WIN32) || defined(__CYGWIN__)
611.1.1.2Schristos#  include &lt;fcntl.h&gt;
621.1.1.2Schristos#  include &lt;io.h&gt;
631.1.1.2Schristos#  define SET_BINARY_MODE(file) setmode(fileno(file), O_BINARY)
641.1.1.2Schristos#else
651.1.1.2Schristos#  define SET_BINARY_MODE(file)
661.1.1.2Schristos#endif
671.1.1.2Schristos</b></pre><!-- -->
681.1Schristos<tt>CHUNK</tt> is simply the buffer size for feeding data to and pulling data
691.1Schristosfrom the <em>zlib</em> routines.  Larger buffer sizes would be more efficient,
701.1Schristosespecially for <tt>inflate()</tt>.  If the memory is available, buffers sizes
711.1Schristoson the order of 128K or 256K bytes should be used.
721.1Schristos<pre><b>
731.1Schristos#define CHUNK 16384
741.1Schristos</b></pre><!-- -->
751.1SchristosThe <tt>def()</tt> routine compresses data from an input file to an output file.  The output data
761.1Schristoswill be in the <em>zlib</em> format, which is different from the <em>gzip</em> or <em>zip</em>
771.1Schristosformats.  The <em>zlib</em> format has a very small header of only two bytes to identify it as
781.1Schristosa <em>zlib</em> stream and to provide decoding information, and a four-byte trailer with a fast
791.1Schristoscheck value to verify the integrity of the uncompressed data after decoding.
801.1Schristos<pre><b>
811.1Schristos/* Compress from file source to file dest until EOF on source.
821.1Schristos   def() returns Z_OK on success, Z_MEM_ERROR if memory could not be
831.1Schristos   allocated for processing, Z_STREAM_ERROR if an invalid compression
841.1Schristos   level is supplied, Z_VERSION_ERROR if the version of zlib.h and the
851.1Schristos   version of the library linked do not match, or Z_ERRNO if there is
861.1Schristos   an error reading or writing the files. */
871.1Schristosint def(FILE *source, FILE *dest, int level)
881.1Schristos{
891.1Schristos</b></pre>
901.1SchristosHere are the local variables for <tt>def()</tt>.  <tt>ret</tt> will be used for <em>zlib</em>
911.1Schristosreturn codes.  <tt>flush</tt> will keep track of the current flushing state for <tt>deflate()</tt>,
921.1Schristoswhich is either no flushing, or flush to completion after the end of the input file is reached.
931.1Schristos<tt>have</tt> is the amount of data returned from <tt>deflate()</tt>.  The <tt>strm</tt> structure
941.1Schristosis used to pass information to and from the <em>zlib</em> routines, and to maintain the
951.1Schristos<tt>deflate()</tt> state.  <tt>in</tt> and <tt>out</tt> are the input and output buffers for
961.1Schristos<tt>deflate()</tt>.
971.1Schristos<pre><b>
981.1Schristos    int ret, flush;
991.1Schristos    unsigned have;
1001.1Schristos    z_stream strm;
1011.1.1.2Schristos    unsigned char in[CHUNK];
1021.1.1.2Schristos    unsigned char out[CHUNK];
1031.1Schristos</b></pre><!-- -->
1041.1SchristosThe first thing we do is to initialize the <em>zlib</em> state for compression using
1051.1Schristos<tt>deflateInit()</tt>.  This must be done before the first use of <tt>deflate()</tt>.
1061.1SchristosThe <tt>zalloc</tt>, <tt>zfree</tt>, and <tt>opaque</tt> fields in the <tt>strm</tt>
1071.1Schristosstructure must be initialized before calling <tt>deflateInit()</tt>.  Here they are
1081.1Schristosset to the <em>zlib</em> constant <tt>Z_NULL</tt> to request that <em>zlib</em> use
1091.1Schristosthe default memory allocation routines.  An application may also choose to provide
1101.1Schristoscustom memory allocation routines here.  <tt>deflateInit()</tt> will allocate on the
1111.1Schristosorder of 256K bytes for the internal state.
1121.1Schristos(See <a href="zlib_tech.html"><em>zlib Technical Details</em></a>.)
1131.1Schristos<p>
1141.1Schristos<tt>deflateInit()</tt> is called with a pointer to the structure to be initialized and
1151.1Schristosthe compression level, which is an integer in the range of -1 to 9.  Lower compression
1161.1Schristoslevels result in faster execution, but less compression.  Higher levels result in
1171.1Schristosgreater compression, but slower execution.  The <em>zlib</em> constant Z_DEFAULT_COMPRESSION,
1181.1Schristosequal to -1,
1191.1Schristosprovides a good compromise between compression and speed and is equivalent to level 6.
1201.1SchristosLevel 0 actually does no compression at all, and in fact expands the data slightly to produce
1211.1Schristosthe <em>zlib</em> format (it is not a byte-for-byte copy of the input).
1221.1SchristosMore advanced applications of <em>zlib</em>
1231.1Schristosmay use <tt>deflateInit2()</tt> here instead.  Such an application may want to reduce how
1241.1Schristosmuch memory will be used, at some price in compression.  Or it may need to request a
1251.1Schristos<em>gzip</em> header and trailer instead of a <em>zlib</em> header and trailer, or raw
1261.1Schristosencoding with no header or trailer at all.
1271.1Schristos<p>
1281.1SchristosWe must check the return value of <tt>deflateInit()</tt> against the <em>zlib</em> constant
1291.1Schristos<tt>Z_OK</tt> to make sure that it was able to
1301.1Schristosallocate memory for the internal state, and that the provided arguments were valid.
1311.1Schristos<tt>deflateInit()</tt> will also check that the version of <em>zlib</em> that the <tt>zlib.h</tt>
1321.1Schristosfile came from matches the version of <em>zlib</em> actually linked with the program.  This
1331.1Schristosis especially important for environments in which <em>zlib</em> is a shared library.
1341.1Schristos<p>
1351.1SchristosNote that an application can initialize multiple, independent <em>zlib</em> streams, which can
1361.1Schristosoperate in parallel.  The state information maintained in the structure allows the <em>zlib</em>
1371.1Schristosroutines to be reentrant.
1381.1Schristos<pre><b>
1391.1Schristos    /* allocate deflate state */
1401.1Schristos    strm.zalloc = Z_NULL;
1411.1Schristos    strm.zfree = Z_NULL;
1421.1Schristos    strm.opaque = Z_NULL;
1431.1Schristos    ret = deflateInit(&amp;strm, level);
1441.1Schristos    if (ret != Z_OK)
1451.1Schristos        return ret;
1461.1Schristos</b></pre><!-- -->
1471.1SchristosWith the pleasantries out of the way, now we can get down to business.  The outer <tt>do</tt>-loop
1481.1Schristosreads all of the input file and exits at the bottom of the loop once end-of-file is reached.
1491.1SchristosThis loop contains the only call of <tt>deflate()</tt>.  So we must make sure that all of the
1501.1Schristosinput data has been processed and that all of the output data has been generated and consumed
1511.1Schristosbefore we fall out of the loop at the bottom.
1521.1Schristos<pre><b>
1531.1Schristos    /* compress until end of file */
1541.1Schristos    do {
1551.1Schristos</b></pre>
1561.1SchristosWe start off by reading data from the input file.  The number of bytes read is put directly
1571.1Schristosinto <tt>avail_in</tt>, and a pointer to those bytes is put into <tt>next_in</tt>.  We also
1581.1Schristoscheck to see if end-of-file on the input has been reached.  If we are at the end of file, then <tt>flush</tt> is set to the
1591.1Schristos<em>zlib</em> constant <tt>Z_FINISH</tt>, which is later passed to <tt>deflate()</tt> to
1601.1Schristosindicate that this is the last chunk of input data to compress.  We need to use <tt>feof()</tt>
1611.1Schristosto check for end-of-file as opposed to seeing if fewer than <tt>CHUNK</tt> bytes have been read.  The
1621.1Schristosreason is that if the input file length is an exact multiple of <tt>CHUNK</tt>, we will miss
1631.1Schristosthe fact that we got to the end-of-file, and not know to tell <tt>deflate()</tt> to finish
1641.1Schristosup the compressed stream.  If we are not yet at the end of the input, then the <em>zlib</em>
1651.1Schristosconstant <tt>Z_NO_FLUSH</tt> will be passed to <tt>deflate</tt> to indicate that we are still
1661.1Schristosin the middle of the uncompressed data.
1671.1Schristos<p>
1681.1SchristosIf there is an error in reading from the input file, the process is aborted with
1691.1Schristos<tt>deflateEnd()</tt> being called to free the allocated <em>zlib</em> state before returning
1701.1Schristosthe error.  We wouldn't want a memory leak, now would we?  <tt>deflateEnd()</tt> can be called
1711.1Schristosat any time after the state has been initialized.  Once that's done, <tt>deflateInit()</tt> (or
1721.1Schristos<tt>deflateInit2()</tt>) would have to be called to start a new compression process.  There is
1731.1Schristosno point here in checking the <tt>deflateEnd()</tt> return code.  The deallocation can't fail.
1741.1Schristos<pre><b>
1751.1Schristos        strm.avail_in = fread(in, 1, CHUNK, source);
1761.1Schristos        if (ferror(source)) {
1771.1Schristos            (void)deflateEnd(&amp;strm);
1781.1Schristos            return Z_ERRNO;
1791.1Schristos        }
1801.1Schristos        flush = feof(source) ? Z_FINISH : Z_NO_FLUSH;
1811.1Schristos        strm.next_in = in;
1821.1Schristos</b></pre><!-- -->
1831.1SchristosThe inner <tt>do</tt>-loop passes our chunk of input data to <tt>deflate()</tt>, and then
1841.1Schristoskeeps calling <tt>deflate()</tt> until it is done producing output.  Once there is no more
1851.1Schristosnew output, <tt>deflate()</tt> is guaranteed to have consumed all of the input, i.e.,
1861.1Schristos<tt>avail_in</tt> will be zero.
1871.1Schristos<pre><b>
1881.1Schristos        /* run deflate() on input until output buffer not full, finish
1891.1Schristos           compression if all of source has been read in */
1901.1Schristos        do {
1911.1Schristos</b></pre>
1921.1SchristosOutput space is provided to <tt>deflate()</tt> by setting <tt>avail_out</tt> to the number
1931.1Schristosof available output bytes and <tt>next_out</tt> to a pointer to that space.
1941.1Schristos<pre><b>
1951.1Schristos            strm.avail_out = CHUNK;
1961.1Schristos            strm.next_out = out;
1971.1Schristos</b></pre>
1981.1SchristosNow we call the compression engine itself, <tt>deflate()</tt>.  It takes as many of the
1991.1Schristos<tt>avail_in</tt> bytes at <tt>next_in</tt> as it can process, and writes as many as
2001.1Schristos<tt>avail_out</tt> bytes to <tt>next_out</tt>.  Those counters and pointers are then
2011.1Schristosupdated past the input data consumed and the output data written.  It is the amount of
2021.1Schristosoutput space available that may limit how much input is consumed.
2031.1SchristosHence the inner loop to make sure that
2041.1Schristosall of the input is consumed by providing more output space each time.  Since <tt>avail_in</tt>
2051.1Schristosand <tt>next_in</tt> are updated by <tt>deflate()</tt>, we don't have to mess with those
2061.1Schristosbetween <tt>deflate()</tt> calls until it's all used up.
2071.1Schristos<p>
2081.1SchristosThe parameters to <tt>deflate()</tt> are a pointer to the <tt>strm</tt> structure containing
2091.1Schristosthe input and output information and the internal compression engine state, and a parameter
2101.1Schristosindicating whether and how to flush data to the output.  Normally <tt>deflate</tt> will consume
2111.1Schristosseveral K bytes of input data before producing any output (except for the header), in order
2121.1Schristosto accumulate statistics on the data for optimum compression.  It will then put out a burst of
2131.1Schristoscompressed data, and proceed to consume more input before the next burst.  Eventually,
2141.1Schristos<tt>deflate()</tt>
2151.1Schristosmust be told to terminate the stream, complete the compression with provided input data, and
2161.1Schristoswrite out the trailer check value.  <tt>deflate()</tt> will continue to compress normally as long
2171.1Schristosas the flush parameter is <tt>Z_NO_FLUSH</tt>.  Once the <tt>Z_FINISH</tt> parameter is provided,
2181.1Schristos<tt>deflate()</tt> will begin to complete the compressed output stream.  However depending on how
2191.1Schristosmuch output space is provided, <tt>deflate()</tt> may have to be called several times until it
2201.1Schristoshas provided the complete compressed stream, even after it has consumed all of the input.  The flush
2211.1Schristosparameter must continue to be <tt>Z_FINISH</tt> for those subsequent calls.
2221.1Schristos<p>
2231.1SchristosThere are other values of the flush parameter that are used in more advanced applications.  You can
2241.1Schristosforce <tt>deflate()</tt> to produce a burst of output that encodes all of the input data provided
2251.1Schristosso far, even if it wouldn't have otherwise, for example to control data latency on a link with
2261.1Schristoscompressed data.  You can also ask that <tt>deflate()</tt> do that as well as erase any history up to
2271.1Schristosthat point so that what follows can be decompressed independently, for example for random access
2281.1Schristosapplications.  Both requests will degrade compression by an amount depending on how often such
2291.1Schristosrequests are made.
2301.1Schristos<p>
2311.1Schristos<tt>deflate()</tt> has a return value that can indicate errors, yet we do not check it here.  Why
2321.1Schristosnot?  Well, it turns out that <tt>deflate()</tt> can do no wrong here.  Let's go through
2331.1Schristos<tt>deflate()</tt>'s return values and dispense with them one by one.  The possible values are
2341.1Schristos<tt>Z_OK</tt>, <tt>Z_STREAM_END</tt>, <tt>Z_STREAM_ERROR</tt>, or <tt>Z_BUF_ERROR</tt>.  <tt>Z_OK</tt>
2351.1Schristosis, well, ok.  <tt>Z_STREAM_END</tt> is also ok and will be returned for the last call of
2361.1Schristos<tt>deflate()</tt>.  This is already guaranteed by calling <tt>deflate()</tt> with <tt>Z_FINISH</tt>
2371.1Schristosuntil it has no more output.  <tt>Z_STREAM_ERROR</tt> is only possible if the stream is not
2381.1Schristosinitialized properly, but we did initialize it properly.  There is no harm in checking for
2391.1Schristos<tt>Z_STREAM_ERROR</tt> here, for example to check for the possibility that some
2401.1Schristosother part of the application inadvertently clobbered the memory containing the <em>zlib</em> state.
2411.1Schristos<tt>Z_BUF_ERROR</tt> will be explained further below, but
2421.1Schristossuffice it to say that this is simply an indication that <tt>deflate()</tt> could not consume
2431.1Schristosmore input or produce more output.  <tt>deflate()</tt> can be called again with more output space
2441.1Schristosor more available input, which it will be in this code.
2451.1Schristos<pre><b>
2461.1Schristos            ret = deflate(&amp;strm, flush);    /* no bad return value */
2471.1Schristos            assert(ret != Z_STREAM_ERROR);  /* state not clobbered */
2481.1Schristos</b></pre>
2491.1SchristosNow we compute how much output <tt>deflate()</tt> provided on the last call, which is the
2501.1Schristosdifference between how much space was provided before the call, and how much output space
2511.1Schristosis still available after the call.  Then that data, if any, is written to the output file.
2521.1SchristosWe can then reuse the output buffer for the next call of <tt>deflate()</tt>.  Again if there
2531.1Schristosis a file i/o error, we call <tt>deflateEnd()</tt> before returning to avoid a memory leak.
2541.1Schristos<pre><b>
2551.1Schristos            have = CHUNK - strm.avail_out;
2561.1Schristos            if (fwrite(out, 1, have, dest) != have || ferror(dest)) {
2571.1Schristos                (void)deflateEnd(&amp;strm);
2581.1Schristos                return Z_ERRNO;
2591.1Schristos            }
2601.1Schristos</b></pre>
2611.1SchristosThe inner <tt>do</tt>-loop is repeated until the last <tt>deflate()</tt> call fails to fill the
2621.1Schristosprovided output buffer.  Then we know that <tt>deflate()</tt> has done as much as it can with
2631.1Schristosthe provided input, and that all of that input has been consumed.  We can then fall out of this
2641.1Schristosloop and reuse the input buffer.
2651.1Schristos<p>
2661.1SchristosThe way we tell that <tt>deflate()</tt> has no more output is by seeing that it did not fill
2671.1Schristosthe output buffer, leaving <tt>avail_out</tt> greater than zero.  However suppose that
2681.1Schristos<tt>deflate()</tt> has no more output, but just so happened to exactly fill the output buffer!
2691.1Schristos<tt>avail_out</tt> is zero, and we can't tell that <tt>deflate()</tt> has done all it can.
2701.1SchristosAs far as we know, <tt>deflate()</tt>
2711.1Schristoshas more output for us.  So we call it again.  But now <tt>deflate()</tt> produces no output
2721.1Schristosat all, and <tt>avail_out</tt> remains unchanged as <tt>CHUNK</tt>.  That <tt>deflate()</tt> call
2731.1Schristoswasn't able to do anything, either consume input or produce output, and so it returns
2741.1Schristos<tt>Z_BUF_ERROR</tt>.  (See, I told you I'd cover this later.)  However this is not a problem at
2751.1Schristosall.  Now we finally have the desired indication that <tt>deflate()</tt> is really done,
2761.1Schristosand so we drop out of the inner loop to provide more input to <tt>deflate()</tt>.
2771.1Schristos<p>
2781.1SchristosWith <tt>flush</tt> set to <tt>Z_FINISH</tt>, this final set of <tt>deflate()</tt> calls will
2791.1Schristoscomplete the output stream.  Once that is done, subsequent calls of <tt>deflate()</tt> would return
2801.1Schristos<tt>Z_STREAM_ERROR</tt> if the flush parameter is not <tt>Z_FINISH</tt>, and do no more processing
2811.1Schristosuntil the state is reinitialized.
2821.1Schristos<p>
2831.1SchristosSome applications of <em>zlib</em> have two loops that call <tt>deflate()</tt>
2841.1Schristosinstead of the single inner loop we have here.  The first loop would call
2851.1Schristoswithout flushing and feed all of the data to <tt>deflate()</tt>.  The second loop would call
2861.1Schristos<tt>deflate()</tt> with no more
2871.1Schristosdata and the <tt>Z_FINISH</tt> parameter to complete the process.  As you can see from this
2881.1Schristosexample, that can be avoided by simply keeping track of the current flush state.
2891.1Schristos<pre><b>
2901.1Schristos        } while (strm.avail_out == 0);
2911.1Schristos        assert(strm.avail_in == 0);     /* all input will be used */
2921.1Schristos</b></pre><!-- -->
2931.1SchristosNow we check to see if we have already processed all of the input file.  That information was
2941.1Schristossaved in the <tt>flush</tt> variable, so we see if that was set to <tt>Z_FINISH</tt>.  If so,
2951.1Schristosthen we're done and we fall out of the outer loop.  We're guaranteed to get <tt>Z_STREAM_END</tt>
2961.1Schristosfrom the last <tt>deflate()</tt> call, since we ran it until the last chunk of input was
2971.1Schristosconsumed and all of the output was generated.
2981.1Schristos<pre><b>
2991.1Schristos        /* done when last data in file processed */
3001.1Schristos    } while (flush != Z_FINISH);
3011.1Schristos    assert(ret == Z_STREAM_END);        /* stream will be complete */
3021.1Schristos</b></pre><!-- -->
3031.1SchristosThe process is complete, but we still need to deallocate the state to avoid a memory leak
3041.1Schristos(or rather more like a memory hemorrhage if you didn't do this).  Then
3051.1Schristosfinally we can return with a happy return value.
3061.1Schristos<pre><b>
3071.1Schristos    /* clean up and return */
3081.1Schristos    (void)deflateEnd(&amp;strm);
3091.1Schristos    return Z_OK;
3101.1Schristos}
3111.1Schristos</b></pre><!-- -->
3121.1SchristosNow we do the same thing for decompression in the <tt>inf()</tt> routine. <tt>inf()</tt>
3131.1Schristosdecompresses what is hopefully a valid <em>zlib</em> stream from the input file and writes the
3141.1Schristosuncompressed data to the output file.  Much of the discussion above for <tt>def()</tt>
3151.1Schristosapplies to <tt>inf()</tt> as well, so the discussion here will focus on the differences between
3161.1Schristosthe two.
3171.1Schristos<pre><b>
3181.1Schristos/* Decompress from file source to file dest until stream ends or EOF.
3191.1Schristos   inf() returns Z_OK on success, Z_MEM_ERROR if memory could not be
3201.1Schristos   allocated for processing, Z_DATA_ERROR if the deflate data is
3211.1Schristos   invalid or incomplete, Z_VERSION_ERROR if the version of zlib.h and
3221.1Schristos   the version of the library linked do not match, or Z_ERRNO if there
3231.1Schristos   is an error reading or writing the files. */
3241.1Schristosint inf(FILE *source, FILE *dest)
3251.1Schristos{
3261.1Schristos</b></pre>
3271.1SchristosThe local variables have the same functionality as they do for <tt>def()</tt>.  The
3281.1Schristosonly difference is that there is no <tt>flush</tt> variable, since <tt>inflate()</tt>
3291.1Schristoscan tell from the <em>zlib</em> stream itself when the stream is complete.
3301.1Schristos<pre><b>
3311.1Schristos    int ret;
3321.1Schristos    unsigned have;
3331.1Schristos    z_stream strm;
3341.1.1.2Schristos    unsigned char in[CHUNK];
3351.1.1.2Schristos    unsigned char out[CHUNK];
3361.1Schristos</b></pre><!-- -->
3371.1SchristosThe initialization of the state is the same, except that there is no compression level,
3381.1Schristosof course, and two more elements of the structure are initialized.  <tt>avail_in</tt>
3391.1Schristosand <tt>next_in</tt> must be initialized before calling <tt>inflateInit()</tt>.  This
3401.1Schristosis because the application has the option to provide the start of the zlib stream in
3411.1Schristosorder for <tt>inflateInit()</tt> to have access to information about the compression
3421.1Schristosmethod to aid in memory allocation.  In the current implementation of <em>zlib</em>
3431.1Schristos(up through versions 1.2.x), the method-dependent memory allocations are deferred to the first call of
3441.1Schristos<tt>inflate()</tt> anyway.  However those fields must be initialized since later versions
3451.1Schristosof <em>zlib</em> that provide more compression methods may take advantage of this interface.
3461.1SchristosIn any case, no decompression is performed by <tt>inflateInit()</tt>, so the
3471.1Schristos<tt>avail_out</tt> and <tt>next_out</tt> fields do not need to be initialized before calling.
3481.1Schristos<p>
3491.1SchristosHere <tt>avail_in</tt> is set to zero and <tt>next_in</tt> is set to <tt>Z_NULL</tt> to
3501.1Schristosindicate that no input data is being provided.
3511.1Schristos<pre><b>
3521.1Schristos    /* allocate inflate state */
3531.1Schristos    strm.zalloc = Z_NULL;
3541.1Schristos    strm.zfree = Z_NULL;
3551.1Schristos    strm.opaque = Z_NULL;
3561.1Schristos    strm.avail_in = 0;
3571.1Schristos    strm.next_in = Z_NULL;
3581.1Schristos    ret = inflateInit(&amp;strm);
3591.1Schristos    if (ret != Z_OK)
3601.1Schristos        return ret;
3611.1Schristos</b></pre><!-- -->
3621.1SchristosThe outer <tt>do</tt>-loop decompresses input until <tt>inflate()</tt> indicates
3631.1Schristosthat it has reached the end of the compressed data and has produced all of the uncompressed
3641.1Schristosoutput.  This is in contrast to <tt>def()</tt> which processes all of the input file.
3651.1SchristosIf end-of-file is reached before the compressed data self-terminates, then the compressed
3661.1Schristosdata is incomplete and an error is returned.
3671.1Schristos<pre><b>
3681.1Schristos    /* decompress until deflate stream ends or end of file */
3691.1Schristos    do {
3701.1Schristos</b></pre>
3711.1SchristosWe read input data and set the <tt>strm</tt> structure accordingly.  If we've reached the
3721.1Schristosend of the input file, then we leave the outer loop and report an error, since the
3731.1Schristoscompressed data is incomplete.  Note that we may read more data than is eventually consumed
3741.1Schristosby <tt>inflate()</tt>, if the input file continues past the <em>zlib</em> stream.
3751.1SchristosFor applications where <em>zlib</em> streams are embedded in other data, this routine would
3761.1Schristosneed to be modified to return the unused data, or at least indicate how much of the input
3771.1Schristosdata was not used, so the application would know where to pick up after the <em>zlib</em> stream.
3781.1Schristos<pre><b>
3791.1Schristos        strm.avail_in = fread(in, 1, CHUNK, source);
3801.1Schristos        if (ferror(source)) {
3811.1Schristos            (void)inflateEnd(&amp;strm);
3821.1Schristos            return Z_ERRNO;
3831.1Schristos        }
3841.1Schristos        if (strm.avail_in == 0)
3851.1Schristos            break;
3861.1Schristos        strm.next_in = in;
3871.1Schristos</b></pre><!-- -->
3881.1SchristosThe inner <tt>do</tt>-loop has the same function it did in <tt>def()</tt>, which is to
3891.1Schristoskeep calling <tt>inflate()</tt> until has generated all of the output it can with the
3901.1Schristosprovided input.
3911.1Schristos<pre><b>
3921.1Schristos        /* run inflate() on input until output buffer not full */
3931.1Schristos        do {
3941.1Schristos</b></pre>
3951.1SchristosJust like in <tt>def()</tt>, the same output space is provided for each call of <tt>inflate()</tt>.
3961.1Schristos<pre><b>
3971.1Schristos            strm.avail_out = CHUNK;
3981.1Schristos            strm.next_out = out;
3991.1Schristos</b></pre>
4001.1SchristosNow we run the decompression engine itself.  There is no need to adjust the flush parameter, since
4011.1Schristosthe <em>zlib</em> format is self-terminating. The main difference here is that there are
4021.1Schristosreturn values that we need to pay attention to.  <tt>Z_DATA_ERROR</tt>
4031.1Schristosindicates that <tt>inflate()</tt> detected an error in the <em>zlib</em> compressed data format,
4041.1Schristoswhich means that either the data is not a <em>zlib</em> stream to begin with, or that the data was
4051.1Schristoscorrupted somewhere along the way since it was compressed.  The other error to be processed is
4061.1Schristos<tt>Z_MEM_ERROR</tt>, which can occur since memory allocation is deferred until <tt>inflate()</tt>
4071.1Schristosneeds it, unlike <tt>deflate()</tt>, whose memory is allocated at the start by <tt>deflateInit()</tt>.
4081.1Schristos<p>
4091.1SchristosAdvanced applications may use
4101.1Schristos<tt>deflateSetDictionary()</tt> to prime <tt>deflate()</tt> with a set of likely data to improve the
4111.1Schristosfirst 32K or so of compression.  This is noted in the <em>zlib</em> header, so <tt>inflate()</tt>
4121.1Schristosrequests that that dictionary be provided before it can start to decompress.  Without the dictionary,
4131.1Schristoscorrect decompression is not possible.  For this routine, we have no idea what the dictionary is,
4141.1Schristosso the <tt>Z_NEED_DICT</tt> indication is converted to a <tt>Z_DATA_ERROR</tt>.
4151.1Schristos<p>
4161.1Schristos<tt>inflate()</tt> can also return <tt>Z_STREAM_ERROR</tt>, which should not be possible here,
4171.1Schristosbut could be checked for as noted above for <tt>def()</tt>.  <tt>Z_BUF_ERROR</tt> does not need to be
4181.1Schristoschecked for here, for the same reasons noted for <tt>def()</tt>.  <tt>Z_STREAM_END</tt> will be
4191.1Schristoschecked for later.
4201.1Schristos<pre><b>
4211.1Schristos            ret = inflate(&amp;strm, Z_NO_FLUSH);
4221.1Schristos            assert(ret != Z_STREAM_ERROR);  /* state not clobbered */
4231.1Schristos            switch (ret) {
4241.1Schristos            case Z_NEED_DICT:
4251.1Schristos                ret = Z_DATA_ERROR;     /* and fall through */
4261.1Schristos            case Z_DATA_ERROR:
4271.1Schristos            case Z_MEM_ERROR:
4281.1Schristos                (void)inflateEnd(&amp;strm);
4291.1Schristos                return ret;
4301.1Schristos            }
4311.1Schristos</b></pre>
4321.1SchristosThe output of <tt>inflate()</tt> is handled identically to that of <tt>deflate()</tt>.
4331.1Schristos<pre><b>
4341.1Schristos            have = CHUNK - strm.avail_out;
4351.1Schristos            if (fwrite(out, 1, have, dest) != have || ferror(dest)) {
4361.1Schristos                (void)inflateEnd(&amp;strm);
4371.1Schristos                return Z_ERRNO;
4381.1Schristos            }
4391.1Schristos</b></pre>
4401.1SchristosThe inner <tt>do</tt>-loop ends when <tt>inflate()</tt> has no more output as indicated
4411.1Schristosby not filling the output buffer, just as for <tt>deflate()</tt>.  In this case, we cannot
4421.1Schristosassert that <tt>strm.avail_in</tt> will be zero, since the deflate stream may end before the file
4431.1Schristosdoes.
4441.1Schristos<pre><b>
4451.1Schristos        } while (strm.avail_out == 0);
4461.1Schristos</b></pre><!-- -->
4471.1SchristosThe outer <tt>do</tt>-loop ends when <tt>inflate()</tt> reports that it has reached the
4481.1Schristosend of the input <em>zlib</em> stream, has completed the decompression and integrity
4491.1Schristoscheck, and has provided all of the output.  This is indicated by the <tt>inflate()</tt>
4501.1Schristosreturn value <tt>Z_STREAM_END</tt>.  The inner loop is guaranteed to leave <tt>ret</tt>
4511.1Schristosequal to <tt>Z_STREAM_END</tt> if the last chunk of the input file read contained the end
4521.1Schristosof the <em>zlib</em> stream.  So if the return value is not <tt>Z_STREAM_END</tt>, the
4531.1Schristosloop continues to read more input.
4541.1Schristos<pre><b>
4551.1Schristos        /* done when inflate() says it's done */
4561.1Schristos    } while (ret != Z_STREAM_END);
4571.1Schristos</b></pre><!-- -->
4581.1SchristosAt this point, decompression successfully completed, or we broke out of the loop due to no
4591.1Schristosmore data being available from the input file.  If the last <tt>inflate()</tt> return value
4601.1Schristosis not <tt>Z_STREAM_END</tt>, then the <em>zlib</em> stream was incomplete and a data error
4611.1Schristosis returned.  Otherwise, we return with a happy return value.  Of course, <tt>inflateEnd()</tt>
4621.1Schristosis called first to avoid a memory leak.
4631.1Schristos<pre><b>
4641.1Schristos    /* clean up and return */
4651.1Schristos    (void)inflateEnd(&amp;strm);
4661.1Schristos    return ret == Z_STREAM_END ? Z_OK : Z_DATA_ERROR;
4671.1Schristos}
4681.1Schristos</b></pre><!-- -->
4691.1SchristosThat ends the routines that directly use <em>zlib</em>.  The following routines make this
4701.1Schristosa command-line program by running data through the above routines from <tt>stdin</tt> to
4711.1Schristos<tt>stdout</tt>, and handling any errors reported by <tt>def()</tt> or <tt>inf()</tt>.
4721.1Schristos<p>
4731.1Schristos<tt>zerr()</tt> is used to interpret the possible error codes from <tt>def()</tt>
4741.1Schristosand <tt>inf()</tt>, as detailed in their comments above, and print out an error message.
4751.1SchristosNote that these are only a subset of the possible return values from <tt>deflate()</tt>
4761.1Schristosand <tt>inflate()</tt>.
4771.1Schristos<pre><b>
4781.1Schristos/* report a zlib or i/o error */
4791.1Schristosvoid zerr(int ret)
4801.1Schristos{
4811.1Schristos    fputs("zpipe: ", stderr);
4821.1Schristos    switch (ret) {
4831.1Schristos    case Z_ERRNO:
4841.1Schristos        if (ferror(stdin))
4851.1Schristos            fputs("error reading stdin\n", stderr);
4861.1Schristos        if (ferror(stdout))
4871.1Schristos            fputs("error writing stdout\n", stderr);
4881.1Schristos        break;
4891.1Schristos    case Z_STREAM_ERROR:
4901.1Schristos        fputs("invalid compression level\n", stderr);
4911.1Schristos        break;
4921.1Schristos    case Z_DATA_ERROR:
4931.1Schristos        fputs("invalid or incomplete deflate data\n", stderr);
4941.1Schristos        break;
4951.1Schristos    case Z_MEM_ERROR:
4961.1Schristos        fputs("out of memory\n", stderr);
4971.1Schristos        break;
4981.1Schristos    case Z_VERSION_ERROR:
4991.1Schristos        fputs("zlib version mismatch!\n", stderr);
5001.1Schristos    }
5011.1Schristos}
5021.1Schristos</b></pre><!-- -->
5031.1SchristosHere is the <tt>main()</tt> routine used to test <tt>def()</tt> and <tt>inf()</tt>.  The
5041.1Schristos<tt>zpipe</tt> command is simply a compression pipe from <tt>stdin</tt> to <tt>stdout</tt>, if
5051.1Schristosno arguments are given, or it is a decompression pipe if <tt>zpipe -d</tt> is used.  If any other
5061.1Schristosarguments are provided, no compression or decompression is performed.  Instead a usage
5071.1Schristosmessage is displayed.  Examples are <tt>zpipe < foo.txt > foo.txt.z</tt> to compress, and
5081.1Schristos<tt>zpipe -d < foo.txt.z > foo.txt</tt> to decompress.
5091.1Schristos<pre><b>
5101.1Schristos/* compress or decompress from stdin to stdout */
5111.1Schristosint main(int argc, char **argv)
5121.1Schristos{
5131.1Schristos    int ret;
5141.1Schristos
5151.1.1.2Schristos    /* avoid end-of-line conversions */
5161.1.1.2Schristos    SET_BINARY_MODE(stdin);
5171.1.1.2Schristos    SET_BINARY_MODE(stdout);
5181.1.1.2Schristos
5191.1Schristos    /* do compression if no arguments */
5201.1Schristos    if (argc == 1) {
5211.1Schristos        ret = def(stdin, stdout, Z_DEFAULT_COMPRESSION);
5221.1Schristos        if (ret != Z_OK)
5231.1Schristos            zerr(ret);
5241.1Schristos        return ret;
5251.1Schristos    }
5261.1Schristos
5271.1Schristos    /* do decompression if -d specified */
5281.1Schristos    else if (argc == 2 &amp;&amp; strcmp(argv[1], "-d") == 0) {
5291.1Schristos        ret = inf(stdin, stdout);
5301.1Schristos        if (ret != Z_OK)
5311.1Schristos            zerr(ret);
5321.1Schristos        return ret;
5331.1Schristos    }
5341.1Schristos
5351.1Schristos    /* otherwise, report usage */
5361.1Schristos    else {
5371.1Schristos        fputs("zpipe usage: zpipe [-d] &lt; source &gt; dest\n", stderr);
5381.1Schristos        return 1;
5391.1Schristos    }
5401.1Schristos}
5411.1Schristos</b></pre>
5421.1Schristos<hr>
5431.1.1.2Schristos<i>Copyright (c) 2004, 2005 by Mark Adler<br>Last modified 11 December 2005</i>
5441.1Schristos</body>
5451.1Schristos</html>
546