Data types and functions used in many places of the public API. More...
Data Structures | |
struct | lzma_allocator |
Custom functions for memory handling. More... | |
struct | lzma_stream |
Passing data to and from liblzma. More... | |
Defines | |
#define | LZMA_STREAM_INIT |
Initialization for lzma_stream. | |
Typedefs | |
typedef unsigned char | lzma_bool |
Boolean. | |
typedef struct lzma_internal_s | lzma_internal |
Internal data structure. | |
Enumerations | |
enum | lzma_reserved_enum { LZMA_RESERVED_ENUM = 0 } |
Type of reserved enumeration variable in structures. More... | |
enum | lzma_ret { LZMA_OK = 0, LZMA_STREAM_END = 1, LZMA_NO_CHECK = 2, LZMA_UNSUPPORTED_CHECK = 3, LZMA_GET_CHECK = 4, LZMA_MEM_ERROR = 5, LZMA_MEMLIMIT_ERROR = 6, LZMA_FORMAT_ERROR = 7, LZMA_OPTIONS_ERROR = 8, LZMA_DATA_ERROR = 9, LZMA_BUF_ERROR = 10, LZMA_PROG_ERROR = 11 } |
Return values used by several functions in liblzma. More... | |
enum | lzma_action { LZMA_RUN = 0, LZMA_SYNC_FLUSH = 1, LZMA_FULL_FLUSH = 2, LZMA_FINISH = 3 } |
The `action' argument for lzma_code(). More... | |
Functions | |
LZMA_API (lzma_ret) lzma_code(lzma_stream *strm | |
Encode or decode data. | |
LZMA_API (void) lzma_end(lzma_stream *strm) | |
Free memory allocated for the coder data structures. | |
LZMA_API (uint64_t) lzma_memusage(const lzma_stream *strm) | |
Get the memory usage of decoder filter chain. | |
Variables | |
lzma_action action | lzma_attr_warn_unused_result |
uint64_t | memlimit |
Data types and functions used in many places of the public API.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
#define LZMA_STREAM_INIT |
{ NULL, 0, 0, NULL, 0, 0, NULL, NULL, \ NULL, NULL, 0, 0, LZMA_RESERVED_ENUM, LZMA_RESERVED_ENUM }
Initialization for lzma_stream.
When you declare an instance of lzma_stream, you can immediatelly initialize it so that initialization functions know that no memory has been allocated yet:
lzma_stream strm = LZMA_STREAM_INIT;
If you need to initialize a dynamically allocated lzma_stream, you can use memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this violates the C standard since NULL may have different internal representation than zero, but it should be portable enough in practice. Anyway, for maximum portability, you can use something like this:
lzma_stream tmp = LZMA_STREAM_INIT; *strm = tmp;
typedef unsigned char lzma_bool |
Boolean.
This is here because C89 doesn't have stdbool.h. To set a value for variables having type lzma_bool, you can use
typedef struct lzma_internal_s lzma_internal |
Internal data structure.
The contents of this structure is not visible outside the library.
enum lzma_reserved_enum |
Type of reserved enumeration variable in structures.
To avoid breaking library ABI when new features are added, several structures contain extra variables that may be used in future. Since sizeof(enum) can be different than sizeof(int), and sizeof(enum) may even vary depending on the range of enumeration constants, we specify a separate type to be used for reserved enumeration variables. All enumeration constants in liblzma API will be non-negative and less than 128, which should guarantee that the ABI won't break even when new constants are added to existing enumerations.
enum lzma_ret |
Return values used by several functions in liblzma.
Check the descriptions of specific functions to find out which return values they can return. With some functions the return values may have more specific meanings than described here; those differences are described per-function basis.
enum lzma_action |
The `action' argument for lzma_code().
After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or LZMA_FINISH, the same `action' must is used until lzma_code() returns LZMA_STREAM_END. Also, the amount of input (that is, strm->avail_in) must not be modified by the application until lzma_code() returns LZMA_STREAM_END. Changing the `action' or modifying the amount of input will make lzma_code() return LZMA_PROG_ERROR.
LZMA_API | ( | lzma_ret | ) |
Encode or decode data.
Decodes variable-length integer.
Compare two lzma_stream_flags structures.
Decode Stream Footer.
Decode Stream Header.
Encode Stream Footer.
Decode and validate the Index field.
Single-call Index decoder.
Single-call Index encoder.
Initialize Index decoder.
Initialize Index encoder.
Concatenate Indexes of two Streams.
Decode Filter Flags from given buffer.
Encode Filter Flags into given buffer.
Calculate encoded size of a Filter Flags field.
Decode the Filter Properties field.
Encode the Filter Properties field.
Get the size of the Filter Properties field.
Single-call raw decoder.
Single-call raw encoder.
Initialize raw decoder.
Single-call .xz Stream decoder.
Initialize .lzma decoder (legacy file format).
Decode .xz Streams and .lzma files with autodetection.
Initialize .xz Stream decoder.
Single-call Stream encoder.
Initialize .lzma encoder (legacy file format).
Initialize .xz Stream encoder using a custom filter chain.
Single-call .xz Block decoder.
Single-call .xz Block encoder.
Initialize .xz Block decoder.
Initialize .xz Block encoder.
Validate and set Compressed Size according to Unpadded Size.
Decode Block Header.
Encode Block Header.
Set the memory usage limit.
Once the lzma_stream has been successfully initialized (e.g. with lzma_stream_encoder()), the actual encoding or decoding is done using this function. The application has to update strm->next_in, strm->avail_in, strm->next_out, and strm->avail_out to pass input to and get output from liblzma.
See the description of the coder-specific initialization function to find out what `action' values are supported by the coder. See documentation of lzma_ret for the possible return values.
This function is supported only when *strm has been initialized with a function that takes a memlimit argument.
The caller must have calculated the size of the Block Header already with lzma_block_header_size(). If larger value than the one calculated by lzma_block_header_size() is used, the Block Header will be padded to the specified size.
out | Beginning of the output buffer. This must be at least block->header_size bytes. | |
block | Block options to be encoded. |
The size of the Block Header must have already been decoded with lzma_block_header_size_decode() macro and stored to block->header_size. block->filters must have been allocated, but not necessarily initialized. Possible existing filter options are _not_ freed.
block | Destination for block options with header_size properly initialized. | |
allocator | lzma_allocator for custom allocator functions. Set to NULL to use malloc() (and also free() if an error occurs). | |
in | Beginning of the input buffer. This must be at least block->header_size bytes. |
Block Header stores Compressed Size, but Index has Unpadded Size. If the application has already parsed the Index and is now decoding Blocks, it can calculate Compressed Size from Unpadded Size. This function does exactly that with error checking:
Valid actions for lzma_code() are LZMA_RUN, LZMA_SYNC_FLUSH (only if the filter chain supports it), and LZMA_FINISH.
Valid actions for lzma_code() are LZMA_RUN and LZMA_FINISH. Using LZMA_FINISH is not required. It is supported only for convenience.
In contrast to the multi-call encoder initialized with lzma_block_encoder(), this function encodes also the Block Header. This is required to make it possible to write appropriate Block Header also in case the data isn't compressible, and different filter chain has to be used to encode the data in uncompressed form using uncompressed chunks of the LZMA2 filter.
When the data isn't compressible, header_size, compressed_size, and uncompressed_size are set just like when the data was compressible, but it is possible that header_size is too small to hold the filter chain specified in block->filters, because that isn't necessarily the filter chain that was actually used to encode the data. lzma_block_unpadded_size() still works normally, because it doesn't read the filters array.
block | Block options: block->version, block->check, and block->filters must be initialized. | |
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]. |
This is single-call equivalent of lzma_block_decoder(), and requires that the caller has already decoded Block Header and checked its memory usage.
block | Block options just like with lzma_block_decoder(). | |
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 encoding succeeds. | |
out_size | Size of the out buffer; the first byte into which no data is written to is out[out_size]. |
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. |
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.
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]. |
strm | Pointer to properly prepared lzma_stream | |
memlimit | Rough memory usage limit as bytes | |
flags | Bitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_TELL_ANY_CHECK, LZMA_CONCATENATED |
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.
strm | Pointer to properly prepared lzma_stream | |
memlimit | Rough memory usage limit as bytes | |
flags | Bitwise-or of flags, or zero for no flags. |
Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. There is no need to use LZMA_FINISH, but allowing it may simplify certain types of applications.
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_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 encoding succeeds. | |
out_size | Size of the out buffer; the first byte into which no data is written to is out[out_size]. |
The initialization of raw decoder goes similarly to raw encoder.
The `action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using LZMA_FINISH is not required, it is supported just for convenience.
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]. |
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 encoding succeeds. | |
out_size | Size of the out buffer; the first byte into which no data is written to is out[out_size]. |
This function may be useful when implementing custom file formats using the raw encoder and decoder.
size | Pointer to uint32_t to hold the size of the properties | |
filter | Filter ID and options (the size of the propeties may vary depending on the options) |
filter | Filter ID and options | |
props | Buffer to hold the encoded options. The size of buffer must have been already determined with lzma_properties_size(). |
filter | filter->id must have been set to the correct Filter ID. filter->options doesn't need to be initialized (it's not freed by this function). The decoded options will be stored to filter->options. filter->options is set to NULL if there are no properties or if an error occurs. | |
allocator | Custom memory allocator used to allocate the options. Set to NULL to use the default malloc(), and in case of an error, also free(). | |
props | Input buffer containing the properties. | |
props_size | Size of the properties. This must be the exact size; giving too much or too little input will return LZMA_OPTIONS_ERROR. |
Knowing the size of Filter Flags is useful to know when allocating memory to hold the encoded Filter Flags.
size | Pointer to integer to hold the calculated size | |
filters | Filter ID and associated options whose encoded size is to be calculted |
In contrast to some functions, this doesn't allocate the needed buffer. This is due to how this function is used internally by liblzma.
filters | Filter ID and options to be encoded | |
out | Beginning of the output buffer | |
out_pos | out[*out_pos] is the next write position. This is updated by the encoder. | |
out_size | out[out_size] is the first byte to not write. |
The decoded result is stored into *filters. filters->options is initialized but the old value is NOT free()d.
dest | Destination Index after which src is appended | |
src | Source Index. The memory allocated for this is either moved to be part of *dest or freed if and only if the function call succeeds, and src will be an invalid pointer. | |
allocator | Custom memory allocator; can be NULL to use malloc() and free(). | |
padding | Size of the Stream Padding field between Streams. This must be a multiple of four. |
strm | Pointer to properly prepared lzma_stream | |
i | Pointer to lzma_index which should be encoded. The read position will be at the end of the Index after lzma_code() has returned LZMA_STREAM_END. |
The only valid action value for lzma_code() is LZMA_RUN.
strm | Pointer to properly prepared lzma_stream | |
i | Pointer to a pointer that will be made to point to the final decoded Index once lzma_code() has returned LZMA_STREAM_END. That is, lzma_index_decoder() always takes care of allocating a new lzma_index structure, and *i doesn't need to be initialized by the caller. | |
memlimit | How much memory the resulting Index is allowed to require. |
The only valid action value for lzma_code() is LZMA_RUN.
i | Index to be encoded. The read position will be at the end of the Index if encoding succeeds, or at unspecified position in case an error occurs. | |
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]. |
i | Pointer to a pointer that will be made to point to the final decoded Index if decoding is successful. That is, lzma_index_buffer_decode() always takes care of allocating a new lzma_index structure, and *i doesn't need to be initialized by the caller. | |
memlimit | Pointer to how much memory the resulting Index is allowed to require. The value pointed by this pointer is modified if and only if LZMA_MEMLIMIT_ERROR is returned. | |
allocator | Pointer to lzma_allocator, or NULL to use malloc() | |
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]. |
After telling the sizes of all Blocks with lzma_index_hash_append(), the actual Index field is decoded with this function. Specifically, once decoding of the Index field has been started, no more Records can be added using lzma_index_hash_append().
This function doesn't use lzma_stream structure to pass the input data. Instead, the input buffer is specified using three arguments. This is because it matches better the internal APIs of liblzma.
index_hash | Pointer to a lzma_index_hash structure | |
in | Pointer to the beginning of the input buffer | |
in_pos | in[*in_pos] is the next byte to process | |
in_size | in[in_size] is the first byte not to process |
options | Stream Footer options to be encoded. | |
out | Beginning of the output buffer of LZMA_STREAM_HEADER_SIZE bytes. |
options | Stream Header options to be encoded. | |
in | Beginning of the input buffer of LZMA_STREAM_HEADER_SIZE bytes. |
options->backward_size is always set to LZMA_VLI_UNKNOWN. This is to help comparing Stream Flags from Stream Header and Stream Footer with lzma_stream_flags_compare().
For example, Stream decoder in liblzma uses LZMA_DATA_ERROR if LZMA_FORMAT_ERROR is returned by lzma_stream_header_decode() when decoding non-first Stream.
options | Stream Header options to be encoded. | |
in | Beginning of the input buffer of LZMA_STREAM_HEADER_SIZE bytes. |
backward_size values are compared only if both are not LZMA_VLI_UNKNOWN.
Like lzma_vli_encode(), this function has single-call and multi-call modes.
vli | Pointer to decoded integer. The decoder will initialize it to zero when *vli_pos == 0, so application isn't required to initialize *vli. | |
vli_pos | How many bytes have already been decoded. When starting to decode a new integer, *vli_pos must be initialized to zero. To use single-call decoding, set this to NULL. | |
in | Beginning of the input buffer | |
in_pos | The next byte will be read from in[*in_pos]. | |
in_size | Size of the input buffer; the first byte that won't be read is in[in_size]. |
Single-call (vli_pos == NULL):
Multi-call (vli_pos != NULL):
References LZMA_FILTERS_MAX, LZMA_OK, LZMA_PROG_ERROR, lzma_vli_is_valid, LZMA_VLI_UNKNOWN, and return_if_error.
LZMA_API | ( | void | ) |
Free memory allocated for the coder data structures.
Rewind the Index.
strm | Pointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT. |
After lzma_end(strm), strm->internal is guaranteed to be NULL. No other members of the lzma_stream structure are touched.
Rewind the Index so that next call to lzma_index_read() will return the first Record.
Free memory allocated for the coder data structures.
Rewind the Index.
If i is NULL, this does nothing.
Rewind the Index so that next call to lzma_index_read() will return the first Record.
LZMA_API | ( | uint64_t | ) | const |
Get the memory usage of decoder filter chain.
Get the uncompressed size of the Stream.
Get the total size of the file.
Get the total size of the Stream.
Get the total size of the Blocks.
Get the size of the Index field as bytes.
Get the number of Records.
Calculate rough memory requirements for raw decoder.
Calculate rough decoder memory usage of a preset.
Calculate the total encoded size of a Block.
Get the current memory usage limit.
This function is currently supported only when *strm has been initialized with a function that takes a memlimit argument. With other functions, you should use e.g. lzma_raw_encoder_memusage() or lzma_raw_decoder_memusage() to estimate the memory requirements.
This function is useful e.g. after LZMA_MEMLIMIT_ERROR to find out how big the memory usage limit should have been to decode the input. Note that this may give misleading information if decoding .xz Streams that have multiple Blocks, because each Block can have different memory requirements.
If this function isn't supported by *strm or some other error occurs, zero is returned.
This function is supported only when *strm has been initialized with a function that takes a memlimit argument.
This is equivalent to lzma_block_unpadded_size() except that the returned value includes the size of the Block Padding field.
This function is a wrapper for lzma_raw_decoder_memusage().
preset | Compression preset (level and possible flags) | |
filters | Array of filters terminated with .id == LZMA_VLI_UNKNOWN. |
This is needed to verify the Backward Size field in the Stream Footer.
This doesn't include the Stream Header, Stream Footer, Stream Padding, or Index fields.
If multiple Indexes have been combined, this works as if the Blocks were in a single Stream.
When no Indexes have been combined with lzma_index_cat(), this function is identical to lzma_index_stream_size(). If multiple Indexes have been combined, this includes also the headers of each separate Stream and the possible Stream Padding fields.
Get the memory usage of decoder filter chain.
Calculates CRC64 using the polynomial from the ECMA-182 standard.
This function is used similarly to lzma_crc32(). See its documentation.