common.c File Reference

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

`#include "common.h"`

## Functions

uint32_t | lzma_version_number (void)
| Run-time version number as an integer. More...
const char * | lzma_version_string (void)
| Run-time version as a string. More...
void * | lzma_attribute ((__malloc__))
void | lzma_free (void *ptr, const lzma_allocator *allocator)
| Frees memory. More...
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_ret | lzma_code (lzma_stream *strm, lzma_action action)
| Encode or decode data. More...
void | lzma_end (lzma_stream *strm)
| Free memory allocated for the coder data structures. More...
void | lzma_get_progress (lzma_stream *strm, uint64_t *progress_in, uint64_t *progress_out)
| Get progress information. More...
lzma_check | lzma_get_check (const lzma_stream *strm)
| Get the type of the integrity check. More...
uint64_t | lzma_memusage (const lzma_stream *strm)
| Get the memory usage of decoder filter chain. More...
uint64_t | lzma_memlimit_get (const lzma_stream *strm)
| Get the current memory usage limit. More...
lzma_ret | lzma_memlimit_set (lzma_stream *strm, uint64_t new_memlimit)
| Set the memory usage limit. More...

## Detailed Description

Common functions needed in many places in liblzma.

## Function Documentation

## lzma_version_number()

uint32_t lzma_version_number | ( | void |  | ) | const

Run-time version number as an integer.

Return the value of LZMA_VERSION macro at the compile time of liblzma. This allows the application to compare if it was built against the same, older, or newer version of liblzma that is currently running.

References LZMA_VERSION.

## lzma_version_string()

const char* lzma_version_string | ( | void |  | ) | const

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.

References LZMA_VERSION_STRING.

## lzma_free()

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

Frees memory.

Referenced by lzma_end().

## 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
| ) |  |

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

Referenced by dict_write().

## lzma_next_filter_init()

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

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
| ) |  |

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

## lzma_next_end()

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

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

Referenced by lzma_end().

## lzma_strm_init()

lzma_ret lzma_strm_init | ( | lzma_stream * | strm | ) |

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

References lzma_stream::allocator, lzma_stream::internal, lzma_alloc(), LZMA_MEM_ERROR, LZMA_NEXT_CODER_INIT, LZMA_PROG_ERROR, lzma_internal_s::next, and strm.

## lzma_code()

lzma_ret lzma_code | ( | lzma_stream * | strm,
|  | lzma_action | action
| ) |  |

Encode or decode data.

Once the lzma_stream has been successfully initialized (e.g. with lzma_stream_encoder()), the actual encoding or decoding is done using this function. The application has to update strm->next_in, strm->avail_in, strm->next_out, and strm->avail_out to pass input to and get output from liblzma.

See the description of the coder-specific initialization function to find out what ‘action’ values are supported by the coder.

References lzma_stream::avail_in, lzma_stream::avail_out, lzma_next_coder_s::code, lzma_stream::internal, LZMA_ACTION_MAX, LZMA_PROG_ERROR, lzma_internal_s::next, lzma_stream::next_in, lzma_stream::next_out, strm, and lzma_internal_s::supported_actions.

## lzma_end()

void lzma_end | ( | lzma_stream * | strm | ) |

Free memory allocated for the coder data structures.

Parameters

  strm | Pointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.

After lzma_end(strm), strm->internal is guaranteed to be NULL. No other members of the lzma_stream structure are touched.

Note
  zlib indicates an error if application end()s unfinished stream structure. liblzma doesn't do this, and assumes that application knows what it is doing.

References lzma_stream::allocator, lzma_stream::internal, lzma_free(), lzma_next_end(), lzma_internal_s::next, and strm.

Referenced by coder_free().

## lzma_get_progress()

void lzma_get_progress | ( | lzma_stream * | strm,
|  | uint64_t * | progress_in,
|  | uint64_t * | progress_out
| ) |  |

Get progress information.

In single-threaded mode, applications can get progress information from strm->total_in and strm->total_out. In multi-threaded mode this is less useful because a significant amount of both input and output data gets buffered internally by liblzma. This makes total_in and total_out give misleading information and also makes the progress indicator updates non-smooth.

This function gives realistic progress information also in multi-threaded mode by taking into account the progress made by each thread. In single-threaded mode *progress_in and *progress_out are set to strm->total_in and strm->total_out, respectively.

References lzma_next_coder_s::coder, lzma_next_coder_s::get_progress, lzma_stream::internal, lzma_internal_s::next, strm, lzma_stream::total_in, and lzma_stream::total_out.

Referenced by progress_pos().

## lzma_get_check()

lzma_check lzma_get_check | ( | const lzma_stream * | strm | ) |

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.

References lzma_next_coder_s::coder, lzma_next_coder_s::get_check, lzma_stream::internal, LZMA_CHECK_NONE, lzma_internal_s::next, and strm.

## lzma_memusage()

uint64_t lzma_memusage | ( | const lzma_stream * | strm | ) |

Get the memory usage of decoder filter chain.

This function is currently supported only when *strm has been initialized with a function that takes a memlimit argument. With other functions, you should use e.g. lzma_raw_encoder_memusage() or lzma_raw_decoder_memusage() to estimate the memory requirements.

This function is useful e.g. after LZMA_MEMLIMIT_ERROR to find out how big the memory usage limit should have been to decode the input. Note that this may give misleading information if decoding .xz Streams that have multiple Blocks, because each Block can have different memory requirements.

Returns
  How much memory is currently allocated for the filter decoders. If no filter chain is currently allocated, some non-zero value is still returned, which is less than or equal to what any filter chain would indicate as its memory requirement.

If this function isn't supported by *strm or some other error occurs, zero is returned.

References lzma_next_coder_s::coder, lzma_stream::internal, LZMA_OK, lzma_next_coder_s::memconfig, lzma_internal_s::next, and strm.

## lzma_memlimit_get()

uint64_t lzma_memlimit_get | ( | const lzma_stream * | strm | ) |

Get the current memory usage limit.

This function is supported only when *strm has been initialized with a function that takes a memlimit argument.

Returns
  On success, the current memory usage limit is returned (always non-zero). On error, zero is returned.

References lzma_next_coder_s::coder, lzma_stream::internal, LZMA_OK, lzma_next_coder_s::memconfig, lzma_internal_s::next, and strm.

## lzma_memlimit_set()

lzma_ret lzma_memlimit_set | ( | lzma_stream * | strm,
|  | uint64_t | memlimit
| ) |  |

Set the memory usage limit.

This function is supported only when *strm has been initialized with a function that takes a memlimit argument.

liblzma 5.2.3 and earlier has a bug where memlimit value of 0 causes this function to do nothing (leaving the limit unchanged) and still return LZMA_OK. Later versions treat 0 as if 1 had been specified (so lzma_memlimit_get() will return 1 even if you specify 0 here).

Returns
  - LZMA_OK: New memory usage limit successfully set.
  - LZMA_MEMLIMIT_ERROR: The new limit is too small. The limit was not changed.
  - LZMA_PROG_ERROR: Invalid arguments, e.g. *strm doesn't support memory usage limit.

References lzma_next_coder_s::coder, lzma_stream::internal, LZMA_PROG_ERROR, lzma_next_coder_s::memconfig, lzma_internal_s::next, and strm.