src/liblzma/api/lzma/container.h File Reference

File formats. More...


Defines

#define LZMA_PRESET_DEFAULT   UINT32_C(6)
 Default compression preset.
#define LZMA_PRESET_LEVEL_MASK   UINT32_C(0x1F)
 Mask for preset level.
#define LZMA_PRESET_EXTREME   (UINT32_C(1) << 31)
 Extreme compression preset.
#define LZMA_TELL_NO_CHECK   UINT32_C(0x01)
#define LZMA_TELL_UNSUPPORTED_CHECK   UINT32_C(0x02)
#define LZMA_TELL_ANY_CHECK   UINT32_C(0x04)
#define LZMA_CONCATENATED   UINT32_C(0x08)

Functions

 LZMA_API (uint64_t) lzma_easy_encoder_memusage(uint32_t preset) lzma_attr_pure
 Calculate rough memory usage of easy encoder.
 LZMA_API (lzma_ret) lzma_easy_encoder(lzma_stream *strm
 Initialize .xz Stream encoder using a preset number.
 LZMA_API (size_t) lzma_stream_buffer_bound(size_t uncompressed_size)
 Calculate output buffer size for single-call Stream encoder.

Variables

uint32_t preset
uint32_t lzma_check check lzma_attr_warn_unused_result
const lzma_filterfilters
lzma_check check
lzma_check lzma_allocatorallocator
lzma_check lzma_allocator
const uint8_t * 
in
lzma_check lzma_allocator
const uint8_t size_t 
in_size
lzma_check lzma_allocator
const uint8_t size_t uint8_t * 
out
lzma_check lzma_allocator
const uint8_t size_t uint8_t
size_t * 
out_pos
uint64_t memlimit
uint32_t flags
uint32_t lzma_allocator const
uint8_t size_t * 
in_pos


Detailed Description

File formats.

Author:
Copyright (C) 1999-2008 Igor Pavlov

Copyright (C) 2007-2008 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_PRESET_DEFAULT   UINT32_C(6)

Default compression preset.

It's not straightforward to recommend a default preset, because in some cases keeping the resource usage relatively low is more important that getting the maximum compression ratio.

#define LZMA_PRESET_LEVEL_MASK   UINT32_C(0x1F)

Mask for preset level.

This is useful only if you need to extract the level from the preset variable. That should be rare.

Referenced by LZMA_API().

#define LZMA_PRESET_EXTREME   (UINT32_C(1) << 31)

Extreme compression preset.

This flag modifies the preset to make the encoding significantly slower while improving the compression ratio only marginally. This is useful when you don't mind wasting time to get as small result as possible.

This flag doesn't affect the memory usage requirements of the decoder (at least not significantly). The memory usage of the encoder may be increased a little but only at the lowest preset levels (0-4 or so).

Referenced by LZMA_API().

#define LZMA_TELL_NO_CHECK   UINT32_C(0x01)

This flag makes lzma_code() return LZMA_NO_CHECK if the input stream being decoded has no integrity check. Note that when used with lzma_auto_decoder(), all .lzma files will trigger LZMA_NO_CHECK if LZMA_TELL_NO_CHECK is used.

#define LZMA_TELL_UNSUPPORTED_CHECK   UINT32_C(0x02)

This flag makes lzma_code() return LZMA_UNSUPPORTED_CHECK if the input stream has an integrity check, but the type of the integrity check is not supported by this liblzma version or build. Such files can still be decoded, but the integrity check cannot be verified.

#define LZMA_TELL_ANY_CHECK   UINT32_C(0x04)

This flag makes lzma_code() return LZMA_GET_CHECK as soon as the type of the integrity check is known. The type can then be got with lzma_get_check().

Referenced by LZMA_API().

#define LZMA_CONCATENATED   UINT32_C(0x08)

This flag enables decoding of concatenated files with file formats that allow concatenating compressed files as is. From the formats currently supported by liblzma, only the .xz format allows concatenated files. Concatenated files are not allowed with the legacy .lzma format.

This flag also affects the usage of the `action' argument for lzma_code(). When LZMA_CONCATENATED is used, lzma_code() won't return LZMA_STREAM_END unless LZMA_FINISH is used as `action'. Thus, the application has to set LZMA_FINISH in the same way as it does when encoding.

If LZMA_CONCATENATED is not used, the decoders still accept LZMA_FINISH as `action' for lzma_code(), but the usage of LZMA_FINISH isn't required.


Function Documentation

LZMA_API ( uint64_t   ) 

Calculate rough memory usage of easy encoder.

Calculate rough decoder memory usage of a preset.

This function is a wrapper for lzma_raw_encoder_memusage().

Parameters:
preset Compression preset (level and possible flags)
This function is a wrapper for lzma_raw_decoder_memusage().

Parameters:
preset Compression preset (level and possible flags)

LZMA_API ( lzma_ret   ) 

Initialize .xz Stream encoder using a preset number.

Calculate Block Header Size.

Single-call .xz Stream decoder.

Initialize .lzma decoder (legacy file format).

Decode .xz Streams and .lzma files with autodetection.

Initialize .xz Stream decoder.

Single-call Stream encoder.

Initialize .lzma encoder (legacy file format).

Initialize .xz Stream encoder using a custom filter chain.

This function is intended for those who just want to use the basic features if liblzma (that is, most developers out there).

Parameters:
strm Pointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
preset Compression preset to use. A preset consist of level number and zero or more flags. Usually flags aren't used, so preset is simply a number [0, 9] which match the options -0 .. -9 of the xz command line tool. Additional flags can be be set using bitwise-or with the preset level number, e.g. 6 | LZMA_PRESET_EXTREME.
check Integrity check type to use. See check.h for available checks. If you are unsure, use LZMA_CHECK_CRC32.
Returns:
- LZMA_OK: Initialization succeeded. Use lzma_code() to encode your data.
  • LZMA_MEM_ERROR: Memory allocation failed. All memory previously allocated for *strm is now freed.
  • LZMA_OPTIONS_ERROR: The given compression level is not supported by this build of liblzma.
  • LZMA_UNSUPPORTED_CHECK: The given check type is not supported by this liblzma build.
  • LZMA_PROG_ERROR: One or more of the parameters have values that will never be valid. For example, strm == NULL.
If initialization succeeds, use lzma_code() to do the actual encoding. Valid values for `action' (the second argument of lzma_code()) are LZMA_RUN, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, and LZMA_FINISH. In future, there may be compression levels or flags that don't support LZMA_SYNC_FLUSH.

Parameters:
strm Pointer to properly prepared lzma_stream
filters Array of filters. This must be terminated with filters[n].id = LZMA_VLI_UNKNOWN. See filter.h for more information.
check Type of the integrity check to calculate from uncompressed data.
Returns:
- LZMA_OK: Initialization was successful.
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
The .lzma format is sometimes called the LZMA_Alone format, which is the reason for the name of this function. The .lzma format supports only the LZMA1 filter. There is no support for integrity checks like CRC32.

Use this function if and only if you need to create files readable by legacy LZMA tools such as LZMA Utils 4.32.x. Moving to the .xz format is strongly recommended.

The valid action values for lzma_code() are LZMA_RUN and LZMA_FINISH. No kind of flushing is supported, because the file format doesn't make it possible.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_PROG_ERROR
Parameters:
filters Array of filters. This must be terminated with filters[n].id = LZMA_VLI_UNKNOWN. See filter.h for more information.
check Type of the integrity check to calculate from uncompressed data.
allocator lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
in Beginning of the input buffer
in_size Size of the input buffer
out Beginning of the output buffer
out_pos The next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_size Size of the out buffer; the first byte into which no data is written to is out[out_size].
Returns:
- LZMA_OK: Encoding was successful.
  • LZMA_BUF_ERROR: Not enough output buffer space.
  • LZMA_OPTIONS_ERROR
  • LZMA_MEM_ERROR
  • LZMA_DATA_ERROR
  • LZMA_PROG_ERROR
Parameters:
strm Pointer to properly prepared lzma_stream
memlimit Rough memory usage limit as bytes
flags Bitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_TELL_ANY_CHECK, LZMA_CONCATENATED
Returns:
- LZMA_OK: Initialization was successful.
  • LZMA_MEM_ERROR: Cannot allocate memory.
  • LZMA_OPTIONS_ERROR: Unsupported flags
This decoder autodetects between the .xz and .lzma file formats, and calls lzma_stream_decoder() or lzma_alone_decoder() once the type of the input file has been detected.

Parameters:
strm Pointer to properly prepared lzma_stream
memlimit Rough memory usage limit as bytes
flags Bitwise-or of flags, or zero for no flags.
Returns:
- LZMA_OK: Initialization was successful.
  • LZMA_MEM_ERROR: Cannot allocate memory.
  • LZMA_OPTIONS_ERROR: Unsupported flags
Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. There is no need to use LZMA_FINISH, but allowing it may simplify certain types of applications.

Returns:
- LZMA_OK
  • LZMA_MEM_ERROR
Parameters:
memlimit Pointer to how much memory the decoder is allowed to allocate. The value pointed by this pointer is modified if and only if LZMA_MEMLIMIT_ERROR is returned.
flags Bitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_CONCATENATED. Note that LZMA_TELL_ANY_CHECK is not allowed and will return LZMA_PROG_ERROR.
allocator lzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
in Beginning of the input buffer
in_pos The next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_size Size of the input buffer; the first byte that won't be read is in[in_size].
out Beginning of the output buffer
out_pos The next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_size Size of the out buffer; the first byte into which no data is written to is out[out_size].
Returns:
- LZMA_OK: Decoding was successful.
  • LZMA_FORMAT_ERROR
  • LZMA_OPTIONS_ERROR
  • LZMA_DATA_ERROR
  • LZMA_NO_CHECK: This can be returned only if using the LZMA_TELL_NO_CHECK flag.
  • LZMA_UNSUPPORTED_CHECK: This can be returned only if using the LZMA_TELL_UNSUPPORTED_CHECK flag.
  • LZMA_MEM_ERROR
  • LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. The minimum required memlimit value was stored to *memlimit.
  • LZMA_BUF_ERROR: Output buffer was too small.
  • LZMA_PROG_ERROR

LZMA_API ( size_t   ) 

Calculate output buffer size for single-call Stream encoder.

When trying to compress uncompressible data, the encoded size will be slightly bigger than the input data. This function calculates how much output buffer space is required to be sure that lzma_stream_buffer_encode() doesn't return LZMA_BUF_ERROR.

The calculated value is not exact, but it is guaranteed to be big enough. The actual maximum output space required may be slightly smaller (up to about 100 bytes). This should not be a problem in practice.

If the calculated maximum size doesn't fit into size_t or would make the Stream grow past LZMA_VLI_MAX (which should never happen in practice), zero is returned to indicate the error.

Note:
The limit calculated by this function applies only to single-call encoding. Multi-call encoding may (and probably will) have larger maximum expansion when encoding uncompressible data. Currently there is no function to calculate the maximum expansion of multi-call encoding.
Calculate output buffer size for single-call Stream encoder.

This is equivalent to lzma_stream_buffer_bound() but for .xz Blocks. See the documentation of lzma_stream_buffer_bound().

References HEADERS_BOUND, LZMA_VLI_C, and LZMA_VLI_MAX.


Generated on Wed May 25 10:35:38 2011 for XZ Utils by  doxygen 1.5.5