XZ Utils
5.2.9
|
File formats. More...
Data Structures | |
struct | lzma_mt |
Multithreading options. More... | |
Macros | |
#define | LZMA_PRESET_DEFAULT UINT32_C(6) |
Default compression preset. More... | |
#define | LZMA_PRESET_LEVEL_MASK UINT32_C(0x1F) |
Mask for preset level. More... | |
#define | LZMA_PRESET_EXTREME (UINT32_C(1) << 31) |
Extreme compression preset. More... | |
#define | LZMA_TELL_NO_CHECK UINT32_C(0x01) |
#define | LZMA_TELL_UNSUPPORTED_CHECK UINT32_C(0x02) |
#define | LZMA_TELL_ANY_CHECK UINT32_C(0x04) |
#define | LZMA_IGNORE_CHECK UINT32_C(0x10) |
#define | LZMA_CONCATENATED UINT32_C(0x08) |
Functions | |
uint64_t | lzma_easy_encoder_memusage (uint32_t preset) lzma_nothrow lzma_attr_pure |
Calculate approximate memory usage of easy encoder. More... | |
uint64_t | lzma_easy_decoder_memusage (uint32_t preset) lzma_nothrow lzma_attr_pure |
Calculate approximate decoder memory usage of a preset. More... | |
lzma_ret | lzma_easy_encoder (lzma_stream *strm, uint32_t preset, lzma_check check) lzma_nothrow lzma_attr_warn_unused_result |
Initialize .xz Stream encoder using a preset number. More... | |
lzma_ret | lzma_easy_buffer_encode (uint32_t preset, lzma_check check, const lzma_allocator *allocator, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow |
Single-call .xz Stream encoding using a preset number. More... | |
lzma_ret | lzma_stream_encoder (lzma_stream *strm, const lzma_filter *filters, lzma_check check) lzma_nothrow lzma_attr_warn_unused_result |
Initialize .xz Stream encoder using a custom filter chain. More... | |
uint64_t | lzma_stream_encoder_mt_memusage (const lzma_mt *options) lzma_nothrow lzma_attr_pure |
Calculate approximate memory usage of multithreaded .xz encoder. More... | |
lzma_ret | lzma_stream_encoder_mt (lzma_stream *strm, const lzma_mt *options) lzma_nothrow lzma_attr_warn_unused_result |
Initialize multithreaded .xz Stream encoder. More... | |
lzma_ret | lzma_alone_encoder (lzma_stream *strm, const lzma_options_lzma *options) lzma_nothrow lzma_attr_warn_unused_result |
Initialize .lzma encoder (legacy file format) More... | |
size_t | lzma_stream_buffer_bound (size_t uncompressed_size) lzma_nothrow |
Calculate output buffer size for single-call Stream encoder. More... | |
lzma_ret | lzma_stream_buffer_encode (lzma_filter *filters, lzma_check check, const lzma_allocator *allocator, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result |
Single-call .xz Stream encoder. More... | |
lzma_ret | lzma_stream_decoder (lzma_stream *strm, uint64_t memlimit, uint32_t flags) lzma_nothrow lzma_attr_warn_unused_result |
Initialize .xz Stream decoder. More... | |
lzma_ret | lzma_auto_decoder (lzma_stream *strm, uint64_t memlimit, uint32_t flags) lzma_nothrow lzma_attr_warn_unused_result |
Decode .xz Streams and .lzma files with autodetection. More... | |
lzma_ret | lzma_alone_decoder (lzma_stream *strm, uint64_t memlimit) lzma_nothrow lzma_attr_warn_unused_result |
Initialize .lzma decoder (legacy file format) More... | |
lzma_ret | lzma_stream_buffer_decode (uint64_t *memlimit, uint32_t flags, const lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result |
Single-call .xz Stream decoder. More... | |
File formats.
#define LZMA_PRESET_DEFAULT UINT32_C(6) |
Default compression preset.
It's not straightforward to recommend a default preset, because in some cases keeping the resource usage relatively low is more important that getting the maximum compression ratio.
#define LZMA_PRESET_LEVEL_MASK UINT32_C(0x1F) |
Mask for preset level.
This is useful only if you need to extract the level from the preset variable. That should be rare.
#define LZMA_PRESET_EXTREME (UINT32_C(1) << 31) |
Extreme compression preset.
This flag modifies the preset to make the encoding significantly slower while improving the compression ratio only marginally. This is useful when you don't mind wasting time to get as small result as possible.
This flag doesn't affect the memory usage requirements of the decoder (at least not significantly). The memory usage of the encoder may be increased a little but only at the lowest preset levels (0-3).
#define LZMA_TELL_NO_CHECK UINT32_C(0x01) |
This flag makes lzma_code() return LZMA_NO_CHECK if the input stream being decoded has no integrity check. Note that when used with lzma_auto_decoder(), all .lzma files will trigger LZMA_NO_CHECK if LZMA_TELL_NO_CHECK is used.
#define LZMA_TELL_UNSUPPORTED_CHECK UINT32_C(0x02) |
This flag makes lzma_code() return LZMA_UNSUPPORTED_CHECK if the input stream has an integrity check, but the type of the integrity check is not supported by this liblzma version or build. Such files can still be decoded, but the integrity check cannot be verified.
#define LZMA_TELL_ANY_CHECK UINT32_C(0x04) |
This flag makes lzma_code() return LZMA_GET_CHECK as soon as the type of the integrity check is known. The type can then be got with lzma_get_check().
#define LZMA_IGNORE_CHECK UINT32_C(0x10) |
This flag makes lzma_code() not calculate and verify the integrity check of the compressed data in .xz files. This means that invalid integrity check values won't be detected and LZMA_DATA_ERROR won't be returned in such cases.
This flag only affects the checks of the compressed data itself; the CRC32 values in the .xz headers will still be verified normally.
Don't use this flag unless you know what you are doing. Possible reasons to use this flag:
Support for this flag was added in liblzma 5.1.4beta.
#define LZMA_CONCATENATED UINT32_C(0x08) |
This flag enables decoding of concatenated files with file formats that allow concatenating compressed files as is. From the formats currently supported by liblzma, only the .xz format allows concatenated files. Concatenated files are not allowed with the legacy .lzma format.
This flag also affects the usage of the ‘action’ argument for lzma_code(). When LZMA_CONCATENATED is used, lzma_code() won't return LZMA_STREAM_END unless LZMA_FINISH is used as ‘action’. Thus, the application has to set LZMA_FINISH in the same way as it does when encoding.
If LZMA_CONCATENATED is not used, the decoders still accept LZMA_FINISH as ‘action’ for lzma_code(), but the usage of LZMA_FINISH isn't required.
uint64_t lzma_easy_encoder_memusage | ( | uint32_t | preset | ) |
Calculate approximate memory usage of easy encoder.
This function is a wrapper for lzma_raw_encoder_memusage().
preset | Compression preset (level and possible flags) |
References lzma_easy_preset().
uint64_t lzma_easy_decoder_memusage | ( | uint32_t | preset | ) |
Calculate approximate decoder memory usage of a preset.
This function is a wrapper for lzma_raw_decoder_memusage().
preset | Compression preset (level and possible flags) |
References lzma_easy_preset().
lzma_ret lzma_easy_encoder | ( | lzma_stream * | strm, |
uint32_t | preset, | ||
lzma_check | check | ||
) |
Initialize .xz Stream encoder using a preset number.
This function is intended for those who just want to use the basic features if liblzma (that is, most developers out there).
strm | Pointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT. |
preset | Compression preset to use. A preset consist of level number and zero or more flags. Usually flags aren't used, so preset is simply a number [0, 9] which match the options -0 ... -9 of the xz command line tool. Additional flags can be be set using bitwise-or with the preset level number, e.g. 6 | LZMA_PRESET_EXTREME. |
check | Integrity check type to use. See check.h for available checks. The xz command line tool defaults to LZMA_CHECK_CRC64, which is a good choice if you are unsure. LZMA_CHECK_CRC32 is good too as long as the uncompressed file is not many gigabytes. |
If initialization fails (return value is not LZMA_OK), all the memory allocated for *strm by liblzma is always freed. Thus, there is no need to call lzma_end() after failed initialization.
If initialization succeeds, use lzma_code() to do the actual encoding. Valid values for ‘action’ (the second argument of lzma_code()) are LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future, there may be compression levels or flags that don't support LZMA_SYNC_FLUSH.
References check, lzma_options_easy::filters, lzma_easy_preset(), LZMA_OPTIONS_ERROR, lzma_stream_encoder(), and strm.
lzma_ret lzma_easy_buffer_encode | ( | uint32_t | preset, |
lzma_check | check, | ||
const lzma_allocator * | allocator, | ||
const uint8_t * | in, | ||
size_t | in_size, | ||
uint8_t * | out, | ||
size_t * | out_pos, | ||
size_t | out_size | ||
) |
Single-call .xz Stream encoding using a preset number.
The maximum required output buffer size can be calculated with lzma_stream_buffer_bound().
preset | Compression preset to use. See the description in lzma_easy_encoder(). |
check | Type of the integrity check to calculate from uncompressed data. |
allocator | lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free(). |
in | Beginning of the input buffer |
in_size | Size of the input buffer |
out | Beginning of the output buffer |
out_pos | The next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds. |
out_size | Size of the out buffer; the first byte into which no data is written to is out[out_size]. |
lzma_ret lzma_stream_encoder | ( | lzma_stream * | strm, |
const lzma_filter * | filters, | ||
lzma_check | check | ||
) |
Initialize .xz Stream encoder using a custom filter chain.
strm | Pointer to properly prepared lzma_stream |
filters | Array of filters. This must be terminated with filters[n].id = LZMA_VLI_UNKNOWN. See filter.h for more information. |
check | Type of the integrity check to calculate from uncompressed data. |
References lzma_next_strm_init.
Referenced by lzma_easy_encoder().
uint64_t lzma_stream_encoder_mt_memusage | ( | const lzma_mt * | options | ) |
Calculate approximate memory usage of multithreaded .xz encoder.
Since doing the encoding in threaded mode doesn't affect the memory requirements of single-threaded decompressor, you can use lzma_easy_decoder_memusage(options->preset) or lzma_raw_decoder_memusage(options->filters) to calculate the decompressor memory requirements.
options | Compression options |
References filters, get_options(), and LZMA_OK.
lzma_ret lzma_stream_encoder_mt | ( | lzma_stream * | strm, |
const lzma_mt * | options | ||
) |
Initialize multithreaded .xz Stream encoder.
This provides the functionality of lzma_easy_encoder() and lzma_stream_encoder() as a single function for multithreaded use.
The supported actions for lzma_code() are LZMA_RUN, LZMA_FULL_FLUSH, LZMA_FULL_BARRIER, and LZMA_FINISH. Support for LZMA_SYNC_FLUSH might be added in the future.
strm | Pointer to properly prepared lzma_stream |
options | Pointer to multithreaded compression options |
References lzma_next_strm_init.
lzma_ret lzma_alone_encoder | ( | lzma_stream * | strm, |
const lzma_options_lzma * | options | ||
) |
Initialize .lzma encoder (legacy file format)
The .lzma format is sometimes called the LZMA_Alone format, which is the reason for the name of this function. The .lzma format supports only the LZMA1 filter. There is no support for integrity checks like CRC32.
Use this function if and only if you need to create files readable by legacy LZMA tools such as LZMA Utils 4.32.x. Moving to the .xz format is strongly recommended.
The valid action values for lzma_code() are LZMA_RUN and LZMA_FINISH. No kind of flushing is supported, because the file format doesn't make it possible.
References lzma_next_strm_init.
size_t lzma_stream_buffer_bound | ( | size_t | uncompressed_size | ) |
Calculate output buffer size for single-call Stream encoder.
When trying to compress uncompressible data, the encoded size will be slightly bigger than the input data. This function calculates how much output buffer space is required to be sure that lzma_stream_buffer_encode() doesn't return LZMA_BUF_ERROR.
The calculated value is not exact, but it is guaranteed to be big enough. The actual maximum output space required may be slightly smaller (up to about 100 bytes). This should not be a problem in practice.
If the calculated maximum size doesn't fit into size_t or would make the Stream grow past LZMA_VLI_MAX (which should never happen in practice), zero is returned to indicate the error.
lzma_ret lzma_stream_buffer_encode | ( | lzma_filter * | filters, |
lzma_check | check, | ||
const lzma_allocator * | allocator, | ||
const uint8_t * | in, | ||
size_t | in_size, | ||
uint8_t * | out, | ||
size_t * | out_pos, | ||
size_t | out_size | ||
) |
Single-call .xz Stream encoder.
filters | Array of filters. This must be terminated with filters[n].id = LZMA_VLI_UNKNOWN. See filter.h for more information. |
check | Type of the integrity check to calculate from uncompressed data. |
allocator | lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free(). |
in | Beginning of the input buffer |
in_size | Size of the input buffer |
out | Beginning of the output buffer |
out_pos | The next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds. |
out_size | Size of the out buffer; the first byte into which no data is written to is out[out_size]. |
lzma_ret lzma_stream_decoder | ( | lzma_stream * | strm, |
uint64_t | memlimit, | ||
uint32_t | flags | ||
) |
Initialize .xz Stream decoder.
strm | Pointer to properly prepared lzma_stream |
memlimit | Memory usage limit as bytes. Use UINT64_MAX to effectively disable the limiter. liblzma 5.2.3 and earlier don't allow 0 here and return LZMA_PROG_ERROR; later versions treat 0 as if 1 had been specified. |
flags | Bitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_TELL_ANY_CHECK, LZMA_IGNORE_CHECK, LZMA_CONCATENATED |
References lzma_next_strm_init.
lzma_ret lzma_auto_decoder | ( | lzma_stream * | strm, |
uint64_t | memlimit, | ||
uint32_t | flags | ||
) |
Decode .xz Streams and .lzma files with autodetection.
This decoder autodetects between the .xz and .lzma file formats, and calls lzma_stream_decoder() or lzma_alone_decoder() once the type of the input file has been detected.
If the flag LZMA_CONCATENATED is used and the input is a .lzma file: For historical reasons concatenated .lzma files aren't supported. If there is trailing data after one .lzma stream, lzma_code() will return LZMA_DATA_ERROR. (lzma_alone_decoder() doesn't have such a check as it doesn't support any decoder flags. It will return LZMA_STREAM_END after one .lzma stream.)
strm | Pointer to properly prepared lzma_stream |
memlimit | Memory usage limit as bytes. Use UINT64_MAX to effectively disable the limiter. liblzma 5.2.3 and earlier don't allow 0 here and return LZMA_PROG_ERROR; later versions treat 0 as if 1 had been specified. |
flags | Bitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_TELL_ANY_CHECK, LZMA_IGNORE_CHECK, LZMA_CONCATENATED |
References lzma_next_strm_init.
lzma_ret lzma_alone_decoder | ( | lzma_stream * | strm, |
uint64_t | memlimit | ||
) |
Initialize .lzma decoder (legacy file format)
strm | Pointer to properly prepared lzma_stream |
memlimit | Memory usage limit as bytes. Use UINT64_MAX to effectively disable the limiter. liblzma 5.2.3 and earlier don't allow 0 here and return LZMA_PROG_ERROR; later versions treat 0 as if 1 had been specified. |
Valid ‘action’ arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. There is no need to use LZMA_FINISH, but it's allowed because it may simplify certain types of applications.
References lzma_next_strm_init.
lzma_ret lzma_stream_buffer_decode | ( | uint64_t * | memlimit, |
uint32_t | flags, | ||
const lzma_allocator * | allocator, | ||
const uint8_t * | in, | ||
size_t * | in_pos, | ||
size_t | in_size, | ||
uint8_t * | out, | ||
size_t * | out_pos, | ||
size_t | out_size | ||
) |
Single-call .xz Stream decoder.
memlimit | Pointer to how much memory the decoder is allowed to allocate. The value pointed by this pointer is modified if and only if LZMA_MEMLIMIT_ERROR is returned. |
flags | Bitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_IGNORE_CHECK, LZMA_CONCATENATED. Note that LZMA_TELL_ANY_CHECK is not allowed and will return LZMA_PROG_ERROR. |
allocator | lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free(). |
in | Beginning of the input buffer |
in_pos | The next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds. |
in_size | Size of the input buffer; the first byte that won't be read is in[in_size]. |
out | Beginning of the output buffer |
out_pos | The next byte will be written to out[*out_pos]. *out_pos is updated only if decoding succeeds. |
out_size | Size of the out buffer; the first byte into which no data is written to is out[out_size]. |