OLD | NEW |
1 /** | 1 /** |
2 * \file lzma/lzma.h | 2 * \file lzma/lzma.h |
3 * \brief LZMA1 and LZMA2 filters | 3 * \brief LZMA1 and LZMA2 filters |
4 */ | 4 */ |
5 | 5 |
6 /* | 6 /* |
7 * Author: Lasse Collin | 7 * Author: Lasse Collin |
8 * | 8 * |
9 * This file has been put into the public domain. | 9 * This file has been put into the public domain. |
10 * You can do whatever you want with this file. | 10 * You can do whatever you want with this file. |
(...skipping 28 matching lines...) Expand all Loading... |
39 */ | 39 */ |
40 #define LZMA_FILTER_LZMA2 LZMA_VLI_C(0x21) | 40 #define LZMA_FILTER_LZMA2 LZMA_VLI_C(0x21) |
41 | 41 |
42 | 42 |
43 /** | 43 /** |
44 * \brief Match finders | 44 * \brief Match finders |
45 * | 45 * |
46 * Match finder has major effect on both speed and compression ratio. | 46 * Match finder has major effect on both speed and compression ratio. |
47 * Usually hash chains are faster than binary trees. | 47 * Usually hash chains are faster than binary trees. |
48 * | 48 * |
| 49 * If you will use LZMA_SYNC_FLUSH often, the hash chains may be a better |
| 50 * choice, because binary trees get much higher compression ratio penalty |
| 51 * with LZMA_SYNC_FLUSH. |
| 52 * |
49 * The memory usage formulas are only rough estimates, which are closest to | 53 * The memory usage formulas are only rough estimates, which are closest to |
50 * reality when dict_size is a power of two. The formulas are more complex | 54 * reality when dict_size is a power of two. The formulas are more complex |
51 * in reality, and can also change a little between liblzma versions. Use | 55 * in reality, and can also change a little between liblzma versions. Use |
52 * lzma_memusage_encoder() to get more accurate estimate of memory usage. | 56 * lzma_raw_encoder_memusage() to get more accurate estimate of memory usage. |
53 */ | 57 */ |
54 typedef enum { | 58 typedef enum { |
55 LZMA_MF_HC3 = 0x03, | 59 LZMA_MF_HC3 = 0x03, |
56 /**< | 60 /**< |
57 * \brief Hash Chain with 2- and 3-byte hashing | 61 * \brief Hash Chain with 2- and 3-byte hashing |
58 * | 62 * |
59 * Minimum nice_len: 3 | 63 * Minimum nice_len: 3 |
60 * | 64 * |
61 * Memory usage: | 65 * Memory usage: |
62 * - dict_size <= 16 MiB: dict_size * 7.5 | 66 * - dict_size <= 16 MiB: dict_size * 7.5 |
63 * - dict_size > 16 MiB: dict_size * 5.5 + 64 MiB | 67 * - dict_size > 16 MiB: dict_size * 5.5 + 64 MiB |
64 */ | 68 */ |
65 | 69 |
66 LZMA_MF_HC4 = 0x04, | 70 LZMA_MF_HC4 = 0x04, |
67 /**< | 71 /**< |
68 * \brief Hash Chain with 2-, 3-, and 4-byte hashing | 72 * \brief Hash Chain with 2-, 3-, and 4-byte hashing |
69 * | 73 * |
70 * Minimum nice_len: 4 | 74 * Minimum nice_len: 4 |
71 * | 75 * |
72 » » * Memory usage: dict_size * 7.5 | 76 » » * Memory usage: |
| 77 » » * - dict_size <= 32 MiB: dict_size * 7.5 |
| 78 » » * - dict_size > 32 MiB: dict_size * 6.5 |
73 */ | 79 */ |
74 | 80 |
75 LZMA_MF_BT2 = 0x12, | 81 LZMA_MF_BT2 = 0x12, |
76 /**< | 82 /**< |
77 * \brief Binary Tree with 2-byte hashing | 83 * \brief Binary Tree with 2-byte hashing |
78 * | 84 * |
79 * Minimum nice_len: 2 | 85 * Minimum nice_len: 2 |
80 * | 86 * |
81 * Memory usage: dict_size * 9.5 | 87 * Memory usage: dict_size * 9.5 |
82 */ | 88 */ |
83 | 89 |
84 LZMA_MF_BT3 = 0x13, | 90 LZMA_MF_BT3 = 0x13, |
85 /**< | 91 /**< |
86 * \brief Binary Tree with 2- and 3-byte hashing | 92 * \brief Binary Tree with 2- and 3-byte hashing |
87 * | 93 * |
88 * Minimum nice_len: 3 | 94 * Minimum nice_len: 3 |
89 * | 95 * |
90 * Memory usage: | 96 * Memory usage: |
91 * - dict_size <= 16 MiB: dict_size * 11.5 | 97 * - dict_size <= 16 MiB: dict_size * 11.5 |
92 * - dict_size > 16 MiB: dict_size * 9.5 + 64 MiB | 98 * - dict_size > 16 MiB: dict_size * 9.5 + 64 MiB |
93 */ | 99 */ |
94 | 100 |
95 LZMA_MF_BT4 = 0x14 | 101 LZMA_MF_BT4 = 0x14 |
96 /**< | 102 /**< |
97 * \brief Binary Tree with 2-, 3-, and 4-byte hashing | 103 * \brief Binary Tree with 2-, 3-, and 4-byte hashing |
98 * | 104 * |
99 * Minimum nice_len: 4 | 105 * Minimum nice_len: 4 |
100 * | 106 * |
101 » » * Memory usage: dict_size * 11.5 | 107 » » * Memory usage: |
| 108 » » * - dict_size <= 32 MiB: dict_size * 11.5 |
| 109 » » * - dict_size > 32 MiB: dict_size * 10.5 |
102 */ | 110 */ |
103 } lzma_match_finder; | 111 } lzma_match_finder; |
104 | 112 |
105 | 113 |
106 /** | 114 /** |
107 * \brief Test if given match finder is supported | 115 * \brief Test if given match finder is supported |
108 * | 116 * |
109 * Return true if the given match finder is supported by this liblzma build. | 117 * Return true if the given match finder is supported by this liblzma build. |
110 * Otherwise false is returned. It is safe to call this with a value that | 118 * Otherwise false is returned. It is safe to call this with a value that |
111 * isn't listed in lzma_match_finder enumeration; the return value will be | 119 * isn't listed in lzma_match_finder enumeration; the return value will be |
(...skipping 50 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
162 extern LZMA_API(lzma_bool) lzma_mode_is_supported(lzma_mode mode) | 170 extern LZMA_API(lzma_bool) lzma_mode_is_supported(lzma_mode mode) |
163 lzma_nothrow lzma_attr_const; | 171 lzma_nothrow lzma_attr_const; |
164 | 172 |
165 | 173 |
166 /** | 174 /** |
167 * \brief Options specific to the LZMA1 and LZMA2 filters | 175 * \brief Options specific to the LZMA1 and LZMA2 filters |
168 * | 176 * |
169 * Since LZMA1 and LZMA2 share most of the code, it's simplest to share | 177 * Since LZMA1 and LZMA2 share most of the code, it's simplest to share |
170 * the options structure too. For encoding, all but the reserved variables | 178 * the options structure too. For encoding, all but the reserved variables |
171 * need to be initialized unless specifically mentioned otherwise. | 179 * need to be initialized unless specifically mentioned otherwise. |
| 180 * lzma_lzma_preset() can be used to get a good starting point. |
172 * | 181 * |
173 * For raw decoding, both LZMA1 and LZMA2 need dict_size, preset_dict, and | 182 * For raw decoding, both LZMA1 and LZMA2 need dict_size, preset_dict, and |
174 * preset_dict_size (if preset_dict != NULL). LZMA1 needs also lc, lp, and pb. | 183 * preset_dict_size (if preset_dict != NULL). LZMA1 needs also lc, lp, and pb. |
175 */ | 184 */ |
176 typedef struct { | 185 typedef struct { |
177 /** | 186 /** |
178 * \brief Dictionary size in bytes | 187 * \brief Dictionary size in bytes |
179 * | 188 * |
180 * Dictionary size indicates how many bytes of the recently processed | 189 * Dictionary size indicates how many bytes of the recently processed |
181 * uncompressed data is kept in memory. One method to reduce size of | 190 * uncompressed data is kept in memory. One method to reduce size of |
(...skipping 62 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
244 */ | 253 */ |
245 uint32_t preset_dict_size; | 254 uint32_t preset_dict_size; |
246 | 255 |
247 /** | 256 /** |
248 * \brief Number of literal context bits | 257 * \brief Number of literal context bits |
249 * | 258 * |
250 * How many of the highest bits of the previous uncompressed | 259 * How many of the highest bits of the previous uncompressed |
251 * eight-bit byte (also known as `literal') are taken into | 260 * eight-bit byte (also known as `literal') are taken into |
252 * account when predicting the bits of the next literal. | 261 * account when predicting the bits of the next literal. |
253 * | 262 * |
254 » * \todo Example | 263 » * E.g. in typical English text, an upper-case letter is |
| 264 » * often followed by a lower-case letter, and a lower-case |
| 265 » * letter is usually followed by another lower-case letter. |
| 266 » * In the US-ASCII character set, the highest three bits are 010 |
| 267 » * for upper-case letters and 011 for lower-case letters. |
| 268 » * When lc is at least 3, the literal coding can take advantage of |
| 269 » * this property in the uncompressed data. |
255 * | 270 * |
256 * There is a limit that applies to literal context bits and literal | 271 * There is a limit that applies to literal context bits and literal |
257 * position bits together: lc + lp <= 4. Without this limit the | 272 * position bits together: lc + lp <= 4. Without this limit the |
258 * decoding could become very slow, which could have security related | 273 * decoding could become very slow, which could have security related |
259 * results in some cases like email servers doing virus scanning. | 274 * results in some cases like email servers doing virus scanning. |
260 * This limit also simplifies the internal implementation in liblzma. | 275 * This limit also simplifies the internal implementation in liblzma. |
261 * | 276 * |
262 * There may be LZMA1 streams that have lc + lp > 4 (maximum possible | 277 * There may be LZMA1 streams that have lc + lp > 4 (maximum possible |
263 * lc would be 8). It is not possible to decode such streams with | 278 * lc would be 8). It is not possible to decode such streams with |
264 * liblzma. | 279 * liblzma. |
265 */ | 280 */ |
266 uint32_t lc; | 281 uint32_t lc; |
267 # define LZMA_LCLP_MIN 0 | 282 # define LZMA_LCLP_MIN 0 |
268 # define LZMA_LCLP_MAX 4 | 283 # define LZMA_LCLP_MAX 4 |
269 # define LZMA_LC_DEFAULT 3 | 284 # define LZMA_LC_DEFAULT 3 |
270 | 285 |
271 /** | 286 /** |
272 * \brief Number of literal position bits | 287 * \brief Number of literal position bits |
273 * | 288 * |
274 » * How many of the lowest bits of the current position (number | 289 » * lp affects what kind of alignment in the uncompressed data is |
275 » * of bytes from the beginning of the uncompressed data) in the | 290 » * assumed when encoding literals. A literal is a single 8-bit byte. |
276 » * uncompressed data is taken into account when predicting the | 291 » * See pb below for more information about alignment. |
277 » * bits of the next literal (a single eight-bit byte). | |
278 » * | |
279 » * \todo Example | |
280 */ | 292 */ |
281 uint32_t lp; | 293 uint32_t lp; |
282 # define LZMA_LP_DEFAULT 0 | 294 # define LZMA_LP_DEFAULT 0 |
283 | 295 |
284 /** | 296 /** |
285 * \brief Number of position bits | 297 * \brief Number of position bits |
286 * | 298 * |
287 » * How many of the lowest bits of the current position in the | 299 » * pb affects what kind of alignment in the uncompressed data is |
288 » * uncompressed data is taken into account when estimating | 300 » * assumed in general. The default means four-byte alignment |
289 » * probabilities of matches. A match is a sequence of bytes for | 301 » * (2^ pb =2^2=4), which is often a good choice when there's |
290 » * which a matching sequence is found from the dictionary and | 302 » * no better guess. |
291 » * thus can be stored as distance-length pair. | |
292 * | 303 * |
293 » * Example: If most of the matches occur at byte positions of | 304 » * When the aligment is known, setting pb accordingly may reduce |
294 » * 8 * n + 3, that is, 3, 11, 19, ... set pb to 3, because 2**3 == 8. | 305 » * the file size a little. E.g. with text files having one-byte |
| 306 » * alignment (US-ASCII, ISO-8859-*, UTF-8), setting pb=0 can |
| 307 » * improve compression slightly. For UTF-16 text, pb=1 is a good |
| 308 » * choice. If the alignment is an odd number like 3 bytes, pb=0 |
| 309 » * might be the best choice. |
| 310 » * |
| 311 » * Even though the assumed alignment can be adjusted with pb and |
| 312 » * lp, LZMA1 and LZMA2 still slightly favor 16-byte alignment. |
| 313 » * It might be worth taking into account when designing file formats |
| 314 » * that are likely to be often compressed with LZMA1 or LZMA2. |
295 */ | 315 */ |
296 uint32_t pb; | 316 uint32_t pb; |
297 # define LZMA_PB_MIN 0 | 317 # define LZMA_PB_MIN 0 |
298 # define LZMA_PB_MAX 4 | 318 # define LZMA_PB_MAX 4 |
299 # define LZMA_PB_DEFAULT 2 | 319 # define LZMA_PB_DEFAULT 2 |
300 | 320 |
301 /** Compression mode */ | 321 /** Compression mode */ |
302 lzma_mode mode; | 322 lzma_mode mode; |
303 | 323 |
304 /** | 324 /** |
(...skipping 30 matching lines...) Expand all Loading... |
335 * been checked; or | 355 * been checked; or |
336 * - maximum search depth is reached. | 356 * - maximum search depth is reached. |
337 * | 357 * |
338 * Maximum search depth is needed to prevent the match finder from | 358 * Maximum search depth is needed to prevent the match finder from |
339 * wasting too much time in case there are lots of short match | 359 * wasting too much time in case there are lots of short match |
340 * candidates. On the other hand, stopping the search before all | 360 * candidates. On the other hand, stopping the search before all |
341 * candidates have been checked can reduce compression ratio. | 361 * candidates have been checked can reduce compression ratio. |
342 * | 362 * |
343 * Setting depth to zero tells liblzma to use an automatic default | 363 * Setting depth to zero tells liblzma to use an automatic default |
344 * value, that depends on the selected match finder and nice_len. | 364 * value, that depends on the selected match finder and nice_len. |
345 » * The default is in the range [10, 200] or so (it may vary between | 365 » * The default is in the range [4, 200] or so (it may vary between |
346 * liblzma versions). | 366 * liblzma versions). |
347 * | 367 * |
348 * Using a bigger depth value than the default can increase | 368 * Using a bigger depth value than the default can increase |
349 * compression ratio in some cases. There is no strict maximum value, | 369 * compression ratio in some cases. There is no strict maximum value, |
350 * but high values (thousands or millions) should be used with care: | 370 * but high values (thousands or millions) should be used with care: |
351 * the encoder could remain fast enough with typical input, but | 371 * the encoder could remain fast enough with typical input, but |
352 * malicious input could cause the match finder to slow down | 372 * malicious input could cause the match finder to slow down |
353 * dramatically, possibly creating a denial of service attack. | 373 * dramatically, possibly creating a denial of service attack. |
354 */ | 374 */ |
355 uint32_t depth; | 375 uint32_t depth; |
356 | 376 |
357 /* | 377 /* |
358 * Reserved space to allow possible future extensions without | 378 * Reserved space to allow possible future extensions without |
359 * breaking the ABI. You should not touch these, because the names | 379 * breaking the ABI. You should not touch these, because the names |
360 * of these variables may change. These are and will never be used | 380 * of these variables may change. These are and will never be used |
361 * with the currently supported options, so it is safe to leave these | 381 * with the currently supported options, so it is safe to leave these |
362 * uninitialized. | 382 * uninitialized. |
363 */ | 383 */ |
364 void *reserved_ptr1; | |
365 void *reserved_ptr2; | |
366 uint32_t reserved_int1; | 384 uint32_t reserved_int1; |
367 uint32_t reserved_int2; | 385 uint32_t reserved_int2; |
368 uint32_t reserved_int3; | 386 uint32_t reserved_int3; |
369 uint32_t reserved_int4; | 387 uint32_t reserved_int4; |
370 uint32_t reserved_int5; | 388 uint32_t reserved_int5; |
371 uint32_t reserved_int6; | 389 uint32_t reserved_int6; |
372 uint32_t reserved_int7; | 390 uint32_t reserved_int7; |
373 uint32_t reserved_int8; | 391 uint32_t reserved_int8; |
374 lzma_reserved_enum reserved_enum1; | 392 lzma_reserved_enum reserved_enum1; |
375 lzma_reserved_enum reserved_enum2; | 393 lzma_reserved_enum reserved_enum2; |
376 lzma_reserved_enum reserved_enum3; | 394 lzma_reserved_enum reserved_enum3; |
377 lzma_reserved_enum reserved_enum4; | 395 lzma_reserved_enum reserved_enum4; |
| 396 void *reserved_ptr1; |
| 397 void *reserved_ptr2; |
378 | 398 |
379 } lzma_options_lzma; | 399 } lzma_options_lzma; |
380 | 400 |
381 | 401 |
382 /** | 402 /** |
383 * \brief Set a compression preset to lzma_options_lzma structure | 403 * \brief Set a compression preset to lzma_options_lzma structure |
384 * | 404 * |
385 * 0 is the fastest and 9 is the slowest. These match the switches -0 .. -9 | 405 * 0 is the fastest and 9 is the slowest. These match the switches -0 .. -9 |
386 * of the xz command line tool. In addition, it is possible to bitwise-or | 406 * of the xz command line tool. In addition, it is possible to bitwise-or |
387 * flags to the preset. Currently only LZMA_PRESET_EXTREME is supported. | 407 * flags to the preset. Currently only LZMA_PRESET_EXTREME is supported. |
388 * The flags are defined in container.h, because the flags are used also | 408 * The flags are defined in container.h, because the flags are used also |
389 * with lzma_easy_encoder(). | 409 * with lzma_easy_encoder(). |
390 * | 410 * |
391 * The preset values are subject to changes between liblzma versions. | 411 * The preset values are subject to changes between liblzma versions. |
392 * | 412 * |
393 * This function is available only if LZMA1 or LZMA2 encoder has been enabled | 413 * This function is available only if LZMA1 or LZMA2 encoder has been enabled |
394 * when building liblzma. | 414 * when building liblzma. |
| 415 * |
| 416 * \return On success, false is returned. If the preset is not |
| 417 * supported, true is returned. |
395 */ | 418 */ |
396 extern LZMA_API(lzma_bool) lzma_lzma_preset( | 419 extern LZMA_API(lzma_bool) lzma_lzma_preset( |
397 lzma_options_lzma *options, uint32_t preset) lzma_nothrow; | 420 lzma_options_lzma *options, uint32_t preset) lzma_nothrow; |
OLD | NEW |