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