common.c File Reference

Common functions needed in many places in liblzma. More...

#include "common.h"

Functions
	LZMA_API (uint32_t)
	LZMA_API (const char *)
	Run-time version as a string.
	lzma_attr_alloc_size (1)
void	lzma_free (void *ptr, const lzma_allocator *allocator)
	Frees memory.
size_t	lzma_bufcpy (const uint8_t *restrict in, size_t *restrict in_pos, size_t in_size, uint8_t *restrict out, size_t *restrict out_pos, size_t out_size)
lzma_ret	lzma_next_filter_init (lzma_next_coder *next, const lzma_allocator *allocator, const lzma_filter_info *filters)
lzma_ret	lzma_next_filter_update (lzma_next_coder *next, const lzma_allocator *allocator, const lzma_filter *reversed_filters)
void	lzma_next_end (lzma_next_coder *next, const lzma_allocator *allocator)
lzma_ret	lzma_strm_init (lzma_stream *strm)
	LZMA_API (lzma_ret)
	LZMA_API (void)
	LZMA_API (lzma_check)
	LZMA_API (uint64_t)
	Calculate approximate memory usage of easy encoder.

Detailed Description

Common functions needed in many places in liblzma.

Function Documentation

LZMA_API() [1/6]

LZMA_API ( const char * ) const

extern

Run-time version as a string.

This function may be useful if you want to display which version of liblzma your application is currently using.

LZMA_API() [2/6]

LZMA_API ( lzma_check )

extern

LZMA_API() [3/6]

LZMA_API ( lzma_ret )

extern

LZMA_API() [4/6]

LZMA_API ( uint32_t )

extern

LZMA_API() [5/6]

LZMA_API ( uint64_t )

extern

Calculate approximate memory usage of easy encoder.

Get the total amount of physical memory (RAM) in bytes.

Calculate approximate memory usage of multithreaded .xz encoder.

Calculate approximate decoder memory usage of a preset.

This function is a wrapper for lzma_raw_encoder_memusage().

Parameters

preset

Compression preset (level and possible flags)

Returns

Number of bytes of memory required for the given preset when encoding. If an error occurs, for example due to unsupported preset, UINT64_MAX is returned.

This function is a wrapper for lzma_raw_decoder_memusage().

Parameters

preset

Compression preset (level and possible flags)

Returns

Number of bytes of memory required to decompress a file that was compressed using the given preset. If an error occurs, for example due to unsupported preset, UINT64_MAX is returned.

Since doing the encoding in threaded mode doesn't affect the memory requirements of single-threaded decompressor, you can use lzma_easy_decoder_memusage(options->preset) or lzma_raw_decoder_memusage(options->filters) to calculate the decompressor memory requirements.

Parameters

options

Compression options

Returns

Number of bytes of memory required for encoding with the given options. If an error occurs, for example due to unsupported preset or filter chain, UINT64_MAX is returned.

Calculate approximate memory usage of easy encoder.

Get the uncompressed size of the file.

Get the total size of the file.

Get the total size of the Blocks.

Get the total size of the Stream.

Get the size of the Index field as bytes.

Get the number of Blocks.

Get the number of Streams.

Calculate the memory usage of an existing lzma_index.

On disk, the size of the Index field depends on both the number of Records stored and how big values the Records store (due to variable-length integer encoding). When the Index is kept in lzma_index structure, the memory usage depends only on the number of Records/Blocks stored in the Index(es), and in case of concatenated lzma_indexes, the number of Streams. The size in RAM is almost always significantly bigger than in the encoded form on disk.

This function calculates an approximate amount of memory needed hold the given number of Streams and Blocks in lzma_index structure. This value may vary between CPU architectures and also between liblzma versions if the internal implementation is modified.

This is a shorthand for lzma_index_memusage(lzma_index_stream_count(i), lzma_index_block_count(i)).

This returns the total number of Blocks in lzma_index. To get number of Blocks in individual Streams, use lzma_index_iter.

This is needed to verify the Backward Size field in the Stream Footer.

If multiple lzma_indexes have been combined, this works as if the Blocks were in a single Stream. This is useful if you are going to combine Blocks from multiple Streams into a single new Stream.

This doesn't include the Stream Header, Stream Footer, Stream Padding, or Index fields.

When no lzma_indexes have been combined with lzma_index_cat() and there is no Stream Padding, this function is identical to lzma_index_stream_size(). If multiple lzma_indexes have been combined, this includes also the headers of each separate Stream and the possible Stream Padding fields.

Calculate approximate memory usage of easy encoder.

Get the uncompressed size of the file.

Get the total size of the file.

Get the total size of the Blocks.

Get the total size of the Stream.

Get the size of the Index field as bytes.

Get the number of Blocks.

Get the number of Streams.

Calculate the memory usage of an existing lzma_index.

On disk, the size of the Index field depends on both the number of Records stored and the size of the Records (due to variable-length integer encoding). When the Index is kept in lzma_index structure, the memory usage depends only on the number of Records/Blocks stored in the Index(es), and in case of concatenated lzma_indexes, the number of Streams. The size in RAM is almost always significantly bigger than in the encoded form on disk.

This function calculates an approximate amount of memory needed to hold the given number of Streams and Blocks in lzma_index structure. This value may vary between CPU architectures and also between liblzma versions if the internal implementation is modified.

Parameters

streams	Number of Streams
blocks	Number of Blocks

Returns

Approximate memory in bytes needed in a lzma_index structure.

This is a shorthand for lzma_index_memusage(lzma_index_stream_count(i), lzma_index_block_count(i)).

Parameters

i	Pointer to lzma_index structure

Returns

Approximate memory in bytes used by the lzma_index structure.

Parameters

i	Pointer to lzma_index structure

Returns

Number of Streams in the lzma_index

This returns the total number of Blocks in lzma_index. To get number of Blocks in individual Streams, use lzma_index_iter.

Parameters

i	Pointer to lzma_index structure

Returns

Number of blocks in the lzma_index

This is needed to verify the Backward Size field in the Stream Footer.

Parameters

i	Pointer to lzma_index structure

Returns

Size in bytes of the Index

If multiple lzma_indexes have been combined, this works as if the Blocks were in a single Stream. This is useful if you are going to combine Blocks from multiple Streams into a single new Stream.

Parameters

i	Pointer to lzma_index structure

Returns

Size in bytes of the Stream (if all Blocks are combined into one Stream).

This doesn't include the Stream Header, Stream Footer, Stream Padding, or Index fields.

Parameters

i	Pointer to lzma_index structure

Returns

Size in bytes of all Blocks in the Stream(s)

When no lzma_indexes have been combined with lzma_index_cat() and there is no Stream Padding, this function is identical to lzma_index_stream_size(). If multiple lzma_indexes have been combined, this includes also the headers of each separate Stream and the possible Stream Padding fields.

Parameters

i	Pointer to lzma_index structure

Returns

Total size of the .xz file in bytes

Parameters

i	Pointer to lzma_index structure

Returns

Size in bytes of the uncompressed data in the file

LZMA_API() [6/6]

LZMA_API ( void )

extern

lzma_attr_alloc_size()

lzma_attr_alloc_size

(

1

)

Allocates memory and zeroes it (like calloc()). This can be faster than lzma_alloc() + memzero() while being backward compatible with custom allocators.

lzma_bufcpy()

size_t lzma_bufcpy ( const uint8_t *restrict in, size_t *restrict in_pos, size_t in_size, uint8_t *restrict out, size_t *restrict out_pos, size_t out_size )

extern

Copy as much data as possible from in[] to out[] and update *in_pos and *out_pos accordingly. Returns the number of bytes copied.

lzma_free()

void lzma_free ( void * ptr, const lzma_allocator * allocator )

extern

Frees memory.

lzma_next_end()

void lzma_next_end ( lzma_next_coder * next, const lzma_allocator * allocator )

extern

Frees the memory allocated for next->coder either using next->end or, if next->end is NULL, using lzma_free.

lzma_next_filter_init()

lzma_ret lzma_next_filter_init ( lzma_next_coder * next, const lzma_allocator * allocator, const lzma_filter_info * filters )

extern

Initializes the next filter in the chain, if any. This takes care of freeing the memory of previously initialized filter if it is different than the filter being initialized now. This way the actual filter initialization functions don't need to use lzma_next_coder_init macro.

lzma_next_filter_update()

lzma_ret lzma_next_filter_update ( lzma_next_coder * next, const lzma_allocator * allocator, const lzma_filter * reversed_filters )

extern

Update the next filter in the chain, if any. This checks that the application is not trying to change the Filter IDs.

lzma_strm_init()

lzma_ret lzma_strm_init ( lzma_stream * strm )

extern

Allocates strm->internal if it is NULL, and initializes *strm and strm->internal. This function is only called via lzma_next_strm_init macro.