/tmp/buildd/xz-utils-5.0.0/src/liblzma/api/lzma/vli.h File Reference

Variable-length integer handling. More...

Defines
#define	LZMA_VLI_MAX   (UINT64_MAX / 2)
	Maximum supported value of a variable-length integer.
#define	LZMA_VLI_UNKNOWN   UINT64_MAX
	VLI value to denote that the value is unknown.
#define	LZMA_VLI_BYTES_MAX   9
	Maximum supported encoded length of variable length integers.
#define	LZMA_VLI_C(n)   UINT64_C(n)
	VLI constant suffix.
#define	lzma_vli_is_valid(vli)   ((vli) <= LZMA_VLI_MAX || (vli) == LZMA_VLI_UNKNOWN)
	Validate a variable-length integer.
Typedefs
typedef uint64_t	lzma_vli
	Variable-length integer type.
Functions
lzma_ret	lzma_vli_encode (lzma_vli vli, size_t *vli_pos, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
	Encode a variable-length integer.
lzma_ret	lzma_vli_decode (lzma_vli *vli, size_t *vli_pos, const uint8_t *in, size_t *in_pos, size_t in_size) lzma_nothrow
	Decode a variable-length integer.
uint32_t	lzma_vli_size (lzma_vli vli) lzma_nothrow lzma_attr_pure
	Get the number of bytes required to encode a VLI.

---

Detailed Description

Variable-length integer handling.

In the .xz format, most integers are encoded in a variable-length representation, which is sometimes called little endian base-128 encoding. This saves space when smaller values are more likely than bigger values.

The encoding scheme encodes seven bits to every byte, using minimum number of bytes required to represent the given value. Encodings that use non-minimum number of bytes are invalid, thus every integer has exactly one encoded representation. The maximum number of bits in a VLI is 63, thus the vli argument must be less than or equal to UINT64_MAX / 2. You should use LZMA_VLI_MAX for clarity.

---

Define Documentation

#define LZMA_VLI_MAX   (UINT64_MAX / 2)

Maximum supported value of a variable-length integer.

Referenced by lzma_index_append(), lzma_index_hash_append(), lzma_index_memusage(), lzma_index_stream_padding(), lzma_properties_size(), lzma_stream_buffer_bound(), and lzma_vli_size().

#define LZMA_VLI_UNKNOWN   UINT64_MAX

VLI value to denote that the value is unknown.

Referenced by lzma_block_compressed_size(), lzma_block_header_encode(), lzma_block_header_size(), lzma_block_total_size(), lzma_block_unpadded_size(), lzma_decoder_init(), lzma_filters_copy(), lzma_filters_update(), lzma_index_append(), lzma_next_filter_update(), lzma_stream_flags_compare(), and parse_block_header().

#define LZMA_VLI_BYTES_MAX   9

Maximum supported encoded length of variable length integers.

Referenced by lzma_vli_size().

#define LZMA_VLI_C

(

n

)

UINT64_C(n)

VLI constant suffix.

Referenced by lzma_block_buffer_bound(), lzma_index_hash_decode(), and lzma_index_padding_size().

#define lzma_vli_is_valid

(

vli

)

((vli) <= LZMA_VLI_MAX || (vli) == LZMA_VLI_UNKNOWN)

Validate a variable-length integer.

This is useful to test that application has given acceptable values for example in the uncompressed_size and compressed_size variables.

Returns:

True if the integer is representable as VLI or if it indicates unknown value.

Referenced by lzma_block_header_encode(), and lzma_block_unpadded_size().

---

Typedef Documentation

typedef uint64_t lzma_vli

Variable-length integer type.

Valid VLI values are in the range [0, LZMA_VLI_MAX]. Unknown value is indicated with LZMA_VLI_UNKNOWN, which is the maximum value of the underlaying integer type.

lzma_vli will be uint64_t for the foreseeable future. If a bigger size is needed in the future, it is guaranteed that 2 * LZMA_VLI_MAX will not overflow lzma_vli. This simplifies integer overflow detection.

---

Function Documentation

lzma_ret lzma_vli_encode	(	lzma_vli	vli,
		size_t *	vli_pos,
		uint8_t *	out,
		size_t *	out_pos,
		size_t	out_size
	)

Encode a variable-length integer.

This function has two modes: single-call and multi-call. Single-call mode encodes the whole integer at once; it is an error if the output buffer is too small. Multi-call mode saves the position in *vli_pos, and thus it is possible to continue encoding if the buffer becomes full before the whole integer has been encoded.

Parameters:

	vli	Integer to be encoded
	vli_pos	How many VLI-encoded bytes have already been written out. When starting to encode a new integer in multi-call mode, *vli_pos must be set to zero. To use single-call encoding, set vli_pos to NULL.
	out	Beginning of the output buffer
	out_pos	The next byte will be written to out[*out_pos].
	out_size	Size of the out buffer; the first byte into which no data is written to is out[out_size].

Returns:

Slightly different return values are used in multi-call and single-call modes.

Single-call (vli_pos == NULL):

• LZMA_OK: Integer successfully encoded.
• LZMA_PROG_ERROR: Arguments are not sane. This can be due to too little output space; single-call mode doesn't use LZMA_BUF_ERROR, since the application should have checked the encoded size with lzma_vli_size().

Multi-call (vli_pos != NULL):

• LZMA_OK: So far all OK, but the integer is not completely written out yet.
• LZMA_STREAM_END: Integer successfully encoded.
• LZMA_BUF_ERROR: No output space was provided.
• LZMA_PROG_ERROR: Arguments are not sane.

Referenced by lzma_block_header_encode(), and lzma_filter_flags_encode().

lzma_ret lzma_vli_decode	(	lzma_vli *	vli,
		size_t *	vli_pos,
		const uint8_t *	in,
		size_t *	in_pos,
		size_t	in_size
	)

Decode a variable-length integer.

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.

Referenced by lzma_block_header_decode(), lzma_filter_flags_decode(), and lzma_index_hash_decode().

uint32_t lzma_vli_size

(

lzma_vli

vli

)

Get the number of bytes required to encode a VLI.

Returns:

Number of bytes on success (1-9). If vli isn't valid, zero is returned.

References LZMA_VLI_BYTES_MAX, and LZMA_VLI_MAX.

Referenced by hash_append(), lzma_block_header_size(), lzma_filter_flags_size(), and lzma_index_append().