ucw/lizard.h

   1 /*
   2  *      LiZaRd -- Fast compression method based on Lempel-Ziv 77
   3  *
   4  *      (c) 2004, Robert Spalek <robert@ucw.cz>
   5  *
   6  *      This software may be freely distributed and used according to the terms
   7  *      of the GNU Lesser General Public License.
   8  */
   9
  10 #ifndef _UCW_LIZARD_H
  11 #define _UCW_LIZARD_H
  12
  13 /***
  14  * [[basic]]
  15  * Basic application
  16  * -----------------
  17  **/
  18
  19 /**
  20  * The compression routine needs input buffer 8 characters longer, because it
  21  * does not check the input bounds all the time.
  22  **/
  23 #define LIZARD_NEEDS_CHARS      8
  24
  25 #define LIZARD_MAX_MULTIPLY     23./22
  26 #define LIZARD_MAX_ADD          4
  27   /* In the worst case, the compressed file will not be longer than its
  28    * original length * 23/22 + 4.
  29    *
  30    * The additive constant is for EOF and the header of the file.
  31    *
  32    * The multiplicative constant comes from 19-byte incompressible string
  33    * followed by a 3-sequence that can be compressed into 2-byte link.  This
  34    * breaks the copy-mode and it needs to be restarted with a new header.  The
  35    * total length is 2(header) + 19(string) + 2(link) = 23.
  36    */
  37
  38 /**
  39  * The compressed data will not be longer than `LIZARD_MAX_LEN(input_length)`.
  40  * Note that `LIZARD_MAX_LEN(length) > length` (this is not a problem of the algorithm,
  41  * every lossless compression algorithm must have an input for which it produces a larger
  42  * output).
  43  *
  44  * Use this to compute the size of @out paramater of @lizard_compress().
  45  **/
  46 #define LIZARD_MAX_LEN(LENGTH) ((LENGTH) * LIZARD_MAX_MULTIPLY + LIZARD_MAX_ADD)
  47
  48 /* lizard.c */
  49
  50 /**
  51  * Compress data provided in @in.
  52  * The input buffer must be at last `@in_len + <<def_LIZARD_NEEDS_CHARS,LIZARD_NEEDS_CHARS>>`
  53  * long (the compression algorithm does not check the bounds all the time).
  54  *
  55  * The output will be stored in @out. The @out buffer must be at last <<def_LIZARD_LEN,`LIZARD_LEN(@in_len)`>>
  56  * bytes long for the output to fit in for sure.
  57  *
  58  * The function returns number of bytes actually needed (the size of output).
  59  *
  60  * Use @lizard_decompress() to get the original data.
  61  **/
  62 int lizard_compress(const byte *in, uns in_len, byte *out);
  63
  64 /**
  65  * Decompress data previously compressed by @lizard_compress().
  66  * Input is taken from @in and the result stored in @out.
  67  * The size of output is returned.
  68  *
  69  * Note that you need to know the maximal possible size of the output to
  70  * allocate enough memory.
  71  *
  72  * See also <<safe,safe decompression>>.
  73  **/
  74 int lizard_decompress(const byte *in, byte *out);
  75
  76 /* lizard-safe.c */
  77
  78 /***
  79  * [[safe]]
  80  * Safe decompression
  81  * ------------------
  82  *
  83  * You can use safe decompression, when you want to make sure you got the
  84  * length right and when you want to reuse the buffer for output.
  85  ***/
  86
  87 struct lizard_buffer;   /** Type of the output buffer for @lizard_decompress_safe(). **/
  88
  89 struct lizard_buffer *lizard_alloc(void);       /** Get me a new <<struct_lizard_buffer,`lizard_buffer`>>. **/
  90 /**
  91  * Return memory used by a <<struct_lizard_buffer,`lizard_buffer`>>.
  92  * It frees even the data stored in it (the result of
  93  * @lizard_decompress_safe() call that used this buffer).
  94  **/
  95 void lizard_free(struct lizard_buffer *buf);
  96
  97 /**
  98  * This one acts much like @lizard_decompress(). The difference is it
  99  * checks the data to be of correct length (therefore it will not
 100  * crash on invalid data).
 101  *
 102  * It decompresses data provided by @in. The @buf is used to get the
 103  * memory for output (you get one by @lizard_alloc()).
 104  *
 105  * The pointer to decompressed data is returned. To free it, free the
 106  * buffer by @lizard_free().
 107  *
 108  * In the case of error, NULL is returned. In that case, `errno` is
 109  * set either to `EINVAL` (expected_length does not match) or to
 110  * `EFAULT` (a segfault has been caught while decompressing -- it
 111  * probably means expected_length was set way too low). Both cases
 112  * suggest either wrongly computed length or data corruption.
 113  *
 114  * The @buf argument may be reused for multiple decompresses. However,
 115  * the data will be overwritten by the next call.
 116  *
 117  * Beware this function is not thread-safe and is not even reentrant
 118  * (because of internal segfault handling).
 119  **/
 120 byte *lizard_decompress_safe(const byte *in, struct lizard_buffer *buf, uns expected_length);
 121
 122 /* adler32.c */
 123
 124 /***
 125  * [[adler]]
 126  * Adler-32 checksum
 127  * -----------------
 128  *
 129  * This is here because it is commonly used to check data compressed by LiZaRd.
 130  * However, it could also belong to <<hash,hashing routines>>.
 131  ***/
 132
 133 /**
 134  * Update the Adler-32 checksum with more data.
 135  * @adler is the old value, @byte points to @len bytes of data to update with.
 136  * Result is returned.
 137  **/
 138 uns adler32_update(uns adler, const byte *ptr, uns len);
 139
 140 /**
 141  * Compute the Adler-32 checksum of a block of data.
 142  **/
 143 static inline uns adler32(const byte *buf, uns len)
 144 {
 145   return adler32_update(1, buf, len);
 146 }
 147
 148 #endif