src/liblzma/common/filter_flags_encoder.c File Reference

Decodes a Filter Flags field. More...

#include "filter_encoder.h"

Functions

 LZMA_API (lzma_ret)
 Calculate Block Header Size.


Detailed Description

Decodes a Filter Flags field.


Function Documentation

LZMA_API ( lzma_ret   ) 

Calculate Block Header Size.

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.

Calculate the minimum size needed for the Block Header field using the settings specified in the lzma_block structure. Note that it is OK to increase the calculated header_size value as long as it is a multiple of four and doesn't exceed LZMA_BLOCK_HEADER_SIZE_MAX. Increasing header_size just means that lzma_block_header_encode() will add Header Padding.

Returns:
- LZMA_OK: Size calculated successfully and stored to block->header_size.
  • LZMA_OPTIONS_ERROR: Unsupported version, filters or filter options.
  • LZMA_PROG_ERROR: Invalid values like compressed_size == 0.
Note:
This doesn't check that all the options are valid i.e. this may return LZMA_OK even if lzma_block_header_encode() or lzma_block_encoder() would fail. If you want to validate the filter chain, consider using lzma_memlimit_encoder() which as a side-effect validates the filter chain.
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.

Parameters:
out Beginning of the output buffer. This must be at least block->header_size bytes.
block Block options to be encoded.
Returns:
- LZMA_OK: Encoding was successful. block->header_size bytes were written to output buffer.
  • LZMA_OPTIONS_ERROR: Invalid or unsupported options.
  • LZMA_PROG_ERROR: Invalid arguments, for example block->header_size is invalid or block->filters is NULL.
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.

Parameters:
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.
Returns:
- LZMA_OK: Decoding was successful. block->header_size bytes were read from the input buffer.
  • LZMA_OPTIONS_ERROR: The Block Header specifies some unsupported options such as unsupported filters.
  • LZMA_DATA_ERROR: Block Header is corrupt, for example, the CRC32 doesn't match.
  • LZMA_PROG_ERROR: Invalid arguments, for example block->header_size is invalid or block->filters is NULL.
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:

  • Compressed Size calculated from Unpadded Size must be positive integer, that is, Unpadded Size must be big enough that after Block Header and Check fields there's still at least one byte for Compressed Size.

  • If Compressed Size was present in Block Header, the new value calculated from Unpadded Size is compared against the value from Block Header.

Note:
This function must be called _after_ decoding the Block Header field so that it can properly validate Compressed Size if it was present in Block Header.
Returns:
- LZMA_OK: block->compressed_size was set successfully.
  • LZMA_DATA_ERROR: unpadded_size is too small compared to block->header_size and lzma_check_size(block->check).
  • LZMA_PROG_ERROR: Some values are invalid. For example, block->header_size must be a multiple of four and between 8 and 1024 inclusive.
Valid actions for lzma_code() are LZMA_RUN, LZMA_SYNC_FLUSH (only if the filter chain supports it), and LZMA_FINISH.

Returns:
- LZMA_OK: All good, continue with lzma_code().
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_UNSUPPORTED_CHECK: block->check specfies a Check ID that is not supported by this buid of liblzma. Initializing the encoder failed.
  • LZMA_PROG_ERROR
Valid actions for lzma_code() are LZMA_RUN and LZMA_FINISH. Using LZMA_FINISH is not required. It is supported only for convenience.

Returns:
- LZMA_OK: All good, continue with lzma_code().
  • LZMA_UNSUPPORTED_CHECK: Initialization was successful, but the given Check ID is not supported, thus Check will be ignored.
  • LZMA_PROG_ERROR
  • LZMA_MEM_ERROR
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.

Parameters:
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].
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_BUF_ERROR: Not enough output buffer space.
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
  • LZMA_DATA_ERROR
  • LZMA_PROG_ERROR
This is single-call equivalent of lzma_block_decoder(), and requires that the caller has already decoded Block Header and checked its memory usage.

Parameters:
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].
Returns:
- LZMA_OK: Decoding was successful.
  • LZMA_OPTIONS_ERROR
  • LZMA_DATA_ERROR
  • LZMA_MEM_ERROR
  • LZMA_BUF_ERROR: Output buffer was too small.
  • LZMA_PROG_ERROR
Calculate Block Header Size.

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.

Returns:
- LZMA_OK: New memory usage limit successfully set.
  • LZMA_MEMLIMIT_ERROR: The new limit is too small. The limit was not changed.
  • LZMA_PROG_ERROR: Invalid arguments, e.g. *strm doesn't support memory usage limit or memlimit was zero.
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.

Parameters:
out Beginning of the output buffer. This must be at least block->header_size bytes.
block Block options to be encoded.
Returns:
- LZMA_OK: Encoding was successful. block->header_size bytes were written to output buffer.
  • LZMA_OPTIONS_ERROR: Invalid or unsupported options.
  • LZMA_PROG_ERROR: Invalid arguments, for example block->header_size is invalid or block->filters is NULL.
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.

Parameters:
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.
Returns:
- LZMA_OK: Decoding was successful. block->header_size bytes were read from the input buffer.
  • LZMA_OPTIONS_ERROR: The Block Header specifies some unsupported options such as unsupported filters.
  • LZMA_DATA_ERROR: Block Header is corrupt, for example, the CRC32 doesn't match.
  • LZMA_PROG_ERROR: Invalid arguments, for example block->header_size is invalid or block->filters is NULL.
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:

  • Compressed Size calculated from Unpadded Size must be positive integer, that is, Unpadded Size must be big enough that after Block Header and Check fields there's still at least one byte for Compressed Size.

  • If Compressed Size was present in Block Header, the new value calculated from Unpadded Size is compared against the value from Block Header.

Note:
This function must be called _after_ decoding the Block Header field so that it can properly validate Compressed Size if it was present in Block Header.
Returns:
- LZMA_OK: block->compressed_size was set successfully.
  • LZMA_DATA_ERROR: unpadded_size is too small compared to block->header_size and lzma_check_size(block->check).
  • LZMA_PROG_ERROR: Some values are invalid. For example, block->header_size must be a multiple of four and between 8 and 1024 inclusive.
Valid actions for lzma_code() are LZMA_RUN, LZMA_SYNC_FLUSH (only if the filter chain supports it), and LZMA_FINISH.

Returns:
- LZMA_OK: All good, continue with lzma_code().
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_UNSUPPORTED_CHECK: block->check specfies a Check ID that is not supported by this buid of liblzma. Initializing the encoder failed.
  • LZMA_PROG_ERROR
Valid actions for lzma_code() are LZMA_RUN and LZMA_FINISH. Using LZMA_FINISH is not required. It is supported only for convenience.

Returns:
- LZMA_OK: All good, continue with lzma_code().
  • LZMA_UNSUPPORTED_CHECK: Initialization was successful, but the given Check ID is not supported, thus Check will be ignored.
  • LZMA_PROG_ERROR
  • LZMA_MEM_ERROR
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.

Parameters:
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].
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_BUF_ERROR: Not enough output buffer space.
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
  • LZMA_DATA_ERROR
  • LZMA_PROG_ERROR
This is single-call equivalent of lzma_block_decoder(), and requires that the caller has already decoded Block Header and checked its memory usage.

Parameters:
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].
Returns:
- LZMA_OK: Decoding was successful.
  • LZMA_OPTIONS_ERROR
  • LZMA_DATA_ERROR
  • LZMA_MEM_ERROR
  • LZMA_BUF_ERROR: Output buffer was too small.
  • LZMA_PROG_ERROR
Parameters:
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.
Returns:
- LZMA_OK: Initialization was successful.
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
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.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Parameters:
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].
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_BUF_ERROR: Not enough output buffer space.
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
  • LZMA_DATA_ERROR
  • LZMA_PROG_ERROR
Parameters:
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
Returns:
- LZMA_OK: Initialization was successful.
  • LZMA_MEM_ERROR: Cannot allocate memory.
  • LZMA_OPTIONS_ERROR: Unsupported flags
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.

Parameters:
strm Pointer to properly prepared lzma_stream
memlimit Rough memory usage limit as bytes
flags Bitwise-or of flags, or zero for no flags.
Returns:
- LZMA_OK: Initialization was successful.
  • LZMA_MEM_ERROR: Cannot allocate memory.
  • LZMA_OPTIONS_ERROR: Unsupported 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.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
Parameters:
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].
Returns:
- LZMA_OK: Decoding was successful.
  • LZMA_FORMAT_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_DATA_ERROR
  • LZMA_NO_CHECK: This can be returned only if using the LZMA_TELL_NO_CHECK flag.
  • LZMA_UNSUPPORTED_CHECK: This can be returned only if using the LZMA_TELL_UNSUPPORTED_CHECK flag.
  • LZMA_MEM_ERROR
  • LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. The minimum required memlimit value was stored to *memlimit.
  • LZMA_BUF_ERROR: Output buffer was too small.
  • LZMA_PROG_ERROR
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.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Parameters:
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].
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_BUF_ERROR: Not enough output buffer space.
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
  • LZMA_DATA_ERROR
  • LZMA_PROG_ERROR
Parameters:
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.

Parameters:
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)
Returns:
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Note:
This function validates the Filter ID, but does not necessarily validate the options. Thus, it is possible that this returns LZMA_OK while the following call to lzma_properties_encode() returns LZMA_OPTIONS_ERROR.
Parameters:
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().
Returns:
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Note:
Even this function won't validate more options than actually necessary. Thus, it is possible that encoding the properties succeeds but using the same options to initialize the encoder will fail.

It is OK to skip calling this function if lzma_properties_size() indicated that the size of the Filter Properties field is zero.

Parameters:
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.
Returns:
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
Knowing the size of Filter Flags is useful to know when allocating memory to hold the encoded Filter Flags.

Parameters:
size Pointer to integer to hold the calculated size
filters Filter ID and associated options whose encoded size is to be calculted
Returns:
- LZMA_OK: *size set successfully. Note that this doesn't guarantee that filters->options is valid, thus lzma_filter_flags_encode() may still fail.
  • LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
  • LZMA_PROG_ERROR: Invalid options
Note:
If you need to calculate size of List of Filter Flags, you need to loop over every lzma_filter entry.
In contrast to some functions, this doesn't allocate the needed buffer. This is due to how this function is used internally by liblzma.

Parameters:
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.
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_OPTIONS_ERROR: Invalid or unsupported options.
  • LZMA_PROG_ERROR: Invalid options or not enough output buffer space (you should have checked it with lzma_filter_flags_size()).
The decoded result is stored into *filters. filters->options is initialized but the old value is NOT free()d.

Returns:
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
  • LZMA_PROG_ERROR
Parameters:
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.
Returns:
- LZMA_OK: Indexes concatenated successfully.
  • LZMA_DATA_ERROR: *dest would grow too big.
  • LZMA_MEM_ERROR
  • LZMA_PROG_ERROR
Parameters:
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.

Returns:
- LZMA_OK: Initialization succeeded, continue with lzma_code().
  • LZMA_MEM_ERROR
  • LZMA_PROG_ERROR
Parameters:
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.

Returns:
- LZMA_OK: Initialization succeeded, continue with lzma_code().
  • LZMA_MEM_ERROR
  • LZMA_MEMLIMIT_ERROR
  • LZMA_PROG_ERROR
Note:
The memory usage limit is checked early in the decoding (within the first dozen input bytes or so). The actual memory is allocated later in smaller pieces. If the memory usage limit is modified after decoding a part of the Index already, the new limit may be ignored.
Parameters:
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].
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_BUF_ERROR: Output buffer is too small. Use lzma_index_size() to find out how much output space is needed.
  • LZMA_PROG_ERROR
Note:
This function doesn't take allocator argument since all the internal data is allocated on stack.
Parameters:
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].
Returns:
- LZMA_OK: Decoding was successful.
  • LZMA_MEM_ERROR
  • LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. The minimum required memlimit value was stored to *memlimit.
  • LZMA_DATA_ERROR
  • LZMA_PROG_ERROR
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.

Parameters:
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
Returns:
- LZMA_OK: So far good, but more input is needed.
  • LZMA_STREAM_END: Index decoded successfully and it matches the Records given with lzma_index_hash_append().
  • LZMA_DATA_ERROR: Index is corrupt or doesn't match the information given with lzma_index_hash_append().
  • LZMA_BUF_ERROR: Cannot progress because *in_pos >= in_size.
  • LZMA_PROG_ERROR
Parameters:
options Stream Footer options to be encoded.
out Beginning of the output buffer of LZMA_STREAM_HEADER_SIZE bytes.
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_OPTIONS_ERROR: options->version is not supported by this liblzma version.
  • LZMA_PROG_ERROR: Invalid options.
Parameters:
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().

Returns:
- LZMA_OK: Decoding was successful.
  • LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given buffer cannot be Stream Header.
  • LZMA_DATA_ERROR: CRC32 doesn't match, thus the header is corrupt.
  • LZMA_OPTIONS_ERROR: Unsupported options are present in the header.
Note:
When decoding .xz files that contain multiple Streams, it may make sense to print "file format not recognized" only if decoding of the Stream Header of the _first_ Stream gives LZMA_FORMAT_ERROR. If non-first Stream Header gives LZMA_FORMAT_ERROR, the message used for LZMA_DATA_ERROR is probably more appropriate.
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.

Parameters:
options Stream Header options to be encoded.
in Beginning of the input buffer of LZMA_STREAM_HEADER_SIZE bytes.
Returns:
- LZMA_OK: Decoding was successful.
  • LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given buffer cannot be Stream Footer.
  • LZMA_DATA_ERROR: CRC32 doesn't match, thus the Stream Footer is corrupt.
  • LZMA_OPTIONS_ERROR: Unsupported options are present in Stream Footer.
Note:
If Stream Header was already decoded successfully, but decoding Stream Footer returns LZMA_FORMAT_ERROR, the application should probably report some other error message than "file format not recognized", since the file more likely is corrupt (possibly truncated). Stream decoder in liblzma uses LZMA_DATA_ERROR in this situation.
backward_size values are compared only if both are not LZMA_VLI_UNKNOWN.

Returns:
- LZMA_OK: Both are equal. If either had backward_size set to LZMA_VLI_UNKNOWN, backward_size values were not compared or validated.
  • LZMA_DATA_ERROR: The structures differ.
  • LZMA_OPTIONS_ERROR: version in either structure is greater than the maximum supported version (currently zero).
  • LZMA_PROG_ERROR: Invalid value, e.g. invalid check or backward_size.
Like lzma_vli_encode(), this function has single-call and multi-call modes.

Parameters:
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].
Returns:
Slightly different return values are used in multi-call and single-call modes.
Single-call (vli_pos == NULL):
  • LZMA_OK: Integer successfully decoded.
  • LZMA_DATA_ERROR: Integer is corrupt. This includes hitting the end of the input buffer before the whole integer was decoded; providing no input at all will use LZMA_DATA_ERROR.
  • LZMA_PROG_ERROR: Arguments are not sane.

Multi-call (vli_pos != NULL):

  • LZMA_OK: So far all OK, but the integer is not completely decoded yet.
  • LZMA_STREAM_END: Integer successfully decoded.
  • LZMA_DATA_ERROR: Integer is corrupt.
  • LZMA_BUF_ERROR: No input was provided.
  • LZMA_PROG_ERROR: Arguments are not sane.

Calculate Block Header Size.

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.

This function is intended for those who just want to use the basic features if liblzma (that is, most developers out there).

Parameters:
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. If you are unsure, use LZMA_CHECK_CRC32.
Returns:
- LZMA_OK: Initialization succeeded. Use lzma_code() to encode your data.
  • LZMA_MEM_ERROR: Memory allocation failed. All memory previously allocated for *strm is now freed.
  • LZMA_OPTIONS_ERROR: The given compression level is not supported by this build of liblzma.
  • LZMA_UNSUPPORTED_CHECK: The given check type is not supported by this liblzma build.
  • LZMA_PROG_ERROR: One or more of the parameters have values that will never be valid. For example, strm == NULL.
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.

Parameters:
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.
Returns:
- LZMA_OK: Initialization was successful.
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
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.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Parameters:
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].
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_BUF_ERROR: Not enough output buffer space.
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
  • LZMA_DATA_ERROR
  • LZMA_PROG_ERROR
Parameters:
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
Returns:
- LZMA_OK: Initialization was successful.
  • LZMA_MEM_ERROR: Cannot allocate memory.
  • LZMA_OPTIONS_ERROR: Unsupported flags
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.

Parameters:
strm Pointer to properly prepared lzma_stream
memlimit Rough memory usage limit as bytes
flags Bitwise-or of flags, or zero for no flags.
Returns:
- LZMA_OK: Initialization was successful.
  • LZMA_MEM_ERROR: Cannot allocate memory.
  • LZMA_OPTIONS_ERROR: Unsupported 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.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
Parameters:
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].
Returns:
- LZMA_OK: Decoding was successful.
  • LZMA_FORMAT_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_DATA_ERROR
  • LZMA_NO_CHECK: This can be returned only if using the LZMA_TELL_NO_CHECK flag.
  • LZMA_UNSUPPORTED_CHECK: This can be returned only if using the LZMA_TELL_UNSUPPORTED_CHECK flag.
  • LZMA_MEM_ERROR
  • LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. The minimum required memlimit value was stored to *memlimit.
  • LZMA_BUF_ERROR: Output buffer was too small.
  • LZMA_PROG_ERROR
Calculate Block Header Size.

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.

This function may be useful when implementing custom file formats.

Parameters:
strm Pointer to properly prepared lzma_stream
filters Array of lzma_filter structures. The end of the array must be marked with .id = LZMA_VLI_UNKNOWN. The minimum number of filters is one and the maximum is four.
The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the filter chain supports it), or LZMA_FINISH.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
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.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Parameters:
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].
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_BUF_ERROR: Not enough output buffer space.
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
  • LZMA_DATA_ERROR
  • LZMA_PROG_ERROR
Parameters:
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.

Parameters:
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)
Returns:
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Note:
This function validates the Filter ID, but does not necessarily validate the options. Thus, it is possible that this returns LZMA_OK while the following call to lzma_properties_encode() returns LZMA_OPTIONS_ERROR.
Parameters:
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().
Returns:
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Note:
Even this function won't validate more options than actually necessary. Thus, it is possible that encoding the properties succeeds but using the same options to initialize the encoder will fail.

It is OK to skip calling this function if lzma_properties_size() indicated that the size of the Filter Properties field is zero.

Parameters:
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.
Returns:
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
Knowing the size of Filter Flags is useful to know when allocating memory to hold the encoded Filter Flags.

Parameters:
size Pointer to integer to hold the calculated size
filters Filter ID and associated options whose encoded size is to be calculted
Returns:
- LZMA_OK: *size set successfully. Note that this doesn't guarantee that filters->options is valid, thus lzma_filter_flags_encode() may still fail.
  • LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
  • LZMA_PROG_ERROR: Invalid options
Note:
If you need to calculate size of List of Filter Flags, you need to loop over every lzma_filter entry.
In contrast to some functions, this doesn't allocate the needed buffer. This is due to how this function is used internally by liblzma.

Parameters:
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.
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_OPTIONS_ERROR: Invalid or unsupported options.
  • LZMA_PROG_ERROR: Invalid options or not enough output buffer space (you should have checked it with lzma_filter_flags_size()).
The decoded result is stored into *filters. filters->options is initialized but the old value is NOT free()d.

Returns:
- LZMA_OK
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
  • LZMA_PROG_ERROR
Calculate Block Header Size.

Single-call Index decoder.

Single-call Index encoder.

Initialize Index decoder.

Initialize Index encoder.

Concatenate Indexes of two Streams.

Parameters:
i Pointer to a lzma_index structure
allocator Pointer to lzma_allocator, or NULL to use malloc()
unpadded_size Unpadded Size of a Block. This can be calculated with lzma_block_unpadded_size() after encoding or decoding the Block.
uncompressed_size Uncompressed Size of a Block. This can be taken directly from lzma_block structure after encoding or decoding the Block.
Appending a new Record does not affect the read position.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
  • LZMA_DATA_ERROR: Compressed or uncompressed size of the Stream or size of the Index field would grow too big.
  • LZMA_PROG_ERROR
Parameters:
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.
Returns:
- LZMA_OK: Indexes concatenated successfully.
  • LZMA_DATA_ERROR: *dest would grow too big.
  • LZMA_MEM_ERROR
  • LZMA_PROG_ERROR
Parameters:
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.

Returns:
- LZMA_OK: Initialization succeeded, continue with lzma_code().
  • LZMA_MEM_ERROR
  • LZMA_PROG_ERROR
Parameters:
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.

Returns:
- LZMA_OK: Initialization succeeded, continue with lzma_code().
  • LZMA_MEM_ERROR
  • LZMA_MEMLIMIT_ERROR
  • LZMA_PROG_ERROR
Note:
The memory usage limit is checked early in the decoding (within the first dozen input bytes or so). The actual memory is allocated later in smaller pieces. If the memory usage limit is modified after decoding a part of the Index already, the new limit may be ignored.
Parameters:
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].
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_BUF_ERROR: Output buffer is too small. Use lzma_index_size() to find out how much output space is needed.
  • LZMA_PROG_ERROR
Note:
This function doesn't take allocator argument since all the internal data is allocated on stack.
Parameters:
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].
Returns:
- LZMA_OK: Decoding was successful.
  • LZMA_MEM_ERROR
  • LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. The minimum required memlimit value was stored to *memlimit.
  • LZMA_DATA_ERROR
  • LZMA_PROG_ERROR
Calculate Block Header Size.

Decode and validate the Index field.

Parameters:
index Pointer to a lzma_index_hash structure
unpadded_size Unpadded Size of a Block
uncompressed_size Uncompressed Size of a Block
Returns:
- LZMA_OK
  • LZMA_DATA_ERROR: Compressed or uncompressed size of the Stream or size of the Index field would grow too big.
  • LZMA_PROG_ERROR: Invalid arguments or this function is being used when lzma_index_hash_decode() has already been used.
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.

Parameters:
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
Returns:
- LZMA_OK: So far good, but more input is needed.
  • LZMA_STREAM_END: Index decoded successfully and it matches the Records given with lzma_index_hash_append().
  • LZMA_DATA_ERROR: Index is corrupt or doesn't match the information given with lzma_index_hash_append().
  • LZMA_BUF_ERROR: Cannot progress because *in_pos >= in_size.
  • LZMA_PROG_ERROR
Calculate Block Header Size.

Decodes variable-length integer.

In the .xz format, most integers are encoded in a variable-length representation, which is sometimes called little endian base-128 encoding. This saves space when smaller values are more likely than bigger values.

The encoding scheme encodes seven bits to every byte, using minimum number of bytes required to represent the given value. Encodings that use non-minimum number of bytes are invalid, thus every integer has exactly one encoded representation. The maximum number of bits in a VLI is 63, thus the vli argument must be at maximum of UINT64_MAX / 2. You should use LZMA_VLI_MAX for clarity.

This function has two modes: single-call and multi-call. Single-call mode encodes the whole integer at once; it is an error if the output buffer is too small. Multi-call mode saves the position in *vli_pos, and thus it is possible to continue encoding if the buffer becomes full before the whole integer has been encoded.

Parameters:
vli Integer to be encoded
vli_pos How many VLI-encoded bytes have already been written out. When starting to encode a new integer, *vli_pos must be set to zero. To use single-call encoding, set vli_pos to NULL.
out Beginning of the output buffer
out_pos The next byte will be written to out[*out_pos].
out_size Size of the out buffer; the first byte into which no data is written to is out[out_size].
Returns:
Slightly different return values are used in multi-call and single-call modes.
Single-call (vli_pos == NULL):
  • LZMA_OK: Integer successfully encoded.
  • LZMA_PROG_ERROR: Arguments are not sane. This can be due to too little output space; single-call mode doesn't use LZMA_BUF_ERROR, since the application should have checked the encoded size with lzma_vli_size().

Multi-call (vli_pos != NULL):

  • LZMA_OK: So far all OK, but the integer is not completely written out yet.
  • LZMA_STREAM_END: Integer successfully encoded.
  • LZMA_BUF_ERROR: No output space was provided.
  • LZMA_PROG_ERROR: Arguments are not sane.

Like lzma_vli_encode(), this function has single-call and multi-call modes.

Parameters:
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].
Returns:
Slightly different return values are used in multi-call and single-call modes.
Single-call (vli_pos == NULL):
  • LZMA_OK: Integer successfully decoded.
  • LZMA_DATA_ERROR: Integer is corrupt. This includes hitting the end of the input buffer before the whole integer was decoded; providing no input at all will use LZMA_DATA_ERROR.
  • LZMA_PROG_ERROR: Arguments are not sane.

Multi-call (vli_pos != NULL):

  • LZMA_OK: So far all OK, but the integer is not completely decoded yet.
  • LZMA_STREAM_END: Integer successfully decoded.
  • LZMA_DATA_ERROR: Integer is corrupt.
  • LZMA_BUF_ERROR: No input was provided.
  • LZMA_PROG_ERROR: Arguments are not sane.

References LZMA_FILTER_RESERVED_START, LZMA_OK, LZMA_PROG_ERROR, and return_if_error.


Generated on Wed May 25 10:35:43 2011 for XZ Utils by  doxygen 1.5.5