check.h File Reference

Integrity checks. More...

Go to the source code of this file.

Macros
#define	LZMA_CHECK_ID_MAX   15
	Maximum valid Check ID. More...
#define	LZMA_CHECK_SIZE_MAX   64
	Maximum size of a Check field. More...

Enumerations
enum	lzma_check { LZMA_CHECK_NONE = 0 , LZMA_CHECK_CRC32 = 1 , LZMA_CHECK_CRC64 = 4 , LZMA_CHECK_SHA256 = 10 }
	Type of the integrity check (Check ID) More...

Functions
	LZMA_API (lzma_bool) lzma_check_is_supported(lzma_check check) lzma_nothrow lzma_attr_const
	Test if the given Check ID is supported. More...
	LZMA_API (uint32_t) lzma_check_size(lzma_check check) lzma_nothrow lzma_attr_const
	Get the size of the Check field with the given Check ID. More...
	LZMA_API (uint64_t) lzma_crc64(const uint8_t *buf
	Calculate CRC64. More...
	LZMA_API (lzma_check) lzma_get_check(const lzma_stream *strm) lzma_nothrow
	Get the type of the integrity check. More...

Variables
size_t	size
size_t uint32_t crc lzma_nothrow	lzma_attr_pure

Detailed Description

Integrity checks.

Definition in file check.h.

Macro Definition Documentation

LZMA_CHECK_ID_MAX

#define LZMA_CHECK_ID_MAX   15

Maximum valid Check ID.

The .xz file format specification specifies 16 Check IDs (0-15). Some of them are only reserved, that is, no actual Check algorithm has been assigned. When decoding, liblzma still accepts unknown Check IDs for future compatibility. If a valid but unsupported Check ID is detected, liblzma can indicate a warning; see the flags LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, and LZMA_TELL_ANY_CHECK in container.h.

Definition at line 68 of file check.h.

LZMA_CHECK_SIZE_MAX

#define LZMA_CHECK_SIZE_MAX   64

Maximum size of a Check field.

Definition at line 102 of file check.h.

Enumeration Type Documentation

lzma_check

enum lzma_check

Type of the integrity check (Check ID)

The .xz format supports multiple types of checks that are calculated from the uncompressed data. They vary in both speed and ability to detect errors.

Enumerator
LZMA_CHECK_NONE	No Check is calculated. Size of the Check field: 0 bytes
LZMA_CHECK_CRC32	CRC32 using the polynomial from the IEEE 802.3 standard Size of the Check field: 4 bytes
LZMA_CHECK_CRC64	CRC64 using the polynomial from the ECMA-182 standard Size of the Check field: 8 bytes
LZMA_CHECK_SHA256	SHA-256 Size of the Check field: 32 bytes

Definition at line 27 of file check.h.

             {
    LZMA_CHECK_NONE     = 0,
    LZMA_CHECK_CRC32    = 1,
    LZMA_CHECK_CRC64    = 4,
    LZMA_CHECK_SHA256   = 10
} lzma_check;

Function Documentation

LZMA_API() [1/4]

LZMA_API

(

lzma_bool

)

const

Test if the given Check ID is supported.

Set a compression preset to lzma_options_lzma structure.

Test if given compression mode is supported.

Locate a Block.

Test if the given Filter ID is supported for decoding.

Return true if the given Check ID is supported by this liblzma build. Otherwise false is returned. It is safe to call this with a value that is not in the range [0, 15]; in that case the return value is always false.

You can assume that LZMA_CHECK_NONE and LZMA_CHECK_CRC32 are always supported (even if liblzma is built with limited features).

Return true if the give Filter ID is supported for decoding by this liblzma build. Otherwise false is returned.

If it is possible to seek in the .xz file, it is possible to parse the Index field(s) and use lzma_index_iter_locate() to do random-access reading with granularity of Block size.

Parameters

iter	Iterator that was earlier initialized with lzma_index_iter_init().
target	Uncompressed target offset which the caller would like to locate from the Stream

If the target is smaller than the uncompressed size of the Stream (can be checked with lzma_index_uncompressed_size()):

• Information about the Stream and Block containing the requested uncompressed offset is stored into *iter.
• Internal state of the iterator is adjusted so that lzma_index_iter_next() can be used to read subsequent Blocks or Streams.
• This function returns false.

If target is greater than the uncompressed size of the Stream, *iter is not modified, and this function returns true.

Return true if the given compression mode is supported by this liblzma build. Otherwise false is returned. It is safe to call this with a value that isn't listed in lzma_mode enumeration; the return value will be false.

There is no way to list which modes are available in this particular liblzma version and build. It would be useless, because a new compression mode, which the application developer wasn't aware, could require giving additional options to the encoder that the older modes don't need.

0 is the fastest and 9 is the slowest. These match the switches -0 .. -9 of the xz command line tool. In addition, it is possible to bitwise-or flags to the preset. Currently only LZMA_PRESET_EXTREME is supported. The flags are defined in container.h, because the flags are used also with lzma_easy_encoder().

The preset values are subject to changes between liblzma versions.

This function is available only if LZMA1 or LZMA2 encoder has been enabled when building liblzma.

Returns

On success, false is returned. If the preset is not supported, true is returned.

Test if the given Check ID is supported.

Locate a Block.

Parameters

iter	Iterator initialized with lzma_index_iter_init()
mode	Specify what kind of information the caller wants to get. See lzma_index_iter_mode for details.

Returns

If next Block or Stream matching the mode was found, *iter is updated and this function returns false. If no Block or Stream matching the mode is found, *iter is not modified and this function returns true. If mode is set to an unknown value, *iter is not modified and this function returns true.

If it is possible to seek in the .xz file, it is possible to parse the Index field(s) and use lzma_index_iter_locate() to do random-access reading with granularity of Block size.

Parameters

iter	Iterator that was earlier initialized with lzma_index_iter_init().
target	Uncompressed target offset which the caller would like to locate from the Stream

If the target is smaller than the uncompressed size of the Stream (can be checked with lzma_index_uncompressed_size()):

• Information about the Stream and Block containing the requested uncompressed offset is stored into *iter.
• Internal state of the iterator is adjusted so that lzma_index_iter_next() can be used to read subsequent Blocks or Streams.
• This function returns false.

If target is greater than the uncompressed size of the Stream, *iter is not modified, and this function returns true.

Test if the given Check ID is supported.

Set a compression preset to lzma_options_lzma structure.

Test if given compression mode is supported.

Return true if the given match finder is supported by this liblzma build. Otherwise false is returned. It is safe to call this with a value that isn't listed in lzma_match_finder enumeration; the return value will be false.

There is no way to list which match finders are available in this particular liblzma version and build. It would be useless, because a new match finder, which the application developer wasn't aware, could require giving additional options to the encoder that the older match finders don't need.

Return true if the given compression mode is supported by this liblzma build. Otherwise false is returned. It is safe to call this with a value that isn't listed in lzma_mode enumeration; the return value will be false.

There is no way to list which modes are available in this particular liblzma version and build. It would be useless, because a new compression mode, which the application developer wasn't aware, could require giving additional options to the encoder that the older modes don't need.

0 is the fastest and 9 is the slowest. These match the switches -0 .. -9 of the xz command line tool. In addition, it is possible to bitwise-or flags to the preset. Currently only LZMA_PRESET_EXTREME is supported. The flags are defined in container.h, because the flags are used also with lzma_easy_encoder().

The preset values are subject to changes between liblzma versions.

This function is available only if LZMA1 or LZMA2 encoder has been enabled when building liblzma.

Returns

On success, false is returned. If the preset is not supported, true is returned.

Definition at line 1209 of file index.c.

{
    const lzma_index *i = iter->internal[ITER_INDEX].p;
 
    // If the target is past the end of the file, return immediately.
    if (i->uncompressed_size <= target)
        return true;
 
    // Locate the Stream containing the target offset.
    const index_stream *stream = index_tree_locate(&i->streams, target);
    assert(stream != NULL);
    target -= stream->node.uncompressed_base;
 
    // Locate the group containing the target offset.
    const index_group *group = index_tree_locate(&stream->groups, target);
    assert(group != NULL);
 
    // Use binary search to locate the exact Record. It is the first
    // Record whose uncompressed_sum is greater than target.
    // This is because we want the rightmost Record that fullfills the
    // search criterion. It is possible that there are empty Blocks;
    // we don't want to return them.
    size_t left = 0;
    size_t right = group->last;
 
    while (left < right) {
        const size_t pos = left + (right - left) / 2;
        if (group->records[pos].uncompressed_sum <= target)
            left = pos + 1;
        else
            right = pos;
    }
 
    iter->internal[ITER_STREAM].p = stream;
    iter->internal[ITER_GROUP].p = group;
    iter->internal[ITER_RECORD].s = left;
 
    iter_set_info(iter);
 
    return false;
}

References assert(), i, index_tree_locate(), ITER_GROUP, ITER_INDEX, ITER_RECORD, iter_set_info(), ITER_STREAM, index_group::last, NULL, pos, index_group::records, lzma_index_s::streams, lzma_index_s::uncompressed_size, and index_record::uncompressed_sum.

LZMA_API() [2/4]

LZMA_API

(

lzma_check

)

const

Get the type of the integrity check.

This function can be called only immediately after lzma_code() has returned LZMA_NO_CHECK, LZMA_UNSUPPORTED_CHECK, or LZMA_GET_CHECK. Calling this function in any other situation has undefined behavior.

LZMA_API() [3/4]

LZMA_API

(

uint32_t

)

Get the size of the Check field with the given Check ID.

Get the number of bytes required to encode a VLI.

Run-time version number as an integer.

Get the number of processor cores or threads.

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.

Calculate 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 starting a new calculation.

Returns

Updated CRC value, which can be passed to this function again to continue CRC calculation.

LZMA_API() [4/4]

LZMA_API

(

uint64_t

)

const

Calculate CRC64.

Get the size of the Index field as bytes.

Calculate approximate memory requirements for raw encoder.

Calculate Unpadded Size.

Get the memory usage of decoder filter chain.

Calculate CRC64 using the polynomial from the ECMA-182 standard.

This function is used similarly to lzma_crc32(). See its documentation.

Definition at line 624 of file block_util.c.

{
    lzma_vli unpadded_size = lzma_block_unpadded_size(block);
 
    if (unpadded_size != LZMA_VLI_UNKNOWN)
        unpadded_size = vli_ceil4(unpadded_size);
 
    return unpadded_size;
}

References LZMA_VLI_UNKNOWN, unpadded_size, and vli_ceil4().

Variable Documentation

lzma_attr_pure

size_t uint64_t crc lzma_nothrow lzma_attr_pure

Definition at line 121 of file check.h.

size

size_t size

Definition at line 120 of file check.h.