base.h File Reference

Data types and functions used in many places in liblzma API. More...

Go to the source code of this file.

Classes
struct	lzma_allocator
	Custom functions for memory handling. More...
struct	lzma_stream
	Passing data to and from liblzma. More...

Macros
#define	LZMA_STREAM_INIT
	Initialization for lzma_stream. More...

Typedefs
typedef unsigned char	lzma_bool
	Boolean. More...
typedef struct lzma_internal_s	lzma_internal
	Internal data structure. More...

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_FULL_BARRIER = 4 ,   LZMA_FINISH = 3 }
	The ‘action’ argument for lzma_code() More...

Functions
	LZMA_API (lzma_ret) lzma_code(lzma_stream *strm
	Encode or decode data. More...
	LZMA_API (void) lzma_end(lzma_stream *strm) lzma_nothrow
	Free memory allocated for the coder data structures. More...
	LZMA_API (uint64_t) lzma_memusage(const lzma_stream *strm) lzma_nothrow lzma_attr_pure
	Get the memory usage of decoder filter chain. More...

Variables
lzma_action action lzma_nothrow	lzma_attr_warn_unused_result
uint64_t *	progress_in
uint64_t uint64_t *progress_out	lzma_nothrow

Detailed Description

Data types and functions used in many places in liblzma API.

Definition in file base.h.

Macro Definition Documentation

LZMA_STREAM_INIT

#define LZMA_STREAM_INIT

Value:

    { NULL, 0, 0, NULL, 0, 0, NULL, NULL, \
    NULL, NULL, NULL, NULL, 0, 0, 0, 0, \
    LZMA_RESERVED_ENUM, LZMA_RESERVED_ENUM }

Initialization for lzma_stream.

When you declare an instance of lzma_stream, you can immediately 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;

Definition at line 545 of file base.h.

Typedef Documentation

lzma_bool

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

• C99's ‘true’ and ‘false’ from stdbool.h;
• C++'s internal ‘true’ and ‘false’; or
• integers one (true) and zero (false).

Definition at line 29 of file base.h.

lzma_internal

typedef struct lzma_internal_s lzma_internal

Internal data structure.

The contents of this structure is not visible outside the library.

Definition at line 29 of file base.h.

Enumeration Type Documentation

lzma_action

enum lzma_action

The ‘action’ argument for lzma_code()

After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, LZMA_FULL_BARRIER, 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.

Enumerator
LZMA_RUN	Continue coding. Encoder: Encode as much input as possible. Some internal buffering will probably be done (depends on the filter chain in use), which causes latency: the input used won't usually be decodeable from the output of the same lzma_code() call. Decoder: Decode as much input as possible and produce as much output as possible.
LZMA_SYNC_FLUSH	Make all the input available at output. Normally the encoder introduces some latency. LZMA_SYNC_FLUSH forces all the buffered data to be available at output without resetting the internal state of the encoder. This way it is possible to use compressed stream for example for communication over network. Only some filters support LZMA_SYNC_FLUSH. Trying to use LZMA_SYNC_FLUSH with filters that don't support it will make lzma_code() return LZMA_OPTIONS_ERROR. For example, LZMA1 doesn't support LZMA_SYNC_FLUSH but LZMA2 does. Using LZMA_SYNC_FLUSH very often can dramatically reduce the compression ratio. With some filters (for example, LZMA2), fine-tuning the compression options may help mitigate this problem significantly (for example, match finder with LZMA2). Decoders don't support LZMA_SYNC_FLUSH.
LZMA_FULL_FLUSH	Finish encoding of the current Block. All the input data going to the current Block must have been given to the encoder (the last bytes can still be pending in *next_in). Call lzma_code() with LZMA_FULL_FLUSH until it returns LZMA_STREAM_END. Then continue normally with LZMA_RUN or finish the Stream with LZMA_FINISH. This action is currently supported only by Stream encoder and easy encoder (which uses Stream encoder). If there is no unfinished Block, no empty Block is created.
LZMA_FULL_BARRIER	Finish encoding of the current Block. This is like LZMA_FULL_FLUSH except that this doesn't necessarily wait until all the input has been made available via the output buffer. That is, lzma_code() might return LZMA_STREAM_END as soon as all the input has been consumed (avail_in == 0). LZMA_FULL_BARRIER is useful with a threaded encoder if one wants to split the .xz Stream into Blocks at specific offsets but doesn't care if the output isn't flushed immediately. Using LZMA_FULL_BARRIER allows keeping the threads busy while LZMA_FULL_FLUSH would make lzma_code() wait until all the threads have finished until more data could be passed to the encoder. With a lzma_stream initialized with the single-threaded lzma_stream_encoder() or lzma_easy_encoder(), LZMA_FULL_BARRIER is an alias for LZMA_FULL_FLUSH.
LZMA_FINISH	Finish the coding operation. All the input data must have been given to the encoder (the last bytes can still be pending in next_in). Call lzma_code() with LZMA_FINISH until it returns LZMA_STREAM_END. Once LZMA_FINISH has been used, the amount of input must no longer be changed by the application. When decoding, using LZMA_FINISH is optional unless the LZMA_CONCATENATED flag was used when the decoder was initialized. When LZMA_CONCATENATED was not used, the only effect of LZMA_FINISH is that the amount of input must not be changed just like in the encoder.

Definition at line 250 of file base.h.

             {
    LZMA_RUN = 0,
    LZMA_SYNC_FLUSH = 1,
    LZMA_FULL_FLUSH = 2,
    LZMA_FULL_BARRIER = 4,
    LZMA_FINISH = 3
} lzma_action;

lzma_reserved_enum

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.

Enumerator
LZMA_RESERVED_ENUM

Definition at line 44 of file base.h.

             {
    LZMA_RESERVED_ENUM      = 0
} lzma_reserved_enum;

lzma_ret

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.

Enumerator
LZMA_OK	Operation completed successfully.
LZMA_STREAM_END	End of stream was reached. In encoder, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or LZMA_FINISH was finished. In decoder, this indicates that all the data was successfully decoded. In all cases, when LZMA_STREAM_END is returned, the last output bytes should be picked from strm->next_out.
LZMA_NO_CHECK	Input stream has no integrity check. This return value can be returned only if the LZMA_TELL_NO_CHECK flag was used when initializing the decoder. LZMA_NO_CHECK is just a warning, and the decoding can be continued normally. It is possible to call lzma_get_check() immediately after lzma_code has returned LZMA_NO_CHECK. The result will naturally be LZMA_CHECK_NONE, but the possibility to call lzma_get_check() may be convenient in some applications.
LZMA_UNSUPPORTED_CHECK	Cannot calculate the integrity check. The usage of this return value is different in encoders and decoders. Encoders can return this value only from the initialization function. If initialization fails with this value, the encoding cannot be done, because there's no way to produce output with the correct integrity check. Decoders can return this value only from lzma_code() and only if the LZMA_TELL_UNSUPPORTED_CHECK flag was used when initializing the decoder. The decoding can still be continued normally even if the check type is unsupported, but naturally the check will not be validated, and possible errors may go undetected. With decoder, it is possible to call lzma_get_check() immediately after lzma_code() has returned LZMA_UNSUPPORTED_CHECK. This way it is possible to find out what the unsupported Check ID was.
LZMA_GET_CHECK	Integrity check type is now available. This value can be returned only by the lzma_code() function and only if the decoder was initialized with the LZMA_TELL_ANY_CHECK flag. LZMA_GET_CHECK tells the application that it may now call lzma_get_check() to find out the Check ID. This can be used, for example, to implement a decoder that accepts only files that have strong enough integrity check.
LZMA_MEM_ERROR	Cannot allocate memory. Memory allocation failed, or the size of the allocation would be greater than SIZE_MAX. Due to internal implementation reasons, the coding cannot be continued even if more memory were made available after LZMA_MEM_ERROR.
LZMA_MEMLIMIT_ERROR
LZMA_FORMAT_ERROR	Memory usage limit was reached. Decoder would need more memory than allowed by the specified memory usage limit. To continue decoding, the memory usage limit has to be increased with lzma_memlimit_set(). File format not recognized The decoder did not recognize the input as supported file format. This error can occur, for example, when trying to decode .lzma format file with lzma_stream_decoder, because lzma_stream_decoder accepts only the .xz format.
LZMA_OPTIONS_ERROR	Invalid or unsupported options. Invalid or unsupported options, for example unsupported filter(s) or filter options; or reserved bits set in headers (decoder only). Rebuilding liblzma with more features enabled, or upgrading to a newer version of liblzma may help.
LZMA_DATA_ERROR	Data is corrupt. The usage of this return value is different in encoders and decoders. In both encoder and decoder, the coding cannot continue after this error. Encoders return this if size limits of the target file format would be exceeded. These limits are huge, thus getting this error from an encoder is mostly theoretical. For example, the maximum compressed and uncompressed size of a .xz Stream is roughly 8 EiB (2^63 bytes). Decoders return this error if the input data is corrupt. This can mean, for example, invalid CRC32 in headers or invalid check of uncompressed data.
LZMA_BUF_ERROR	No progress is possible. This error code is returned when the coder cannot consume any new input and produce any new output. The most common reason for this error is that the input stream being decoded is truncated or corrupt. This error is not fatal. Coding can be continued normally by providing more input and/or more output space, if possible. Typically the first call to lzma_code() that can do no progress returns LZMA_OK instead of LZMA_BUF_ERROR. Only the second consecutive call doing no progress will return LZMA_BUF_ERROR. This is intentional. With zlib, Z_BUF_ERROR may be returned even if the application is doing nothing wrong, so apps will need to handle Z_BUF_ERROR specially. The above hack guarantees that liblzma never returns LZMA_BUF_ERROR to properly written applications unless the input file is truncated or corrupt. This should simplify the applications a little.
LZMA_PROG_ERROR	Programming error. This indicates that the arguments given to the function are invalid or the internal state of the decoder is corrupt. Function arguments are invalid or the structures pointed by the argument pointers are invalid e.g. if strm->next_out has been set to NULL and strm->avail_out > 0 when calling lzma_code(). lzma_* functions have been called in wrong order e.g. lzma_code() was called right after lzma_end(). If errors occur randomly, the reason might be flaky hardware. If you think that your code is correct, this error code can be a sign of a bug in liblzma. See the documentation how to report bugs.

Definition at line 57 of file base.h.

             {
    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,
} lzma_ret;

Function Documentation

LZMA_API() [1/3]

LZMA_API

(

lzma_ret

)

Encode or decode data.

Decode a 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 .xz Index decoder.

Single-call .xz Index encoder.

Initialize .xz Index decoder.

Initialize .xz Index encoder.

Concatenate lzma_indexes.

Set the amount of Stream Padding.

Set the Stream Flags.

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.

Update the filter chain in the encoder.

Initialize raw decoder.

Initialize raw encoder.

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 .xz Stream encoder.

Initialize .lzma encoder (legacy file format)

Initialize multithreaded .xz Stream encoder.

Initialize .xz Stream encoder using a custom filter chain.

Single-call .xz Stream encoding using a preset number.

Single-call .xz Block decoder.

Single-call uncompressed .xz Block encoder.

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.

This function is supported only when *strm has been initialized with a function that takes a memlimit argument.

liblzma 5.2.3 and earlier has a bug where memlimit value of 0 causes this function to do nothing (leaving the limit unchanged) and still return LZMA_OK. Later versions treat 0 as if 1 had been specified (so lzma_memlimit_get() will return 1 even if you specify 0 here).

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.

The caller must have calculated the size of the Block Header already with lzma_block_header_size(). If a value larger 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.

block->version should (usually) be set to the highest value supported by the application. If the application sets block->version to a value higher than supported by the current liblzma version, this function will downgrade block->version to the highest value supported by it. Thus one should check the value of block->version after calling this function if block->version was set to a non-zero value and the application doesn't otherwise know that the liblzma version being used is new enough to support the specified block->version.

The size of the Block Header must have already been decoded with lzma_block_header_size_decode() macro and stored to block->header_size.

The integrity check type from Stream Header must have been stored to block->check.

block->filters must have been allocated, but they don't need to be initialized (possible existing filter options are not freed).

Parameters

block	Destination for Block options.
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. This can happen also if block->version was set to a too low value compared to what would be required to properly represent the information stored in the Block Header.
• 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 specifies a Check ID that is not supported by this build 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 have been 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_UNSUPPORTED_CHECK
• LZMA_OPTIONS_ERROR
• LZMA_MEM_ERROR
• LZMA_DATA_ERROR
• LZMA_PROG_ERROR

This is like lzma_block_buffer_encode() except this doesn't try to compress the data and instead encodes the data using LZMA2 uncompressed chunks. The required output buffer size can be determined with lzma_block_buffer_bound().

Since the data won't be compressed, this function ignores block->filters. This function doesn't take lzma_allocator because this function doesn't allocate any memory from the heap.

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

The maximum required output buffer size can be calculated with lzma_stream_buffer_bound().

Parameters

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].

Returns

- LZMA_OK: Encoding was successful.

• LZMA_BUF_ERROR: Not enough output buffer space.
• LZMA_UNSUPPORTED_CHECK
• LZMA_OPTIONS_ERROR
• LZMA_MEM_ERROR
• LZMA_DATA_ERROR
• 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_UNSUPPORTED_CHECK
• LZMA_OPTIONS_ERROR
• LZMA_PROG_ERROR

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.

Parameters

strm	Pointer to properly prepared lzma_stream
options	Pointer to multithreaded compression options

Returns

- LZMA_OK

• LZMA_MEM_ERROR
• LZMA_UNSUPPORTED_CHECK
• 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_UNSUPPORTED_CHECK
• LZMA_OPTIONS_ERROR
• LZMA_MEM_ERROR
• LZMA_DATA_ERROR
• LZMA_PROG_ERROR

Parameters

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_CONCATENATED

Returns

- LZMA_OK: Initialization was successful.

• LZMA_MEM_ERROR: Cannot allocate memory.
• LZMA_OPTIONS_ERROR: Unsupported flags
• LZMA_PROG_ERROR

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	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 flags, or zero for no flags.

Returns

- LZMA_OK: Initialization was successful.

• LZMA_MEM_ERROR: Cannot allocate memory.
• LZMA_OPTIONS_ERROR: Unsupported flags
• LZMA_PROG_ERROR

Parameters

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.

Returns

- LZMA_OK

• LZMA_MEM_ERROR
• LZMA_PROG_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 decoding 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

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 ‘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

This function is for advanced users only. This function has two slightly different purposes:

• After LZMA_FULL_FLUSH when using Stream encoder: Set a new filter chain, which will be used starting from the next Block.
• After LZMA_SYNC_FLUSH using Raw, Block, or Stream encoder: Change the filter-specific options in the middle of encoding. The actual filters in the chain (Filter IDs) cannot be changed. In the future, it might become possible to change the filter options without using LZMA_SYNC_FLUSH.

While rarely useful, this function may be called also when no data has been compressed yet. In that case, this function will behave as if LZMA_FULL_FLUSH (Stream encoder) or LZMA_SYNC_FLUSH (Raw or Block encoder) had been used right before calling this function.

Returns

- LZMA_OK

• LZMA_MEM_ERROR
• LZMA_MEMLIMIT_ERROR
• LZMA_OPTIONS_ERROR
• LZMA_PROG_ERROR

Parameters

filters	Array of lzma_filter structures. The end of the array must be marked with .id = LZMA_VLI_UNKNOWN.
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

Note

There is no function to calculate how big output buffer would surely be big enough. (lzma_stream_buffer_bound() works only for lzma_stream_buffer_encode(); raw encoder won't necessarily meet that bound.)

Parameters

filters	Array of lzma_filter structures. The end of the array must be marked with .id = LZMA_VLI_UNKNOWN.
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 properties 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.

If lzma_properties_size() indicated that the size of the Filter Properties field is zero, calling lzma_properties_encode() is not required, but it won't do any harm either.

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 in filter->options; it's application's responsibility to free it when appropriate. 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
filter	Filter ID and associated options whose encoded size is to be calculated

Returns

- LZMA_OK: *size set successfully. Note that this doesn't guarantee that filter->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

filter	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 *filter. The old value of filter->options is not free()d.

Returns

- LZMA_OK

• LZMA_OPTIONS_ERROR
• LZMA_MEM_ERROR
• LZMA_PROG_ERROR

Set the Stream Flags of the last (and typically the only) Stream in lzma_index. This can be useful when reading information from the lzma_index, because to decode Blocks, knowing the integrity check type is needed.

The given Stream Flags are copied into internal preallocated structure in the lzma_index, thus the caller doesn't need to keep the *stream_flags available after calling this function.

Returns

- LZMA_OK

• LZMA_OPTIONS_ERROR: Unsupported stream_flags->version.
• LZMA_PROG_ERROR

Set the amount of Stream Padding of the last (and typically the only) Stream in the lzma_index. This is needed when planning to do random-access reading within multiple concatenated Streams.

By default, the amount of Stream Padding is assumed to be zero bytes.

Returns

- LZMA_OK

• LZMA_DATA_ERROR: The file size would grow too big.
• LZMA_PROG_ERROR

Concatenating lzma_indexes is useful when doing random-access reading in multi-Stream .xz file, or when combining multiple Streams into single Stream.

Parameters

dest	lzma_index after which src is appended
src	lzma_index to be appended after dest. If this function succeeds, the memory allocated for src is freed or moved to be part of dest, and all iterators pointing to src will become invalid.
allocator	Custom memory allocator; can be NULL to use malloc() and free().

Returns

- LZMA_OK: lzma_indexes were concatenated successfully. src is now a dangling pointer.

• 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 valid ‘action’ values for lzma_code() are LZMA_RUN and LZMA_FINISH. It is enough to use only one of them (you can choose freely).

Returns

- LZMA_OK: Initialization succeeded, continue with lzma_code().

• LZMA_MEM_ERROR
• LZMA_PROG_ERROR

Parameters

strm	Pointer to properly prepared lzma_stream
i	The decoded Index will be made available via this pointer. Initially this function will set *i to NULL (the old value is ignored). If decoding succeeds (lzma_code() returns LZMA_STREAM_END), *i will be set to point to a new lzma_index, which the application has to later free with lzma_index_end().
memlimit	How much memory the resulting lzma_index is allowed to require. 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.

Returns

- LZMA_OK: Initialization succeeded, continue with lzma_code().

• LZMA_MEM_ERROR
• LZMA_PROG_ERROR

liblzma 5.2.3 and older list also LZMA_MEMLIMIT_ERROR here but that error code has never been possible from this initialization function.

Parameters

i	lzma_index to be encoded
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	If decoding succeeds, *i will point to a new lzma_index, which the application has to later free with lzma_index_end(). If an error occurs, *i will be NULL. The old value of *i is always ignored and thus doesn't need to be initialized by the caller.
memlimit	Pointer to how much memory the resulting lzma_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	Target for the decoded Stream Header options.
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	Target for the decoded Stream Header options.
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 in multi-call mode, *vli_pos must be initialized to zero. To use single-call decoding, set vli_pos 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.

Definition at line 328 of file block_buffer_encoder.c.

{
    // It won't allocate any memory from heap so no need
    // for lzma_allocator.
    return block_buffer_encode(block, NULL,
            in, in_size, out, out_pos, out_size, false);
}

References block_buffer_encode(), in, in_size, NULL, out, and out_pos.

LZMA_API() [2/3]

LZMA_API

(

uint64_t

)

const

Get the memory usage of decoder filter chain.

Get the uncompressed size of the file.

Get the total size of the file.

Get the total size of the Blocks.

Get the total size of the Stream.

Get the size of the Index field as bytes.

Get the number of Blocks.

Get the number of Streams.

Calculate the memory usage of an existing lzma_index.

Calculate approximate memory requirements for raw decoder.

Calculate approximate memory usage of multithreaded .xz encoder.

Calculate approximate 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.

Returns

How much memory is currently allocated for the filter decoders. If no filter chain is currently allocated, some non-zero value is still returned, which is less than or equal to what any filter chain would indicate as its memory requirement.

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.

Returns

On success, the current memory usage limit is returned (always non-zero). On error, zero is returned.

This is equivalent to lzma_block_unpadded_size() except that the returned value includes the size of the Block Padding field.

Returns

On success, total encoded size of the Block. On error, zero is returned.

This function is a wrapper for lzma_raw_decoder_memusage().

Parameters

preset

Compression preset (level and possible flags)

Returns

Number of bytes of memory required to decompress a file that was compressed using the given preset. If an error occurs, for example due to unsupported preset, UINT64_MAX is returned.

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.

Parameters

options

Compression options

Returns

Number of bytes of memory required for encoding with the given options. If an error occurs, for example due to unsupported preset or filter chain, UINT64_MAX is returned.

This function can be used to calculate the memory requirements for Block and Stream decoders too because Block and Stream decoders don't need significantly more memory than raw decoder.

Parameters

filters

Array of filters terminated with .id == LZMA_VLI_UNKNOWN.

Returns

Number of bytes of memory required for the given filter chain when decoding. If an error occurs, for example due to unsupported filter chain, UINT64_MAX is returned.

This is a shorthand for lzma_index_memusage(lzma_index_stream_count(i), lzma_index_block_count(i)).

This returns the total number of Blocks in lzma_index. To get number of Blocks in individual Streams, use lzma_index_iter.

This is needed to verify the Backward Size field in the Stream Footer.

If multiple lzma_indexes have been combined, this works as if the Blocks were in a single Stream. This is useful if you are going to combine Blocks from multiple Streams into a single new Stream.

This doesn't include the Stream Header, Stream Footer, Stream Padding, or Index fields.

When no lzma_indexes have been combined with lzma_index_cat() and there is no Stream Padding, this function is identical to lzma_index_stream_size(). If multiple lzma_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.

Calculate CRC64 using the polynomial from the ECMA-182 standard.

This function is used similarly to lzma_crc32(). See its documentation.

Definition at line 81 of file block_util.c.

{
    lzma_vli unpadded_size = lzma_block_unpadded_size(block);
 
    if (unpadded_size != LZMA_VLI_UNKNOWN)
        unpadded_size = vli_ceil4(unpadded_size);
 
    return unpadded_size;
}

References LZMA_VLI_UNKNOWN, unpadded_size, and vli_ceil4().

LZMA_API() [3/3]

LZMA_API

(

void

)

Free memory allocated for the coder data structures.

Rewind the iterator.

Initialize an iterator.

Get progress information.

Parameters

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.

Note

zlib indicates an error if application end()s unfinished stream structure. liblzma doesn't do this, and assumes that application knows what it is doing.

In single-threaded mode, applications can get progress information from strm->total_in and strm->total_out. In multi-threaded mode this is less useful because a significant amount of both input and output data gets buffered internally by liblzma. This makes total_in and total_out give misleading information and also makes the progress indicator updates non-smooth.

This function gives realistic progress information also in multi-threaded mode by taking into account the progress made by each thread. In single-threaded mode *progress_in and *progress_out are set to strm->total_in and strm->total_out, respectively.

Parameters

iter	Pointer to a lzma_index_iter structure
i	lzma_index to which the iterator will be associated

This function associates the iterator with the given lzma_index, and calls lzma_index_iter_rewind() on the iterator.

This function doesn't allocate any memory, thus there is no lzma_index_iter_end(). The iterator is valid as long as the associated lzma_index is valid, that is, until lzma_index_end() or using it as source in lzma_index_cat(). Specifically, lzma_index doesn't become invalid if new Blocks are added to it with lzma_index_append() or if it is used as the destination in lzma_index_cat().

It is safe to make copies of an initialized lzma_index_iter, for example, to easily restart reading at some particular position.

Rewind the iterator so that next call to lzma_index_iter_next() will return the first Block or Stream.

Definition at line 369 of file common.c.

{
    if (strm->internal->next.get_progress != NULL) {
        strm->internal->next.get_progress(strm->internal->next.coder,
                progress_in, progress_out);
    } else {
        *progress_in = strm->total_in;
        *progress_out = strm->total_out;
    }
 
    return;
}

References lzma_next_coder_s::coder, lzma_next_coder_s::get_progress, lzma_stream::internal, lzma_internal_s::next, NULL, progress_in, strm, lzma_stream::total_in, and lzma_stream::total_out.

Variable Documentation

lzma_attr_warn_unused_result

lzma_action action lzma_nothrow lzma_attr_warn_unused_result

Definition at line 564 of file base.h.

lzma_nothrow

uint64_t memlimit lzma_nothrow

Definition at line 599 of file base.h.

progress_in

uint64_t* progress_in

Definition at line 599 of file base.h.

Referenced by get_progress(), and LZMA_API().