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