cannam@89: /* zran.c -- example of zlib/gzip stream indexing and random access
cannam@89:  * Copyright (C) 2005 Mark Adler
cannam@89:  * For conditions of distribution and use, see copyright notice in zlib.h
cannam@89:    Version 1.0  29 May 2005  Mark Adler */
cannam@89: 
cannam@89: /* Illustrate the use of Z_BLOCK, inflatePrime(), and inflateSetDictionary()
cannam@89:    for random access of a compressed file.  A file containing a zlib or gzip
cannam@89:    stream is provided on the command line.  The compressed stream is decoded in
cannam@89:    its entirety, and an index built with access points about every SPAN bytes
cannam@89:    in the uncompressed output.  The compressed file is left open, and can then
cannam@89:    be read randomly, having to decompress on the average SPAN/2 uncompressed
cannam@89:    bytes before getting to the desired block of data.
cannam@89: 
cannam@89:    An access point can be created at the start of any deflate block, by saving
cannam@89:    the starting file offset and bit of that block, and the 32K bytes of
cannam@89:    uncompressed data that precede that block.  Also the uncompressed offset of
cannam@89:    that block is saved to provide a referece for locating a desired starting
cannam@89:    point in the uncompressed stream.  build_index() works by decompressing the
cannam@89:    input zlib or gzip stream a block at a time, and at the end of each block
cannam@89:    deciding if enough uncompressed data has gone by to justify the creation of
cannam@89:    a new access point.  If so, that point is saved in a data structure that
cannam@89:    grows as needed to accommodate the points.
cannam@89: 
cannam@89:    To use the index, an offset in the uncompressed data is provided, for which
cannam@89:    the latest accees point at or preceding that offset is located in the index.
cannam@89:    The input file is positioned to the specified location in the index, and if
cannam@89:    necessary the first few bits of the compressed data is read from the file.
cannam@89:    inflate is initialized with those bits and the 32K of uncompressed data, and
cannam@89:    the decompression then proceeds until the desired offset in the file is
cannam@89:    reached.  Then the decompression continues to read the desired uncompressed
cannam@89:    data from the file.
cannam@89: 
cannam@89:    Another approach would be to generate the index on demand.  In that case,
cannam@89:    requests for random access reads from the compressed data would try to use
cannam@89:    the index, but if a read far enough past the end of the index is required,
cannam@89:    then further index entries would be generated and added.
cannam@89: 
cannam@89:    There is some fair bit of overhead to starting inflation for the random
cannam@89:    access, mainly copying the 32K byte dictionary.  So if small pieces of the
cannam@89:    file are being accessed, it would make sense to implement a cache to hold
cannam@89:    some lookahead and avoid many calls to extract() for small lengths.
cannam@89: 
cannam@89:    Another way to build an index would be to use inflateCopy().  That would
cannam@89:    not be constrained to have access points at block boundaries, but requires
cannam@89:    more memory per access point, and also cannot be saved to file due to the
cannam@89:    use of pointers in the state.  The approach here allows for storage of the
cannam@89:    index in a file.
cannam@89:  */
cannam@89: 
cannam@89: #include <stdio.h>
cannam@89: #include <stdlib.h>
cannam@89: #include <string.h>
cannam@89: #include "zlib.h"
cannam@89: 
cannam@89: #define local static
cannam@89: 
cannam@89: #define SPAN 1048576L       /* desired distance between access points */
cannam@89: #define WINSIZE 32768U      /* sliding window size */
cannam@89: #define CHUNK 16384         /* file input buffer size */
cannam@89: 
cannam@89: /* access point entry */
cannam@89: struct point {
cannam@89:     off_t out;          /* corresponding offset in uncompressed data */
cannam@89:     off_t in;           /* offset in input file of first full byte */
cannam@89:     int bits;           /* number of bits (1-7) from byte at in - 1, or 0 */
cannam@89:     unsigned char window[WINSIZE];  /* preceding 32K of uncompressed data */
cannam@89: };
cannam@89: 
cannam@89: /* access point list */
cannam@89: struct access {
cannam@89:     int have;           /* number of list entries filled in */
cannam@89:     int size;           /* number of list entries allocated */
cannam@89:     struct point *list; /* allocated list */
cannam@89: };
cannam@89: 
cannam@89: /* Deallocate an index built by build_index() */
cannam@89: local void free_index(struct access *index)
cannam@89: {
cannam@89:     if (index != NULL) {
cannam@89:         free(index->list);
cannam@89:         free(index);
cannam@89:     }
cannam@89: }
cannam@89: 
cannam@89: /* Add an entry to the access point list.  If out of memory, deallocate the
cannam@89:    existing list and return NULL. */
cannam@89: local struct access *addpoint(struct access *index, int bits,
cannam@89:     off_t in, off_t out, unsigned left, unsigned char *window)
cannam@89: {
cannam@89:     struct point *next;
cannam@89: 
cannam@89:     /* if list is empty, create it (start with eight points) */
cannam@89:     if (index == NULL) {
cannam@89:         index = malloc(sizeof(struct access));
cannam@89:         if (index == NULL) return NULL;
cannam@89:         index->list = malloc(sizeof(struct point) << 3);
cannam@89:         if (index->list == NULL) {
cannam@89:             free(index);
cannam@89:             return NULL;
cannam@89:         }
cannam@89:         index->size = 8;
cannam@89:         index->have = 0;
cannam@89:     }
cannam@89: 
cannam@89:     /* if list is full, make it bigger */
cannam@89:     else if (index->have == index->size) {
cannam@89:         index->size <<= 1;
cannam@89:         next = realloc(index->list, sizeof(struct point) * index->size);
cannam@89:         if (next == NULL) {
cannam@89:             free_index(index);
cannam@89:             return NULL;
cannam@89:         }
cannam@89:         index->list = next;
cannam@89:     }
cannam@89: 
cannam@89:     /* fill in entry and increment how many we have */
cannam@89:     next = index->list + index->have;
cannam@89:     next->bits = bits;
cannam@89:     next->in = in;
cannam@89:     next->out = out;
cannam@89:     if (left)
cannam@89:         memcpy(next->window, window + WINSIZE - left, left);
cannam@89:     if (left < WINSIZE)
cannam@89:         memcpy(next->window + left, window, WINSIZE - left);
cannam@89:     index->have++;
cannam@89: 
cannam@89:     /* return list, possibly reallocated */
cannam@89:     return index;
cannam@89: }
cannam@89: 
cannam@89: /* Make one entire pass through the compressed stream and build an index, with
cannam@89:    access points about every span bytes of uncompressed output -- span is
cannam@89:    chosen to balance the speed of random access against the memory requirements
cannam@89:    of the list, about 32K bytes per access point.  Note that data after the end
cannam@89:    of the first zlib or gzip stream in the file is ignored.  build_index()
cannam@89:    returns the number of access points on success (>= 1), Z_MEM_ERROR for out
cannam@89:    of memory, Z_DATA_ERROR for an error in the input file, or Z_ERRNO for a
cannam@89:    file read error.  On success, *built points to the resulting index. */
cannam@89: local int build_index(FILE *in, off_t span, struct access **built)
cannam@89: {
cannam@89:     int ret;
cannam@89:     off_t totin, totout;        /* our own total counters to avoid 4GB limit */
cannam@89:     off_t last;                 /* totout value of last access point */
cannam@89:     struct access *index;       /* access points being generated */
cannam@89:     z_stream strm;
cannam@89:     unsigned char input[CHUNK];
cannam@89:     unsigned char window[WINSIZE];
cannam@89: 
cannam@89:     /* initialize inflate */
cannam@89:     strm.zalloc = Z_NULL;
cannam@89:     strm.zfree = Z_NULL;
cannam@89:     strm.opaque = Z_NULL;
cannam@89:     strm.avail_in = 0;
cannam@89:     strm.next_in = Z_NULL;
cannam@89:     ret = inflateInit2(&strm, 47);      /* automatic zlib or gzip decoding */
cannam@89:     if (ret != Z_OK)
cannam@89:         return ret;
cannam@89: 
cannam@89:     /* inflate the input, maintain a sliding window, and build an index -- this
cannam@89:        also validates the integrity of the compressed data using the check
cannam@89:        information at the end of the gzip or zlib stream */
cannam@89:     totin = totout = last = 0;
cannam@89:     index = NULL;               /* will be allocated by first addpoint() */
cannam@89:     strm.avail_out = 0;
cannam@89:     do {
cannam@89:         /* get some compressed data from input file */
cannam@89:         strm.avail_in = fread(input, 1, CHUNK, in);
cannam@89:         if (ferror(in)) {
cannam@89:             ret = Z_ERRNO;
cannam@89:             goto build_index_error;
cannam@89:         }
cannam@89:         if (strm.avail_in == 0) {
cannam@89:             ret = Z_DATA_ERROR;
cannam@89:             goto build_index_error;
cannam@89:         }
cannam@89:         strm.next_in = input;
cannam@89: 
cannam@89:         /* process all of that, or until end of stream */
cannam@89:         do {
cannam@89:             /* reset sliding window if necessary */
cannam@89:             if (strm.avail_out == 0) {
cannam@89:                 strm.avail_out = WINSIZE;
cannam@89:                 strm.next_out = window;
cannam@89:             }
cannam@89: 
cannam@89:             /* inflate until out of input, output, or at end of block --
cannam@89:                update the total input and output counters */
cannam@89:             totin += strm.avail_in;
cannam@89:             totout += strm.avail_out;
cannam@89:             ret = inflate(&strm, Z_BLOCK);      /* return at end of block */
cannam@89:             totin -= strm.avail_in;
cannam@89:             totout -= strm.avail_out;
cannam@89:             if (ret == Z_NEED_DICT)
cannam@89:                 ret = Z_DATA_ERROR;
cannam@89:             if (ret == Z_MEM_ERROR || ret == Z_DATA_ERROR)
cannam@89:                 goto build_index_error;
cannam@89:             if (ret == Z_STREAM_END)
cannam@89:                 break;
cannam@89: 
cannam@89:             /* if at end of block, consider adding an index entry (note that if
cannam@89:                data_type indicates an end-of-block, then all of the
cannam@89:                uncompressed data from that block has been delivered, and none
cannam@89:                of the compressed data after that block has been consumed,
cannam@89:                except for up to seven bits) -- the totout == 0 provides an
cannam@89:                entry point after the zlib or gzip header, and assures that the
cannam@89:                index always has at least one access point; we avoid creating an
cannam@89:                access point after the last block by checking bit 6 of data_type
cannam@89:              */
cannam@89:             if ((strm.data_type & 128) && !(strm.data_type & 64) &&
cannam@89:                 (totout == 0 || totout - last > span)) {
cannam@89:                 index = addpoint(index, strm.data_type & 7, totin,
cannam@89:                                  totout, strm.avail_out, window);
cannam@89:                 if (index == NULL) {
cannam@89:                     ret = Z_MEM_ERROR;
cannam@89:                     goto build_index_error;
cannam@89:                 }
cannam@89:                 last = totout;
cannam@89:             }
cannam@89:         } while (strm.avail_in != 0);
cannam@89:     } while (ret != Z_STREAM_END);
cannam@89: 
cannam@89:     /* clean up and return index (release unused entries in list) */
cannam@89:     (void)inflateEnd(&strm);
cannam@89:     index = realloc(index, sizeof(struct point) * index->have);
cannam@89:     index->size = index->have;
cannam@89:     *built = index;
cannam@89:     return index->size;
cannam@89: 
cannam@89:     /* return error */
cannam@89:   build_index_error:
cannam@89:     (void)inflateEnd(&strm);
cannam@89:     if (index != NULL)
cannam@89:         free_index(index);
cannam@89:     return ret;
cannam@89: }
cannam@89: 
cannam@89: /* Use the index to read len bytes from offset into buf, return bytes read or
cannam@89:    negative for error (Z_DATA_ERROR or Z_MEM_ERROR).  If data is requested past
cannam@89:    the end of the uncompressed data, then extract() will return a value less
cannam@89:    than len, indicating how much as actually read into buf.  This function
cannam@89:    should not return a data error unless the file was modified since the index
cannam@89:    was generated.  extract() may also return Z_ERRNO if there is an error on
cannam@89:    reading or seeking the input file. */
cannam@89: local int extract(FILE *in, struct access *index, off_t offset,
cannam@89:                   unsigned char *buf, int len)
cannam@89: {
cannam@89:     int ret, skip;
cannam@89:     z_stream strm;
cannam@89:     struct point *here;
cannam@89:     unsigned char input[CHUNK];
cannam@89:     unsigned char discard[WINSIZE];
cannam@89: 
cannam@89:     /* proceed only if something reasonable to do */
cannam@89:     if (len < 0)
cannam@89:         return 0;
cannam@89: 
cannam@89:     /* find where in stream to start */
cannam@89:     here = index->list;
cannam@89:     ret = index->have;
cannam@89:     while (--ret && here[1].out <= offset)
cannam@89:         here++;
cannam@89: 
cannam@89:     /* initialize file and inflate state to start there */
cannam@89:     strm.zalloc = Z_NULL;
cannam@89:     strm.zfree = Z_NULL;
cannam@89:     strm.opaque = Z_NULL;
cannam@89:     strm.avail_in = 0;
cannam@89:     strm.next_in = Z_NULL;
cannam@89:     ret = inflateInit2(&strm, -15);         /* raw inflate */
cannam@89:     if (ret != Z_OK)
cannam@89:         return ret;
cannam@89:     ret = fseeko(in, here->in - (here->bits ? 1 : 0), SEEK_SET);
cannam@89:     if (ret == -1)
cannam@89:         goto extract_ret;
cannam@89:     if (here->bits) {
cannam@89:         ret = getc(in);
cannam@89:         if (ret == -1) {
cannam@89:             ret = ferror(in) ? Z_ERRNO : Z_DATA_ERROR;
cannam@89:             goto extract_ret;
cannam@89:         }
cannam@89:         (void)inflatePrime(&strm, here->bits, ret >> (8 - here->bits));
cannam@89:     }
cannam@89:     (void)inflateSetDictionary(&strm, here->window, WINSIZE);
cannam@89: 
cannam@89:     /* skip uncompressed bytes until offset reached, then satisfy request */
cannam@89:     offset -= here->out;
cannam@89:     strm.avail_in = 0;
cannam@89:     skip = 1;                               /* while skipping to offset */
cannam@89:     do {
cannam@89:         /* define where to put uncompressed data, and how much */
cannam@89:         if (offset == 0 && skip) {          /* at offset now */
cannam@89:             strm.avail_out = len;
cannam@89:             strm.next_out = buf;
cannam@89:             skip = 0;                       /* only do this once */
cannam@89:         }
cannam@89:         if (offset > WINSIZE) {             /* skip WINSIZE bytes */
cannam@89:             strm.avail_out = WINSIZE;
cannam@89:             strm.next_out = discard;
cannam@89:             offset -= WINSIZE;
cannam@89:         }
cannam@89:         else if (offset != 0) {             /* last skip */
cannam@89:             strm.avail_out = (unsigned)offset;
cannam@89:             strm.next_out = discard;
cannam@89:             offset = 0;
cannam@89:         }
cannam@89: 
cannam@89:         /* uncompress until avail_out filled, or end of stream */
cannam@89:         do {
cannam@89:             if (strm.avail_in == 0) {
cannam@89:                 strm.avail_in = fread(input, 1, CHUNK, in);
cannam@89:                 if (ferror(in)) {
cannam@89:                     ret = Z_ERRNO;
cannam@89:                     goto extract_ret;
cannam@89:                 }
cannam@89:                 if (strm.avail_in == 0) {
cannam@89:                     ret = Z_DATA_ERROR;
cannam@89:                     goto extract_ret;
cannam@89:                 }
cannam@89:                 strm.next_in = input;
cannam@89:             }
cannam@89:             ret = inflate(&strm, Z_NO_FLUSH);       /* normal inflate */
cannam@89:             if (ret == Z_NEED_DICT)
cannam@89:                 ret = Z_DATA_ERROR;
cannam@89:             if (ret == Z_MEM_ERROR || ret == Z_DATA_ERROR)
cannam@89:                 goto extract_ret;
cannam@89:             if (ret == Z_STREAM_END)
cannam@89:                 break;
cannam@89:         } while (strm.avail_out != 0);
cannam@89: 
cannam@89:         /* if reach end of stream, then don't keep trying to get more */
cannam@89:         if (ret == Z_STREAM_END)
cannam@89:             break;
cannam@89: 
cannam@89:         /* do until offset reached and requested data read, or stream ends */
cannam@89:     } while (skip);
cannam@89: 
cannam@89:     /* compute number of uncompressed bytes read after offset */
cannam@89:     ret = skip ? 0 : len - strm.avail_out;
cannam@89: 
cannam@89:     /* clean up and return bytes read or error */
cannam@89:   extract_ret:
cannam@89:     (void)inflateEnd(&strm);
cannam@89:     return ret;
cannam@89: }
cannam@89: 
cannam@89: /* Demonstrate the use of build_index() and extract() by processing the file
cannam@89:    provided on the command line, and the extracting 16K from about 2/3rds of
cannam@89:    the way through the uncompressed output, and writing that to stdout. */
cannam@89: int main(int argc, char **argv)
cannam@89: {
cannam@89:     int len;
cannam@89:     off_t offset;
cannam@89:     FILE *in;
cannam@89:     struct access *index = NULL;
cannam@89:     unsigned char buf[CHUNK];
cannam@89: 
cannam@89:     /* open input file */
cannam@89:     if (argc != 2) {
cannam@89:         fprintf(stderr, "usage: zran file.gz\n");
cannam@89:         return 1;
cannam@89:     }
cannam@89:     in = fopen(argv[1], "rb");
cannam@89:     if (in == NULL) {
cannam@89:         fprintf(stderr, "zran: could not open %s for reading\n", argv[1]);
cannam@89:         return 1;
cannam@89:     }
cannam@89: 
cannam@89:     /* build index */
cannam@89:     len = build_index(in, SPAN, &index);
cannam@89:     if (len < 0) {
cannam@89:         fclose(in);
cannam@89:         switch (len) {
cannam@89:         case Z_MEM_ERROR:
cannam@89:             fprintf(stderr, "zran: out of memory\n");
cannam@89:             break;
cannam@89:         case Z_DATA_ERROR:
cannam@89:             fprintf(stderr, "zran: compressed data error in %s\n", argv[1]);
cannam@89:             break;
cannam@89:         case Z_ERRNO:
cannam@89:             fprintf(stderr, "zran: read error on %s\n", argv[1]);
cannam@89:             break;
cannam@89:         default:
cannam@89:             fprintf(stderr, "zran: error %d while building index\n", len);
cannam@89:         }
cannam@89:         return 1;
cannam@89:     }
cannam@89:     fprintf(stderr, "zran: built index with %d access points\n", len);
cannam@89: 
cannam@89:     /* use index by reading some bytes from an arbitrary offset */
cannam@89:     offset = (index->list[index->have - 1].out << 1) / 3;
cannam@89:     len = extract(in, index, offset, buf, CHUNK);
cannam@89:     if (len < 0)
cannam@89:         fprintf(stderr, "zran: extraction failed: %s error\n",
cannam@89:                 len == Z_MEM_ERROR ? "out of memory" : "input corrupted");
cannam@89:     else {
cannam@89:         fwrite(buf, 1, len, stdout);
cannam@89:         fprintf(stderr, "zran: extracted %d bytes at %llu\n", len, offset);
cannam@89:     }
cannam@89: 
cannam@89:     /* clean up and exit */
cannam@89:     free_index(index);
cannam@89:     fclose(in);
cannam@89:     return 0;
cannam@89: }