OLD | NEW |
1 /** | 1 /** |
2 * \file lzma/container.h | 2 * \file lzma/container.h |
3 * \brief File formats | 3 * \brief File formats |
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 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
48 | 48 |
49 /** | 49 /** |
50 * \brief Extreme compression preset | 50 * \brief Extreme compression preset |
51 * | 51 * |
52 * This flag modifies the preset to make the encoding significantly slower | 52 * This flag modifies the preset to make the encoding significantly slower |
53 * while improving the compression ratio only marginally. This is useful | 53 * while improving the compression ratio only marginally. This is useful |
54 * when you don't mind wasting time to get as small result as possible. | 54 * when you don't mind wasting time to get as small result as possible. |
55 * | 55 * |
56 * This flag doesn't affect the memory usage requirements of the decoder (at | 56 * This flag doesn't affect the memory usage requirements of the decoder (at |
57 * least not significantly). The memory usage of the encoder may be increased | 57 * least not significantly). The memory usage of the encoder may be increased |
58 * a little but only at the lowest preset levels (0-2). | 58 * a little but only at the lowest preset levels (0-3). |
59 */ | 59 */ |
60 #define LZMA_PRESET_EXTREME (UINT32_C(1) << 31) | 60 #define LZMA_PRESET_EXTREME (UINT32_C(1) << 31) |
61 | 61 |
62 | 62 |
63 /** | 63 /** |
64 * \brief Calculate rough memory usage of easy encoder | 64 * \brief Calculate approximate memory usage of easy encoder |
65 * | 65 * |
66 * This function is a wrapper for lzma_raw_encoder_memusage(). | 66 * This function is a wrapper for lzma_raw_encoder_memusage(). |
67 * | 67 * |
68 * \param preset Compression preset (level and possible flags) | 68 * \param preset Compression preset (level and possible flags) |
| 69 * |
| 70 * \return Number of bytes of memory required for the given |
| 71 * preset when encoding. If an error occurs, for example |
| 72 * due to unsupported preset, UINT64_MAX is returned. |
69 */ | 73 */ |
70 extern LZMA_API(uint64_t) lzma_easy_encoder_memusage(uint32_t preset) | 74 extern LZMA_API(uint64_t) lzma_easy_encoder_memusage(uint32_t preset) |
71 lzma_nothrow lzma_attr_pure; | 75 lzma_nothrow lzma_attr_pure; |
72 | 76 |
73 | 77 |
74 /** | 78 /** |
75 * \brief Calculate rough decoder memory usage of a preset | 79 * \brief Calculate approximate decoder memory usage of a preset |
76 * | 80 * |
77 * This function is a wrapper for lzma_raw_decoder_memusage(). | 81 * This function is a wrapper for lzma_raw_decoder_memusage(). |
78 * | 82 * |
79 * \param preset Compression preset (level and possible flags) | 83 * \param preset Compression preset (level and possible flags) |
| 84 * |
| 85 * \return Number of bytes of memory required to decompress a file |
| 86 * that was compressed using the given preset. If an error |
| 87 * occurs, for example due to unsupported preset, UINT64_MAX |
| 88 * is returned. |
80 */ | 89 */ |
81 extern LZMA_API(uint64_t) lzma_easy_decoder_memusage(uint32_t preset) | 90 extern LZMA_API(uint64_t) lzma_easy_decoder_memusage(uint32_t preset) |
82 lzma_nothrow lzma_attr_pure; | 91 lzma_nothrow lzma_attr_pure; |
83 | 92 |
84 | 93 |
85 /** | 94 /** |
86 * \brief Initialize .xz Stream encoder using a preset number | 95 * \brief Initialize .xz Stream encoder using a preset number |
87 * | 96 * |
88 * This function is intended for those who just want to use the basic features | 97 * This function is intended for those who just want to use the basic features |
89 * if liblzma (that is, most developers out there). | 98 * if liblzma (that is, most developers out there). |
90 * | 99 * |
91 * \param strm Pointer to lzma_stream that is at least initialized | 100 * \param strm Pointer to lzma_stream that is at least initialized |
92 * with LZMA_STREAM_INIT. | 101 * with LZMA_STREAM_INIT. |
93 * \param preset Compression preset to use. A preset consist of level | 102 * \param preset Compression preset to use. A preset consist of level |
94 * number and zero or more flags. Usually flags aren't | 103 * number and zero or more flags. Usually flags aren't |
95 * used, so preset is simply a number [0, 9] which match | 104 * used, so preset is simply a number [0, 9] which match |
96 * the options -0 .. -9 of the xz command line tool. | 105 * the options -0 ... -9 of the xz command line tool. |
97 * Additional flags can be be set using bitwise-or with | 106 * Additional flags can be be set using bitwise-or with |
98 * the preset level number, e.g. 6 | LZMA_PRESET_EXTREME. | 107 * the preset level number, e.g. 6 | LZMA_PRESET_EXTREME. |
99 * \param check Integrity check type to use. See check.h for available | 108 * \param check Integrity check type to use. See check.h for available |
100 * checks. If you are unsure, use LZMA_CHECK_CRC32. | 109 * checks. The xz command line tool defaults to |
| 110 * LZMA_CHECK_CRC64, which is a good choice if you are |
| 111 * unsure. LZMA_CHECK_CRC32 is good too as long as the |
| 112 * uncompressed file is not many gigabytes. |
101 * | 113 * |
102 * \return - LZMA_OK: Initialization succeeded. Use lzma_code() to | 114 * \return - LZMA_OK: Initialization succeeded. Use lzma_code() to |
103 * encode your data. | 115 * encode your data. |
104 * - LZMA_MEM_ERROR: Memory allocation failed. | 116 * - LZMA_MEM_ERROR: Memory allocation failed. |
105 * - LZMA_OPTIONS_ERROR: The given compression level is not | 117 * - LZMA_OPTIONS_ERROR: The given compression preset is not |
106 * supported by this build of liblzma. | 118 * supported by this build of liblzma. |
107 * - LZMA_UNSUPPORTED_CHECK: The given check type is not | 119 * - LZMA_UNSUPPORTED_CHECK: The given check type is not |
108 * supported by this liblzma build. | 120 * supported by this liblzma build. |
109 * - LZMA_PROG_ERROR: One or more of the parameters have values | 121 * - LZMA_PROG_ERROR: One or more of the parameters have values |
110 * that will never be valid. For example, strm == NULL. | 122 * that will never be valid. For example, strm == NULL. |
111 * | 123 * |
112 * If initialization fails (return value is not LZMA_OK), all the memory | 124 * If initialization fails (return value is not LZMA_OK), all the memory |
113 * allocated for *strm by liblzma is always freed. Thus, there is no need | 125 * allocated for *strm by liblzma is always freed. Thus, there is no need |
114 * to call lzma_end() after failed initialization. | 126 * to call lzma_end() after failed initialization. |
115 * | 127 * |
(...skipping 22 matching lines...) Expand all Loading... |
138 * \param in Beginning of the input buffer | 150 * \param in Beginning of the input buffer |
139 * \param in_size Size of the input buffer | 151 * \param in_size Size of the input buffer |
140 * \param out Beginning of the output buffer | 152 * \param out Beginning of the output buffer |
141 * \param out_pos The next byte will be written to out[*out_pos]. | 153 * \param out_pos The next byte will be written to out[*out_pos]. |
142 * *out_pos is updated only if encoding succeeds. | 154 * *out_pos is updated only if encoding succeeds. |
143 * \param out_size Size of the out buffer; the first byte into | 155 * \param out_size Size of the out buffer; the first byte into |
144 * which no data is written to is out[out_size]. | 156 * which no data is written to is out[out_size]. |
145 * | 157 * |
146 * \return - LZMA_OK: Encoding was successful. | 158 * \return - LZMA_OK: Encoding was successful. |
147 * - LZMA_BUF_ERROR: Not enough output buffer space. | 159 * - LZMA_BUF_ERROR: Not enough output buffer space. |
| 160 * - LZMA_UNSUPPORTED_CHECK |
148 * - LZMA_OPTIONS_ERROR | 161 * - LZMA_OPTIONS_ERROR |
149 * - LZMA_MEM_ERROR | 162 * - LZMA_MEM_ERROR |
150 * - LZMA_DATA_ERROR | 163 * - LZMA_DATA_ERROR |
151 * - LZMA_PROG_ERROR | 164 * - LZMA_PROG_ERROR |
152 */ | 165 */ |
153 extern LZMA_API(lzma_ret) lzma_easy_buffer_encode( | 166 extern LZMA_API(lzma_ret) lzma_easy_buffer_encode( |
154 uint32_t preset, lzma_check check, | 167 uint32_t preset, lzma_check check, |
155 lzma_allocator *allocator, const uint8_t *in, size_t in_size, | 168 lzma_allocator *allocator, const uint8_t *in, size_t in_size, |
156 uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow; | 169 uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow; |
157 | 170 |
158 | 171 |
159 /** | 172 /** |
160 * \brief Initialize .xz Stream encoder using a custom filter chain | 173 * \brief Initialize .xz Stream encoder using a custom filter chain |
161 * | 174 * |
162 * \param strm Pointer to properly prepared lzma_stream | 175 * \param strm Pointer to properly prepared lzma_stream |
163 * \param filters Array of filters. This must be terminated with | 176 * \param filters Array of filters. This must be terminated with |
164 * filters[n].id = LZMA_VLI_UNKNOWN. See filter.h for | 177 * filters[n].id = LZMA_VLI_UNKNOWN. See filter.h for |
165 * more information. | 178 * more information. |
166 * \param check Type of the integrity check to calculate from | 179 * \param check Type of the integrity check to calculate from |
167 * uncompressed data. | 180 * uncompressed data. |
168 * | 181 * |
169 * \return - LZMA_OK: Initialization was successful. | 182 * \return - LZMA_OK: Initialization was successful. |
170 * - LZMA_MEM_ERROR | 183 * - LZMA_MEM_ERROR |
| 184 * - LZMA_UNSUPPORTED_CHECK |
171 * - LZMA_OPTIONS_ERROR | 185 * - LZMA_OPTIONS_ERROR |
172 * - LZMA_PROG_ERROR | 186 * - LZMA_PROG_ERROR |
173 */ | 187 */ |
174 extern LZMA_API(lzma_ret) lzma_stream_encoder(lzma_stream *strm, | 188 extern LZMA_API(lzma_ret) lzma_stream_encoder(lzma_stream *strm, |
175 const lzma_filter *filters, lzma_check check) | 189 const lzma_filter *filters, lzma_check check) |
176 lzma_nothrow lzma_attr_warn_unused_result; | 190 lzma_nothrow lzma_attr_warn_unused_result; |
177 | 191 |
178 | 192 |
179 /** | 193 /** |
180 * \brief Initialize .lzma encoder (legacy file format) | 194 * \brief Initialize .lzma encoder (legacy file format) |
(...skipping 59 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
240 * \param in Beginning of the input buffer | 254 * \param in Beginning of the input buffer |
241 * \param in_size Size of the input buffer | 255 * \param in_size Size of the input buffer |
242 * \param out Beginning of the output buffer | 256 * \param out Beginning of the output buffer |
243 * \param out_pos The next byte will be written to out[*out_pos]. | 257 * \param out_pos The next byte will be written to out[*out_pos]. |
244 * *out_pos is updated only if encoding succeeds. | 258 * *out_pos is updated only if encoding succeeds. |
245 * \param out_size Size of the out buffer; the first byte into | 259 * \param out_size Size of the out buffer; the first byte into |
246 * which no data is written to is out[out_size]. | 260 * which no data is written to is out[out_size]. |
247 * | 261 * |
248 * \return - LZMA_OK: Encoding was successful. | 262 * \return - LZMA_OK: Encoding was successful. |
249 * - LZMA_BUF_ERROR: Not enough output buffer space. | 263 * - LZMA_BUF_ERROR: Not enough output buffer space. |
| 264 * - LZMA_UNSUPPORTED_CHECK |
250 * - LZMA_OPTIONS_ERROR | 265 * - LZMA_OPTIONS_ERROR |
251 * - LZMA_MEM_ERROR | 266 * - LZMA_MEM_ERROR |
252 * - LZMA_DATA_ERROR | 267 * - LZMA_DATA_ERROR |
253 * - LZMA_PROG_ERROR | 268 * - LZMA_PROG_ERROR |
254 */ | 269 */ |
255 extern LZMA_API(lzma_ret) lzma_stream_buffer_encode( | 270 extern LZMA_API(lzma_ret) lzma_stream_buffer_encode( |
256 lzma_filter *filters, lzma_check check, | 271 lzma_filter *filters, lzma_check check, |
257 lzma_allocator *allocator, const uint8_t *in, size_t in_size, | 272 lzma_allocator *allocator, const uint8_t *in, size_t in_size, |
258 uint8_t *out, size_t *out_pos, size_t out_size) | 273 uint8_t *out, size_t *out_pos, size_t out_size) |
259 lzma_nothrow lzma_attr_warn_unused_result; | 274 lzma_nothrow lzma_attr_warn_unused_result; |
(...skipping 43 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
303 * If LZMA_CONCATENATED is not used, the decoders still accept LZMA_FINISH | 318 * If LZMA_CONCATENATED is not used, the decoders still accept LZMA_FINISH |
304 * as `action' for lzma_code(), but the usage of LZMA_FINISH isn't required. | 319 * as `action' for lzma_code(), but the usage of LZMA_FINISH isn't required. |
305 */ | 320 */ |
306 #define LZMA_CONCATENATED UINT32_C(0x08) | 321 #define LZMA_CONCATENATED UINT32_C(0x08) |
307 | 322 |
308 | 323 |
309 /** | 324 /** |
310 * \brief Initialize .xz Stream decoder | 325 * \brief Initialize .xz Stream decoder |
311 * | 326 * |
312 * \param strm Pointer to properly prepared lzma_stream | 327 * \param strm Pointer to properly prepared lzma_stream |
313 * \param memlimit Rough memory usage limit as bytes | 328 * \param memlimit Memory usage limit as bytes. Use UINT64_MAX |
| 329 * to effectively disable the limiter. |
314 * \param flags Bitwise-or of zero or more of the decoder flags: | 330 * \param flags Bitwise-or of zero or more of the decoder flags: |
315 * LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, | 331 * LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, |
316 * LZMA_TELL_ANY_CHECK, LZMA_CONCATENATED | 332 * LZMA_TELL_ANY_CHECK, LZMA_CONCATENATED |
317 * | 333 * |
318 * \return - LZMA_OK: Initialization was successful. | 334 * \return - LZMA_OK: Initialization was successful. |
319 * - LZMA_MEM_ERROR: Cannot allocate memory. | 335 * - LZMA_MEM_ERROR: Cannot allocate memory. |
320 * - LZMA_OPTIONS_ERROR: Unsupported flags | 336 * - LZMA_OPTIONS_ERROR: Unsupported flags |
| 337 * - LZMA_PROG_ERROR |
321 */ | 338 */ |
322 extern LZMA_API(lzma_ret) lzma_stream_decoder( | 339 extern LZMA_API(lzma_ret) lzma_stream_decoder( |
323 lzma_stream *strm, uint64_t memlimit, uint32_t flags) | 340 lzma_stream *strm, uint64_t memlimit, uint32_t flags) |
324 lzma_nothrow lzma_attr_warn_unused_result; | 341 lzma_nothrow lzma_attr_warn_unused_result; |
325 | 342 |
326 | 343 |
327 /** | 344 /** |
328 * \brief Decode .xz Streams and .lzma files with autodetection | 345 * \brief Decode .xz Streams and .lzma files with autodetection |
329 * | 346 * |
330 * This decoder autodetects between the .xz and .lzma file formats, and | 347 * This decoder autodetects between the .xz and .lzma file formats, and |
331 * calls lzma_stream_decoder() or lzma_alone_decoder() once the type | 348 * calls lzma_stream_decoder() or lzma_alone_decoder() once the type |
332 * of the input file has been detected. | 349 * of the input file has been detected. |
333 * | 350 * |
334 * \param strm Pointer to properly prepared lzma_stream | 351 * \param strm Pointer to properly prepared lzma_stream |
335 * \param memlimit Rough memory usage limit as bytes | 352 * \param memlimit Memory usage limit as bytes. Use UINT64_MAX |
| 353 * to effectively disable the limiter. |
336 * \param flags Bitwise-or of flags, or zero for no flags. | 354 * \param flags Bitwise-or of flags, or zero for no flags. |
337 * | 355 * |
338 * \return - LZMA_OK: Initialization was successful. | 356 * \return - LZMA_OK: Initialization was successful. |
339 * - LZMA_MEM_ERROR: Cannot allocate memory. | 357 * - LZMA_MEM_ERROR: Cannot allocate memory. |
340 * - LZMA_OPTIONS_ERROR: Unsupported flags | 358 * - LZMA_OPTIONS_ERROR: Unsupported flags |
| 359 * - LZMA_PROG_ERROR |
341 */ | 360 */ |
342 extern LZMA_API(lzma_ret) lzma_auto_decoder( | 361 extern LZMA_API(lzma_ret) lzma_auto_decoder( |
343 lzma_stream *strm, uint64_t memlimit, uint32_t flags) | 362 lzma_stream *strm, uint64_t memlimit, uint32_t flags) |
344 lzma_nothrow lzma_attr_warn_unused_result; | 363 lzma_nothrow lzma_attr_warn_unused_result; |
345 | 364 |
346 | 365 |
347 /** | 366 /** |
348 * \brief Initialize .lzma decoder (legacy file format) | 367 * \brief Initialize .lzma decoder (legacy file format) |
349 * | 368 * |
350 * Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. | 369 * Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. |
351 * There is no need to use LZMA_FINISH, but allowing it may simplify | 370 * There is no need to use LZMA_FINISH, but allowing it may simplify |
352 * certain types of applications. | 371 * certain types of applications. |
353 * | 372 * |
354 * \return - LZMA_OK | 373 * \return - LZMA_OK |
355 * - LZMA_MEM_ERROR | 374 * - LZMA_MEM_ERROR |
| 375 * - LZMA_PROG_ERROR |
356 */ | 376 */ |
357 extern LZMA_API(lzma_ret) lzma_alone_decoder( | 377 extern LZMA_API(lzma_ret) lzma_alone_decoder( |
358 lzma_stream *strm, uint64_t memlimit) | 378 lzma_stream *strm, uint64_t memlimit) |
359 lzma_nothrow lzma_attr_warn_unused_result; | 379 lzma_nothrow lzma_attr_warn_unused_result; |
360 | 380 |
361 | 381 |
362 /** | 382 /** |
363 * \brief Single-call .xz Stream decoder | 383 * \brief Single-call .xz Stream decoder |
364 * | 384 * |
365 * \param memlimit Pointer to how much memory the decoder is allowed | 385 * \param memlimit Pointer to how much memory the decoder is allowed |
366 * to allocate. The value pointed by this pointer is | 386 * to allocate. The value pointed by this pointer is |
367 * modified if and only if LZMA_MEMLIMIT_ERROR is | 387 * modified if and only if LZMA_MEMLIMIT_ERROR is |
368 * returned. | 388 * returned. |
369 * \param flags Bitwise-or of zero or more of the decoder flags: | 389 * \param flags Bitwise-or of zero or more of the decoder flags: |
370 * LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, | 390 * LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, |
371 * LZMA_CONCATENATED. Note that LZMA_TELL_ANY_CHECK | 391 * LZMA_CONCATENATED. Note that LZMA_TELL_ANY_CHECK |
372 * is not allowed and will return LZMA_PROG_ERROR. | 392 * is not allowed and will return LZMA_PROG_ERROR. |
373 * \param allocator lzma_allocator for custom allocator functions. | 393 * \param allocator lzma_allocator for custom allocator functions. |
374 * Set to NULL to use malloc() and free(). | 394 * Set to NULL to use malloc() and free(). |
375 * \param in Beginning of the input buffer | 395 * \param in Beginning of the input buffer |
376 * \param in_pos The next byte will be read from in[*in_pos]. | 396 * \param in_pos The next byte will be read from in[*in_pos]. |
377 * *in_pos is updated only if decoding succeeds. | 397 * *in_pos is updated only if decoding succeeds. |
378 * \param in_size Size of the input buffer; the first byte that | 398 * \param in_size Size of the input buffer; the first byte that |
379 * won't be read is in[in_size]. | 399 * won't be read is in[in_size]. |
380 * \param out Beginning of the output buffer | 400 * \param out Beginning of the output buffer |
381 * \param out_pos The next byte will be written to out[*out_pos]. | 401 * \param out_pos The next byte will be written to out[*out_pos]. |
382 * *out_pos is updated only if encoding succeeds. | 402 * *out_pos is updated only if decoding succeeds. |
383 * \param out_size Size of the out buffer; the first byte into | 403 * \param out_size Size of the out buffer; the first byte into |
384 * which no data is written to is out[out_size]. | 404 * which no data is written to is out[out_size]. |
385 * | 405 * |
386 * \return - LZMA_OK: Decoding was successful. | 406 * \return - LZMA_OK: Decoding was successful. |
387 * - LZMA_FORMAT_ERROR | 407 * - LZMA_FORMAT_ERROR |
388 * - LZMA_OPTIONS_ERROR | 408 * - LZMA_OPTIONS_ERROR |
389 * - LZMA_DATA_ERROR | 409 * - LZMA_DATA_ERROR |
390 * - LZMA_NO_CHECK: This can be returned only if using | 410 * - LZMA_NO_CHECK: This can be returned only if using |
391 * the LZMA_TELL_NO_CHECK flag. | 411 * the LZMA_TELL_NO_CHECK flag. |
392 * - LZMA_UNSUPPORTED_CHECK: This can be returned only if using | 412 * - LZMA_UNSUPPORTED_CHECK: This can be returned only if using |
393 * the LZMA_TELL_UNSUPPORTED_CHECK flag. | 413 * the LZMA_TELL_UNSUPPORTED_CHECK flag. |
394 * - LZMA_MEM_ERROR | 414 * - LZMA_MEM_ERROR |
395 * - LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. | 415 * - LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. |
396 * The minimum required memlimit value was stored to *memlimit. | 416 * The minimum required memlimit value was stored to *memlimit. |
397 * - LZMA_BUF_ERROR: Output buffer was too small. | 417 * - LZMA_BUF_ERROR: Output buffer was too small. |
398 * - LZMA_PROG_ERROR | 418 * - LZMA_PROG_ERROR |
399 */ | 419 */ |
400 extern LZMA_API(lzma_ret) lzma_stream_buffer_decode( | 420 extern LZMA_API(lzma_ret) lzma_stream_buffer_decode( |
401 uint64_t *memlimit, uint32_t flags, lzma_allocator *allocator, | 421 uint64_t *memlimit, uint32_t flags, lzma_allocator *allocator, |
402 const uint8_t *in, size_t *in_pos, size_t in_size, | 422 const uint8_t *in, size_t *in_pos, size_t in_size, |
403 uint8_t *out, size_t *out_pos, size_t out_size) | 423 uint8_t *out, size_t *out_pos, size_t out_size) |
404 lzma_nothrow lzma_attr_warn_unused_result; | 424 lzma_nothrow lzma_attr_warn_unused_result; |
OLD | NEW |