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

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

Data Structures
struct	lzma_stream_flags
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_API (lzma_ret) lzma_stream_header_encode(const lzma_stream_flags *options
	Encode Stream Header.
Variables
uint8_t *out	lzma_attr_warn_unused_result
const lzma_stream_flags *b	lzma_attr_pure

---

Detailed Description

.xz Stream Header and Stream Footer encoder and decoder

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

---

Function Documentation

LZMA_API

(

lzma_ret

)

const

Encode Stream Header.

Compare two lzma_stream_flags structures.

Decode Stream Footer.

Decode Stream Header.

Encode Stream Footer.

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.

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.