kusano fc6ab3
Puff -- A Simple Inflate
kusano fc6ab3
3 Mar 2003
kusano fc6ab3
Mark Adler
kusano fc6ab3
madler@alumni.caltech.edu
kusano fc6ab3
kusano fc6ab3
What this is --
kusano fc6ab3
kusano fc6ab3
puff.c provides the routine puff() to decompress the deflate data format.  It
kusano fc6ab3
does so more slowly than zlib, but the code is about one-fifth the size of the
kusano fc6ab3
inflate code in zlib, and written to be very easy to read.
kusano fc6ab3
kusano fc6ab3
Why I wrote this --
kusano fc6ab3
kusano fc6ab3
puff.c was written to document the deflate format unambiguously, by virtue of
kusano fc6ab3
being working C code.  It is meant to supplement RFC 1951, which formally
kusano fc6ab3
describes the deflate format.  I have received many questions on details of the
kusano fc6ab3
deflate format, and I hope that reading this code will answer those questions.
kusano fc6ab3
puff.c is heavily commented with details of the deflate format, especially
kusano fc6ab3
those little nooks and cranies of the format that might not be obvious from a
kusano fc6ab3
specification.
kusano fc6ab3
kusano fc6ab3
puff.c may also be useful in applications where code size or memory usage is a
kusano fc6ab3
very limited resource, and speed is not as important.
kusano fc6ab3
kusano fc6ab3
How to use it --
kusano fc6ab3
kusano fc6ab3
Well, most likely you should just be reading puff.c and using zlib for actual
kusano fc6ab3
applications, but if you must ...
kusano fc6ab3
kusano fc6ab3
Include puff.h in your code, which provides this prototype:
kusano fc6ab3
kusano fc6ab3
int puff(unsigned char *dest,           /* pointer to destination pointer */
kusano fc6ab3
         unsigned long *destlen,        /* amount of output space */
kusano fc6ab3
         unsigned char *source,         /* pointer to source data pointer */
kusano fc6ab3
         unsigned long *sourcelen);     /* amount of input available */
kusano fc6ab3
kusano fc6ab3
Then you can call puff() to decompress a deflate stream that is in memory in
kusano fc6ab3
its entirety at source, to a sufficiently sized block of memory for the
kusano fc6ab3
decompressed data at dest.  puff() is the only external symbol in puff.c  The
kusano fc6ab3
only C library functions that puff.c needs are setjmp() and longjmp(), which
kusano fc6ab3
are used to simplify error checking in the code to improve readabilty.  puff.c
kusano fc6ab3
does no memory allocation, and uses less than 2K bytes off of the stack.
kusano fc6ab3
kusano fc6ab3
If destlen is not enough space for the uncompressed data, then inflate will
kusano fc6ab3
return an error without writing more than destlen bytes.  Note that this means
kusano fc6ab3
that in order to decompress the deflate data successfully, you need to know
kusano fc6ab3
the size of the uncompressed data ahead of time.
kusano fc6ab3
kusano fc6ab3
If needed, puff() can determine the size of the uncompressed data with no
kusano fc6ab3
output space.  This is done by passing dest equal to (unsigned char *)0.  Then
kusano fc6ab3
the initial value of *destlen is ignored and *destlen is set to the length of
kusano fc6ab3
the uncompressed data.  So if the size of the uncompressed data is not known,
kusano fc6ab3
then two passes of puff() can be used--first to determine the size, and second
kusano fc6ab3
to do the actual inflation after allocating the appropriate memory.  Not
kusano fc6ab3
pretty, but it works.  (This is one of the reasons you should be using zlib.)
kusano fc6ab3
kusano fc6ab3
The deflate format is self-terminating.  If the deflate stream does not end
kusano fc6ab3
in *sourcelen bytes, puff() will return an error without reading at or past
kusano fc6ab3
endsource.
kusano fc6ab3
kusano fc6ab3
On return, *sourcelen is updated to the amount of input data consumed, and
kusano fc6ab3
*destlen is updated to the size of the uncompressed data.  See the comments
kusano fc6ab3
in puff.c for the possible return codes for puff().