Mercurial > hg > sv-dependency-builds

annotate src/zlib-1.2.7/examples/zlib_how.html @ 4:e13257ea84a4

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