1275793eaSopenharmony_ciPuff -- A Simple Inflate 2275793eaSopenharmony_ci3 Mar 2003 3275793eaSopenharmony_ciMark Adler 4275793eaSopenharmony_cimadler@alumni.caltech.edu 5275793eaSopenharmony_ci 6275793eaSopenharmony_ciWhat this is -- 7275793eaSopenharmony_ci 8275793eaSopenharmony_cipuff.c provides the routine puff() to decompress the deflate data format. It 9275793eaSopenharmony_cidoes so more slowly than zlib, but the code is about one-fifth the size of the 10275793eaSopenharmony_ciinflate code in zlib, and written to be very easy to read. 11275793eaSopenharmony_ci 12275793eaSopenharmony_ciWhy I wrote this -- 13275793eaSopenharmony_ci 14275793eaSopenharmony_cipuff.c was written to document the deflate format unambiguously, by virtue of 15275793eaSopenharmony_cibeing working C code. It is meant to supplement RFC 1951, which formally 16275793eaSopenharmony_cidescribes the deflate format. I have received many questions on details of the 17275793eaSopenharmony_cideflate format, and I hope that reading this code will answer those questions. 18275793eaSopenharmony_cipuff.c is heavily commented with details of the deflate format, especially 19275793eaSopenharmony_cithose little nooks and cranies of the format that might not be obvious from a 20275793eaSopenharmony_cispecification. 21275793eaSopenharmony_ci 22275793eaSopenharmony_cipuff.c may also be useful in applications where code size or memory usage is a 23275793eaSopenharmony_civery limited resource, and speed is not as important. 24275793eaSopenharmony_ci 25275793eaSopenharmony_ciHow to use it -- 26275793eaSopenharmony_ci 27275793eaSopenharmony_ciWell, most likely you should just be reading puff.c and using zlib for actual 28275793eaSopenharmony_ciapplications, but if you must ... 29275793eaSopenharmony_ci 30275793eaSopenharmony_ciInclude puff.h in your code, which provides this prototype: 31275793eaSopenharmony_ci 32275793eaSopenharmony_ciint puff(unsigned char *dest, /* pointer to destination pointer */ 33275793eaSopenharmony_ci unsigned long *destlen, /* amount of output space */ 34275793eaSopenharmony_ci unsigned char *source, /* pointer to source data pointer */ 35275793eaSopenharmony_ci unsigned long *sourcelen); /* amount of input available */ 36275793eaSopenharmony_ci 37275793eaSopenharmony_ciThen you can call puff() to decompress a deflate stream that is in memory in 38275793eaSopenharmony_ciits entirety at source, to a sufficiently sized block of memory for the 39275793eaSopenharmony_cidecompressed data at dest. puff() is the only external symbol in puff.c The 40275793eaSopenharmony_cionly C library functions that puff.c needs are setjmp() and longjmp(), which 41275793eaSopenharmony_ciare used to simplify error checking in the code to improve readability. puff.c 42275793eaSopenharmony_cidoes no memory allocation, and uses less than 2K bytes off of the stack. 43275793eaSopenharmony_ci 44275793eaSopenharmony_ciIf destlen is not enough space for the uncompressed data, then inflate will 45275793eaSopenharmony_cireturn an error without writing more than destlen bytes. Note that this means 46275793eaSopenharmony_cithat in order to decompress the deflate data successfully, you need to know 47275793eaSopenharmony_cithe size of the uncompressed data ahead of time. 48275793eaSopenharmony_ci 49275793eaSopenharmony_ciIf needed, puff() can determine the size of the uncompressed data with no 50275793eaSopenharmony_cioutput space. This is done by passing dest equal to (unsigned char *)0. Then 51275793eaSopenharmony_cithe initial value of *destlen is ignored and *destlen is set to the length of 52275793eaSopenharmony_cithe uncompressed data. So if the size of the uncompressed data is not known, 53275793eaSopenharmony_cithen two passes of puff() can be used--first to determine the size, and second 54275793eaSopenharmony_cito do the actual inflation after allocating the appropriate memory. Not 55275793eaSopenharmony_cipretty, but it works. (This is one of the reasons you should be using zlib.) 56275793eaSopenharmony_ci 57275793eaSopenharmony_ciThe deflate format is self-terminating. If the deflate stream does not end 58275793eaSopenharmony_ciin *sourcelen bytes, puff() will return an error without reading at or past 59275793eaSopenharmony_ciendsource. 60275793eaSopenharmony_ci 61275793eaSopenharmony_ciOn return, *sourcelen is updated to the amount of input data consumed, and 62275793eaSopenharmony_ci*destlen is updated to the size of the uncompressed data. See the comments 63275793eaSopenharmony_ciin puff.c for the possible return codes for puff(). 64