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