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 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 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)
 Simple macro to validate variable-length integer.

Typedefs

typedef uint64_t lzma_vli
 Variable-length integer type.

Functions

 LZMA_API (lzma_ret) lzma_vli_encode(lzma_vli vli
 Encodes variable-length integer.
 LZMA_API (uint32_t) lzma_vli_size(lzma_vli vli) lzma_attr_pure
 Get the number of bytes required to encode a VLI.

Variables

size_t *lzma_restrict vli_pos
size_t *lzma_restrict uint8_t
*lzma_restrict 
out
size_t *lzma_restrict uint8_t
*lzma_restrict size_t
*lzma_restrict 
out_pos
size_t *lzma_restrict uint8_t
*lzma_restrict size_t
*lzma_restrict size_t 
out_size
size_t *lzma_restrict const
uint8_t *lzma_restrict 
in
size_t *lzma_restrict const
uint8_t *lzma_restrict size_t
*lzma_restrict 
in_pos
size_t *lzma_restrict const
uint8_t *lzma_restrict size_t
*lzma_restrict size_t 
in_size

Detailed Description

Variable-length integer handling.

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_VLI_MAX   (UINT64_MAX / 2)

Maximum supported value of variable-length integer.

Referenced by LZMA_API().

#define LZMA_VLI_UNKNOWN   UINT64_MAX

VLI value to denote that the value is unknown.

Referenced by LZMA_API(), lzma_decoder_init(), and message_filters().

#define LZMA_VLI_BYTES_MAX   9

Maximum supported length of variable length integers.

#define LZMA_VLI_C (  )     UINT64_C(n)

VLI constant suffix.

Referenced by LZMA_API(), and lzma_index_padding_size().

#define lzma_vli_is_valid ( vli   )     ((vli) <= LZMA_VLI_MAX || (vli) == LZMA_VLI_UNKNOWN)

Simple macro to validate 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_API().


Typedef Documentation

typedef uint64_t lzma_vli

Variable-length integer type.

This will always be unsigned integer. 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.

In future, even if lzma_vli is typdefined to something else than uint64_t, it is guaranteed that 2 * LZMA_VLI_MAX will not overflow lzma_vli. This simplifies integer overflow detection.


Function Documentation

LZMA_API ( lzma_ret   ) 

Encodes variable-length integer.

Decodes variable-length integer.

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 at maximum of UINT64_MAX / 2. You should use LZMA_VLI_MAX for clarity.

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

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.
LZMA_API ( uint32_t   )  const

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.

Get the number of bytes required to encode a VLI.

liblzma version number as an integer

Calculate CRC32.

Although not all Check IDs have a check algorithm associated, the size of every Check is already frozen. This function returns the size (in bytes) of the Check field with the specified Check ID. The values are: { 0, 4, 4, 4, 8, 8, 8, 16, 16, 16, 32, 32, 32, 64, 64, 64 }

If the argument is not in the range [0, 15], UINT32_MAX is returned.

Calculates CRC32 using the polynomial from the IEEE 802.3 standard.

Parameters:
buf Pointer to the input buffer
size Size of the input buffer
crc Previously returned CRC value. This is used to calculate the CRC of a big buffer in smaller chunks. Set to zero when there is no previous value.
Returns:
Updated CRC value, which can be passed to this function again to continue CRC calculation.

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