Common filter related types and functions. More...

Data Structures
struct	lzma_filter
	Filter options. More...

Macros
#define	LZMA_FILTERS_MAX 4
	Maximum number of filters in a chain.

#define	LZMA_STR_ALL_FILTERS UINT32_C(0x01)
	Allow or show all filters.

#define	LZMA_STR_NO_VALIDATION UINT32_C(0x02)
	Do not validate the filter chain in lzma_str_to_filters()

#define	LZMA_STR_ENCODER UINT32_C(0x10)
	Stringify encoder options.

#define	LZMA_STR_DECODER UINT32_C(0x20)
	Stringify decoder options.

#define	LZMA_STR_GETOPT_LONG UINT32_C(0x40)
	Produce xz-compatible getopt_long() syntax.

#define	LZMA_STR_NO_SPACES UINT32_C(0x80)
	Use two dashes "--" instead of a space to separate filters.

Functions
lzma_bool	lzma_filter_encoder_is_supported (lzma_vli id) lzma_nothrow lzma_attr_const
	Test if the given Filter ID is supported for encoding.

lzma_bool	lzma_filter_decoder_is_supported (lzma_vli id) lzma_nothrow lzma_attr_const
	Test if the given Filter ID is supported for decoding.

lzma_ret	lzma_filters_copy (const lzma_filter src, lzma_filter dest, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
	Copy the filters array.

void	lzma_filters_free (lzma_filter filters, const lzma_allocator allocator) lzma_nothrow
	Free the options in the array of lzma_filter structures.

uint64_t	lzma_raw_encoder_memusage (const lzma_filter *filters) lzma_nothrow lzma_attr_pure
	Calculate approximate memory requirements for raw encoder.

uint64_t	lzma_raw_decoder_memusage (const lzma_filter *filters) lzma_nothrow lzma_attr_pure
	Calculate approximate memory requirements for raw decoder.

lzma_ret	lzma_raw_encoder (lzma_stream strm, const lzma_filter filters) lzma_nothrow lzma_attr_warn_unused_result
	Initialize raw encoder.

lzma_ret	lzma_raw_decoder (lzma_stream strm, const lzma_filter filters) lzma_nothrow lzma_attr_warn_unused_result
	Initialize raw decoder.

lzma_ret	lzma_filters_update (lzma_stream strm, const lzma_filter filters) lzma_nothrow
	Update the filter chain in the encoder.

lzma_ret	lzma_raw_buffer_encode (const lzma_filter filters, const lzma_allocator allocator, const uint8_t in, size_t in_size, uint8_t out, size_t *out_pos, size_t out_size) lzma_nothrow
	Single-call raw encoder.

lzma_ret	lzma_raw_buffer_decode (const lzma_filter filters, const lzma_allocator allocator, const uint8_t in, size_t in_pos, size_t in_size, uint8_t out, size_t out_pos, size_t out_size) lzma_nothrow
	Single-call raw decoder.

lzma_ret	lzma_properties_size (uint32_t size, const lzma_filter filter) lzma_nothrow
	Get the size of the Filter Properties field.

lzma_ret	lzma_properties_encode (const lzma_filter filter, uint8_t props) lzma_nothrow
	Encode the Filter Properties field.

lzma_ret	lzma_properties_decode (lzma_filter filter, const lzma_allocator allocator, const uint8_t *props, size_t props_size) lzma_nothrow
	Decode the Filter Properties field.

lzma_ret	lzma_filter_flags_size (uint32_t size, const lzma_filter filter) lzma_nothrow lzma_attr_warn_unused_result
	Calculate encoded size of a Filter Flags field.

lzma_ret	lzma_filter_flags_encode (const lzma_filter filter, uint8_t out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result
	Encode Filter Flags into given buffer.

lzma_ret	lzma_filter_flags_decode (lzma_filter filter, const lzma_allocator allocator, const uint8_t in, size_t in_pos, size_t in_size) lzma_nothrow lzma_attr_warn_unused_result
	Decode Filter Flags from given buffer.

const char *	lzma_str_to_filters (const char str, int error_pos, lzma_filter filters, uint32_t flags, const lzma_allocator allocator) lzma_nothrow lzma_attr_warn_unused_result
	Convert a string to a filter chain.

lzma_ret	lzma_str_from_filters (char *str, const lzma_filter filters, uint32_t flags, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
	Convert a filter chain to a string.

lzma_ret	lzma_str_list_filters (char *str, lzma_vli filter_id, uint32_t flags, const lzma_allocator allocator) lzma_nothrow lzma_attr_warn_unused_result
	List available filters and/or their options (for help message)

Detailed Description

Common filter related types and functions.

Note: Never include this file directly. Use <lzma.h> instead.

Macro Definition Documentation

◆ LZMA_FILTERS_MAX

#define LZMA_FILTERS_MAX 4

Maximum number of filters in a chain.

A filter chain can have 1-4 filters, of which three are allowed to change the size of the data. Usually only one or two filters are needed.

◆ LZMA_STR_ALL_FILTERS

#define LZMA_STR_ALL_FILTERS UINT32_C(0x01)

Allow or show all filters.

By default only the filters supported in the .xz format are accept by lzma_str_to_filters() or shown by lzma_str_list_filters().

◆ LZMA_STR_NO_VALIDATION

#define LZMA_STR_NO_VALIDATION UINT32_C(0x02)

Do not validate the filter chain in lzma_str_to_filters()

By default lzma_str_to_filters() can return an error if the filter chain as a whole isn't usable in the .xz format or in the raw encoder or decoder. With this flag, this validation is skipped. This flag doesn't affect the handling of the individual filter options. To allow non-.xz filters also LZMA_STR_ALL_FILTERS is needed.

◆ LZMA_STR_ENCODER

#define LZMA_STR_ENCODER UINT32_C(0x10)

Stringify encoder options.

Show the filter-specific options that the encoder will use. This may be useful for verbose diagnostic messages.

Note that if options were decoded from .xz headers then the encoder options may be undefined. This flag shouldn't be used in such a situation.

◆ LZMA_STR_DECODER

#define LZMA_STR_DECODER UINT32_C(0x20)

Stringify decoder options.

Show the filter-specific options that the decoder will use. This may be useful for showing what filter options were decoded from file headers.

◆ LZMA_STR_GETOPT_LONG

#define LZMA_STR_GETOPT_LONG UINT32_C(0x40)

Produce xz-compatible getopt_long() syntax.

That is, "delta:dist=2 lzma2:dict=4MiB,pb=1,lp=1" becomes "--delta=dist=2 --lzma2=dict=4MiB,pb=1,lp=1".

This syntax is compatible with xz 5.0.0 as long as the filters and their options are supported too.

◆ LZMA_STR_NO_SPACES

#define LZMA_STR_NO_SPACES UINT32_C(0x80)

Use two dashes "--" instead of a space to separate filters.

That is, "delta:dist=2 lzma2:pb=1,lp=1" becomes "delta:dist=2--lzma2:pb=1,lp=1". This looks slightly odd but this kind of strings should be usable on the command line without quoting. However, it is possible that future versions with new filter options might produce strings that require shell quoting anyway as the exact set of possible characters isn't frozen for now.

It is guaranteed that the single quote (') will never be used in filter chain strings (even if LZMA_STR_NO_SPACES isn't used).

Function Documentation

◆ lzma_filter_encoder_is_supported()

lzma_bool lzma_filter_encoder_is_supported ( lzma_vli id ) const

extern

Test if the given Filter ID is supported for encoding.

Parameters

id Filter ID

Returns

lzma_bool:

true if the Filter ID is supported for encoding by this liblzma build.
false otherwise.

◆ lzma_filter_decoder_is_supported()

lzma_bool lzma_filter_decoder_is_supported ( lzma_vli id ) const

extern

Test if the given Filter ID is supported for decoding.

Parameters

id Filter ID

Returns

lzma_bool:

true if the Filter ID is supported for decoding by this liblzma build.
false otherwise.

◆ lzma_filters_copy()

lzma_ret lzma_filters_copy	(	const lzma_filter *	src,
		lzma_filter *	dest,
		const lzma_allocator *	allocator
	)

extern

Copy the filters array.

Copy the Filter IDs and filter-specific options from src to dest. Up to LZMA_FILTERS_MAX filters are copied, plus the terminating .id == LZMA_VLI_UNKNOWN. Thus, dest should have at least LZMA_FILTERS_MAX + 1 elements space unless the caller knows that src is smaller than that.

Unless the filter-specific options is NULL, the Filter ID has to be supported by liblzma, because liblzma needs to know the size of every filter-specific options structure. The filter-specific options are not validated. If options is NULL, any unsupported Filter IDs are copied without returning an error.

Old filter-specific options in dest are not freed, so dest doesn't need to be initialized by the caller in any way.

If an error occurs, memory possibly already allocated by this function is always freed. liblzma versions older than 5.2.7 may modify the dest array and leave its contents in an undefined state if an error occurs. liblzma 5.2.7 and newer only modify the dest array when returning LZMA_OK.

Parameters

	src	Array of filters terminated with .id == LZMA_VLI_UNKNOWN.
[out]	dest	Destination filter array
	allocator	lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().

Returns

Possible lzma_ret values:

LZMA_OK
LZMA_MEM_ERROR
LZMA_OPTIONS_ERROR: Unsupported Filter ID and its options is not NULL.
LZMA_PROG_ERROR: src or dest is NULL.

◆ lzma_filters_free()

void lzma_filters_free	(	lzma_filter *	filters,
		const lzma_allocator *	allocator
	)

extern

Free the options in the array of lzma_filter structures.

This frees the filter chain options. The filters array itself is not freed.

The filters array must have at most LZMA_FILTERS_MAX + 1 elements including the terminating element which must have .id = LZMA_VLI_UNKNOWN. For all elements before the terminating element:

options will be freed using the given lzma_allocator or, if allocator is NULL, using free().
options will be set to NULL.
id will be set to LZMA_VLI_UNKNOWN.

If filters is NULL, this does nothing. Again, this never frees the filters array itself.

Parameters

filters	Array of filters terminated with .id == LZMA_VLI_UNKNOWN.
allocator	lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().

◆ lzma_raw_encoder_memusage()

uint64_t lzma_raw_encoder_memusage ( const lzma_filter * filters )

extern

Calculate approximate memory requirements for raw encoder.

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

Parameters

filters Array of filters terminated with .id == LZMA_VLI_UNKNOWN.

Returns: Number of bytes of memory required for the given filter chain when encoding or UINT64_MAX on error.

◆ lzma_raw_decoder_memusage()

uint64_t lzma_raw_decoder_memusage ( const lzma_filter * filters )

extern

Calculate approximate memory requirements for raw decoder.

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 or UINT64_MAX on error.

◆ lzma_raw_encoder()

lzma_ret lzma_raw_encoder	(	lzma_stream *	strm,
		const lzma_filter *	filters
	)

extern

Initialize raw encoder.

This function may be useful when implementing custom file formats.

The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the filter chain supports it), or LZMA_FINISH.

Parameters

strm	Pointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
filters	Array of filters terminated with .id == LZMA_VLI_UNKNOWN.

Returns

Possible lzma_ret values:

LZMA_OK
LZMA_MEM_ERROR
LZMA_OPTIONS_ERROR
LZMA_PROG_ERROR

◆ lzma_raw_decoder()

lzma_ret lzma_raw_decoder	(	lzma_stream *	strm,
		const lzma_filter *	filters
	)

extern

Initialize raw decoder.

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.

Parameters

strm	Pointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
filters	Array of filters terminated with .id == LZMA_VLI_UNKNOWN.

Returns

Possible lzma_ret values:

LZMA_OK
LZMA_MEM_ERROR
LZMA_OPTIONS_ERROR
LZMA_PROG_ERROR

◆ lzma_filters_update()

lzma_ret lzma_filters_update	(	lzma_stream *	strm,
		const lzma_filter *	filters
	)

extern

Update the filter chain in the encoder.

This function may be called after lzma_code() has returned LZMA_STREAM_END when LZMA_FULL_BARRIER, LZMA_FULL_FLUSH, or LZMA_SYNC_FLUSH was used:

After LZMA_FULL_BARRIER or LZMA_FULL_FLUSH: Single-threaded .xz Stream encoder (lzma_stream_encoder()) and (since liblzma 5.4.0) multi-threaded Stream encoder (lzma_stream_encoder_mt()) allow setting a new filter chain to be used for the next Block(s).
After LZMA_SYNC_FLUSH: Raw encoder (lzma_raw_encoder()), Block encoder (lzma_block_encoder()), and single-threaded .xz Stream encoder (lzma_stream_encoder()) allow changing certain filter-specific options in the middle of encoding. The actual filters in the chain (Filter IDs) must not be changed! Currently only the lc, lp, and pb options of LZMA2 (not LZMA1) can be changed this way.
In the future some filters might allow changing some of their options without any barrier or flushing but currently such filters don't exist.

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

Parameters

strm	Pointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
filters	Array of filters terminated with .id == LZMA_VLI_UNKNOWN.

Returns

Possible lzma_ret values:

LZMA_OK
LZMA_MEM_ERROR
LZMA_MEMLIMIT_ERROR
LZMA_OPTIONS_ERROR
LZMA_PROG_ERROR

◆ lzma_raw_buffer_encode()

lzma_ret lzma_raw_buffer_encode	(	const lzma_filter *	filters,
		const lzma_allocator *	allocator,
		const uint8_t *	in,
		size_t	in_size,
		uint8_t *	out,
		size_t *	out_pos,
		size_t	out_size
	)

extern

Single-call raw encoder.

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 filters terminated 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]	out	Beginning of the output buffer
[out]	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

Possible lzma_ret values:

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

◆ lzma_raw_buffer_decode()

lzma_ret lzma_raw_buffer_decode	(	const lzma_filter *	filters,
		const lzma_allocator *	allocator,
		const uint8_t *	in,
		size_t *	in_pos,
		size_t	in_size,
		uint8_t *	out,
		size_t *	out_pos,
		size_t	out_size
	)

extern

Single-call raw decoder.

Parameters

	filters	Array of filters terminated 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]	out	Beginning of the output buffer
[out]	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

Possible lzma_ret values:

LZMA_OK: Decoding was successful.
LZMA_BUF_ERROR: Not enough output buffer space.
LZMA_OPTIONS_ERROR
LZMA_MEM_ERROR
LZMA_DATA_ERROR
LZMA_PROG_ERROR

◆ lzma_properties_size()

lzma_ret lzma_properties_size	(	uint32_t *	size,
		const lzma_filter *	filter
	)

extern

Get the size of the Filter Properties field.

This function may be useful when implementing custom file formats using the raw encoder and decoder.

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

[out]	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

Possible lzma_ret values:

LZMA_OK
LZMA_OPTIONS_ERROR
LZMA_PROG_ERROR

◆ lzma_properties_encode()

lzma_ret lzma_properties_encode	(	const lzma_filter *	filter,
		uint8_t *	props
	)

extern

Encode the Filter Properties field.

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 and options
[out]	props	Buffer to hold the encoded options. The size of the buffer must have been already determined with lzma_properties_size().

Returns

Possible lzma_ret values:

LZMA_OK
LZMA_PROG_ERROR

◆ lzma_properties_decode()

lzma_ret lzma_properties_decode	(	lzma_filter *	filter,
		const lzma_allocator *	allocator,
		const uint8_t *	props,
		size_t	props_size
	)

extern

Decode the Filter Properties field.

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	lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free(). 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

Possible lzma_ret values:

LZMA_OK
LZMA_OPTIONS_ERROR
LZMA_MEM_ERROR

◆ lzma_filter_flags_size()

lzma_ret lzma_filter_flags_size	(	uint32_t *	size,
		const lzma_filter *	filter
	)

extern

Calculate encoded size of a Filter Flags field.

Knowing the size of Filter Flags is useful to know when allocating memory to hold the encoded Filter Flags.

Note: If you need to calculate size of List of Filter Flags, you need to loop over every lzma_filter entry.

Parameters

[out]	size	Pointer to integer to hold the calculated size
	filter	Filter ID and associated options whose encoded size is to be calculated

Returns

Possible lzma_ret values:

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

◆ lzma_filter_flags_encode()

lzma_ret lzma_filter_flags_encode	(	const lzma_filter *	filter,
		uint8_t *	out,
		size_t *	out_pos,
		size_t	out_size
	)

extern

Encode Filter Flags into given buffer.

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]	out	Beginning of the output buffer
[out]	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

Possible lzma_ret values:

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

◆ lzma_filter_flags_decode()

lzma_ret lzma_filter_flags_decode	(	lzma_filter *	filter,
		const lzma_allocator *	allocator,
		const uint8_t *	in,
		size_t *	in_pos,
		size_t	in_size
	)

extern

Decode Filter Flags from given buffer.

The decoded result is stored into *filter. The old value of filter->options is not free()d. If anything other than LZMA_OK is returned, filter->options is set to NULL.

Parameters

[out]	filter	Destination filter. The decoded Filter ID will be stored in filter->id. If options are needed they will be allocated and the pointer will be stored in filter->options.
	allocator	lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
	in	Beginning of the input buffer
[out]	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

Possible lzma_ret values:

LZMA_OK
LZMA_OPTIONS_ERROR
LZMA_MEM_ERROR
LZMA_DATA_ERROR
LZMA_PROG_ERROR

◆ lzma_str_to_filters()

const char * lzma_str_to_filters	(	const char *	str,
		int *	error_pos,
		lzma_filter *	filters,
		uint32_t	flags,
		const lzma_allocator *	allocator
	)

extern

Convert a string to a filter chain.

This tries to make it easier to write applications that allow users to set custom compression options. This only handles the filter configuration (including presets) but not the number of threads, block size, check type, or memory limits.

The input string can be either a preset or a filter chain. Presets begin with a digit 0-9 and may be followed by zero or more flags which are lower-case letters. Currently only "e" is supported, matching LZMA_PRESET_EXTREME. For partial xz command line syntax compatibility, a preset string may start with a single dash "-".

A filter chain consists of one or more "filtername:opt1=value1,opt2=value2" strings separated by one or more spaces. Leading and trailing spaces are ignored. All names and values must be lower-case. Extra commas in the option list are ignored. The order of filters is significant: when encoding, the uncompressed input data goes to the leftmost filter first. Normally "lzma2" is the last filter in the chain.

If one wishes to avoid spaces, for example, to avoid shell quoting, it is possible to use two dashes "--" instead of spaces to separate the filters.

For xz command line compatibility, each filter may be prefixed with two dashes "--" and the colon ":" separating the filter name from the options may be replaced with an equals sign "=".

By default, only filters that can be used in the .xz format are accepted. To allow all filters (LZMA1) use the flag LZMA_STR_ALL_FILTERS.

By default, very basic validation is done for the filter chain as a whole, for example, that LZMA2 is only used as the last filter in the chain. The validation isn't perfect though and it's possible that this function succeeds but using the filter chain for encoding or decoding will still result in LZMA_OPTIONS_ERROR. To disable this validation, use the flag LZMA_STR_NO_VALIDATION.

The available filter names and their options are available via lzma_str_list_filters(). See the xz man page for the description of filter names and options.

For command line applications, below is an example how an error message can be displayed. Note the use of an empty string for the field width. If "^" was used there it would create an off-by-one error except at the very beginning of the line.

const char *str = ...; // From user
lzma_filter filters[LZMA_FILTERS_MAX + 1];
int pos;
const char *msg = lzma_str_to_filters(str, &pos, filters, 0, NULL);
if (msg != NULL) {
    printf("%s: Error in XZ compression options:\n", argv[0]);
    printf("%s: %s\n", argv[0], str);
    printf("%s: %*s^\n", argv[0], errpos, "");
    printf("%s: %s\n", argv[0], msg);
}

Parameters

	str	User-supplied string describing a preset or a filter chain. If a default value is needed and you don't know what would be good, use "6" since that is the default preset in xz too.
[out]	error_pos	If this isn't NULL, this value will be set on both success and on all errors. This tells the location of the error in the string. This is an int to make it straightforward to use this as printf() field width. The value is guaranteed to be in the range [0, INT_MAX] even if strlen(str) somehow was greater than INT_MAX.
[out]	filters	An array of lzma_filter structures. There must be LZMA_FILTERS_MAX + 1 (that is, five) elements in the array. The old contents are ignored so it doesn't need to be initialized. This array is modified only if this function returns NULL. Once the allocated filter options are no longer needed, lzma_filters_free() can be used to free the options (it doesn't free the filters array itself).
	flags	Bitwise-or of zero or more of the flags LZMA_STR_ALL_FILTERS and LZMA_STR_NO_VALIDATION.
	allocator	lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().

Returns: On success, NULL is returned. On error, a statically-allocated error message is returned which together with the error_pos should give some idea what is wrong.

◆ lzma_str_from_filters()

lzma_ret lzma_str_from_filters	(	char **	str,
		const lzma_filter *	filters,
		uint32_t	flags,
		const lzma_allocator *	allocator
	)

extern

Convert a filter chain to a string.

Use cases:

Verbose output showing the full encoder options to the user (use LZMA_STR_ENCODER in flags)
Showing the filters and options that are required to decode a file (use LZMA_STR_DECODER in flags)
Showing the filter names without any options in informational messages where the technical details aren't important (no flags). In this case the .options in the filters array are ignored and may be NULL even if a filter has a mandatory options structure.

Note that even if the filter chain was specified using a preset, the resulting filter chain isn't reversed to a preset. So if you specify "6" to lzma_str_to_filters() then lzma_str_from_filters() will produce a string containing "lzma2".

Parameters

[out]	str	On success str will be set to point to an allocated string describing the given filter chain. Old value is ignored. On error str is always set to NULL.
	filters	Array of filters terminated with .id == LZMA_VLI_UNKNOWN.
	flags	Bitwise-or of zero or more of the flags LZMA_STR_ENCODER, LZMA_STR_DECODER, LZMA_STR_GETOPT_LONG, and LZMA_STR_NO_SPACES.
	allocator	lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().

Returns

Possible lzma_ret values:

LZMA_OK
LZMA_OPTIONS_ERROR: Empty filter chain (filters[0].id == LZMA_VLI_UNKNOWN) or the filter chain includes a Filter ID that is not supported by this function.
LZMA_MEM_ERROR
LZMA_PROG_ERROR

◆ lzma_str_list_filters()

lzma_ret lzma_str_list_filters	(	char **	str,
		lzma_vli	filter_id,
		uint32_t	flags,
		const lzma_allocator *	allocator
	)

extern

List available filters and/or their options (for help message)

If a filter_id is given then only one line is created which contains the filter name. If LZMA_STR_ENCODER or LZMA_STR_DECODER is used then the options read by the encoder or decoder are printed on the same line.

If filter_id is LZMA_VLI_UNKNOWN then all supported .xz-compatible filters are listed:

If neither LZMA_STR_ENCODER nor LZMA_STR_DECODER is used then the supported filter names are listed on a single line separated by spaces.
If LZMA_STR_ENCODER or LZMA_STR_DECODER is used then filters and the supported options are listed one filter per line. There won't be a newline after the last filter.
If LZMA_STR_ALL_FILTERS is used then the list will include also those filters that cannot be used in the .xz format (LZMA1).

Parameters

str	On success str will be set to point to an allocated string listing the filters and options. Old value is ignored. On error str is always set to NULL.
filter_id	Filter ID or LZMA_VLI_UNKNOWN.
flags	Bitwise-or of zero or more of the flags LZMA_STR_ALL_FILTERS, LZMA_STR_ENCODER, LZMA_STR_DECODER, and LZMA_STR_GETOPT_LONG.
allocator	lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().

Returns

Possible lzma_ret values:

LZMA_OK
LZMA_OPTIONS_ERROR: Unsupported filter_id or flags
LZMA_MEM_ERROR
LZMA_PROG_ERROR

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ LZMA_FILTERS_MAX

◆ LZMA_STR_ALL_FILTERS

◆ LZMA_STR_NO_VALIDATION

◆ LZMA_STR_ENCODER

◆ LZMA_STR_DECODER

◆ LZMA_STR_GETOPT_LONG

◆ LZMA_STR_NO_SPACES

Function Documentation

◆ lzma_filter_encoder_is_supported()

◆ lzma_filter_decoder_is_supported()

◆ lzma_filters_copy()

◆ lzma_filters_free()

◆ lzma_raw_encoder_memusage()

◆ lzma_raw_decoder_memusage()

◆ lzma_raw_encoder()

◆ lzma_raw_decoder()

◆ lzma_filters_update()

◆ lzma_raw_buffer_encode()

◆ lzma_raw_buffer_decode()

◆ lzma_properties_size()

◆ lzma_properties_encode()

◆ lzma_properties_decode()

◆ lzma_filter_flags_size()

◆ lzma_filter_flags_encode()

◆ lzma_filter_flags_decode()

◆ lzma_str_to_filters()

◆ lzma_str_from_filters()

◆ lzma_str_list_filters()