|
cannam@89
|
1 Puff -- A Simple Inflate
|
|
cannam@89
|
2 3 Mar 2003
|
|
cannam@89
|
3 Mark Adler
|
|
cannam@89
|
4 madler@alumni.caltech.edu
|
|
cannam@89
|
5
|
|
cannam@89
|
6 What this is --
|
|
cannam@89
|
7
|
|
cannam@89
|
8 puff.c provides the routine puff() to decompress the deflate data format. It
|
|
cannam@89
|
9 does so more slowly than zlib, but the code is about one-fifth the size of the
|
|
cannam@89
|
10 inflate code in zlib, and written to be very easy to read.
|
|
cannam@89
|
11
|
|
cannam@89
|
12 Why I wrote this --
|
|
cannam@89
|
13
|
|
cannam@89
|
14 puff.c was written to document the deflate format unambiguously, by virtue of
|
|
cannam@89
|
15 being working C code. It is meant to supplement RFC 1951, which formally
|
|
cannam@89
|
16 describes the deflate format. I have received many questions on details of the
|
|
cannam@89
|
17 deflate format, and I hope that reading this code will answer those questions.
|
|
cannam@89
|
18 puff.c is heavily commented with details of the deflate format, especially
|
|
cannam@89
|
19 those little nooks and cranies of the format that might not be obvious from a
|
|
cannam@89
|
20 specification.
|
|
cannam@89
|
21
|
|
cannam@89
|
22 puff.c may also be useful in applications where code size or memory usage is a
|
|
cannam@89
|
23 very limited resource, and speed is not as important.
|
|
cannam@89
|
24
|
|
cannam@89
|
25 How to use it --
|
|
cannam@89
|
26
|
|
cannam@89
|
27 Well, most likely you should just be reading puff.c and using zlib for actual
|
|
cannam@89
|
28 applications, but if you must ...
|
|
cannam@89
|
29
|
|
cannam@89
|
30 Include puff.h in your code, which provides this prototype:
|
|
cannam@89
|
31
|
|
cannam@89
|
32 int puff(unsigned char *dest, /* pointer to destination pointer */
|
|
cannam@89
|
33 unsigned long *destlen, /* amount of output space */
|
|
cannam@89
|
34 unsigned char *source, /* pointer to source data pointer */
|
|
cannam@89
|
35 unsigned long *sourcelen); /* amount of input available */
|
|
cannam@89
|
36
|
|
cannam@89
|
37 Then you can call puff() to decompress a deflate stream that is in memory in
|
|
cannam@89
|
38 its entirety at source, to a sufficiently sized block of memory for the
|
|
cannam@89
|
39 decompressed data at dest. puff() is the only external symbol in puff.c The
|
|
cannam@89
|
40 only C library functions that puff.c needs are setjmp() and longjmp(), which
|
|
cannam@89
|
41 are used to simplify error checking in the code to improve readabilty. puff.c
|
|
cannam@89
|
42 does no memory allocation, and uses less than 2K bytes off of the stack.
|
|
cannam@89
|
43
|
|
cannam@89
|
44 If destlen is not enough space for the uncompressed data, then inflate will
|
|
cannam@89
|
45 return an error without writing more than destlen bytes. Note that this means
|
|
cannam@89
|
46 that in order to decompress the deflate data successfully, you need to know
|
|
cannam@89
|
47 the size of the uncompressed data ahead of time.
|
|
cannam@89
|
48
|
|
cannam@89
|
49 If needed, puff() can determine the size of the uncompressed data with no
|
|
cannam@89
|
50 output space. This is done by passing dest equal to (unsigned char *)0. Then
|
|
cannam@89
|
51 the initial value of *destlen is ignored and *destlen is set to the length of
|
|
cannam@89
|
52 the uncompressed data. So if the size of the uncompressed data is not known,
|
|
cannam@89
|
53 then two passes of puff() can be used--first to determine the size, and second
|
|
cannam@89
|
54 to do the actual inflation after allocating the appropriate memory. Not
|
|
cannam@89
|
55 pretty, but it works. (This is one of the reasons you should be using zlib.)
|
|
cannam@89
|
56
|
|
cannam@89
|
57 The deflate format is self-terminating. If the deflate stream does not end
|
|
cannam@89
|
58 in *sourcelen bytes, puff() will return an error without reading at or past
|
|
cannam@89
|
59 endsource.
|
|
cannam@89
|
60
|
|
cannam@89
|
61 On return, *sourcelen is updated to the amount of input data consumed, and
|
|
cannam@89
|
62 *destlen is updated to the size of the uncompressed data. See the comments
|
|
cannam@89
|
63 in puff.c for the possible return codes for puff().
|
