src/liblzma/api/lzma/base.h File Reference

Data types and functions used in many places of the public API. More...

Data Structures

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

Defines

#define LZMA_STREAM_INIT
 Initialization for lzma_stream.

Typedefs

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

Enumerations

enum  lzma_reserved_enum { LZMA_RESERVED_ENUM = 0 }
 

Type of reserved enumeration variable in structures.

More...
enum  lzma_ret {
  LZMA_OK = 0, LZMA_STREAM_END = 1, LZMA_NO_CHECK = 2, LZMA_UNSUPPORTED_CHECK = 3,
  LZMA_GET_CHECK = 4, LZMA_MEM_ERROR = 5, LZMA_MEMLIMIT_ERROR = 6, LZMA_FORMAT_ERROR = 7,
  LZMA_OPTIONS_ERROR = 8, LZMA_DATA_ERROR = 9, LZMA_BUF_ERROR = 10, LZMA_PROG_ERROR = 11
}
 

Return values used by several functions in liblzma.

More...
enum  lzma_action { LZMA_RUN = 0, LZMA_SYNC_FLUSH = 1, LZMA_FULL_FLUSH = 2, LZMA_FINISH = 3 }
 

The `action' argument for lzma_code().

More...

Functions

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

Variables

lzma_action action lzma_attr_warn_unused_result
uint64_t memlimit

Detailed Description

Data types and functions used in many places of the public API.

Author:
Copyright (C) 1999-2006 Igor Pavlov
Copyright (C) 2007 Lasse Collin

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.


Define Documentation

#define LZMA_STREAM_INIT
Value:
{ NULL, 0, 0, NULL, 0, 0, NULL, NULL, \
        NULL, NULL, 0, 0, LZMA_RESERVED_ENUM, LZMA_RESERVED_ENUM }

Initialization for lzma_stream.

When you declare an instance of lzma_stream, you can immediatelly initialize it so that initialization functions know that no memory has been allocated yet:

lzma_stream strm = LZMA_STREAM_INIT;

If you need to initialize a dynamically allocated lzma_stream, you can use memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this violates the C standard since NULL may have different internal representation than zero, but it should be portable enough in practice. Anyway, for maximum portability, you can use something like this:

lzma_stream tmp = LZMA_STREAM_INIT; *strm = tmp;


Typedef Documentation

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

Internal data structure.

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


Enumeration Type Documentation

Type of reserved enumeration variable in structures.

To avoid breaking library ABI when new features are added, several structures contain extra variables that may be used in future. Since sizeof(enum) can be different than sizeof(int), and sizeof(enum) may even vary depending on the range of enumeration constants, we specify a separate type to be used for reserved enumeration variables. All enumeration constants in liblzma API will be non-negative and less than 128, which should guarantee that the ABI won't break even when new constants are added to existing enumerations.

enum lzma_ret

Return values used by several functions in liblzma.

Check the descriptions of specific functions to find out which return values they can return. With some functions the return values may have more specific meanings than described here; those differences are described per-function basis.

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() immediatelly 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() immediatelly 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_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(). 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 created with lzma_stream_encoder is 2^63 - 1 bytes (one byte less than 8 EiB).

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

The `action' argument for lzma_code().

After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or LZMA_FINISH, the same `action' must is used until lzma_code() returns LZMA_STREAM_END. Also, the amount of input (that is, strm->avail_in) must not be modified by the application until lzma_code() returns LZMA_STREAM_END. Changing the `action' or modifying the amount of input will make lzma_code() return LZMA_PROG_ERROR.

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), finetuning the compression options may help mitigate this problem significantly.

Decoders don't support LZMA_SYNC_FLUSH.

LZMA_FULL_FLUSH 

Make all the input available at output.

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_FINISH 

Finish the coding operation.

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


Function Documentation

LZMA_API ( lzma_ret   ) 

Encode or decode data.

Decodes variable-length integer.

Compare two lzma_stream_flags structures.

Decode Stream Footer.

Decode Stream Header.

Encode Stream Footer.

Decode and validate the Index field.

Single-call Index decoder.

Single-call Index encoder.

Initialize Index decoder.

Initialize Index encoder.

Concatenate Indexes of two Streams.

Decode Filter Flags from given buffer.

Encode Filter Flags into given buffer.

Calculate encoded size of a Filter Flags field.

Decode the Filter Properties field.

Encode the Filter Properties field.

Get the size of the Filter Properties field.

Single-call raw decoder.

Single-call raw encoder.

Initialize raw decoder.

Single-call .xz Stream decoder.

Initialize .lzma decoder (legacy file format).

Decode .xz Streams and .lzma files with autodetection.

Initialize .xz Stream decoder.

Single-call Stream encoder.

Initialize .lzma encoder (legacy file format).

Initialize .xz Stream encoder using a custom filter chain.

Single-call .xz Block decoder.

Single-call .xz Block encoder.

Initialize .xz Block decoder.

Initialize .xz Block encoder.

Validate and set Compressed Size according to Unpadded Size.

Decode Block Header.

Encode Block Header.

Set the memory usage limit.

Once the lzma_stream has been successfully initialized (e.g. with lzma_stream_encoder()), the actual encoding or decoding is done using this function. The application has to update strm->next_in, strm->avail_in, strm->next_out, and strm->avail_out to pass input to and get output from liblzma.

See the description of the coder-specific initialization function to find out what `action' values are supported by the coder. See documentation of lzma_ret for the possible return values.

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

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.

References LZMA_FILTERS_MAX, LZMA_OK, LZMA_PROG_ERROR, lzma_vli_is_valid, LZMA_VLI_UNKNOWN, and return_if_error.

LZMA_API ( void   ) 

Free memory allocated for the coder data structures.

Rewind the Index.

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.

Rewind the Index so that next call to lzma_index_read() will return the first Record.

Free memory allocated for the coder data structures.

Rewind the Index.

If i is NULL, this does nothing.

Rewind the Index so that next call to lzma_index_read() will return the first Record.

LZMA_API ( uint64_t   )  const

Get the memory usage of decoder filter chain.

Get the uncompressed size of the Stream.

Get the total size of the file.

Get the total size of the Stream.

Get the total size of the Blocks.

Get the size of the Index field as bytes.

Get the number of Records.

Calculate rough memory requirements for raw decoder.

Calculate rough decoder memory usage of a preset.

Calculate the total encoded size of a Block.

Get the current memory usage limit.

This function is currently supported only when *strm has been initialized with a function that takes a memlimit argument. With other functions, you should use e.g. lzma_raw_encoder_memusage() or lzma_raw_decoder_memusage() to estimate the memory requirements.

This function is useful e.g. after LZMA_MEMLIMIT_ERROR to find out how big the memory usage limit should have been to decode the input. Note that this may give misleading information if decoding .xz Streams that have multiple Blocks, because each Block can have different memory requirements.

Returns:
Rough estimate of 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)
filters Array of filters terminated with .id == LZMA_VLI_UNKNOWN.
Returns:
Rough number of bytes required for the given filter chain when decoding.

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

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

If multiple Indexes have been combined, this works as if the Blocks were in a single Stream.

When no Indexes have been combined with lzma_index_cat(), this function is identical to lzma_index_stream_size(). If multiple Indexes have been combined, this includes also the headers of each separate Stream and the possible Stream Padding fields.

Get the memory usage of decoder filter chain.

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

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


Generated on Tue Oct 6 14:02:22 2009 for XZ Utils by  doxygen 1.6.1