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