src/liblzma/api/lzma/lzma.h

   1 /**
   2  * \file        lzma/lzma.h
   3  * \brief       LZMA filter
   4  *
   5  * \author      Copyright (C) 1999-2006 Igor Pavlov
   6  * \author      Copyright (C) 2007 Lasse Collin
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  */
  18
  19 #ifndef LZMA_H_INTERNAL
  20 #       error Never include this file directly. Use <lzma.h> instead.
  21 #endif
  22
  23
  24 /**
  25  * \brief       Filter ID
  26  *
  27  * Filter ID of the LZMA filter. This is used as lzma_filter.id.
  28  */
  29 #define LZMA_FILTER_LZMA        LZMA_VLI_C(0x20)
  30
  31 #define LZMA_FILTER_LZMA2       LZMA_VLI_C(0x21)
  32
  33
  34 /**
  35  * \brief       Match finders
  36  *
  37  * Match finder has major effect on both speed and compression ratio.
  38  * Usually hash chains are faster than binary trees.
  39  */
  40 typedef enum {
  41         LZMA_MF_HC3     = 0x03,
  42                 /**<
  43                  * \brief       Hash Chain with 3 bytes hashing
  44                  *
  45                  * \todo Memory requirements
  46                  *
  47                  * \note        It's possible that this match finder gets
  48                  *              removed in future. The definition will stay
  49                  *              in this header, but liblzma may return
  50                  *              LZMA_OPTIONS_ERROR if it is specified (just
  51                  *              like it would if the match finder had been
  52                  *              disabled at compile time).
  53                  */
  54
  55         LZMA_MF_HC4     = 0x04,
  56                 /**<
  57                  * \brief       Hash Chain with 4 bytes hashing
  58                  *
  59                  * Memory requirements: 7.5 * dictionary_size + 4 MiB
  60                  *
  61                  * \note        It's possible that this match finder gets
  62                  *              removed in future. The definition will stay
  63                  *              in this header, but liblzma may return
  64                  *              LZMA_OPTIONS_ERROR if it is specified (just
  65                  *              like it would if the match finder had been
  66                  *              disabled at compile time).
  67                  */
  68
  69         LZMA_MF_BT2     = 0x12,
  70                 /**<
  71                  * \brief       Binary Tree with 2 bytes hashing
  72                  *
  73                  * Memory requirements: 9.5 * dictionary_size + 4 MiB
  74                  */
  75
  76         LZMA_MF_BT3     = 0x13,
  77                 /**<
  78                  * \brief       Binary Tree with 3 bytes hashing
  79                  *
  80                  * Memory requirements: 11.5 * dictionary_size + 4 MiB
  81                  */
  82
  83         LZMA_MF_BT4     = 0x14
  84                 /**<
  85                  * \brief       Binary Tree with 4 bytes hashing
  86                  *
  87                  * Memory requirements: 11.5 * dictionary_size + 4 MiB
  88                  */
  89 } lzma_match_finder;
  90
  91
  92 /**
  93  * \brief       Test if given match finder is supported
  94  *
  95  * Returns true if the given match finder is supported by this liblzma build.
  96  * Otherwise false is returned. It is safe to call this with a value that
  97  * isn't listed in lzma_match_finder enumeration; the return value will be
  98  * false.
  99  *
 100  * There is no way to list which match finders are available in this
 101  * particular liblzma version and build. It would be useless, because
 102  * a new match finder, which the application developer wasn't aware,
 103  * could require giving additional options to the encoder that the older
 104  * match finders don't need.
 105  */
 106 extern lzma_bool lzma_mf_is_supported(lzma_match_finder match_finder)
 107                 lzma_attr_const;
 108
 109
 110 /**
 111  * \brief       LZMA compression modes
 112  *
 113  * This selects the function used to analyze the data produced by the match
 114  * finder.
 115  */
 116 typedef enum {
 117         LZMA_MODE_FAST = 0,
 118                 /**<
 119                  * \brief       Fast compression
 120                  *
 121                  * Fast mode is usually at its best when combined with
 122                  * a hash chain match finder.
 123                  */
 124
 125         LZMA_MODE_NORMAL = 1
 126                 /**<
 127                  * \brief       Normal compression
 128                  *
 129                  * This is usually notably slower than fast mode. Use this
 130                  * together with binary tree match finders to expose the
 131                  * full potential of the LZMA encoder.
 132                  */
 133 } lzma_mode;
 134
 135
 136 /**
 137  * \brief       Test if given compression mode is supported
 138  *
 139  * Returns true if the given compression mode is supported by this liblzma
 140  * build. Otherwise false is returned. It is safe to call this with a value
 141  * that isn't listed in lzma_mode enumeration; the return value will be false.
 142  *
 143  * There is no way to list which modes are available in this particular
 144  * liblzma version and build. It would be useless, because a new compression
 145  * mode, which the application developer wasn't aware, could require giving
 146  * additional options to the encoder that the older modes don't need.
 147  */
 148 extern lzma_bool lzma_mode_is_available(lzma_mode mode) lzma_attr_const;
 149
 150
 151 /**
 152  * \brief       Options specific to the LZMA method handler
 153  */
 154 typedef struct {
 155         /**********************************
 156          * LZMA encoding/decoding options *
 157          **********************************/
 158
 159         /* These options are required in encoder and also with raw decoding. */
 160
 161         /**
 162          * \brief       Dictionary size in bytes
 163          *
 164          * Dictionary size indicates how many bytes of the recently processed
 165          * uncompressed data is kept in memory. One method to reduce size of
 166          * the uncompressed data is to store distance-length pairs, which
 167          * indicate what data to repeat from the dictionary buffer. Thus,
 168          * the bigger the dictionary, the better compression ratio usually is.
 169          *
 170          * Raw decoding: Too big dictionary does no other harm than
 171          * wasting memory. This value is ignored by lzma_raw_decode_buffer(),
 172          * because it uses the target buffer as the dictionary.
 173          */
 174         uint32_t dictionary_size;
 175 #       define LZMA_DICTIONARY_SIZE_MIN            (UINT32_C(1) << 12)
 176 #       define LZMA_DICTIONARY_SIZE_MAX            (UINT32_C(1) << 30)
 177 #       define LZMA_DICTIONARY_SIZE_DEFAULT        (UINT32_C(1) << 23)
 178
 179         /**
 180          * \brief       Pointer to an initial dictionary
 181          *
 182          * It is possible to initialize the LZ77 history window using
 183          * a preset dictionary. Here is a good quote from zlib's
 184          * documentation; this applies to LZMA as is:
 185          *
 186          * "The dictionary should consist of strings (byte sequences) that
 187          * are likely to be encountered later in the data to be compressed,
 188          * with the most commonly used strings preferably put towards the
 189          * end of the dictionary. Using a dictionary is most useful when
 190          * the data to be compressed is short and can be predicted with
 191          * good accuracy; the data can then be compressed better than
 192          * with the default empty dictionary."
 193          * (From deflateSetDictionary() in zlib.h of zlib version 1.2.3)
 194          *
 195          * This feature should be used only in special situations.
 196          * It works correctly only with raw encoding and decoding.
 197          * Currently none of the container formats supported by
 198          * liblzma allow preset dictionary when decoding, thus if
 199          * you create a .lzma file with preset dictionary, it cannot
 200          * be decoded with the regular .lzma decoder functions.
 201          *
 202          * \todo        This feature is not implemented yet.
 203          */
 204         const uint8_t *preset_dictionary;
 205
 206         /**
 207          * \brief       Size of the preset dictionary
 208          *
 209          * Specifies the size of the preset dictionary. If the size is
 210          * bigger than dictionary_size, only the last dictionary_size
 211          * bytes are processed.
 212          *
 213          * This variable is read only when preset_dictionary is not NULL.
 214          */
 215         uint32_t preset_dictionary_size;
 216
 217         /**
 218          * \brief       Number of literal context bits
 219          *
 220          * How many of the highest bits of the previous uncompressed
 221          * eight-bit byte (also known as `literal') are taken into
 222          * account when predicting the bits of the next literal.
 223          *
 224          * \todo        Example
 225          */
 226         uint32_t literal_context_bits;
 227 #       define LZMA_LITERAL_CONTEXT_BITS_MIN       0
 228 #       define LZMA_LITERAL_CONTEXT_BITS_MAX       4
 229 #       define LZMA_LITERAL_CONTEXT_BITS_DEFAULT   3
 230
 231         /**
 232          * \brief       Number of literal position bits
 233          *
 234          * How many of the lowest bits of the current position (number
 235          * of bytes from the beginning of the uncompressed data) in the
 236          * uncompressed data is taken into account when predicting the
 237          * bits of the next literal (a single eight-bit byte).
 238          *
 239          * \todo        Example
 240          */
 241         uint32_t literal_pos_bits;
 242 #       define LZMA_LITERAL_POS_BITS_MIN           0
 243 #       define LZMA_LITERAL_POS_BITS_MAX           4
 244 #       define LZMA_LITERAL_POS_BITS_DEFAULT       0
 245
 246         /**
 247          * \brief       Number of position bits
 248          *
 249          * How many of the lowest bits of the current position in the
 250          * uncompressed data is taken into account when estimating
 251          * probabilities of matches. A match is a sequence of bytes for
 252          * which a matching sequence is found from the dictionary and
 253          * thus can be stored as distance-length pair.
 254          *
 255          * Example: If most of the matches occur at byte positions
 256          * of 8 * n + 3, that is, 3, 11, 19, ... set pos_bits to 3,
 257          * because 2**3 == 8.
 258          */
 259         uint32_t pos_bits;
 260 #       define LZMA_POS_BITS_MIN                   0
 261 #       define LZMA_POS_BITS_MAX                   4
 262 #       define LZMA_POS_BITS_DEFAULT               2
 263
 264         /******************************************
 265          * LZMA options needed only when encoding *
 266          ******************************************/
 267
 268         /**
 269          * \brief       Indicate if the options structure is persistent
 270          *
 271          * If this is true, the application must keep this options structure
 272          * available after the LZMA2 encoder has been initialized. With
 273          * persistent structure it is possible to change some encoder options
 274          * in the middle of the encoding process without resetting the encoder.
 275          *
 276          * This option is used only by LZMA2. LZMA1 ignores this and it is
 277          * safeto not initialize this when encoding with LZMA1.
 278          */
 279         lzma_bool persistent;
 280
 281         /** LZMA compression mode */
 282         lzma_mode mode;
 283
 284         /**
 285          * \brief       Number of fast bytes
 286          *
 287          * Number of fast bytes determines how many bytes the encoder
 288          * compares from the match candidates when looking for the best
 289          * match. Bigger fast bytes value usually increase both compression
 290          * ratio and time.
 291          */
 292         uint32_t fast_bytes;
 293 #       define LZMA_FAST_BYTES_MIN                 5
 294 #       define LZMA_FAST_BYTES_MAX                 273
 295 #       define LZMA_FAST_BYTES_DEFAULT             128
 296
 297         /** Match finder ID */
 298         lzma_match_finder match_finder;
 299
 300         /**
 301          * \brief       Match finder cycles
 302          *
 303          * Higher values give slightly better compression ratio but
 304          * decrease speed. Use special value 0 to let liblzma use
 305          * match-finder-dependent default value.
 306          *
 307          * \todo        Write much better description.
 308          */
 309         uint32_t match_finder_cycles;
 310
 311         /**
 312          * \brief       Reserved space for possible future extensions
 313          *
 314          * You should not touch these, because the names of these variables
 315          * may change. These are and will never be used with the currently
 316          * supported options, so it is safe to leave these uninitialized.
 317          */
 318         uint32_t reserved_int1;
 319         uint32_t reserved_int2;
 320         uint32_t reserved_int3;
 321         uint32_t reserved_int4;
 322         void *reserved_ptr1;
 323         void *reserved_ptr2;
 324
 325 } lzma_options_lzma;
 326
 327
 328 /**
 329  * \brief       Maximum sum of literal_context_bits and literal_pos_bits
 330  *
 331  * literal_context_bits + literal_pos_bits <= LZMA_LITERAL_BITS_MAX
 332  */
 333 #define LZMA_LITERAL_BITS_MAX 4
 334
 335
 336 /**
 337  * \brief       Table of presets for the LZMA filter
 338  *
 339  * lzma_preset_lzma[0] is the fastest and lzma_preset_lzma[8] is the slowest.
 340  * These presets match the switches -1 .. -9 of the lzma command line tool
 341  *
 342  * The preset values are subject to changes between liblzma versions.
 343  *
 344  * This variable is available only if LZMA encoder has been enabled.
 345  */
 346 extern const lzma_options_lzma lzma_preset_lzma[9];