root/lib/zlib/contrib/puff/puff.c

/* [<][>][^][v][top][bottom][index][help] */

DEFINITIONS

This source file includes following definitions.
  1. bits
  2. stored
  3. decode
  4. decode
  5. construct
  6. codes
  7. fixed
  8. dynamic
  9. puff
  10. yank
  11. main

   1 /*
   2  * puff.c
   3  * Copyright (C) 2002-2004 Mark Adler
   4  * For conditions of distribution and use, see copyright notice in puff.h
   5  * version 1.8, 9 Jan 2004
   6  *
   7  * puff.c is a simple inflate written to be an unambiguous way to specify the
   8  * deflate format.  It is not written for speed but rather simplicity.  As a
   9  * side benefit, this code might actually be useful when small code is more
  10  * important than speed, such as bootstrap applications.  For typical deflate
  11  * data, zlib's inflate() is about four times as fast as puff().  zlib's
  12  * inflate compiles to around 20K on my machine, whereas puff.c compiles to
  13  * around 4K on my machine (a PowerPC using GNU cc).  If the faster decode()
  14  * function here is used, then puff() is only twice as slow as zlib's
  15  * inflate().
  16  *
  17  * All dynamically allocated memory comes from the stack.  The stack required
  18  * is less than 2K bytes.  This code is compatible with 16-bit int's and
  19  * assumes that long's are at least 32 bits.  puff.c uses the short data type,
  20  * assumed to be 16 bits, for arrays in order to to conserve memory.  The code
  21  * works whether integers are stored big endian or little endian.
  22  *
  23  * In the comments below are "Format notes" that describe the inflate process
  24  * and document some of the less obvious aspects of the format.  This source
  25  * code is meant to supplement RFC 1951, which formally describes the deflate
  26  * format:
  27  *
  28  *    http://www.zlib.org/rfc-deflate.html
  29  */
  30 
  31 /*
  32  * Change history:
  33  *
  34  * 1.0  10 Feb 2002     - First version
  35  * 1.1  17 Feb 2002     - Clarifications of some comments and notes
  36  *                      - Update puff() dest and source pointers on negative
  37  *                        errors to facilitate debugging deflators
  38  *                      - Remove longest from struct huffman -- not needed
  39  *                      - Simplify offs[] index in construct()
  40  *                      - Add input size and checking, using longjmp() to
  41  *                        maintain easy readability
  42  *                      - Use short data type for large arrays
  43  *                      - Use pointers instead of long to specify source and
  44  *                        destination sizes to avoid arbitrary 4 GB limits
  45  * 1.2  17 Mar 2002     - Add faster version of decode(), doubles speed (!),
  46  *                        but leave simple version for readabilty
  47  *                      - Make sure invalid distances detected if pointers
  48  *                        are 16 bits
  49  *                      - Fix fixed codes table error
  50  *                      - Provide a scanning mode for determining size of
  51  *                        uncompressed data
  52  * 1.3  20 Mar 2002     - Go back to lengths for puff() parameters [Jean-loup]
  53  *                      - Add a puff.h file for the interface
  54  *                      - Add braces in puff() for else do [Jean-loup]
  55  *                      - Use indexes instead of pointers for readability
  56  * 1.4  31 Mar 2002     - Simplify construct() code set check
  57  *                      - Fix some comments
  58  *                      - Add FIXLCODES #define
  59  * 1.5   6 Apr 2002     - Minor comment fixes
  60  * 1.6   7 Aug 2002     - Minor format changes
  61  * 1.7   3 Mar 2003     - Added test code for distribution
  62  *                      - Added zlib-like license
  63  * 1.8   9 Jan 2004     - Added some comments on no distance codes case
  64  */
  65 
  66 #include <setjmp.h>             /* for setjmp(), longjmp(), and jmp_buf */
  67 #include "puff.h"               /* prototype for puff() */
  68 
  69 #define local static            /* for local function definitions */
  70 #define NIL ((unsigned char *)0)        /* for no output option */
  71 
  72 /*
  73  * Maximums for allocations and loops.  It is not useful to change these --
  74  * they are fixed by the deflate format.
  75  */
  76 #define MAXBITS 15              /* maximum bits in a code */
  77 #define MAXLCODES 286           /* maximum number of literal/length codes */
  78 #define MAXDCODES 30            /* maximum number of distance codes */
  79 #define MAXCODES (MAXLCODES+MAXDCODES)  /* maximum codes lengths to read */
  80 #define FIXLCODES 288           /* number of fixed literal/length codes */
  81 
  82 /* input and output state */
  83 struct state {
  84     /* output state */
  85     unsigned char *out;         /* output buffer */
  86     unsigned long outlen;       /* available space at out */
  87     unsigned long outcnt;       /* bytes written to out so far */
  88 
  89     /* input state */
  90     unsigned char *in;          /* input buffer */
  91     unsigned long inlen;        /* available input at in */
  92     unsigned long incnt;        /* bytes read so far */
  93     int bitbuf;                 /* bit buffer */
  94     int bitcnt;                 /* number of bits in bit buffer */
  95 
  96     /* input limit error return state for bits() and decode() */
  97     jmp_buf env;
  98 };
  99 
 100 /*
 101  * Return need bits from the input stream.  This always leaves less than
 102  * eight bits in the buffer.  bits() works properly for need == 0.
 103  *
 104  * Format notes:
 105  *
 106  * - Bits are stored in bytes from the least significant bit to the most
 107  *   significant bit.  Therefore bits are dropped from the bottom of the bit
 108  *   buffer, using shift right, and new bytes are appended to the top of the
 109  *   bit buffer, using shift left.
 110  */
 111 local int bits(struct state *s, int need)
     /* [<][>][^][v][top][bottom][index][help] */
 112 {
 113     long val;           /* bit accumulator (can use up to 20 bits) */
 114 
 115     /* load at least need bits into val */
 116     val = s->bitbuf;
 117     while (s->bitcnt < need) {
 118         if (s->incnt == s->inlen) longjmp(s->env, 1);   /* out of input */
 119         val |= (long)(s->in[s->incnt++]) << s->bitcnt;  /* load eight bits */
 120         s->bitcnt += 8;
 121     }
 122 
 123     /* drop need bits and update buffer, always zero to seven bits left */
 124     s->bitbuf = (int)(val >> need);
 125     s->bitcnt -= need;
 126 
 127     /* return need bits, zeroing the bits above that */
 128     return (int)(val & ((1L << need) - 1));
 129 }
 130 
 131 /*
 132  * Process a stored block.
 133  *
 134  * Format notes:
 135  *
 136  * - After the two-bit stored block type (00), the stored block length and
 137  *   stored bytes are byte-aligned for fast copying.  Therefore any leftover
 138  *   bits in the byte that has the last bit of the type, as many as seven, are
 139  *   discarded.  The value of the discarded bits are not defined and should not
 140  *   be checked against any expectation.
 141  *
 142  * - The second inverted copy of the stored block length does not have to be
 143  *   checked, but it's probably a good idea to do so anyway.
 144  *
 145  * - A stored block can have zero length.  This is sometimes used to byte-align
 146  *   subsets of the compressed data for random access or partial recovery.
 147  */
 148 local int stored(struct state *s)
     /* [<][>][^][v][top][bottom][index][help] */
 149 {
 150     unsigned len;       /* length of stored block */
 151 
 152     /* discard leftover bits from current byte (assumes s->bitcnt < 8) */
 153     s->bitbuf = 0;
 154     s->bitcnt = 0;
 155 
 156     /* get length and check against its one's complement */
 157     if (s->incnt + 4 > s->inlen) return 2;      /* not enough input */
 158     len = s->in[s->incnt++];
 159     len |= s->in[s->incnt++] << 8;
 160     if (s->in[s->incnt++] != (~len & 0xff) ||
 161         s->in[s->incnt++] != ((~len >> 8) & 0xff))
 162         return -2;                              /* didn't match complement! */
 163 
 164     /* copy len bytes from in to out */
 165     if (s->incnt + len > s->inlen) return 2;    /* not enough input */
 166     if (s->out != NIL) {
 167         if (s->outcnt + len > s->outlen)
 168             return 1;                           /* not enough output space */
 169         while (len--)
 170             s->out[s->outcnt++] = s->in[s->incnt++];
 171     }
 172     else {                                      /* just scanning */
 173         s->outcnt += len;
 174         s->incnt += len;
 175     }
 176 
 177     /* done with a valid stored block */
 178     return 0;
 179 }
 180 
 181 /*
 182  * Huffman code decoding tables.  count[1..MAXBITS] is the number of symbols of
 183  * each length, which for a canonical code are stepped through in order.
 184  * symbol[] are the symbol values in canonical order, where the number of
 185  * entries is the sum of the counts in count[].  The decoding process can be
 186  * seen in the function decode() below.
 187  */
 188 struct huffman {
 189     short *count;       /* number of symbols of each length */
 190     short *symbol;      /* canonically ordered symbols */
 191 };
 192 
 193 /*
 194  * Decode a code from the stream s using huffman table h.  Return the symbol or
 195  * a negative value if there is an error.  If all of the lengths are zero, i.e.
 196  * an empty code, or if the code is incomplete and an invalid code is received,
 197  * then -9 is returned after reading MAXBITS bits.
 198  *
 199  * Format notes:
 200  *
 201  * - The codes as stored in the compressed data are bit-reversed relative to
 202  *   a simple integer ordering of codes of the same lengths.  Hence below the
 203  *   bits are pulled from the compressed data one at a time and used to
 204  *   build the code value reversed from what is in the stream in order to
 205  *   permit simple integer comparisons for decoding.  A table-based decoding
 206  *   scheme (as used in zlib) does not need to do this reversal.
 207  *
 208  * - The first code for the shortest length is all zeros.  Subsequent codes of
 209  *   the same length are simply integer increments of the previous code.  When
 210  *   moving up a length, a zero bit is appended to the code.  For a complete
 211  *   code, the last code of the longest length will be all ones.
 212  *
 213  * - Incomplete codes are handled by this decoder, since they are permitted
 214  *   in the deflate format.  See the format notes for fixed() and dynamic().
 215  */
 216 #ifdef SLOW
 217 local int decode(struct state *s, struct huffman *h)
     /* [<][>][^][v][top][bottom][index][help] */
 218 {
 219     int len;            /* current number of bits in code */
 220     int code;           /* len bits being decoded */
 221     int first;          /* first code of length len */
 222     int count;          /* number of codes of length len */
 223     int index;          /* index of first code of length len in symbol table */
 224 
 225     code = first = index = 0;
 226     for (len = 1; len <= MAXBITS; len++) {
 227         code |= bits(s, 1);             /* get next bit */
 228         count = h->count[len];
 229         if (code < first + count)       /* if length len, return symbol */
 230             return h->symbol[index + (code - first)];
 231         index += count;                 /* else update for next length */
 232         first += count;
 233         first <<= 1;
 234         code <<= 1;
 235     }
 236     return -9;                          /* ran out of codes */
 237 }
 238 
 239 /*
 240  * A faster version of decode() for real applications of this code.   It's not
 241  * as readable, but it makes puff() twice as fast.  And it only makes the code
 242  * a few percent larger.
 243  */
 244 #else /* !SLOW */
 245 local int decode(struct state *s, struct huffman *h)
     /* [<][>][^][v][top][bottom][index][help] */
 246 {
 247     int len;            /* current number of bits in code */
 248     int code;           /* len bits being decoded */
 249     int first;          /* first code of length len */
 250     int count;          /* number of codes of length len */
 251     int index;          /* index of first code of length len in symbol table */
 252     int bitbuf;         /* bits from stream */
 253     int left;           /* bits left in next or left to process */
 254     short *next;        /* next number of codes */
 255 
 256     bitbuf = s->bitbuf;
 257     left = s->bitcnt;
 258     code = first = index = 0;
 259     len = 1;
 260     next = h->count + 1;
 261     while (1) {
 262         while (left--) {
 263             code |= bitbuf & 1;
 264             bitbuf >>= 1;
 265             count = *next++;
 266             if (code < first + count) { /* if length len, return symbol */
 267                 s->bitbuf = bitbuf;
 268                 s->bitcnt = (s->bitcnt - len) & 7;
 269                 return h->symbol[index + (code - first)];
 270             }
 271             index += count;             /* else update for next length */
 272             first += count;
 273             first <<= 1;
 274             code <<= 1;
 275             len++;
 276         }
 277         left = (MAXBITS+1) - len;
 278         if (left == 0) break;
 279         if (s->incnt == s->inlen) longjmp(s->env, 1);   /* out of input */
 280         bitbuf = s->in[s->incnt++];
 281         if (left > 8) left = 8;
 282     }
 283     return -9;                          /* ran out of codes */
 284 }
 285 #endif /* SLOW */
 286 
 287 /*
 288  * Given the list of code lengths length[0..n-1] representing a canonical
 289  * Huffman code for n symbols, construct the tables required to decode those
 290  * codes.  Those tables are the number of codes of each length, and the symbols
 291  * sorted by length, retaining their original order within each length.  The
 292  * return value is zero for a complete code set, negative for an over-
 293  * subscribed code set, and positive for an incomplete code set.  The tables
 294  * can be used if the return value is zero or positive, but they cannot be used
 295  * if the return value is negative.  If the return value is zero, it is not
 296  * possible for decode() using that table to return an error--any stream of
 297  * enough bits will resolve to a symbol.  If the return value is positive, then
 298  * it is possible for decode() using that table to return an error for received
 299  * codes past the end of the incomplete lengths.
 300  *
 301  * Not used by decode(), but used for error checking, h->count[0] is the number
 302  * of the n symbols not in the code.  So n - h->count[0] is the number of
 303  * codes.  This is useful for checking for incomplete codes that have more than
 304  * one symbol, which is an error in a dynamic block.
 305  *
 306  * Assumption: for all i in 0..n-1, 0 <= length[i] <= MAXBITS
 307  * This is assured by the construction of the length arrays in dynamic() and
 308  * fixed() and is not verified by construct().
 309  *
 310  * Format notes:
 311  *
 312  * - Permitted and expected examples of incomplete codes are one of the fixed
 313  *   codes and any code with a single symbol which in deflate is coded as one
 314  *   bit instead of zero bits.  See the format notes for fixed() and dynamic().
 315  *
 316  * - Within a given code length, the symbols are kept in ascending order for
 317  *   the code bits definition.
 318  */
 319 local int construct(struct huffman *h, short *length, int n)
     /* [<][>][^][v][top][bottom][index][help] */
 320 {
 321     int symbol;         /* current symbol when stepping through length[] */
 322     int len;            /* current length when stepping through h->count[] */
 323     int left;           /* number of possible codes left of current length */
 324     short offs[MAXBITS+1];      /* offsets in symbol table for each length */
 325 
 326     /* count number of codes of each length */
 327     for (len = 0; len <= MAXBITS; len++)
 328         h->count[len] = 0;
 329     for (symbol = 0; symbol < n; symbol++)
 330         (h->count[length[symbol]])++;   /* assumes lengths are within bounds */
 331     if (h->count[0] == n)               /* no codes! */
 332         return 0;                       /* complete, but decode() will fail */
 333 
 334     /* check for an over-subscribed or incomplete set of lengths */
 335     left = 1;                           /* one possible code of zero length */
 336     for (len = 1; len <= MAXBITS; len++) {
 337         left <<= 1;                     /* one more bit, double codes left */
 338         left -= h->count[len];          /* deduct count from possible codes */
 339         if (left < 0) return left;      /* over-subscribed--return negative */
 340     }                                   /* left > 0 means incomplete */
 341 
 342     /* generate offsets into symbol table for each length for sorting */
 343     offs[1] = 0;
 344     for (len = 1; len < MAXBITS; len++)
 345         offs[len + 1] = offs[len] + h->count[len];
 346 
 347     /*
 348      * put symbols in table sorted by length, by symbol order within each
 349      * length
 350      */
 351     for (symbol = 0; symbol < n; symbol++)
 352         if (length[symbol] != 0)
 353             h->symbol[offs[length[symbol]]++] = symbol;
 354 
 355     /* return zero for complete set, positive for incomplete set */
 356     return left;
 357 }
 358 
 359 /*
 360  * Decode literal/length and distance codes until an end-of-block code.
 361  *
 362  * Format notes:
 363  *
 364  * - Compressed data that is after the block type if fixed or after the code
 365  *   description if dynamic is a combination of literals and length/distance
 366  *   pairs terminated by and end-of-block code.  Literals are simply Huffman
 367  *   coded bytes.  A length/distance pair is a coded length followed by a
 368  *   coded distance to represent a string that occurs earlier in the
 369  *   uncompressed data that occurs again at the current location.
 370  *
 371  * - Literals, lengths, and the end-of-block code are combined into a single
 372  *   code of up to 286 symbols.  They are 256 literals (0..255), 29 length
 373  *   symbols (257..285), and the end-of-block symbol (256).
 374  *
 375  * - There are 256 possible lengths (3..258), and so 29 symbols are not enough
 376  *   to represent all of those.  Lengths 3..10 and 258 are in fact represented
 377  *   by just a length symbol.  Lengths 11..257 are represented as a symbol and
 378  *   some number of extra bits that are added as an integer to the base length
 379  *   of the length symbol.  The number of extra bits is determined by the base
 380  *   length symbol.  These are in the static arrays below, lens[] for the base
 381  *   lengths and lext[] for the corresponding number of extra bits.
 382  *
 383  * - The reason that 258 gets its own symbol is that the longest length is used
 384  *   often in highly redundant files.  Note that 258 can also be coded as the
 385  *   base value 227 plus the maximum extra value of 31.  While a good deflate
 386  *   should never do this, it is not an error, and should be decoded properly.
 387  *
 388  * - If a length is decoded, including its extra bits if any, then it is
 389  *   followed a distance code.  There are up to 30 distance symbols.  Again
 390  *   there are many more possible distances (1..32768), so extra bits are added
 391  *   to a base value represented by the symbol.  The distances 1..4 get their
 392  *   own symbol, but the rest require extra bits.  The base distances and
 393  *   corresponding number of extra bits are below in the static arrays dist[]
 394  *   and dext[].
 395  *
 396  * - Literal bytes are simply written to the output.  A length/distance pair is
 397  *   an instruction to copy previously uncompressed bytes to the output.  The
 398  *   copy is from distance bytes back in the output stream, copying for length
 399  *   bytes.
 400  *
 401  * - Distances pointing before the beginning of the output data are not
 402  *   permitted.
 403  *
 404  * - Overlapped copies, where the length is greater than the distance, are
 405  *   allowed and common.  For example, a distance of one and a length of 258
 406  *   simply copies the last byte 258 times.  A distance of four and a length of
 407  *   twelve copies the last four bytes three times.  A simple forward copy
 408  *   ignoring whether the length is greater than the distance or not implements
 409  *   this correctly.  You should not use memcpy() since its behavior is not
 410  *   defined for overlapped arrays.  You should not use memmove() or bcopy()
 411  *   since though their behavior -is- defined for overlapping arrays, it is
 412  *   defined to do the wrong thing in this case.
 413  */
 414 local int codes(struct state *s,
     /* [<][>][^][v][top][bottom][index][help] */
 415                 struct huffman *lencode,
 416                 struct huffman *distcode)
 417 {
 418     int symbol;         /* decoded symbol */
 419     int len;            /* length for copy */
 420     unsigned dist;      /* distance for copy */
 421     static const short lens[29] = { /* Size base for length codes 257..285 */
 422         3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31,
 423         35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258};
 424     static const short lext[29] = { /* Extra bits for length codes 257..285 */
 425         0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2,
 426         3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0};
 427     static const short dists[30] = { /* Offset base for distance codes 0..29 */
 428         1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193,
 429         257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145,
 430         8193, 12289, 16385, 24577};
 431     static const short dext[30] = { /* Extra bits for distance codes 0..29 */
 432         0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6,
 433         7, 7, 8, 8, 9, 9, 10, 10, 11, 11,
 434         12, 12, 13, 13};
 435 
 436     /* decode literals and length/distance pairs */
 437     do {
 438         symbol = decode(s, lencode);
 439         if (symbol < 0) return symbol;  /* invalid symbol */
 440         if (symbol < 256) {             /* literal: symbol is the byte */
 441             /* write out the literal */
 442             if (s->out != NIL) {
 443                 if (s->outcnt == s->outlen) return 1;
 444                 s->out[s->outcnt] = symbol;
 445             }
 446             s->outcnt++;
 447         }
 448         else if (symbol > 256) {        /* length */
 449             /* get and compute length */
 450             symbol -= 257;
 451             if (symbol >= 29) return -9;        /* invalid fixed code */
 452             len = lens[symbol] + bits(s, lext[symbol]);
 453 
 454             /* get and check distance */
 455             symbol = decode(s, distcode);
 456             if (symbol < 0) return symbol;      /* invalid symbol */
 457             dist = dists[symbol] + bits(s, dext[symbol]);
 458             if (dist > s->outcnt)
 459                 return -10;     /* distance too far back */
 460 
 461             /* copy length bytes from distance bytes back */
 462             if (s->out != NIL) {
 463                 if (s->outcnt + len > s->outlen) return 1;
 464                 while (len--) {
 465                     s->out[s->outcnt] = s->out[s->outcnt - dist];
 466                     s->outcnt++;
 467                 }
 468             }
 469             else
 470                 s->outcnt += len;
 471         }
 472     } while (symbol != 256);            /* end of block symbol */
 473 
 474     /* done with a valid fixed or dynamic block */
 475     return 0;
 476 }
 477 
 478 /*
 479  * Process a fixed codes block.
 480  *
 481  * Format notes:
 482  *
 483  * - This block type can be useful for compressing small amounts of data for
 484  *   which the size of the code descriptions in a dynamic block exceeds the
 485  *   benefit of custom codes for that block.  For fixed codes, no bits are
 486  *   spent on code descriptions.  Instead the code lengths for literal/length
 487  *   codes and distance codes are fixed.  The specific lengths for each symbol
 488  *   can be seen in the "for" loops below.
 489  *
 490  * - The literal/length code is complete, but has two symbols that are invalid
 491  *   and should result in an error if received.  This cannot be implemented
 492  *   simply as an incomplete code since those two symbols are in the "middle"
 493  *   of the code.  They are eight bits long and the longest literal/length\
 494  *   code is nine bits.  Therefore the code must be constructed with those
 495  *   symbols, and the invalid symbols must be detected after decoding.
 496  *
 497  * - The fixed distance codes also have two invalid symbols that should result
 498  *   in an error if received.  Since all of the distance codes are the same
 499  *   length, this can be implemented as an incomplete code.  Then the invalid
 500  *   codes are detected while decoding.
 501  */
 502 local int fixed(struct state *s)
     /* [<][>][^][v][top][bottom][index][help] */
 503 {
 504     static int virgin = 1;
 505     static short lencnt[MAXBITS+1], lensym[FIXLCODES];
 506     static short distcnt[MAXBITS+1], distsym[MAXDCODES];
 507     static struct huffman lencode = {lencnt, lensym};
 508     static struct huffman distcode = {distcnt, distsym};
 509 
 510     /* build fixed huffman tables if first call (may not be thread safe) */
 511     if (virgin) {
 512         int symbol;
 513         short lengths[FIXLCODES];
 514 
 515         /* literal/length table */
 516         for (symbol = 0; symbol < 144; symbol++)
 517             lengths[symbol] = 8;
 518         for (; symbol < 256; symbol++)
 519             lengths[symbol] = 9;
 520         for (; symbol < 280; symbol++)
 521             lengths[symbol] = 7;
 522         for (; symbol < FIXLCODES; symbol++)
 523             lengths[symbol] = 8;
 524         construct(&lencode, lengths, FIXLCODES);
 525 
 526         /* distance table */
 527         for (symbol = 0; symbol < MAXDCODES; symbol++)
 528             lengths[symbol] = 5;
 529         construct(&distcode, lengths, MAXDCODES);
 530 
 531         /* do this just once */
 532         virgin = 0;
 533     }
 534 
 535     /* decode data until end-of-block code */
 536     return codes(s, &lencode, &distcode);
 537 }
 538 
 539 /*
 540  * Process a dynamic codes block.
 541  *
 542  * Format notes:
 543  *
 544  * - A dynamic block starts with a description of the literal/length and
 545  *   distance codes for that block.  New dynamic blocks allow the compressor to
 546  *   rapidly adapt to changing data with new codes optimized for that data.
 547  *
 548  * - The codes used by the deflate format are "canonical", which means that
 549  *   the actual bits of the codes are generated in an unambiguous way simply
 550  *   from the number of bits in each code.  Therefore the code descriptions
 551  *   are simply a list of code lengths for each symbol.
 552  *
 553  * - The code lengths are stored in order for the symbols, so lengths are
 554  *   provided for each of the literal/length symbols, and for each of the
 555  *   distance symbols.
 556  *
 557  * - If a symbol is not used in the block, this is represented by a zero as
 558  *   as the code length.  This does not mean a zero-length code, but rather
 559  *   that no code should be created for this symbol.  There is no way in the
 560  *   deflate format to represent a zero-length code.
 561  *
 562  * - The maximum number of bits in a code is 15, so the possible lengths for
 563  *   any code are 1..15.
 564  *
 565  * - The fact that a length of zero is not permitted for a code has an
 566  *   interesting consequence.  Normally if only one symbol is used for a given
 567  *   code, then in fact that code could be represented with zero bits.  However
 568  *   in deflate, that code has to be at least one bit.  So for example, if
 569  *   only a single distance base symbol appears in a block, then it will be
 570  *   represented by a single code of length one, in particular one 0 bit.  This
 571  *   is an incomplete code, since if a 1 bit is received, it has no meaning,
 572  *   and should result in an error.  So incomplete distance codes of one symbol
 573  *   should be permitted, and the receipt of invalid codes should be handled.
 574  *
 575  * - It is also possible to have a single literal/length code, but that code
 576  *   must be the end-of-block code, since every dynamic block has one.  This
 577  *   is not the most efficient way to create an empty block (an empty fixed
 578  *   block is fewer bits), but it is allowed by the format.  So incomplete
 579  *   literal/length codes of one symbol should also be permitted.
 580  *
 581  * - If there are only literal codes and no lengths, then there are no distance
 582  *   codes.  This is represented by one distance code with zero bits.
 583  *
 584  * - The list of up to 286 length/literal lengths and up to 30 distance lengths
 585  *   are themselves compressed using Huffman codes and run-length encoding.  In
 586  *   the list of code lengths, a 0 symbol means no code, a 1..15 symbol means
 587  *   that length, and the symbols 16, 17, and 18 are run-length instructions.
 588  *   Each of 16, 17, and 18 are follwed by extra bits to define the length of
 589  *   the run.  16 copies the last length 3 to 6 times.  17 represents 3 to 10
 590  *   zero lengths, and 18 represents 11 to 138 zero lengths.  Unused symbols
 591  *   are common, hence the special coding for zero lengths.
 592  *
 593  * - The symbols for 0..18 are Huffman coded, and so that code must be
 594  *   described first.  This is simply a sequence of up to 19 three-bit values
 595  *   representing no code (0) or the code length for that symbol (1..7).
 596  *
 597  * - A dynamic block starts with three fixed-size counts from which is computed
 598  *   the number of literal/length code lengths, the number of distance code
 599  *   lengths, and the number of code length code lengths (ok, you come up with
 600  *   a better name!) in the code descriptions.  For the literal/length and
 601  *   distance codes, lengths after those provided are considered zero, i.e. no
 602  *   code.  The code length code lengths are received in a permuted order (see
 603  *   the order[] array below) to make a short code length code length list more
 604  *   likely.  As it turns out, very short and very long codes are less likely
 605  *   to be seen in a dynamic code description, hence what may appear initially
 606  *   to be a peculiar ordering.
 607  *
 608  * - Given the number of literal/length code lengths (nlen) and distance code
 609  *   lengths (ndist), then they are treated as one long list of nlen + ndist
 610  *   code lengths.  Therefore run-length coding can and often does cross the
 611  *   boundary between the two sets of lengths.
 612  *
 613  * - So to summarize, the code description at the start of a dynamic block is
 614  *   three counts for the number of code lengths for the literal/length codes,
 615  *   the distance codes, and the code length codes.  This is followed by the
 616  *   code length code lengths, three bits each.  This is used to construct the
 617  *   code length code which is used to read the remainder of the lengths.  Then
 618  *   the literal/length code lengths and distance lengths are read as a single
 619  *   set of lengths using the code length codes.  Codes are constructed from
 620  *   the resulting two sets of lengths, and then finally you can start
 621  *   decoding actual compressed data in the block.
 622  *
 623  * - For reference, a "typical" size for the code description in a dynamic
 624  *   block is around 80 bytes.
 625  */
 626 local int dynamic(struct state *s)
     /* [<][>][^][v][top][bottom][index][help] */
 627 {
 628     int nlen, ndist, ncode;             /* number of lengths in descriptor */
 629     int index;                          /* index of lengths[] */
 630     int err;                            /* construct() return value */
 631     short lengths[MAXCODES];            /* descriptor code lengths */
 632     short lencnt[MAXBITS+1], lensym[MAXLCODES];         /* lencode memory */
 633     short distcnt[MAXBITS+1], distsym[MAXDCODES];       /* distcode memory */
 634     struct huffman lencode = {lencnt, lensym};          /* length code */
 635     struct huffman distcode = {distcnt, distsym};       /* distance code */
 636     static const short order[19] =      /* permutation of code length codes */
 637         {16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15};
 638 
 639     /* get number of lengths in each table, check lengths */
 640     nlen = bits(s, 5) + 257;
 641     ndist = bits(s, 5) + 1;
 642     ncode = bits(s, 4) + 4;
 643     if (nlen > MAXLCODES || ndist > MAXDCODES)
 644         return -3;                      /* bad counts */
 645 
 646     /* read code length code lengths (really), missing lengths are zero */
 647     for (index = 0; index < ncode; index++)
 648         lengths[order[index]] = bits(s, 3);
 649     for (; index < 19; index++)
 650         lengths[order[index]] = 0;
 651 
 652     /* build huffman table for code lengths codes (use lencode temporarily) */
 653     err = construct(&lencode, lengths, 19);
 654     if (err != 0) return -4;            /* require complete code set here */
 655 
 656     /* read length/literal and distance code length tables */
 657     index = 0;
 658     while (index < nlen + ndist) {
 659         int symbol;             /* decoded value */
 660         int len;                /* last length to repeat */
 661 
 662         symbol = decode(s, &lencode);
 663         if (symbol < 16)                /* length in 0..15 */
 664             lengths[index++] = symbol;
 665         else {                          /* repeat instruction */
 666             len = 0;                    /* assume repeating zeros */
 667             if (symbol == 16) {         /* repeat last length 3..6 times */
 668                 if (index == 0) return -5;      /* no last length! */
 669                 len = lengths[index - 1];       /* last length */
 670                 symbol = 3 + bits(s, 2);
 671             }
 672             else if (symbol == 17)      /* repeat zero 3..10 times */
 673                 symbol = 3 + bits(s, 3);
 674             else                        /* == 18, repeat zero 11..138 times */
 675                 symbol = 11 + bits(s, 7);
 676             if (index + symbol > nlen + ndist)
 677                 return -6;              /* too many lengths! */
 678             while (symbol--)            /* repeat last or zero symbol times */
 679                 lengths[index++] = len;
 680         }
 681     }
 682 
 683     /* build huffman table for literal/length codes */
 684     err = construct(&lencode, lengths, nlen);
 685     if (err < 0 || (err > 0 && nlen - lencode.count[0] != 1))
 686         return -7;      /* only allow incomplete codes if just one code */
 687 
 688     /* build huffman table for distance codes */
 689     err = construct(&distcode, lengths + nlen, ndist);
 690     if (err < 0 || (err > 0 && ndist - distcode.count[0] != 1))
 691         return -8;      /* only allow incomplete codes if just one code */
 692 
 693     /* decode data until end-of-block code */
 694     return codes(s, &lencode, &distcode);
 695 }
 696 
 697 /*
 698  * Inflate source to dest.  On return, destlen and sourcelen are updated to the
 699  * size of the uncompressed data and the size of the deflate data respectively.
 700  * On success, the return value of puff() is zero.  If there is an error in the
 701  * source data, i.e. it is not in the deflate format, then a negative value is
 702  * returned.  If there is not enough input available or there is not enough
 703  * output space, then a positive error is returned.  In that case, destlen and
 704  * sourcelen are not updated to facilitate retrying from the beginning with the
 705  * provision of more input data or more output space.  In the case of invalid
 706  * inflate data (a negative error), the dest and source pointers are updated to
 707  * facilitate the debugging of deflators.
 708  *
 709  * puff() also has a mode to determine the size of the uncompressed output with
 710  * no output written.  For this dest must be (unsigned char *)0.  In this case,
 711  * the input value of *destlen is ignored, and on return *destlen is set to the
 712  * size of the uncompressed output.
 713  *
 714  * The return codes are:
 715  *
 716  *   2:  available inflate data did not terminate
 717  *   1:  output space exhausted before completing inflate
 718  *   0:  successful inflate
 719  *  -1:  invalid block type (type == 3)
 720  *  -2:  stored block length did not match one's complement
 721  *  -3:  dynamic block code description: too many length or distance codes
 722  *  -4:  dynamic block code description: code lengths codes incomplete
 723  *  -5:  dynamic block code description: repeat lengths with no first length
 724  *  -6:  dynamic block code description: repeat more than specified lengths
 725  *  -7:  dynamic block code description: invalid literal/length code lengths
 726  *  -8:  dynamic block code description: invalid distance code lengths
 727  *  -9:  invalid literal/length or distance code in fixed or dynamic block
 728  * -10:  distance is too far back in fixed or dynamic block
 729  *
 730  * Format notes:
 731  *
 732  * - Three bits are read for each block to determine the kind of block and
 733  *   whether or not it is the last block.  Then the block is decoded and the
 734  *   process repeated if it was not the last block.
 735  *
 736  * - The leftover bits in the last byte of the deflate data after the last
 737  *   block (if it was a fixed or dynamic block) are undefined and have no
 738  *   expected values to check.
 739  */
 740 int puff(unsigned char *dest,           /* pointer to destination pointer */
     /* [<][>][^][v][top][bottom][index][help] */
 741          unsigned long *destlen,        /* amount of output space */
 742          unsigned char *source,         /* pointer to source data pointer */
 743          unsigned long *sourcelen)      /* amount of input available */
 744 {
 745     struct state s;             /* input/output state */
 746     int last, type;             /* block information */
 747     int err;                    /* return value */
 748 
 749     /* initialize output state */
 750     s.out = dest;
 751     s.outlen = *destlen;                /* ignored if dest is NIL */
 752     s.outcnt = 0;
 753 
 754     /* initialize input state */
 755     s.in = source;
 756     s.inlen = *sourcelen;
 757     s.incnt = 0;
 758     s.bitbuf = 0;
 759     s.bitcnt = 0;
 760 
 761     /* return if bits() or decode() tries to read past available input */
 762     if (setjmp(s.env) != 0)             /* if came back here via longjmp() */
 763         err = 2;                        /* then skip do-loop, return error */
 764     else {
 765         /* process blocks until last block or error */
 766         do {
 767             last = bits(&s, 1);         /* one if last block */
 768             type = bits(&s, 2);         /* block type 0..3 */
 769             err = type == 0 ? stored(&s) :
 770                   (type == 1 ? fixed(&s) :
 771                    (type == 2 ? dynamic(&s) :
 772                     -1));               /* type == 3, invalid */
 773             if (err != 0) break;        /* return with error */
 774         } while (!last);
 775     }
 776 
 777     /* update the lengths and return */
 778     if (err <= 0) {
 779         *destlen = s.outcnt;
 780         *sourcelen = s.incnt;
 781     }
 782     return err;
 783 }
 784 
 785 #ifdef TEST
 786 /* Example of how to use puff() */
 787 #include <stdio.h>
 788 #include <stdlib.h>
 789 #include <sys/types.h>
 790 #include <sys/stat.h>
 791 
 792 local unsigned char *yank(char *name, unsigned long *len)
     /* [<][>][^][v][top][bottom][index][help] */
 793 {
 794     unsigned long size;
 795     unsigned char *buf;
 796     FILE *in;
 797     struct stat s;
 798 
 799     *len = 0;
 800     if (stat(name, &s)) return NULL;
 801     if ((s.st_mode & S_IFMT) != S_IFREG) return NULL;
 802     size = (unsigned long)(s.st_size);
 803     if (size == 0 || (off_t)size != s.st_size) return NULL;
 804     in = fopen(name, "r");
 805     if (in == NULL) return NULL;
 806     buf = malloc(size);
 807     if (buf != NULL && fread(buf, 1, size, in) != size) {
 808         free(buf);
 809         buf = NULL;
 810     }
 811     fclose(in);
 812     *len = size;
 813     return buf;
 814 }
 815 
 816 int main(int argc, char **argv)
     /* [<][>][^][v][top][bottom][index][help] */
 817 {
 818     int ret;
 819     unsigned char *source;
 820     unsigned long len, sourcelen, destlen;
 821 
 822     if (argc < 2) return 2;
 823     source = yank(argv[1], &len);
 824     if (source == NULL) return 2;
 825     sourcelen = len;
 826     ret = puff(NIL, &destlen, source, &sourcelen);
 827     if (ret)
 828         printf("puff() failed with return code %d\n", ret);
 829     else {
 830         printf("puff() succeeded uncompressing %lu bytes\n", destlen);
 831         if (sourcelen < len) printf("%lu compressed bytes unused\n",
 832                                     len - sourcelen);
 833     }
 834     free(source);
 835     return ret;
 836 }
 837 #endif

/* [<][>][^][v][top][bottom][index][help] */