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