liblzma/api/lzma/stream_flags.h File Reference

.xz Stream Header and Stream Footer encoder and decoder More...

Data Structures
struct	lzma_stream_flags
	Options for encoding/decoding Stream Header and Stream Footer. More...
Defines
#define	LZMA_STREAM_HEADER_SIZE   12
	Size of Stream Header and Stream Footer.
#define	LZMA_BACKWARD_SIZE_MIN   4
#define	LZMA_BACKWARD_SIZE_MAX   (LZMA_VLI_C(1) << 34)
Functions
lzma_ret	lzma_stream_header_encode (const lzma_stream_flags *options, uint8_t *out) lzma_nothrow lzma_attr_warn_unused_result
	Encode Stream Header.
lzma_ret	lzma_stream_footer_encode (const lzma_stream_flags *options, uint8_t *out) lzma_nothrow lzma_attr_warn_unused_result
	Encode Stream Footer.
lzma_ret	lzma_stream_header_decode (lzma_stream_flags *options, const uint8_t *in) lzma_nothrow lzma_attr_warn_unused_result
	Decode Stream Header.
lzma_ret	lzma_stream_footer_decode (lzma_stream_flags *options, const uint8_t *in) lzma_nothrow lzma_attr_warn_unused_result
	Decode Stream Footer.
lzma_ret	lzma_stream_flags_compare (const lzma_stream_flags *a, const lzma_stream_flags *b) lzma_nothrow lzma_attr_pure
	Compare two lzma_stream_flags structures.

---

Detailed Description

.xz Stream Header and Stream Footer encoder and decoder

---

Define Documentation

#define LZMA_STREAM_HEADER_SIZE   12

Size of Stream Header and Stream Footer.

Stream Header and Stream Footer have the same size and they are not going to change even if a newer version of the .xz file format is developed in future.

Referenced by lzma_index_stream_size(), lzma_stream_buffer_encode(), lzma_stream_footer_encode(), lzma_stream_header_encode(), and parse_indexes().

---

Function Documentation

lzma_ret lzma_stream_header_encode	(	const lzma_stream_flags *	options,
		uint8_t *	out
	)

Encode Stream Header.

Parameters:

options	Stream Header options to be encoded. options->backward_size is ignored and doesn't need to be initialized.
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.

References lzma_crc32(), LZMA_OK, LZMA_OPTIONS_ERROR, LZMA_PROG_ERROR, LZMA_STREAM_FLAGS_SIZE, and LZMA_STREAM_HEADER_SIZE.

Referenced by lzma_stream_buffer_encode().

lzma_ret lzma_stream_footer_encode	(	const lzma_stream_flags *	options,
		uint8_t *	out
	)

Encode Stream Footer.

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.

References lzma_crc32(), LZMA_OK, LZMA_OPTIONS_ERROR, LZMA_PROG_ERROR, LZMA_STREAM_FLAGS_SIZE, and LZMA_STREAM_HEADER_SIZE.

Referenced by lzma_stream_buffer_encode().

lzma_ret lzma_stream_header_decode	(	lzma_stream_flags *	options,
		const uint8_t *	in
	)

Decode Stream Header.

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.

References lzma_crc32(), LZMA_DATA_ERROR, LZMA_FORMAT_ERROR, LZMA_OK, LZMA_OPTIONS_ERROR, LZMA_STREAM_FLAGS_SIZE, and LZMA_VLI_UNKNOWN.

Referenced by parse_indexes().

lzma_ret lzma_stream_footer_decode	(	lzma_stream_flags *	options,
		const uint8_t *	in
	)

Decode Stream Footer.

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.

References lzma_crc32(), LZMA_DATA_ERROR, LZMA_FORMAT_ERROR, LZMA_OK, LZMA_OPTIONS_ERROR, and LZMA_STREAM_FLAGS_SIZE.

Referenced by parse_indexes().

lzma_ret lzma_stream_flags_compare	(	const lzma_stream_flags *	a,
		const lzma_stream_flags *	b
	)

Compare two lzma_stream_flags structures.

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.

References LZMA_CHECK_ID_MAX, LZMA_DATA_ERROR, LZMA_OK, LZMA_OPTIONS_ERROR, LZMA_PROG_ERROR, and LZMA_VLI_UNKNOWN.

Referenced by lzma_index_stream_flags(), and parse_indexes().