From 5262a872f308b3b584c97d621992fb3877e392b8 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 05:10:08 +0200 Subject: Adding upstream version 5.6.1+really5.4.5. Signed-off-by: Daniel Baumann --- doc/api/annotated.html | 68 + doc/api/base_8h.html | 580 ++++++ doc/api/bc_s.png | Bin 0 -> 675 bytes doc/api/bc_sd.png | Bin 0 -> 604 bytes doc/api/bcj_8h.html | 105 ++ doc/api/block_8h.html | 758 ++++++++ doc/api/check_8h.html | 340 ++++ doc/api/classes.html | 60 + doc/api/closed.png | Bin 0 -> 132 bytes doc/api/container_8h.html | 1279 +++++++++++++ doc/api/delta_8h.html | 132 ++ doc/api/dir_b17a1d403082bd69a703ed987cf158fb.html | 104 ++ doc/api/doc.svg | 12 + doc/api/docd.svg | 12 + doc/api/doxygen.css | 2017 +++++++++++++++++++++ doc/api/doxygen.svg | 28 + doc/api/files.html | 74 + doc/api/filter_8h.html | 1342 ++++++++++++++ doc/api/folderclosed.svg | 11 + doc/api/folderclosedd.svg | 11 + doc/api/folderopen.svg | 17 + doc/api/folderopend.svg | 12 + doc/api/functions.html | 210 +++ doc/api/functions_vars.html | 210 +++ doc/api/globals.html | 272 +++ doc/api/globals_defs.html | 119 ++ doc/api/globals_enum.html | 71 + doc/api/globals_eval.html | 103 ++ doc/api/globals_func.html | 177 ++ doc/api/globals_type.html | 68 + doc/api/hardware_8h.html | 123 ++ doc/api/index.html | 53 + doc/api/index_8h.html | 1268 +++++++++++++ doc/api/index__hash_8h.html | 311 ++++ doc/api/lzma12_8h.html | 436 +++++ doc/api/lzma_8h.html | 109 ++ doc/api/nav_f.png | Bin 0 -> 167 bytes doc/api/nav_fd.png | Bin 0 -> 144 bytes doc/api/nav_g.png | Bin 0 -> 95 bytes doc/api/nav_h.png | Bin 0 -> 97 bytes doc/api/nav_hd.png | Bin 0 -> 104 bytes doc/api/open.png | Bin 0 -> 121 bytes doc/api/splitbar.png | Bin 0 -> 309 bytes doc/api/splitbard.png | Bin 0 -> 278 bytes doc/api/stream__flags_8h.html | 348 ++++ doc/api/structlzma__allocator.html | 153 ++ doc/api/structlzma__block.html | 347 ++++ doc/api/structlzma__filter.html | 114 ++ doc/api/structlzma__index__iter.html | 407 +++++ doc/api/structlzma__mt.html | 256 +++ doc/api/structlzma__options__bcj.html | 95 + doc/api/structlzma__options__delta.html | 113 ++ doc/api/structlzma__options__lzma.html | 363 ++++ doc/api/structlzma__stream.html | 251 +++ doc/api/structlzma__stream__flags.html | 134 ++ doc/api/sync_off.png | Bin 0 -> 857 bytes doc/api/sync_on.png | Bin 0 -> 851 bytes doc/api/tab_a.png | Bin 0 -> 135 bytes doc/api/tab_ad.png | Bin 0 -> 133 bytes doc/api/tab_b.png | Bin 0 -> 178 bytes doc/api/tab_bd.png | Bin 0 -> 157 bytes doc/api/tab_h.png | Bin 0 -> 179 bytes doc/api/tab_hd.png | Bin 0 -> 168 bytes doc/api/tab_s.png | Bin 0 -> 208 bytes doc/api/tab_sd.png | Bin 0 -> 171 bytes doc/api/tabs.css | 62 + doc/api/version_8h.html | 239 +++ doc/api/vli_8h.html | 323 ++++ doc/examples/00_README.txt | 31 + doc/examples/01_compress_easy.c | 297 +++ doc/examples/02_decompress.c | 287 +++ doc/examples/03_compress_custom.c | 193 ++ doc/examples/04_compress_easy_mt.c | 206 +++ doc/examples/Makefile | 25 + doc/examples_old/xz_pipe_comp.c | 127 ++ doc/examples_old/xz_pipe_decomp.c | 123 ++ doc/faq.txt | 244 +++ doc/history.txt | 150 ++ doc/lzma-file-format.txt | 173 ++ doc/man/pdf-a4/lzmainfo-a4.pdf | Bin 0 -> 16384 bytes doc/man/pdf-a4/xz-a4.pdf | Bin 0 -> 114746 bytes doc/man/pdf-a4/xzdec-a4.pdf | Bin 0 -> 19978 bytes doc/man/pdf-a4/xzdiff-a4.pdf | Bin 0 -> 17200 bytes doc/man/pdf-a4/xzgrep-a4.pdf | Bin 0 -> 18338 bytes doc/man/pdf-a4/xzless-a4.pdf | Bin 0 -> 15029 bytes doc/man/pdf-a4/xzmore-a4.pdf | Bin 0 -> 15203 bytes doc/man/pdf-letter/lzmainfo-letter.pdf | Bin 0 -> 16394 bytes doc/man/pdf-letter/xz-letter.pdf | Bin 0 -> 115882 bytes doc/man/pdf-letter/xzdec-letter.pdf | Bin 0 -> 19970 bytes doc/man/pdf-letter/xzdiff-letter.pdf | Bin 0 -> 17227 bytes doc/man/pdf-letter/xzgrep-letter.pdf | Bin 0 -> 18322 bytes doc/man/pdf-letter/xzless-letter.pdf | Bin 0 -> 15022 bytes doc/man/pdf-letter/xzmore-letter.pdf | Bin 0 -> 15159 bytes doc/man/txt/lzmainfo.txt | 40 + doc/man/txt/xz.txt | 1586 ++++++++++++++++ doc/man/txt/xzdec.txt | 80 + doc/man/txt/xzdiff.txt | 37 + doc/man/txt/xzgrep.txt | 49 + doc/man/txt/xzless.txt | 39 + doc/man/txt/xzmore.txt | 34 + doc/xz-file-format.txt | 1165 ++++++++++++ 101 files changed, 18583 insertions(+) create mode 100644 doc/api/annotated.html create mode 100644 doc/api/base_8h.html create mode 100644 doc/api/bc_s.png create mode 100644 doc/api/bc_sd.png create mode 100644 doc/api/bcj_8h.html create mode 100644 doc/api/block_8h.html create mode 100644 doc/api/check_8h.html create mode 100644 doc/api/classes.html create mode 100644 doc/api/closed.png create mode 100644 doc/api/container_8h.html create mode 100644 doc/api/delta_8h.html create mode 100644 doc/api/dir_b17a1d403082bd69a703ed987cf158fb.html create mode 100644 doc/api/doc.svg create mode 100644 doc/api/docd.svg create mode 100644 doc/api/doxygen.css create mode 100644 doc/api/doxygen.svg create mode 100644 doc/api/files.html create mode 100644 doc/api/filter_8h.html create mode 100644 doc/api/folderclosed.svg create mode 100644 doc/api/folderclosedd.svg create mode 100644 doc/api/folderopen.svg create mode 100644 doc/api/folderopend.svg create mode 100644 doc/api/functions.html create mode 100644 doc/api/functions_vars.html create mode 100644 doc/api/globals.html create mode 100644 doc/api/globals_defs.html create mode 100644 doc/api/globals_enum.html create mode 100644 doc/api/globals_eval.html create mode 100644 doc/api/globals_func.html create mode 100644 doc/api/globals_type.html create mode 100644 doc/api/hardware_8h.html create mode 100644 doc/api/index.html create mode 100644 doc/api/index_8h.html create mode 100644 doc/api/index__hash_8h.html create mode 100644 doc/api/lzma12_8h.html create mode 100644 doc/api/lzma_8h.html create mode 100644 doc/api/nav_f.png create mode 100644 doc/api/nav_fd.png create mode 100644 doc/api/nav_g.png create mode 100644 doc/api/nav_h.png create mode 100644 doc/api/nav_hd.png create mode 100644 doc/api/open.png create mode 100644 doc/api/splitbar.png create mode 100644 doc/api/splitbard.png create mode 100644 doc/api/stream__flags_8h.html create mode 100644 doc/api/structlzma__allocator.html create mode 100644 doc/api/structlzma__block.html create mode 100644 doc/api/structlzma__filter.html create mode 100644 doc/api/structlzma__index__iter.html create mode 100644 doc/api/structlzma__mt.html create mode 100644 doc/api/structlzma__options__bcj.html create mode 100644 doc/api/structlzma__options__delta.html create mode 100644 doc/api/structlzma__options__lzma.html create mode 100644 doc/api/structlzma__stream.html create mode 100644 doc/api/structlzma__stream__flags.html create mode 100644 doc/api/sync_off.png create mode 100644 doc/api/sync_on.png create mode 100644 doc/api/tab_a.png create mode 100644 doc/api/tab_ad.png create mode 100644 doc/api/tab_b.png create mode 100644 doc/api/tab_bd.png create mode 100644 doc/api/tab_h.png create mode 100644 doc/api/tab_hd.png create mode 100644 doc/api/tab_s.png create mode 100644 doc/api/tab_sd.png create mode 100644 doc/api/tabs.css create mode 100644 doc/api/version_8h.html create mode 100644 doc/api/vli_8h.html create mode 100644 doc/examples/00_README.txt create mode 100644 doc/examples/01_compress_easy.c create mode 100644 doc/examples/02_decompress.c create mode 100644 doc/examples/03_compress_custom.c create mode 100644 doc/examples/04_compress_easy_mt.c create mode 100644 doc/examples/Makefile create mode 100644 doc/examples_old/xz_pipe_comp.c create mode 100644 doc/examples_old/xz_pipe_decomp.c create mode 100644 doc/faq.txt create mode 100644 doc/history.txt create mode 100644 doc/lzma-file-format.txt create mode 100644 doc/man/pdf-a4/lzmainfo-a4.pdf create mode 100644 doc/man/pdf-a4/xz-a4.pdf create mode 100644 doc/man/pdf-a4/xzdec-a4.pdf create mode 100644 doc/man/pdf-a4/xzdiff-a4.pdf create mode 100644 doc/man/pdf-a4/xzgrep-a4.pdf create mode 100644 doc/man/pdf-a4/xzless-a4.pdf create mode 100644 doc/man/pdf-a4/xzmore-a4.pdf create mode 100644 doc/man/pdf-letter/lzmainfo-letter.pdf create mode 100644 doc/man/pdf-letter/xz-letter.pdf create mode 100644 doc/man/pdf-letter/xzdec-letter.pdf create mode 100644 doc/man/pdf-letter/xzdiff-letter.pdf create mode 100644 doc/man/pdf-letter/xzgrep-letter.pdf create mode 100644 doc/man/pdf-letter/xzless-letter.pdf create mode 100644 doc/man/pdf-letter/xzmore-letter.pdf create mode 100644 doc/man/txt/lzmainfo.txt create mode 100644 doc/man/txt/xz.txt create mode 100644 doc/man/txt/xzdec.txt create mode 100644 doc/man/txt/xzdiff.txt create mode 100644 doc/man/txt/xzgrep.txt create mode 100644 doc/man/txt/xzless.txt create mode 100644 doc/man/txt/xzmore.txt create mode 100644 doc/xz-file-format.txt (limited to 'doc') diff --git a/doc/api/annotated.html b/doc/api/annotated.html new file mode 100644 index 0000000..4016c49 --- /dev/null +++ b/doc/api/annotated.html @@ -0,0 +1,68 @@ + + + + + + + +liblzma (XZ Utils): Data Structures + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
Data Structures
+
+
+
Here are the data structures with brief descriptions:
+ + + + + + + + + + + +
 Clzma_allocatorCustom functions for memory handling
 Clzma_blockOptions for the Block and Block Header encoders and decoders
 Clzma_filterFilter options
 Clzma_index_iterIterator to get information about Blocks and Streams
 Clzma_mtMultithreading options
 Clzma_options_bcjOptions for BCJ filters
 Clzma_options_deltaOptions for the Delta filter
 Clzma_options_lzmaOptions specific to the LZMA1 and LZMA2 filters
 Clzma_streamPassing data to and from liblzma
 Clzma_stream_flagsOptions for encoding/decoding Stream Header and Stream Footer
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/base_8h.html b/doc/api/base_8h.html new file mode 100644 index 0000000..417ccef --- /dev/null +++ b/doc/api/base_8h.html @@ -0,0 +1,580 @@ + + + + + + + +liblzma (XZ Utils): lzma/base.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Typedefs | +Enumerations | +Functions
+
base.h File Reference
+
+
+ +

Data types and functions used in many places in liblzma API. +More...

+ + + + + + + + +

+Data Structures

struct  lzma_allocator
 Custom functions for memory handling. More...
 
struct  lzma_stream
 Passing data to and from liblzma. More...
 
+ + + + +

+Macros

#define LZMA_STREAM_INIT
 Initialization for lzma_stream.
 
+ + + + + + + +

+Typedefs

typedef unsigned char lzma_bool
 Boolean.
 
typedef struct lzma_internal_s lzma_internal
 Internal data structure.
 
+ + + + + + + + + + +

+Enumerations

enum  lzma_reserved_enum { LZMA_RESERVED_ENUM = 0 + }
 Type of reserved enumeration variable in structures. More...
 
enum  lzma_ret {
+  LZMA_OK = 0 +, LZMA_STREAM_END = 1 +, LZMA_NO_CHECK = 2 +, LZMA_UNSUPPORTED_CHECK = 3 +,
+  LZMA_GET_CHECK = 4 +, LZMA_MEM_ERROR = 5 +, LZMA_MEMLIMIT_ERROR = 6 +, LZMA_FORMAT_ERROR = 7 +,
+  LZMA_OPTIONS_ERROR = 8 +, LZMA_DATA_ERROR = 9 +, LZMA_BUF_ERROR = 10 +, LZMA_PROG_ERROR = 11 +,
+  LZMA_SEEK_NEEDED = 12 +, LZMA_RET_INTERNAL1 = 101 +, LZMA_RET_INTERNAL2 = 102 +, LZMA_RET_INTERNAL3 = 103 +,
+  LZMA_RET_INTERNAL4 = 104 +, LZMA_RET_INTERNAL5 = 105 +, LZMA_RET_INTERNAL6 = 106 +, LZMA_RET_INTERNAL7 = 107 +,
+  LZMA_RET_INTERNAL8 = 108 +
+ }
 Return values used by several functions in liblzma. More...
 
enum  lzma_action {
+  LZMA_RUN = 0 +, LZMA_SYNC_FLUSH = 1 +, LZMA_FULL_FLUSH = 2 +, LZMA_FULL_BARRIER = 4 +,
+  LZMA_FINISH = 3 +
+ }
 The `action' argument for lzma_code() More...
 
+ + + + + + + + + + + + + + + + + + + +

+Functions

lzma_ret lzma_code (lzma_stream *strm, lzma_action action) lzma_nothrow lzma_attr_warn_unused_result
 Encode or decode data.
 
void lzma_end (lzma_stream *strm) lzma_nothrow
 Free memory allocated for the coder data structures.
 
void lzma_get_progress (lzma_stream *strm, uint64_t *progress_in, uint64_t *progress_out) lzma_nothrow
 Get progress information.
 
uint64_t lzma_memusage (const lzma_stream *strm) lzma_nothrow lzma_attr_pure
 Get the memory usage of decoder filter chain.
 
uint64_t lzma_memlimit_get (const lzma_stream *strm) lzma_nothrow lzma_attr_pure
 Get the current memory usage limit.
 
lzma_ret lzma_memlimit_set (lzma_stream *strm, uint64_t memlimit) lzma_nothrow
 Set the memory usage limit.
 
+

Detailed Description

+

Data types and functions used in many places in liblzma API.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_STREAM_INIT

+ +
+
+ + + + +
#define LZMA_STREAM_INIT
+
+Value:
{ NULL, 0, 0, NULL, 0, 0, NULL, NULL, \
+
NULL, NULL, NULL, NULL, 0, 0, 0, 0, \
+
LZMA_RESERVED_ENUM, LZMA_RESERVED_ENUM }
+
+

Initialization for lzma_stream.

+

When you declare an instance of lzma_stream, you can immediately initialize it so that initialization functions know that no memory has been allocated yet:

+

lzma_stream strm = LZMA_STREAM_INIT;

+

If you need to initialize a dynamically allocated lzma_stream, you can use memset(strm_pointer, 0, sizeof(lzma_stream)). Strictly speaking, this violates the C standard since NULL may have different internal representation than zero, but it should be portable enough in practice. Anyway, for maximum portability, you can use something like this:

+

lzma_stream tmp = LZMA_STREAM_INIT; *strm = tmp;

+ +
+
+

Typedef Documentation

+ +

◆ lzma_bool

+ +
+
+ + + + +
typedef unsigned char lzma_bool
+
+ +

Boolean.

+

This is here because C89 doesn't have stdbool.h. To set a value for variables having type lzma_bool, you can use

    +
  • C99's `true' and `false' from stdbool.h;
    • +
  • C++'s internal `true' and `false'; or
    • +
  • integers one (true) and zero (false).
    • +
+ +
+
+ +

◆ lzma_internal

+ +
+
+ + + + +
typedef struct lzma_internal_s lzma_internal
+
+ +

Internal data structure.

+

The contents of this structure is not visible outside the library.

+ +
+
+

Enumeration Type Documentation

+ +

◆ lzma_reserved_enum

+ +
+
+ + + + +
enum lzma_reserved_enum
+
+ +

Type of reserved enumeration variable in structures.

+

To avoid breaking library ABI when new features are added, several structures contain extra variables that may be used in future. Since sizeof(enum) can be different than sizeof(int), and sizeof(enum) may even vary depending on the range of enumeration constants, we specify a separate type to be used for reserved enumeration variables. All enumeration constants in liblzma API will be non-negative and less than 128, which should guarantee that the ABI won't break even when new constants are added to existing enumerations.

+ +
+
+ +

◆ lzma_ret

+ +
+
+ + + + +
enum lzma_ret
+
+ +

Return values used by several functions in liblzma.

+

Check the descriptions of specific functions to find out which return values they can return. With some functions the return values may have more specific meanings than described here; those differences are described per-function basis.

+ + + + + + + + + + + + + + +
Enumerator
LZMA_OK 

Operation completed successfully.

+
LZMA_STREAM_END 

End of stream was reached.

+

In encoder, LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, or LZMA_FINISH was finished. In decoder, this indicates that all the data was successfully decoded.

+

In all cases, when LZMA_STREAM_END is returned, the last output bytes should be picked from strm->next_out.

+
LZMA_NO_CHECK 

Input stream has no integrity check.

+

This return value can be returned only if the LZMA_TELL_NO_CHECK flag was used when initializing the decoder. LZMA_NO_CHECK is just a warning, and the decoding can be continued normally.

+

It is possible to call lzma_get_check() immediately after lzma_code has returned LZMA_NO_CHECK. The result will naturally be LZMA_CHECK_NONE, but the possibility to call lzma_get_check() may be convenient in some applications.

+
LZMA_UNSUPPORTED_CHECK 

Cannot calculate the integrity check.

+

The usage of this return value is different in encoders and decoders.

+

Encoders can return this value only from the initialization function. If initialization fails with this value, the encoding cannot be done, because there's no way to produce output with the correct integrity check.

+

Decoders can return this value only from lzma_code() and only if the LZMA_TELL_UNSUPPORTED_CHECK flag was used when initializing the decoder. The decoding can still be continued normally even if the check type is unsupported, but naturally the check will not be validated, and possible errors may go undetected.

+

With decoder, it is possible to call lzma_get_check() immediately after lzma_code() has returned LZMA_UNSUPPORTED_CHECK. This way it is possible to find out what the unsupported Check ID was.

+
LZMA_GET_CHECK 

Integrity check type is now available.

+

This value can be returned only by the lzma_code() function and only if the decoder was initialized with the LZMA_TELL_ANY_CHECK flag. LZMA_GET_CHECK tells the application that it may now call lzma_get_check() to find out the Check ID. This can be used, for example, to implement a decoder that accepts only files that have strong enough integrity check.

+
LZMA_MEM_ERROR 

Cannot allocate memory.

+

Memory allocation failed, or the size of the allocation would be greater than SIZE_MAX.

+

Due to internal implementation reasons, the coding cannot be continued even if more memory were made available after LZMA_MEM_ERROR.

+
LZMA_MEMLIMIT_ERROR 

Memory usage limit was reached.

+

Decoder would need more memory than allowed by the specified memory usage limit. To continue decoding, the memory usage limit has to be increased with lzma_memlimit_set().

+

liblzma 5.2.6 and earlier had a bug in single-threaded .xz decoder (lzma_stream_decoder()) which made it impossible to continue decoding after LZMA_MEMLIMIT_ERROR even if the limit was increased using lzma_memlimit_set(). Other decoders worked correctly.

+
LZMA_FORMAT_ERROR 

File format not recognized.

+

The decoder did not recognize the input as supported file format. This error can occur, for example, when trying to decode .lzma format file with lzma_stream_decoder, because lzma_stream_decoder accepts only the .xz format.

+
LZMA_OPTIONS_ERROR 

Invalid or unsupported options.

+

Invalid or unsupported options, for example

    +
  • unsupported filter(s) or filter options; or
    • +
  • reserved bits set in headers (decoder only).
    • +
+

Rebuilding liblzma with more features enabled, or upgrading to a newer version of liblzma may help.

+
LZMA_DATA_ERROR 

Data is corrupt.

+

The usage of this return value is different in encoders and decoders. In both encoder and decoder, the coding cannot continue after this error.

+

Encoders return this if size limits of the target file format would be exceeded. These limits are huge, thus getting this error from an encoder is mostly theoretical. For example, the maximum compressed and uncompressed size of a .xz Stream is roughly 8 EiB (2^63 bytes).

+

Decoders return this error if the input data is corrupt. This can mean, for example, invalid CRC32 in headers or invalid check of uncompressed data.

+
LZMA_BUF_ERROR 

No progress is possible.

+

This error code is returned when the coder cannot consume any new input and produce any new output. The most common reason for this error is that the input stream being decoded is truncated or corrupt.

+

This error is not fatal. Coding can be continued normally by providing more input and/or more output space, if possible.

+

Typically the first call to lzma_code() that can do no progress returns LZMA_OK instead of LZMA_BUF_ERROR. Only the second consecutive call doing no progress will return LZMA_BUF_ERROR. This is intentional.

+

With zlib, Z_BUF_ERROR may be returned even if the application is doing nothing wrong, so apps will need to handle Z_BUF_ERROR specially. The above hack guarantees that liblzma never returns LZMA_BUF_ERROR to properly written applications unless the input file is truncated or corrupt. This should simplify the applications a little.

+
LZMA_PROG_ERROR 

Programming error.

+

This indicates that the arguments given to the function are invalid or the internal state of the decoder is corrupt.

    +
  • Function arguments are invalid or the structures pointed by the argument pointers are invalid e.g. if strm->next_out has been set to NULL and strm->avail_out > 0 when calling lzma_code().
    • +
  • lzma_* functions have been called in wrong order e.g. lzma_code() was called right after lzma_end().
    • +
  • If errors occur randomly, the reason might be flaky hardware.
    • +
+

If you think that your code is correct, this error code can be a sign of a bug in liblzma. See the documentation how to report bugs.

+
LZMA_SEEK_NEEDED 

Request to change the input file position.

+

Some coders can do random access in the input file. The initialization functions of these coders take the file size as an argument. No other coders can return LZMA_SEEK_NEEDED.

+

When this value is returned, the application must seek to the file position given in lzma_stream.seek_pos. This value is guaranteed to never exceed the file size that was specified at the coder initialization.

+

After seeking the application should read new input and pass it normally via lzma_stream.next_in and .avail_in.

+
+ +
+
+ +

◆ lzma_action

+ +
+
+ + + + +
enum lzma_action
+
+ +

The `action' argument for lzma_code()

+

After the first use of LZMA_SYNC_FLUSH, LZMA_FULL_FLUSH, LZMA_FULL_BARRIER, or LZMA_FINISH, the same `action' must be used until lzma_code() returns LZMA_STREAM_END. Also, the amount of input (that is, strm->avail_in) must not be modified by the application until lzma_code() returns LZMA_STREAM_END. Changing the `action' or modifying the amount of input will make lzma_code() return LZMA_PROG_ERROR.

+ + + + + + +
Enumerator
LZMA_RUN 

Continue coding.

+

Encoder: Encode as much input as possible. Some internal buffering will probably be done (depends on the filter chain in use), which causes latency: the input used won't usually be decodeable from the output of the same lzma_code() call.

+

Decoder: Decode as much input as possible and produce as much output as possible.

+
LZMA_SYNC_FLUSH 

Make all the input available at output.

+

Normally the encoder introduces some latency. LZMA_SYNC_FLUSH forces all the buffered data to be available at output without resetting the internal state of the encoder. This way it is possible to use compressed stream for example for communication over network.

+

Only some filters support LZMA_SYNC_FLUSH. Trying to use LZMA_SYNC_FLUSH with filters that don't support it will make lzma_code() return LZMA_OPTIONS_ERROR. For example, LZMA1 doesn't support LZMA_SYNC_FLUSH but LZMA2 does.

+

Using LZMA_SYNC_FLUSH very often can dramatically reduce the compression ratio. With some filters (for example, LZMA2), fine-tuning the compression options may help mitigate this problem significantly (for example, match finder with LZMA2).

+

Decoders don't support LZMA_SYNC_FLUSH.

+
LZMA_FULL_FLUSH 

Finish encoding of the current Block.

+

All the input data going to the current Block must have been given to the encoder (the last bytes can still be pending in *next_in). Call lzma_code() with LZMA_FULL_FLUSH until it returns LZMA_STREAM_END. Then continue normally with LZMA_RUN or finish the Stream with LZMA_FINISH.

+

This action is currently supported only by Stream encoder and easy encoder (which uses Stream encoder). If there is no unfinished Block, no empty Block is created.

+
LZMA_FULL_BARRIER 

Finish encoding of the current Block.

+

This is like LZMA_FULL_FLUSH except that this doesn't necessarily wait until all the input has been made available via the output buffer. That is, lzma_code() might return LZMA_STREAM_END as soon as all the input has been consumed (avail_in == 0).

+

LZMA_FULL_BARRIER is useful with a threaded encoder if one wants to split the .xz Stream into Blocks at specific offsets but doesn't care if the output isn't flushed immediately. Using LZMA_FULL_BARRIER allows keeping the threads busy while LZMA_FULL_FLUSH would make lzma_code() wait until all the threads have finished until more data could be passed to the encoder.

+

With a lzma_stream initialized with the single-threaded lzma_stream_encoder() or lzma_easy_encoder(), LZMA_FULL_BARRIER is an alias for LZMA_FULL_FLUSH.

+
LZMA_FINISH 

Finish the coding operation.

+

All the input data must have been given to the encoder (the last bytes can still be pending in next_in). Call lzma_code() with LZMA_FINISH until it returns LZMA_STREAM_END. Once LZMA_FINISH has been used, the amount of input must no longer be changed by the application.

+

When decoding, using LZMA_FINISH is optional unless the LZMA_CONCATENATED flag was used when the decoder was initialized. When LZMA_CONCATENATED was not used, the only effect of LZMA_FINISH is that the amount of input must not be changed just like in the encoder.

+
+ +
+
+

Function Documentation

+ +

◆ 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.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
actionAction for this function to take. Must be a valid lzma_action enum value.
+
+
+
Returns
Any valid lzma_ret. See the lzma_ret enum description for more information.
+ +
+
+ +

◆ lzma_end()

+ +
+
+ + + + + + + + +
void lzma_end (lzma_stream * strm)
+
+ +

Free memory allocated for the coder data structures.

+

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.
+
Parameters
+ + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
+
+
+ +
+
+ +

◆ 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.

+
Parameters
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
[out]progress_inPointer to the number of input bytes processed.
[out]progress_outPointer to the number of output bytes processed.
+
+
+ +
+
+ +

◆ 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.

+
Parameters
+ + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
+
+
+
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.

+ +
+
+ +

◆ 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.

+
Parameters
+ + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
+
+
+
Returns
On success, the current memory usage limit is returned (always non-zero). On error, zero is returned.
+ +
+
+ +

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

+

liblzma 5.2.6 and earlier had a bug in single-threaded .xz decoder (lzma_stream_decoder()) which made it impossible to continue decoding after LZMA_MEMLIMIT_ERROR even if the limit was increased using lzma_memlimit_set(). Other decoders worked correctly.

+
Returns
Possible lzma_ret values:
    +
  • 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.
    • +
+
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/bc_s.png b/doc/api/bc_s.png new file mode 100644 index 0000000..bb50b82 Binary files /dev/null and b/doc/api/bc_s.png differ diff --git a/doc/api/bc_sd.png b/doc/api/bc_sd.png new file mode 100644 index 0000000..8d8be4c Binary files /dev/null and b/doc/api/bc_sd.png differ diff --git a/doc/api/bcj_8h.html b/doc/api/bcj_8h.html new file mode 100644 index 0000000..1dabca4 --- /dev/null +++ b/doc/api/bcj_8h.html @@ -0,0 +1,105 @@ + + + + + + + +liblzma (XZ Utils): lzma/bcj.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros
+
bcj.h File Reference
+
+
+ +

Branch/Call/Jump conversion filters. +More...

+ + + + + +

+Data Structures

struct  lzma_options_bcj
 Options for BCJ filters. More...
 
+ + + + + + + + + + + + + + + + + + + + + + +

+Macros

+#define LZMA_FILTER_X86   LZMA_VLI_C(0x04)
 Filter for x86 binaries.
 
+#define LZMA_FILTER_POWERPC   LZMA_VLI_C(0x05)
 Filter for Big endian PowerPC binaries.
 
+#define LZMA_FILTER_IA64   LZMA_VLI_C(0x06)
 Filter for IA-64 (Itanium) binaries.
 
+#define LZMA_FILTER_ARM   LZMA_VLI_C(0x07)
 Filter for ARM binaries.
 
+#define LZMA_FILTER_ARMTHUMB   LZMA_VLI_C(0x08)
 Filter for ARM-Thumb binaries.
 
+#define LZMA_FILTER_SPARC   LZMA_VLI_C(0x09)
 Filter for SPARC binaries.
 
+#define LZMA_FILTER_ARM64   LZMA_VLI_C(0x0A)
 Filter for ARM64 binaries.
 
+

Detailed Description

+

Branch/Call/Jump conversion filters.

+
Note
Never include this file directly. Use <lzma.h> instead.
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/block_8h.html b/doc/api/block_8h.html new file mode 100644 index 0000000..e2e1702 --- /dev/null +++ b/doc/api/block_8h.html @@ -0,0 +1,758 @@ + + + + + + + +liblzma (XZ Utils): lzma/block.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Functions
+
block.h File Reference
+
+
+ +

.xz Block handling +More...

+ + + + + +

+Data Structures

struct  lzma_block
 Options for the Block and Block Header encoders and decoders. More...
 
+ + + + + + + + +

+Macros

+#define LZMA_BLOCK_HEADER_SIZE_MIN   8
 
+#define LZMA_BLOCK_HEADER_SIZE_MAX   1024
 
#define lzma_block_header_size_decode(b)   (((uint32_t)(b) + 1) * 4)
 Decode the Block Header Size field.
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

lzma_ret lzma_block_header_size (lzma_block *block) lzma_nothrow lzma_attr_warn_unused_result
 Calculate Block Header Size.
 
lzma_ret lzma_block_header_encode (const lzma_block *block, uint8_t *out) lzma_nothrow lzma_attr_warn_unused_result
 Encode Block Header.
 
lzma_ret lzma_block_header_decode (lzma_block *block, const lzma_allocator *allocator, const uint8_t *in) lzma_nothrow lzma_attr_warn_unused_result
 Decode Block Header.
 
lzma_ret lzma_block_compressed_size (lzma_block *block, lzma_vli unpadded_size) lzma_nothrow lzma_attr_warn_unused_result
 Validate and set Compressed Size according to Unpadded Size.
 
lzma_vli lzma_block_unpadded_size (const lzma_block *block) lzma_nothrow lzma_attr_pure
 Calculate Unpadded Size.
 
lzma_vli lzma_block_total_size (const lzma_block *block) lzma_nothrow lzma_attr_pure
 Calculate the total encoded size of a Block.
 
lzma_ret lzma_block_encoder (lzma_stream *strm, lzma_block *block) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Block encoder.
 
lzma_ret lzma_block_decoder (lzma_stream *strm, lzma_block *block) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Block decoder.
 
size_t lzma_block_buffer_bound (size_t uncompressed_size) lzma_nothrow
 Calculate maximum output size for single-call Block encoding.
 
lzma_ret lzma_block_buffer_encode (lzma_block *block, const lzma_allocator *allocator, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result
 Single-call .xz Block encoder.
 
lzma_ret lzma_block_uncomp_encode (lzma_block *block, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result
 Single-call uncompressed .xz Block encoder.
 
lzma_ret lzma_block_buffer_decode (lzma_block *block, const lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Single-call .xz Block decoder.
 
+

Detailed Description

+

.xz Block handling

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ lzma_block_header_size_decode

+ +
+
+ + + + + + + + +
#define lzma_block_header_size_decode( b)   (((uint32_t)(b) + 1) * 4)
+
+ +

Decode the Block Header Size field.

+

To decode Block Header using lzma_block_header_decode(), the size of the Block Header has to be known and stored into lzma_block.header_size. The size can be calculated from the first byte of a Block using this macro. Note that if the first byte is 0x00, it indicates beginning of Index; use this macro only when the byte is not 0x00.

+

There is no encoding macro because lzma_block_header_size() and lzma_block_header_encode() should be used.

+ +
+
+

Function Documentation

+ +

◆ lzma_block_header_size()

+ +
+
+ + + + + + + + +
lzma_ret lzma_block_header_size (lzma_block * block)
+
+ +

Calculate Block Header Size.

+

Calculate the minimum size needed for the Block Header field using the settings specified in the lzma_block structure. Note that it is OK to increase the calculated header_size value as long as it is a multiple of four and doesn't exceed LZMA_BLOCK_HEADER_SIZE_MAX. Increasing header_size just means that lzma_block_header_encode() will add Header Padding.

+
Note
This doesn't check that all the options are valid i.e. this may return LZMA_OK even if lzma_block_header_encode() or lzma_block_encoder() would fail. If you want to validate the filter chain, consider using lzma_memlimit_encoder() which as a side-effect validates the filter chain.
+
Parameters
+ + +
blockBlock options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Size calculated successfully and stored to block->header_size.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported version, filters or filter options.
    • +
  • LZMA_PROG_ERROR: Invalid values like compressed_size == 0.
    • +
+
+ +
+
+ +

◆ lzma_block_header_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_header_encode (const lzma_block * block,
uint8_t * out 
)
+
+ +

Encode Block Header.

+

The caller must have calculated the size of the Block Header already with lzma_block_header_size(). If a value larger than the one calculated by lzma_block_header_size() is used, the Block Header will be padded to the specified size.

+
Parameters
+ + + +
blockBlock options to be encoded.
[out]outBeginning of the output buffer. This must be at least block->header_size bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful. block->header_size bytes were written to output buffer.
    • +
  • LZMA_OPTIONS_ERROR: Invalid or unsupported options.
    • +
  • LZMA_PROG_ERROR: Invalid arguments, for example block->header_size is invalid or block->filters is NULL.
    • +
+
+ +
+
+ +

◆ lzma_block_header_decode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_header_decode (lzma_block * block,
const lzma_allocator * allocator,
const uint8_t * in 
)
+
+ +

Decode Block Header.

+

block->version should (usually) be set to the highest value supported by the application. If the application sets block->version to a value higher than supported by the current liblzma version, this function will downgrade block->version to the highest value supported by it. Thus one should check the value of block->version after calling this function if block->version was set to a non-zero value and the application doesn't otherwise know that the liblzma version being used is new enough to support the specified block->version.

+

The size of the Block Header must have already been decoded with lzma_block_header_size_decode() macro and stored to block->header_size.

+

The integrity check type from Stream Header must have been stored to block->check.

+

block->filters must have been allocated, but they don't need to be initialized (possible existing filter options are not freed).

+
Parameters
+ + + + +
[out]blockDestination for Block options
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() (and also free() if an error occurs).
inBeginning of the input buffer. This must be at least block->header_size bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful. block->header_size bytes were read from the input buffer.
    • +
  • LZMA_OPTIONS_ERROR: The Block Header specifies some unsupported options such as unsupported filters. This can happen also if block->version was set to a too low value compared to what would be required to properly represent the information stored in the Block Header.
    • +
  • LZMA_DATA_ERROR: Block Header is corrupt, for example, the CRC32 doesn't match.
    • +
  • LZMA_PROG_ERROR: Invalid arguments, for example block->header_size is invalid or block->filters is NULL.
    • +
+
+ +
+
+ +

◆ lzma_block_compressed_size()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_compressed_size (lzma_block * block,
lzma_vli unpadded_size 
)
+
+ +

Validate and set Compressed Size according to Unpadded Size.

+

Block Header stores Compressed Size, but Index has Unpadded Size. If the application has already parsed the Index and is now decoding Blocks, it can calculate Compressed Size from Unpadded Size. This function does exactly that with error checking:

+
    +
  • Compressed Size calculated from Unpadded Size must be positive integer, that is, Unpadded Size must be big enough that after Block Header and Check fields there's still at least one byte for Compressed Size.
    • +
  • If Compressed Size was present in Block Header, the new value calculated from Unpadded Size is compared against the value from Block Header.
    • +
+
Note
This function must be called _after_ decoding the Block Header field so that it can properly validate Compressed Size if it was present in Block Header.
+
Parameters
+ + + +
blockBlock options: block->header_size must already be set with lzma_block_header_size().
unpadded_sizeUnpadded Size from the Index field in bytes
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: block->compressed_size was set successfully.
    • +
  • LZMA_DATA_ERROR: unpadded_size is too small compared to block->header_size and lzma_check_size(block->check).
    • +
  • LZMA_PROG_ERROR: Some values are invalid. For example, block->header_size must be a multiple of four and between 8 and 1024 inclusive.
    • +
+
+ +
+
+ +

◆ lzma_block_unpadded_size()

+ +
+
+ + + + + + + + +
lzma_vli lzma_block_unpadded_size (const lzma_block * block)
+
+ +

Calculate Unpadded Size.

+

The Index field stores Unpadded Size and Uncompressed Size. The latter can be taken directly from the lzma_block structure after coding a Block, but Unpadded Size needs to be calculated from Block Header Size, Compressed Size, and size of the Check field. This is where this function is needed.

+
Parameters
+ + +
blockBlock options: block->header_size must already be set with lzma_block_header_size().
+
+
+
Returns
Unpadded Size on success, or zero on error.
+ +
+
+ +

◆ lzma_block_total_size()

+ +
+
+ + + + + + + + +
lzma_vli lzma_block_total_size (const lzma_block * block)
+
+ +

Calculate the total encoded size of a Block.

+

This is equivalent to lzma_block_unpadded_size() except that the returned value includes the size of the Block Padding field.

+
Parameters
+ + +
blockBlock options: block->header_size must already be set with lzma_block_header_size().
+
+
+
Returns
On success, total encoded size of the Block. On error, zero is returned.
+ +
+
+ +

◆ lzma_block_encoder()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_encoder (lzma_stream * strm,
lzma_block * block 
)
+
+ +

Initialize .xz Block encoder.

+

Valid actions for lzma_code() are LZMA_RUN, LZMA_SYNC_FLUSH (only if the filter chain supports it), and LZMA_FINISH.

+

The Block encoder encodes the Block Data, Block Padding, and Check value. It does NOT encode the Block Header which can be encoded with lzma_block_header_encode().

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
blockBlock options: block->version, block->check, and block->filters must have been initialized.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: All good, continue with lzma_code().
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_UNSUPPORTED_CHECK: block->check specifies a Check ID that is not supported by this build of liblzma. Initializing the encoder failed.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_block_decoder()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_decoder (lzma_stream * strm,
lzma_block * block 
)
+
+ +

Initialize .xz Block decoder.

+

Valid actions for lzma_code() are LZMA_RUN and LZMA_FINISH. Using LZMA_FINISH is not required. It is supported only for convenience.

+

The Block decoder decodes the Block Data, Block Padding, and Check value. It does NOT decode the Block Header which can be decoded with lzma_block_header_decode().

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
blockBlock options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: All good, continue with lzma_code().
    • +
  • LZMA_PROG_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
+
+ +
+
+ +

◆ lzma_block_buffer_bound()

+ +
+
+ + + + + + + + +
size_t lzma_block_buffer_bound (size_t uncompressed_size)
+
+ +

Calculate maximum output size for single-call Block encoding.

+

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

+
Parameters
+ + +
uncompressed_sizeSize of the data to be encoded with the single-call Block encoder.
+
+
+
Returns
Maximum output size in bytes for single-call Block encoding.
+ +
+
+ +

◆ lzma_block_buffer_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_buffer_encode (lzma_block * block,
const lzma_allocator * allocator,
const uint8_t * in,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+
+ +

Single-call .xz Block encoder.

+

In contrast to the multi-call encoder initialized with lzma_block_encoder(), this function encodes also the Block Header. This is required to make it possible to write appropriate Block Header also in case the data isn't compressible, and different filter chain has to be used to encode the data in uncompressed form using uncompressed chunks of the LZMA2 filter.

+

When the data isn't compressible, header_size, compressed_size, and uncompressed_size are set just like when the data was compressible, but it is possible that header_size is too small to hold the filter chain specified in block->filters, because that isn't necessarily the filter chain that was actually used to encode the data. lzma_block_unpadded_size() still works normally, because it doesn't read the filters array.

+
Parameters
+ + + + + + + + +
blockBlock options: block->version, block->check, and block->filters must have been initialized.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_sizeSize of the input buffer
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_BUF_ERROR: Not enough output buffer space.
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_block_uncomp_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_uncomp_encode (lzma_block * block,
const uint8_t * in,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+
+ +

Single-call uncompressed .xz Block encoder.

+

This is like lzma_block_buffer_encode() except this doesn't try to compress the data and instead encodes the data using LZMA2 uncompressed chunks. The required output buffer size can be determined with lzma_block_buffer_bound().

+

Since the data won't be compressed, this function ignores block->filters. This function doesn't take lzma_allocator because this function doesn't allocate any memory from the heap.

+
Parameters
+ + + + + + + +
blockBlock options: block->version, block->check, and block->filters must have been initialized.
inBeginning of the input buffer
in_sizeSize of the input buffer
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_BUF_ERROR: Not enough output buffer space.
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_block_buffer_decode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_block_buffer_decode (lzma_block * block,
const lzma_allocator * allocator,
const uint8_t * in,
size_t * in_pos,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+
+ +

Single-call .xz Block decoder.

+

This is single-call equivalent of lzma_block_decoder(), and requires that the caller has already decoded Block Header and checked its memory usage.

+
Parameters
+ + + + + + + + + +
blockBlock options
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_posThe next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_sizeSize of the input buffer; the first byte that won't be read is in[in_size].
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful.
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_BUF_ERROR: Output buffer was too small.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/check_8h.html b/doc/api/check_8h.html new file mode 100644 index 0000000..2323c6c --- /dev/null +++ b/doc/api/check_8h.html @@ -0,0 +1,340 @@ + + + + + + + +liblzma (XZ Utils): lzma/check.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Macros | +Enumerations | +Functions
+
check.h File Reference
+
+
+ +

Integrity checks. +More...

+ + + + + + + + +

+Macros

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

+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_bool lzma_check_is_supported (lzma_check check) lzma_nothrow lzma_attr_const
 Test if the given Check ID is supported.
 
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.
 
uint32_t lzma_crc32 (const uint8_t *buf, size_t size, uint32_t crc) lzma_nothrow lzma_attr_pure
 Calculate CRC32.
 
uint64_t lzma_crc64 (const uint8_t *buf, size_t size, uint64_t crc) lzma_nothrow lzma_attr_pure
 Calculate CRC64.
 
lzma_check lzma_get_check (const lzma_stream *strm) lzma_nothrow
 Get the type of the integrity check.
 
+

Detailed Description

+

Integrity checks.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

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.

+ +
+
+

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

+
+ +
+
+

Function Documentation

+ +

◆ lzma_check_is_supported()

+ +
+
+ + + + + + + + +
lzma_bool lzma_check_is_supported (lzma_check check) const
+
+ +

Test if the given Check ID is supported.

+

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

+
Note
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.
+
Parameters
+ + +
checkCheck ID
+
+
+
Returns
lzma_bool:
    +
  • true if Check ID is supported by this liblzma build.
    • +
  • false otherwise.
    • +
+
+ +
+
+ +

◆ lzma_check_size()

+ +
+
+ + + + + + + + +
uint32_t lzma_check_size (lzma_check check) const
+
+ +

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

+

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 }

+
Parameters
+ + +
checkCheck ID
+
+
+
Returns
Size of the Check field in bytes. If the argument is not in the range [0, 15], UINT32_MAX is returned.
+ +
+
+ +

◆ lzma_crc32()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
uint32_t lzma_crc32 (const uint8_t * buf,
size_t size,
uint32_t crc 
)
+
+ +

Calculate CRC32.

+

Calculate CRC32 using the polynomial from the IEEE 802.3 standard.

+
Parameters
+ + + + +
bufPointer to the input buffer
sizeSize of the input buffer
crcPreviously 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_crc64()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
uint64_t lzma_crc64 (const uint8_t * buf,
size_t size,
uint64_t crc 
)
+
+ +

Calculate CRC64.

+

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

+

This function is used similarly to lzma_crc32().

+
Parameters
+ + + + +
bufPointer to the input buffer
sizeSize of the input buffer
crcPreviously 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_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.

+
Parameters
+ + +
strmPointer to lzma_stream meeting the above conditions.
+
+
+
Returns
Check ID in the lzma_stream, or undefined if called improperly.
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/classes.html b/doc/api/classes.html new file mode 100644 index 0000000..a010270 --- /dev/null +++ b/doc/api/classes.html @@ -0,0 +1,60 @@ + + + + + + + +liblzma (XZ Utils): Data Structure Index + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
Data Structure Index
+
+
+
L
+
+
+
L
+
lzma_allocator
lzma_block
lzma_filter
lzma_index_iter
lzma_mt
lzma_options_bcj
lzma_options_delta
lzma_options_lzma
lzma_stream
lzma_stream_flags
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/closed.png b/doc/api/closed.png new file mode 100644 index 0000000..91f4888 Binary files /dev/null and b/doc/api/closed.png differ diff --git a/doc/api/container_8h.html b/doc/api/container_8h.html new file mode 100644 index 0000000..332b2b1 --- /dev/null +++ b/doc/api/container_8h.html @@ -0,0 +1,1279 @@ + + + + + + + +liblzma (XZ Utils): lzma/container.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Functions
+
container.h File Reference
+
+
+ +

File formats. +More...

+ + + + + +

+Data Structures

struct  lzma_mt
 Multithreading options. More...
 
+ + + + + + + + + + + + + + + + + + + + + + +

+Macros

#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_IGNORE_CHECK   UINT32_C(0x10)
 
#define LZMA_CONCATENATED   UINT32_C(0x08)
 
#define LZMA_FAIL_FAST   UINT32_C(0x20)
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

uint64_t lzma_easy_encoder_memusage (uint32_t preset) lzma_nothrow lzma_attr_pure
 Calculate approximate memory usage of easy encoder.
 
uint64_t lzma_easy_decoder_memusage (uint32_t preset) lzma_nothrow lzma_attr_pure
 Calculate approximate decoder memory usage of a preset.
 
lzma_ret lzma_easy_encoder (lzma_stream *strm, uint32_t preset, lzma_check check) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Stream encoder using a preset number.
 
lzma_ret lzma_easy_buffer_encode (uint32_t preset, lzma_check check, const lzma_allocator *allocator, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Single-call .xz Stream encoding using a preset number.
 
lzma_ret lzma_stream_encoder (lzma_stream *strm, const lzma_filter *filters, lzma_check check) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Stream encoder using a custom filter chain.
 
uint64_t lzma_stream_encoder_mt_memusage (const lzma_mt *options) lzma_nothrow lzma_attr_pure
 Calculate approximate memory usage of multithreaded .xz encoder.
 
lzma_ret lzma_stream_encoder_mt (lzma_stream *strm, const lzma_mt *options) lzma_nothrow lzma_attr_warn_unused_result
 Initialize multithreaded .xz Stream encoder.
 
lzma_ret lzma_alone_encoder (lzma_stream *strm, const lzma_options_lzma *options) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .lzma encoder (legacy file format)
 
size_t lzma_stream_buffer_bound (size_t uncompressed_size) lzma_nothrow
 Calculate output buffer size for single-call Stream encoder.
 
lzma_ret lzma_stream_buffer_encode (lzma_filter *filters, lzma_check check, const lzma_allocator *allocator, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result
 Single-call .xz Stream encoder.
 
lzma_ret lzma_microlzma_encoder (lzma_stream *strm, const lzma_options_lzma *options) lzma_nothrow
 MicroLZMA encoder.
 
lzma_ret lzma_stream_decoder (lzma_stream *strm, uint64_t memlimit, uint32_t flags) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Stream decoder.
 
lzma_ret lzma_stream_decoder_mt (lzma_stream *strm, const lzma_mt *options) lzma_nothrow lzma_attr_warn_unused_result
 Initialize multithreaded .xz Stream decoder.
 
lzma_ret lzma_auto_decoder (lzma_stream *strm, uint64_t memlimit, uint32_t flags) lzma_nothrow lzma_attr_warn_unused_result
 Decode .xz, .lzma, and .lz (lzip) files with autodetection.
 
lzma_ret lzma_alone_decoder (lzma_stream *strm, uint64_t memlimit) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .lzma decoder (legacy file format)
 
lzma_ret lzma_lzip_decoder (lzma_stream *strm, uint64_t memlimit, uint32_t flags) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .lz (lzip) decoder (a foreign file format)
 
lzma_ret lzma_stream_buffer_decode (uint64_t *memlimit, uint32_t flags, const lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result
 Single-call .xz Stream decoder.
 
lzma_ret lzma_microlzma_decoder (lzma_stream *strm, uint64_t comp_size, uint64_t uncomp_size, lzma_bool uncomp_size_is_exact, uint32_t dict_size) lzma_nothrow
 MicroLZMA decoder.
 
+

Detailed Description

+

File formats.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_PRESET_DEFAULT

+ +
+
+ + + + +
#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.

+ +
+
+ +

◆ LZMA_PRESET_LEVEL_MASK

+ +
+
+ + + + +
#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.

+ +
+
+ +

◆ LZMA_PRESET_EXTREME

+ +
+
+ + + + +
#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 spending 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-3).

+ +
+
+ +

◆ LZMA_TELL_NO_CHECK

+ +
+
+ + + + +
#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.

+ +
+
+ +

◆ LZMA_TELL_UNSUPPORTED_CHECK

+ +
+
+ + + + +
#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.

+ +
+
+ +

◆ LZMA_TELL_ANY_CHECK

+ +
+
+ + + + +
#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().

+ +
+
+ +

◆ LZMA_IGNORE_CHECK

+ +
+
+ + + + +
#define LZMA_IGNORE_CHECK   UINT32_C(0x10)
+
+

This flag makes lzma_code() not calculate and verify the integrity check of the compressed data in .xz files. This means that invalid integrity check values won't be detected and LZMA_DATA_ERROR won't be returned in such cases.

+

This flag only affects the checks of the compressed data itself; the CRC32 values in the .xz headers will still be verified normally.

+

Don't use this flag unless you know what you are doing. Possible reasons to use this flag:

+
    +
  • Trying to recover data from a corrupt .xz file.
    • +
  • Speeding up decompression, which matters mostly with SHA-256 or with files that have compressed extremely well. It's recommended to not use this flag for this purpose unless the file integrity is verified externally in some other way.
    • +
+

Support for this flag was added in liblzma 5.1.4beta.

+ +
+
+ +

◆ LZMA_CONCATENATED

+ +
+
+ + + + +
#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 and .lz formats allow 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.

+ +
+
+ +

◆ LZMA_FAIL_FAST

+ +
+
+ + + + +
#define LZMA_FAIL_FAST   UINT32_C(0x20)
+
+

This flag makes the threaded decoder report errors (like LZMA_DATA_ERROR) as soon as they are detected. This saves time when the application has no interest in a partially decompressed truncated or corrupt file. Note that due to timing randomness, if the same truncated or corrupt input is decompressed multiple times with this flag, a different amount of output may be produced by different runs, and even the error code might vary.

+

When using LZMA_FAIL_FAST, it is recommended to use LZMA_FINISH to tell the decoder when no more input will be coming because it can help fast detection and reporting of truncated files. Note that in this situation truncated files might be diagnosed with LZMA_DATA_ERROR instead of LZMA_OK or LZMA_BUF_ERROR!

+

Without this flag the threaded decoder will provide as much output as possible at first and then report the pending error. This default behavior matches the single-threaded decoder and provides repeatable behavior with truncated or corrupt input. There are a few special cases where the behavior can still differ like memory allocation failures (LZMA_MEM_ERROR).

+

Single-threaded decoders currently ignore this flag.

+

Support for this flag was added in liblzma 5.3.3alpha. Note that in older versions this flag isn't supported (LZMA_OPTIONS_ERROR) even by functions that ignore this flag in newer liblzma versions.

+ +
+
+

Function Documentation

+ +

◆ lzma_easy_encoder_memusage()

+ +
+
+ + + + + + + + +
uint64_t lzma_easy_encoder_memusage (uint32_t preset)
+
+ +

Calculate approximate memory usage of easy encoder.

+

This function is a wrapper for lzma_raw_encoder_memusage().

+
Parameters
+ + +
presetCompression preset (level and possible flags)
+
+
+
Returns
Number of bytes of memory required for the given preset when encoding or UINT64_MAX on error.
+ +
+
+ +

◆ lzma_easy_decoder_memusage()

+ +
+
+ + + + + + + + +
uint64_t lzma_easy_decoder_memusage (uint32_t preset)
+
+ +

Calculate approximate decoder memory usage of a preset.

+

This function is a wrapper for lzma_raw_decoder_memusage().

+
Parameters
+ + +
presetCompression preset (level and possible flags)
+
+
+
Returns
Number of bytes of memory required to decompress a file that was compressed using the given preset or UINT64_MAX on error.
+ +
+
+ +

◆ lzma_easy_encoder()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_easy_encoder (lzma_stream * strm,
uint32_t preset,
lzma_check check 
)
+
+ +

Initialize .xz Stream encoder using a preset number.

+

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

+

If initialization fails (return value is not LZMA_OK), all the memory allocated for *strm by liblzma is always freed. Thus, there is no need to call lzma_end() after failed initialization.

+

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
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
presetCompression 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.
checkIntegrity check type to use. See check.h for available checks. The xz command line tool defaults to LZMA_CHECK_CRC64, which is a good choice if you are unsure. LZMA_CHECK_CRC32 is good too as long as the uncompressed file is not many gigabytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization succeeded. Use lzma_code() to encode your data.
    • +
  • LZMA_MEM_ERROR: Memory allocation failed.
    • +
  • LZMA_OPTIONS_ERROR: The given compression preset 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.
    • +
+
+ +
+
+ +

◆ lzma_easy_buffer_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_easy_buffer_encode (uint32_t preset,
lzma_check check,
const lzma_allocator * allocator,
const uint8_t * in,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+
+ +

Single-call .xz Stream encoding using a preset number.

+

The maximum required output buffer size can be calculated with lzma_stream_buffer_bound().

+
Parameters
+ + + + + + + + + +
presetCompression preset to use. See the description in lzma_easy_encoder().
checkType of the integrity check to calculate from uncompressed data.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_sizeSize of the input buffer
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_BUF_ERROR: Not enough output buffer space.
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_stream_encoder()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_encoder (lzma_stream * strm,
const lzma_filter * filters,
lzma_check check 
)
+
+ +

Initialize .xz Stream encoder using a custom filter chain.

+
Parameters
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN. See filters.h for more information.
checkType of the integrity check to calculate from uncompressed data.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization was successful.
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_stream_encoder_mt_memusage()

+ +
+
+ + + + + + + + +
uint64_t lzma_stream_encoder_mt_memusage (const lzma_mt * options)
+
+ +

Calculate approximate memory usage of multithreaded .xz encoder.

+

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
+ + +
optionsCompression 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.
+ +
+
+ +

◆ lzma_stream_encoder_mt()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_encoder_mt (lzma_stream * strm,
const lzma_mt * options 
)
+
+ +

Initialize multithreaded .xz Stream encoder.

+

This provides the functionality of lzma_easy_encoder() and lzma_stream_encoder() as a single function for multithreaded use.

+

The supported actions for lzma_code() are LZMA_RUN, LZMA_FULL_FLUSH, LZMA_FULL_BARRIER, and LZMA_FINISH. Support for LZMA_SYNC_FLUSH might be added in the future.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
optionsPointer to multithreaded compression options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_alone_encoder()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_alone_encoder (lzma_stream * strm,
const lzma_options_lzma * options 
)
+
+ +

Initialize .lzma encoder (legacy file format)

+

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.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
optionsPointer to encoder options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_stream_buffer_bound()

+ +
+
+ + + + + + + + +
size_t lzma_stream_buffer_bound (size_t uncompressed_size)
+
+ +

Calculate output buffer size for single-call Stream encoder.

+

When trying to compress incompressible 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 incompressible data. Currently there is no function to calculate the maximum expansion of multi-call encoding.
+
Parameters
+ + +
uncompressed_sizeSize in bytes of the uncompressed input data
+
+
+
Returns
Maximum number of bytes needed to store the compressed data.
+ +
+
+ +

◆ lzma_stream_buffer_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_buffer_encode (lzma_filter * filters,
lzma_check check,
const lzma_allocator * allocator,
const uint8_t * in,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+
+ +

Single-call .xz Stream encoder.

+
Parameters
+ + + + + + + + + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN. See filters.h for more information.
checkType of the integrity check to calculate from uncompressed data.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_sizeSize of the input buffer
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_BUF_ERROR: Not enough output buffer space.
    • +
  • LZMA_UNSUPPORTED_CHECK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_microlzma_encoder()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_microlzma_encoder (lzma_stream * strm,
const lzma_options_lzma * options 
)
+
+ +

MicroLZMA encoder.

+

The MicroLZMA format is a raw LZMA stream whose first byte (always 0x00) has been replaced with bitwise-negation of the LZMA properties (lc/lp/pb). This encoding ensures that the first byte of MicroLZMA stream is never 0x00. There is no end of payload marker and thus the uncompressed size must be stored separately. For the best error detection the dictionary size should be stored separately as well but alternatively one may use the uncompressed size as the dictionary size when decoding.

+

With the MicroLZMA encoder, lzma_code() behaves slightly unusually. The action argument must be LZMA_FINISH and the return value will never be LZMA_OK. Thus the encoding is always done with a single lzma_code() after the initialization. The benefit of the combination of initialization function and lzma_code() is that memory allocations can be re-used for better performance.

+

lzma_code() will try to encode as much input as is possible to fit into the given output buffer. If not all input can be encoded, the stream will be finished without encoding all the input. The caller must check both input and output buffer usage after lzma_code() (total_in and total_out in lzma_stream can be convenient). Often lzma_code() can fill the output buffer completely if there is a lot of input, but sometimes a few bytes may remain unused because the next LZMA symbol would require more space.

+

lzma_stream.avail_out must be at least 6. Otherwise LZMA_PROG_ERROR will be returned.

+

The LZMA dictionary should be reasonably low to speed up the encoder re-initialization. A good value is bigger than the resulting uncompressed size of most of the output chunks. For example, if output size is 4 KiB, dictionary size of 32 KiB or 64 KiB is good. If the data compresses extremely well, even 128 KiB may be useful.

+

The MicroLZMA format and this encoder variant were made with the EROFS file system in mind. This format may be convenient in other embedded uses too where many small streams are needed. XZ Embedded includes a decoder for this format.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
optionsPointer to encoder options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_STREAM_END: All good. Check the amounts of input used and output produced. Store the amount of input used (uncompressed size) as it needs to be known to decompress the data.
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR: In addition to the generic reasons for this error code, this may also be returned if there isn't enough output space (6 bytes) to create a valid MicroLZMA stream.
    • +
+
+ +
+
+ +

◆ lzma_stream_decoder()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_decoder (lzma_stream * strm,
uint64_t memlimit,
uint32_t flags 
)
+
+ +

Initialize .xz Stream decoder.

+
Parameters
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
memlimitMemory usage limit as bytes. Use UINT64_MAX to effectively disable the limiter. liblzma 5.2.3 and earlier don't allow 0 here and return LZMA_PROG_ERROR; later versions treat 0 as if 1 had been specified.
flagsBitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_TELL_ANY_CHECK, LZMA_IGNORE_CHECK, LZMA_CONCATENATED, LZMA_FAIL_FAST
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization was successful.
    • +
  • LZMA_MEM_ERROR: Cannot allocate memory.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported flags
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_stream_decoder_mt()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_decoder_mt (lzma_stream * strm,
const lzma_mt * options 
)
+
+ +

Initialize multithreaded .xz Stream decoder.

+

The decoder can decode multiple Blocks in parallel. This requires that each Block Header contains the Compressed Size and Uncompressed size fields which are added by the multi-threaded encoder, see lzma_stream_encoder_mt().

+

A Stream with one Block will only utilize one thread. A Stream with multiple Blocks but without size information in Block Headers will be processed in single-threaded mode in the same way as done by lzma_stream_decoder(). Concatenated Streams are processed one Stream at a time; no inter-Stream parallelization is done.

+

This function behaves like lzma_stream_decoder() when options->threads == 1 and options->memlimit_threading <= 1.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
optionsPointer to multithreaded compression options
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization was successful.
    • +
  • LZMA_MEM_ERROR: Cannot allocate memory.
    • +
  • LZMA_MEMLIMIT_ERROR: Memory usage limit was reached.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported flags.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_auto_decoder()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_auto_decoder (lzma_stream * strm,
uint64_t memlimit,
uint32_t flags 
)
+
+ +

Decode .xz, .lzma, and .lz (lzip) files with autodetection.

+

This decoder autodetects between the .xz, .lzma, and .lz file formats, and calls lzma_stream_decoder(), lzma_alone_decoder(), or lzma_lzip_decoder() once the type of the input file has been detected.

+

Support for .lz was added in 5.4.0.

+

If the flag LZMA_CONCATENATED is used and the input is a .lzma file: For historical reasons concatenated .lzma files aren't supported. If there is trailing data after one .lzma stream, lzma_code() will return LZMA_DATA_ERROR. (lzma_alone_decoder() doesn't have such a check as it doesn't support any decoder flags. It will return LZMA_STREAM_END after one .lzma stream.)

+
Parameters
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
memlimitMemory usage limit as bytes. Use UINT64_MAX to effectively disable the limiter. liblzma 5.2.3 and earlier don't allow 0 here and return LZMA_PROG_ERROR; later versions treat 0 as if 1 had been specified.
flagsBitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_TELL_ANY_CHECK, LZMA_IGNORE_CHECK, LZMA_CONCATENATED, LZMA_FAIL_FAST
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization was successful.
    • +
  • LZMA_MEM_ERROR: Cannot allocate memory.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported flags
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_alone_decoder()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_alone_decoder (lzma_stream * strm,
uint64_t memlimit 
)
+
+ +

Initialize .lzma decoder (legacy file format)

+

Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. There is no need to use LZMA_FINISH, but it's allowed because it may simplify certain types of applications.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
memlimitMemory usage limit as bytes. Use UINT64_MAX to effectively disable the limiter. liblzma 5.2.3 and earlier don't allow 0 here and return LZMA_PROG_ERROR; later versions treat 0 as if 1 had been specified.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_lzip_decoder()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_lzip_decoder (lzma_stream * strm,
uint64_t memlimit,
uint32_t flags 
)
+
+ +

Initialize .lz (lzip) decoder (a foreign file format)

+

This decoder supports the .lz format version 0 and the unextended .lz format version 1:

+
    +
  • Files in the format version 0 were produced by lzip 1.3 and older. Such files aren't common but may be found from file archives as a few source packages were released in this format. People might have old personal files in this format too. Decompression support for the format version 0 was removed in lzip 1.18.
    • +
  • lzip 1.3 added decompression support for .lz format version 1 files. Compression support was added in lzip 1.4. In lzip 1.6 the .lz format version 1 was extended to support the Sync Flush marker. This extension is not supported by liblzma. lzma_code() will return LZMA_DATA_ERROR at the location of the Sync Flush marker. In practice files with the Sync Flush marker are very rare and thus liblzma can decompress almost all .lz files.
    • +
+

Just like with lzma_stream_decoder() for .xz files, LZMA_CONCATENATED should be used when decompressing normal standalone .lz files.

+

The .lz format allows putting non-.lz data at the end of a file after at least one valid .lz member. That is, one can append custom data at the end of a .lz file and the decoder is required to ignore it. In liblzma this is relevant only when LZMA_CONCATENATED is used. In that case lzma_code() will return LZMA_STREAM_END and leave lzma_stream.next_in pointing to the first byte of the non-.lz data. An exception to this is if the first 1-3 bytes of the non-.lz data are identical to the .lz magic bytes (0x4C, 0x5A, 0x49, 0x50; "LZIP" in US-ASCII). In such a case the 1-3 bytes will have been ignored by lzma_code(). If one wishes to locate the non-.lz data reliably, one must ensure that the first byte isn't 0x4C. Actually one should ensure that none of the first four bytes of trailing data are equal to the magic bytes because lzip >= 1.20 requires it by default.

+
Parameters
+ + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
memlimitMemory usage limit as bytes. Use UINT64_MAX to effectively disable the limiter.
flagsBitwise-or of flags, or zero for no flags. All decoder flags listed above are supported although only LZMA_CONCATENATED and (in very rare cases) LZMA_IGNORE_CHECK are actually useful. LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, and LZMA_FAIL_FAST do nothing. LZMA_TELL_ANY_CHECK is supported for consistency only as CRC32 is always used in the .lz format.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization was successful.
    • +
  • LZMA_MEM_ERROR: Cannot allocate memory.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported flags
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_stream_buffer_decode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_buffer_decode (uint64_t * memlimit,
uint32_t flags,
const lzma_allocator * allocator,
const uint8_t * in,
size_t * in_pos,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+
+ +

Single-call .xz Stream decoder.

+
Parameters
+ + + + + + + + + + +
memlimitPointer 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.
flagsBitwise-or of zero or more of the decoder flags: LZMA_TELL_NO_CHECK, LZMA_TELL_UNSUPPORTED_CHECK, LZMA_IGNORE_CHECK, LZMA_CONCATENATED, LZMA_FAIL_FAST. Note that LZMA_TELL_ANY_CHECK is not allowed and will return LZMA_PROG_ERROR.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_posThe next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_sizeSize of the input buffer; the first byte that won't be read is in[in_size].
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if decoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • 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_microlzma_decoder()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_microlzma_decoder (lzma_stream * strm,
uint64_t comp_size,
uint64_t uncomp_size,
lzma_bool uncomp_size_is_exact,
uint32_t dict_size 
)
+
+ +

MicroLZMA decoder.

+

See lzma_microlzma_encoder() for more information.

+

The lzma_code() usage with this decoder is completely normal. The special behavior of lzma_code() applies to lzma_microlzma_encoder() only.

+
Parameters
+ + + + + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
comp_sizeCompressed size of the MicroLZMA stream. The caller must somehow know this exactly.
uncomp_sizeUncompressed size of the MicroLZMA stream. If the exact uncompressed size isn't known, this can be set to a value that is at most as big as the exact uncompressed size would be, but then the next argument uncomp_size_is_exact must be false.
uncomp_size_is_exactIf true, uncomp_size must be exactly correct. This will improve error detection at the end of the stream. If the exact uncompressed size isn't known, this must be false. uncomp_size must still be at most as big as the exact uncompressed size is. Setting this to false when the exact size is known will work but error detection at the end of the stream will be weaker.
dict_sizeLZMA dictionary size that was used when compressing the data. It is OK to use a bigger value too but liblzma will then allocate more memory than would actually be required and error detection will be slightly worse. (Note that with the implementation in XZ Embedded it doesn't affect the memory usage if one specifies bigger dictionary than actually required.)
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/delta_8h.html b/doc/api/delta_8h.html new file mode 100644 index 0000000..dd64be2 --- /dev/null +++ b/doc/api/delta_8h.html @@ -0,0 +1,132 @@ + + + + + + + +liblzma (XZ Utils): lzma/delta.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Enumerations
+
delta.h File Reference
+
+
+ +

Delta filter. +More...

+ + + + + +

+Data Structures

struct  lzma_options_delta
 Options for the Delta filter. More...
 
+ + + + + + + + + + +

+Macros

#define LZMA_FILTER_DELTA   LZMA_VLI_C(0x03)
 Filter ID.
 
+#define LZMA_DELTA_DIST_MIN   1
 Minimum value for lzma_options_delta.dist.
 
+#define LZMA_DELTA_DIST_MAX   256
 Maximum value for lzma_options_delta.dist.
 
+ + + + +

+Enumerations

enum  lzma_delta_type { LZMA_DELTA_TYPE_BYTE + }
 Type of the delta calculation. More...
 
+

Detailed Description

+

Delta filter.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_FILTER_DELTA

+ +
+
+ + + + +
#define LZMA_FILTER_DELTA   LZMA_VLI_C(0x03)
+
+ +

Filter ID.

+

Filter ID of the Delta filter. This is used as lzma_filter.id.

+ +
+
+

Enumeration Type Documentation

+ +

◆ lzma_delta_type

+ +
+
+ + + + +
enum lzma_delta_type
+
+ +

Type of the delta calculation.

+

Currently only byte-wise delta is supported. Other possible types could be, for example, delta of 16/32/64-bit little/big endian integers, but these are not currently planned since byte-wise delta is almost as good.

+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/dir_b17a1d403082bd69a703ed987cf158fb.html b/doc/api/dir_b17a1d403082bd69a703ed987cf158fb.html new file mode 100644 index 0000000..ff360ae --- /dev/null +++ b/doc/api/dir_b17a1d403082bd69a703ed987cf158fb.html @@ -0,0 +1,104 @@ + + + + + + + +liblzma (XZ Utils): lzma Directory Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
lzma Directory Reference
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Files

 base.h
 Data types and functions used in many places in liblzma API.
 
 bcj.h
 Branch/Call/Jump conversion filters.
 
 block.h
 .xz Block handling
 
 check.h
 Integrity checks.
 
 container.h
 File formats.
 
 delta.h
 Delta filter.
 
 filter.h
 Common filter related types and functions.
 
 hardware.h
 Hardware information.
 
 index.h
 Handling of .xz Index and related information.
 
 index_hash.h
 Validate Index by using a hash function.
 
 lzma12.h
 LZMA1 and LZMA2 filters.
 
 stream_flags.h
 .xz Stream Header and Stream Footer encoder and decoder
 
 version.h
 Version number.
 
 vli.h
 Variable-length integer handling.
 
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/doc.svg b/doc/api/doc.svg new file mode 100644 index 0000000..296728b --- /dev/null +++ b/doc/api/doc.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + diff --git a/doc/api/docd.svg b/doc/api/docd.svg new file mode 100644 index 0000000..65cf4b5 --- /dev/null +++ b/doc/api/docd.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + diff --git a/doc/api/doxygen.css b/doc/api/doxygen.css new file mode 100644 index 0000000..6ce2813 --- /dev/null +++ b/doc/api/doxygen.css @@ -0,0 +1,2017 @@ +/* The standard CSS for doxygen 1.9.7*/ + +html { +/* page base colors */ +--page-background-color: white; +--page-foreground-color: black; +--page-link-color: #144779; +--page-visited-link-color: #195794; + +/* index */ +--index-odd-item-bg-color: #F3F8FD; +--index-even-item-bg-color: white; +--index-header-color: black; +--index-separator-color: #A0A0A0; + +/* header */ +--header-background-color: #F5F9FD; +--header-separator-color: #A0C7EE; +--header-gradient-image: url('nav_h.png'); +--group-header-separator-color: #4491DE; +--group-header-color: #113B65; +--inherit-header-color: gray; + +--footer-foreground-color: #0C2B4A; +--footer-logo-width: 104px; +--citation-label-color: #10375F; +--glow-color: cyan; + +--title-background-color: white; +--title-separator-color: #1E67AF; +--directory-separator-color: #62A3E4; +--separator-color: #1B5D9E; + +--blockquote-background-color: #F1F7FC; +--blockquote-border-color: #62A3E4; + +--scrollbar-thumb-color: #62A3E4; +--scrollbar-background-color: #F5F9FD; + +--icon-background-color: #257FD9; +--icon-foreground-color: white; +--icon-doc-image: url('doc.svg'); +--icon-folder-open-image: url('folderopen.svg'); +--icon-folder-closed-image: url('folderclosed.svg'); + +/* brief member declaration list */ +--memdecl-background-color: #F5F9FD; +--memdecl-separator-color: #C8DFF5; +--memdecl-foreground-color: #555; +--memdecl-template-color: #195794; + +/* detailed member list */ +--memdef-border-color: #74ADE7; +--memdef-title-background-color: #D0E3F6; +--memdef-title-gradient-image: url('nav_f.png'); +--memdef-proto-background-color: #CAE0F5; +--memdef-proto-text-color: #0A233D; +--memdef-proto-text-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); +--memdef-doc-background-color: white; +--memdef-param-name-color: #602020; +--memdef-template-color: #195794; + +/* tables */ +--table-cell-border-color: #0D2F50; +--table-header-background-color: #123E6A; +--table-header-foreground-color: #FFFFFF; + +/* labels */ +--label-background-color: #257FD9; +--label-left-top-border-color: #1E67AF; +--label-right-bottom-border-color: #A0C7EE; +--label-foreground-color: white; + +/** navigation bar/tree/menu */ +--nav-background-color: #F5F9FD; +--nav-foreground-color: #113C67; +--nav-gradient-image: url('tab_b.png'); +--nav-gradient-hover-image: url('tab_h.png'); +--nav-gradient-active-image: url('tab_a.png'); +--nav-gradient-active-image-parent: url("../tab_a.png"); +--nav-separator-image: url('tab_s.png'); +--nav-breadcrumb-image: url('bc_s.png'); +--nav-breadcrumb-border-color: #9CC5EE; +--nav-splitbar-image: url('splitbar.png'); +--nav-font-size-level1: 13px; +--nav-font-size-level2: 10px; +--nav-font-size-level3: 9px; +--nav-text-normal-color: #0B2845; +--nav-text-hover-color: white; +--nav-text-active-color: white; +--nav-text-normal-shadow: 0px 1px 1px rgba(255, 255, 255, 0.9); +--nav-text-hover-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0); +--nav-text-active-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0); +--nav-menu-button-color: #113C67; +--nav-menu-background-color: white; +--nav-menu-foreground-color: #555555; +--nav-menu-toggle-color: rgba(255, 255, 255, 0.5); +--nav-arrow-color: #62A3E4; +--nav-arrow-selected-color: #62A3E4; + +/* table of contents */ +--toc-background-color: #EEF5FC; +--toc-border-color: #BFD9F4; +--toc-header-color: #195794; +--toc-down-arrow-image: url("data:image/svg+xml;utf8,&%238595;"); + +/** search field */ +--search-background-color: white; +--search-foreground-color: #909090; +--search-magnification-image: url('mag.svg'); +--search-magnification-select-image: url('mag_sel.svg'); +--search-active-color: black; +--search-filter-background-color: #F5F9FD; +--search-filter-foreground-color: black; +--search-filter-border-color: #5098E0; +--search-filter-highlight-text-color: white; +--search-filter-highlight-bg-color: #144779; +--search-results-foreground-color: #174F86; +--search-results-background-color: #E2EEFA; +--search-results-border-color: black; +--search-box-shadow: inset 0.5px 0.5px 3px 0px #555; + +/** code fragments */ +--code-keyword-color: #008000; +--code-type-keyword-color: #604020; +--code-flow-keyword-color: #E08000; +--code-comment-color: #800000; +--code-preprocessor-color: #806020; +--code-string-literal-color: #002080; +--code-char-literal-color: #008080; +--code-xml-cdata-color: black; +--code-vhdl-digit-color: #FF00FF; +--code-vhdl-char-color: #000000; +--code-vhdl-keyword-color: #700070; +--code-vhdl-logic-color: #FF0000; +--code-link-color: #195794; +--code-external-link-color: #195794; +--fragment-foreground-color: black; +--fragment-background-color: #F9FBFE; +--fragment-border-color: #A0C7EE; +--fragment-lineno-border-color: #00FF00; +--fragment-lineno-background-color: #E8E8E8; +--fragment-lineno-foreground-color: black; +--fragment-lineno-link-fg-color: #195794; +--fragment-lineno-link-bg-color: #D8D8D8; +--fragment-lineno-link-hover-fg-color: #195794; +--fragment-lineno-link-hover-bg-color: #C8C8C8; +--tooltip-foreground-color: black; +--tooltip-background-color: white; +--tooltip-border-color: gray; +--tooltip-doc-color: grey; +--tooltip-declaration-color: #006318; +--tooltip-link-color: #195794; +--tooltip-shadow: 1px 1px 7px gray; + +/** font-family */ +--font-family-normal: Roboto,sans-serif; +--font-family-monospace: 'JetBrains Mono',Consolas,Monaco,'Andale Mono','Ubuntu Mono',monospace,fixed; +--font-family-nav: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; +--font-family-title: Tahoma,Arial,sans-serif; +--font-family-toc: Verdana,'DejaVu Sans',Geneva,sans-serif; +--font-family-search: Arial,Verdana,sans-serif; +--font-family-icon: Arial,Helvetica; +--font-family-tooltip: Roboto,sans-serif; + +} + +@media (prefers-color-scheme: dark) { + html:not(.dark-mode) { + color-scheme: dark; + +/* page base colors */ +--page-background-color: black; +--page-foreground-color: #C9D1D9; +--page-link-color: #5098E0; +--page-visited-link-color: #6DA9E5; + +/* index */ +--index-odd-item-bg-color: #02070C; +--index-even-item-bg-color: black; +--index-header-color: #A0C7EE; +--index-separator-color: #10375F; + +/* header */ +--header-background-color: #010407; +--header-separator-color: #040F1A; +--header-gradient-image: url('nav_hd.png'); +--group-header-separator-color: #0B2845; +--group-header-color: #5098E0; +--inherit-header-color: #A0A0A0; + +--footer-foreground-color: #206DBA; +--footer-logo-width: 60px; +--citation-label-color: #5098E0; +--glow-color: cyan; + +--title-background-color: #010509; +--title-separator-color: #113A63; +--directory-separator-color: #0B2845; +--separator-color: #0B2845; + +--blockquote-background-color: #030C14; +--blockquote-border-color: #0B2845; + +--scrollbar-thumb-color: #0B2845; +--scrollbar-background-color: #010407; + +--icon-background-color: #10375F; +--icon-foreground-color: #A0C7EE; +--icon-doc-image: url('docd.svg'); +--icon-folder-open-image: url('folderopend.svg'); +--icon-folder-closed-image: url('folderclosedd.svg'); + +/* brief member declaration list */ +--memdecl-background-color: #02070C; +--memdecl-separator-color: #0D2D4D; +--memdecl-foreground-color: #BBB; +--memdecl-template-color: #3488DC; + +/* detailed member list */ +--memdef-border-color: #092138; +--memdef-title-background-color: #071829; +--memdef-title-gradient-image: url('nav_fd.png'); +--memdef-proto-background-color: #061524; +--memdef-proto-text-color: #64A4E4; +--memdef-proto-text-shadow: 0px 1px 1px rgba(0, 0, 0, 0.9); +--memdef-doc-background-color: black; +--memdef-param-name-color: #D28757; +--memdef-template-color: #3488DC; + +/* tables */ +--table-cell-border-color: #0B2845; +--table-header-background-color: #0B2845; +--table-header-foreground-color: #A0C7EE; + +/* labels */ +--label-background-color: #113B65; +--label-left-top-border-color: #195794; +--label-right-bottom-border-color: #0B2845; +--label-foreground-color: #CCCCCC; + +/** navigation bar/tree/menu */ +--nav-background-color: #030C14; +--nav-foreground-color: #113C67; +--nav-gradient-image: url('tab_bd.png'); +--nav-gradient-hover-image: url('tab_hd.png'); +--nav-gradient-active-image: url('tab_ad.png'); +--nav-gradient-active-image-parent: url("../tab_ad.png"); +--nav-separator-image: url('tab_sd.png'); +--nav-breadcrumb-image: url('bc_sd.png'); +--nav-breadcrumb-border-color: #0C2B4A; +--nav-splitbar-image: url('splitbard.png'); +--nav-font-size-level1: 13px; +--nav-font-size-level2: 10px; +--nav-font-size-level3: 9px; +--nav-text-normal-color: #8ABAEA; +--nav-text-hover-color: #C5DDF5; +--nav-text-active-color: #C5DDF5; +--nav-text-normal-shadow: 0px 1px 1px black; +--nav-text-hover-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0); +--nav-text-active-shadow: 0px 1px 1px rgba(0, 0, 0, 1.0); +--nav-menu-button-color: #8ABAEA; +--nav-menu-background-color: #000204; +--nav-menu-foreground-color: #BBBBBB; +--nav-menu-toggle-color: rgba(255, 255, 255, 0.2); +--nav-arrow-color: #10375F; +--nav-arrow-selected-color: #5098E0; + +/* table of contents */ +--toc-background-color: #04101B; +--toc-border-color: #081D32; +--toc-header-color: #6DA9E5; +--toc-down-arrow-image: url("data:image/svg+xml;utf8,&%238595;"); + +/** search field */ +--search-background-color: black; +--search-foreground-color: #C5C5C5; +--search-magnification-image: url('mag_d.svg'); +--search-magnification-select-image: url('mag_seld.svg'); +--search-active-color: #C5C5C5; +--search-filter-background-color: #030C14; +--search-filter-foreground-color: #5098E0; +--search-filter-border-color: #3488DC; +--search-filter-highlight-text-color: #93BFEC; +--search-filter-highlight-bg-color: #0B2845; +--search-results-background-color: #030C14; +--search-results-foreground-color: #5098E0; +--search-results-border-color: #3488DC; +--search-box-shadow: inset 0.5px 0.5px 3px 0px #0E3255; + +/** code fragments */ +--code-keyword-color: #CC99CD; +--code-type-keyword-color: #AB99CD; +--code-flow-keyword-color: #E08000; +--code-comment-color: #717790; +--code-preprocessor-color: #65CABE; +--code-string-literal-color: #7EC699; +--code-char-literal-color: #00E0F0; +--code-xml-cdata-color: #C9D1D9; +--code-vhdl-digit-color: #FF00FF; +--code-vhdl-char-color: #000000; +--code-vhdl-keyword-color: #700070; +--code-vhdl-logic-color: #FF0000; +--code-link-color: #79C0FF; +--code-external-link-color: #79C0FF; +--fragment-foreground-color: #C9D1D9; +--fragment-background-color: black; +--fragment-border-color: #30363D; +--fragment-lineno-border-color: #30363D; +--fragment-lineno-background-color: black; +--fragment-lineno-foreground-color: #6E7681; +--fragment-lineno-link-fg-color: #6E7681; +--fragment-lineno-link-bg-color: #303030; +--fragment-lineno-link-hover-fg-color: #8E96A1; +--fragment-lineno-link-hover-bg-color: #505050; +--tooltip-foreground-color: #C9D1D9; +--tooltip-background-color: #202020; +--tooltip-border-color: #C9D1D9; +--tooltip-doc-color: #D9E1E9; +--tooltip-declaration-color: #20C348; +--tooltip-link-color: #79C0FF; +--tooltip-shadow: none; + +/** font-family */ +--font-family-normal: Roboto,sans-serif; +--font-family-monospace: 'JetBrains Mono',Consolas,Monaco,'Andale Mono','Ubuntu Mono',monospace,fixed; +--font-family-nav: 'Lucida Grande',Geneva,Helvetica,Arial,sans-serif; +--font-family-title: Tahoma,Arial,sans-serif; +--font-family-toc: Verdana,'DejaVu Sans',Geneva,sans-serif; +--font-family-search: Arial,Verdana,sans-serif; +--font-family-icon: Arial,Helvetica; +--font-family-tooltip: Roboto,sans-serif; + +}} +body { + background-color: var(--page-background-color); + color: var(--page-foreground-color); +} + +body, table, div, p, dl { + font-weight: 400; + font-size: 14px; + font-family: var(--font-family-normal); + line-height: 22px; +} + +/* @group Heading Levels */ + +.title { + font-weight: 400; + font-size: 14px; + font-family: var(--font-family-normal); + line-height: 28px; + font-size: 150%; + font-weight: bold; + margin: 10px 2px; +} + +h1.groupheader { + font-size: 150%; +} + +h2.groupheader { + border-bottom: 1px solid var(--group-header-separator-color); + color: var(--group-header-color); + font-size: 150%; + font-weight: normal; + margin-top: 1.75em; + padding-top: 8px; + padding-bottom: 4px; + width: 100%; +} + +h3.groupheader { + font-size: 100%; +} + +h1, h2, h3, h4, h5, h6 { + -webkit-transition: text-shadow 0.5s linear; + -moz-transition: text-shadow 0.5s linear; + -ms-transition: text-shadow 0.5s linear; + -o-transition: text-shadow 0.5s linear; + transition: text-shadow 0.5s linear; + margin-right: 15px; +} + +h1.glow, h2.glow, h3.glow, h4.glow, h5.glow, h6.glow { + text-shadow: 0 0 15px var(--glow-color); +} + +dt { + font-weight: bold; +} + +p.startli, p.startdd { + margin-top: 2px; +} + +th p.starttd, th p.intertd, th p.endtd { + font-size: 100%; + font-weight: 700; +} + +p.starttd { + margin-top: 0px; +} + +p.endli { + margin-bottom: 0px; +} + +p.enddd { + margin-bottom: 4px; +} + +p.endtd { + margin-bottom: 2px; +} + +p.interli { +} + +p.interdd { +} + +p.intertd { +} + +/* @end */ + +caption { + font-weight: bold; +} + +span.legend { + font-size: 70%; + text-align: center; +} + +h3.version { + font-size: 90%; + text-align: center; +} + +div.navtab { + padding-right: 15px; + text-align: right; + line-height: 110%; +} + +div.navtab table { + border-spacing: 0; +} + +td.navtab { + padding-right: 6px; + padding-left: 6px; +} + +td.navtabHL { + background-image: var(--nav-gradient-active-image); + background-repeat:repeat-x; + padding-right: 6px; + padding-left: 6px; +} + +td.navtabHL a, td.navtabHL a:visited { + color: var(--nav-text-hover-color); + text-shadow: var(--nav-text-hover-shadow); +} + +a.navtab { + font-weight: bold; +} + +div.qindex{ + text-align: center; + width: 100%; + line-height: 140%; + font-size: 130%; + color: var(--index-separator-color); +} + +dt.alphachar{ + font-size: 180%; + font-weight: bold; +} + +.alphachar a{ + color: var(--index-header-color); +} + +.alphachar a:hover, .alphachar a:visited{ + text-decoration: none; +} + +.classindex dl { + padding: 25px; + column-count:1 +} + +.classindex dd { + display:inline-block; + margin-left: 50px; + width: 90%; + line-height: 1.15em; +} + +.classindex dl.even { + background-color: var(--index-even-item-bg-color); +} + +.classindex dl.odd { + background-color: var(--index-odd-item-bg-color); +} + +@media(min-width: 1120px) { + .classindex dl { + column-count:2 + } +} + +@media(min-width: 1320px) { + .classindex dl { + column-count:3 + } +} + + +/* @group Link Styling */ + +a { + color: var(--page-link-color); + font-weight: normal; + text-decoration: none; +} + +.contents a:visited { + color: var(--page-visited-link-color); +} + +a:hover { + text-decoration: underline; +} + +a.el { + font-weight: bold; +} + +a.elRef { +} + +a.code, a.code:visited, a.line, a.line:visited { + color: var(--code-link-color); +} + +a.codeRef, a.codeRef:visited, a.lineRef, a.lineRef:visited { + color: var(--code-external-link-color); +} + +a.code.hl_class { /* style for links to class names in code snippets */ } +a.code.hl_struct { /* style for links to struct names in code snippets */ } +a.code.hl_union { /* style for links to union names in code snippets */ } +a.code.hl_interface { /* style for links to interface names in code snippets */ } +a.code.hl_protocol { /* style for links to protocol names in code snippets */ } +a.code.hl_category { /* style for links to category names in code snippets */ } +a.code.hl_exception { /* style for links to exception names in code snippets */ } +a.code.hl_service { /* style for links to service names in code snippets */ } +a.code.hl_singleton { /* style for links to singleton names in code snippets */ } +a.code.hl_concept { /* style for links to concept names in code snippets */ } +a.code.hl_namespace { /* style for links to namespace names in code snippets */ } +a.code.hl_package { /* style for links to package names in code snippets */ } +a.code.hl_define { /* style for links to macro names in code snippets */ } +a.code.hl_function { /* style for links to function names in code snippets */ } +a.code.hl_variable { /* style for links to variable names in code snippets */ } +a.code.hl_typedef { /* style for links to typedef names in code snippets */ } +a.code.hl_enumvalue { /* style for links to enum value names in code snippets */ } +a.code.hl_enumeration { /* style for links to enumeration names in code snippets */ } +a.code.hl_signal { /* style for links to Qt signal names in code snippets */ } +a.code.hl_slot { /* style for links to Qt slot names in code snippets */ } +a.code.hl_friend { /* style for links to friend names in code snippets */ } +a.code.hl_dcop { /* style for links to KDE3 DCOP names in code snippets */ } +a.code.hl_property { /* style for links to property names in code snippets */ } +a.code.hl_event { /* style for links to event names in code snippets */ } +a.code.hl_sequence { /* style for links to sequence names in code snippets */ } +a.code.hl_dictionary { /* style for links to dictionary names in code snippets */ } + +/* @end */ + +dl.el { + margin-left: -1cm; +} + +ul { + overflow: visible; +} + +ul.multicol { + -moz-column-gap: 1em; + -webkit-column-gap: 1em; + column-gap: 1em; + -moz-column-count: 3; + -webkit-column-count: 3; + column-count: 3; + list-style-type: none; +} + +#side-nav ul { + overflow: visible; /* reset ul rule for scroll bar in GENERATE_TREEVIEW window */ +} + +#main-nav ul { + overflow: visible; /* reset ul rule for the navigation bar drop down lists */ +} + +.fragment { + text-align: left; + direction: ltr; + overflow-x: auto; /*Fixed: fragment lines overlap floating elements*/ + overflow-y: hidden; +} + +pre.fragment { + border: 1px solid var(--fragment-border-color); + background-color: var(--fragment-background-color); + color: var(--fragment-foreground-color); + padding: 4px 6px; + margin: 4px 8px 4px 2px; + overflow: auto; + word-wrap: break-word; + font-size: 9pt; + line-height: 125%; + font-family: var(--font-family-monospace); + font-size: 105%; +} + +div.fragment { + padding: 0 0 1px 0; /*Fixed: last line underline overlap border*/ + margin: 4px 8px 4px 2px; + color: var(--fragment-foreground-color); + background-color: var(--fragment-background-color); + border: 1px solid var(--fragment-border-color); +} + +div.line { + font-family: var(--font-family-monospace); + font-size: 13px; + min-height: 13px; + line-height: 1.2; + text-wrap: unrestricted; + white-space: -moz-pre-wrap; /* Moz */ + white-space: -pre-wrap; /* Opera 4-6 */ + white-space: -o-pre-wrap; /* Opera 7 */ + white-space: pre-wrap; /* CSS3 */ + word-wrap: break-word; /* IE 5.5+ */ + text-indent: -53px; + padding-left: 53px; + padding-bottom: 0px; + margin: 0px; + -webkit-transition-property: background-color, box-shadow; + -webkit-transition-duration: 0.5s; + -moz-transition-property: background-color, box-shadow; + -moz-transition-duration: 0.5s; + -ms-transition-property: background-color, box-shadow; + -ms-transition-duration: 0.5s; + -o-transition-property: background-color, box-shadow; + -o-transition-duration: 0.5s; + transition-property: background-color, box-shadow; + transition-duration: 0.5s; +} + +div.line:after { + content:"\000A"; + white-space: pre; +} + +div.line.glow { + background-color: var(--glow-color); + box-shadow: 0 0 10px var(--glow-color); +} + + +span.lineno { + padding-right: 4px; + margin-right: 9px; + text-align: right; + border-right: 2px solid var(--fragment-lineno-border-color); + color: var(--fragment-lineno-foreground-color); + background-color: var(--fragment-lineno-background-color); + white-space: pre; +} +span.lineno a, span.lineno a:visited { + color: var(--fragment-lineno-link-fg-color); + background-color: var(--fragment-lineno-link-bg-color); +} + +span.lineno a:hover { + color: var(--fragment-lineno-link-hover-fg-color); + background-color: var(--fragment-lineno-link-hover-bg-color); +} + +.lineno { + -webkit-touch-callout: none; + -webkit-user-select: none; + -khtml-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; +} + +div.classindex ul { + list-style: none; + padding-left: 0; +} + +div.classindex span.ai { + display: inline-block; +} + +div.groupHeader { + margin-left: 16px; + margin-top: 12px; + font-weight: bold; +} + +div.groupText { + margin-left: 16px; + font-style: italic; +} + +body { + color: var(--page-foreground-color); + margin: 0; +} + +div.contents { + margin-top: 10px; + margin-left: 12px; + margin-right: 8px; +} + +p.formulaDsp { + text-align: center; +} + +img.dark-mode-visible { + display: none; +} +img.light-mode-visible { + display: none; +} + +img.formulaDsp { + +} + +img.formulaInl, img.inline { + vertical-align: middle; +} + +div.center { + text-align: center; + margin-top: 0px; + margin-bottom: 0px; + padding: 0px; +} + +div.center img { + border: 0px; +} + +address.footer { + text-align: right; + padding-right: 12px; +} + +img.footer { + border: 0px; + vertical-align: middle; + width: var(--footer-logo-width); +} + +.compoundTemplParams { + color: var(--memdecl-template-color); + font-size: 80%; + line-height: 120%; +} + +/* @group Code Colorization */ + +span.keyword { + color: var(--code-keyword-color); +} + +span.keywordtype { + color: var(--code-type-keyword-color); +} + +span.keywordflow { + color: var(--code-flow-keyword-color); +} + +span.comment { + color: var(--code-comment-color); +} + +span.preprocessor { + color: var(--code-preprocessor-color); +} + +span.stringliteral { + color: var(--code-string-literal-color); +} + +span.charliteral { + color: var(--code-char-literal-color); +} + +span.xmlcdata { + color: var(--code-xml-cdata-color); +} + +span.vhdldigit { + color: var(--code-vhdl-digit-color); +} + +span.vhdlchar { + color: var(--code-vhdl-char-color); +} + +span.vhdlkeyword { + color: var(--code-vhdl-keyword-color); +} + +span.vhdllogic { + color: var(--code-vhdl-logic-color); +} + +blockquote { + background-color: var(--blockquote-background-color); + border-left: 2px solid var(--blockquote-border-color); + margin: 0 24px 0 4px; + padding: 0 12px 0 16px; +} + +/* @end */ + +td.tiny { + font-size: 75%; +} + +.dirtab { + padding: 4px; + border-collapse: collapse; + border: 1px solid var(--table-cell-border-color); +} + +th.dirtab { + background-color: var(--table-header-background-color); + color: var(--table-header-foreground-color); + font-weight: bold; +} + +hr { + height: 0px; + border: none; + border-top: 1px solid var(--separator-color); +} + +hr.footer { + height: 1px; +} + +/* @group Member Descriptions */ + +table.memberdecls { + border-spacing: 0px; + padding: 0px; +} + +.memberdecls td, .fieldtable tr { + -webkit-transition-property: background-color, box-shadow; + -webkit-transition-duration: 0.5s; + -moz-transition-property: background-color, box-shadow; + -moz-transition-duration: 0.5s; + -ms-transition-property: background-color, box-shadow; + -ms-transition-duration: 0.5s; + -o-transition-property: background-color, box-shadow; + -o-transition-duration: 0.5s; + transition-property: background-color, box-shadow; + transition-duration: 0.5s; +} + +.memberdecls td.glow, .fieldtable tr.glow { + background-color: var(--glow-color); + box-shadow: 0 0 15px var(--glow-color); +} + +.mdescLeft, .mdescRight, +.memItemLeft, .memItemRight, +.memTemplItemLeft, .memTemplItemRight, .memTemplParams { + background-color: var(--memdecl-background-color); + border: none; + margin: 4px; + padding: 1px 0 0 8px; +} + +.mdescLeft, .mdescRight { + padding: 0px 8px 4px 8px; + color: var(--memdecl-foreground-color); +} + +.memSeparator { + border-bottom: 1px solid var(--memdecl-separator-color); + line-height: 1px; + margin: 0px; + padding: 0px; +} + +.memItemLeft, .memTemplItemLeft { + white-space: nowrap; +} + +.memItemRight, .memTemplItemRight { + width: 100%; +} + +.memTemplParams { + color: var(--memdecl-template-color); + white-space: nowrap; + font-size: 80%; +} + +/* @end */ + +/* @group Member Details */ + +/* Styles for detailed member documentation */ + +.memtitle { + padding: 8px; + border-top: 1px solid var(--memdef-border-color); + border-left: 1px solid var(--memdef-border-color); + border-right: 1px solid var(--memdef-border-color); + border-top-right-radius: 4px; + border-top-left-radius: 4px; + margin-bottom: -1px; + background-image: var(--memdef-title-gradient-image); + background-repeat: repeat-x; + background-color: var(--memdef-title-background-color); + line-height: 1.25; + font-weight: 300; + float:left; +} + +.permalink +{ + font-size: 65%; + display: inline-block; + vertical-align: middle; +} + +.memtemplate { + font-size: 80%; + color: var(--memdef-template-color); + font-weight: normal; + margin-left: 9px; +} + +.mempage { + width: 100%; +} + +.memitem { + padding: 0; + margin-bottom: 10px; + margin-right: 5px; + -webkit-transition: box-shadow 0.5s linear; + -moz-transition: box-shadow 0.5s linear; + -ms-transition: box-shadow 0.5s linear; + -o-transition: box-shadow 0.5s linear; + transition: box-shadow 0.5s linear; + display: table !important; + width: 100%; +} + +.memitem.glow { + box-shadow: 0 0 15px var(--glow-color); +} + +.memname { + font-weight: 400; + margin-left: 6px; +} + +.memname td { + vertical-align: bottom; +} + +.memproto, dl.reflist dt { + border-top: 1px solid var(--memdef-border-color); + border-left: 1px solid var(--memdef-border-color); + border-right: 1px solid var(--memdef-border-color); + padding: 6px 0px 6px 0px; + color: var(--memdef-proto-text-color); + font-weight: bold; + text-shadow: var(--memdef-proto-text-shadow); + background-color: var(--memdef-proto-background-color); + box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); + border-top-right-radius: 4px; +} + +.overload { + font-family: var(--font-family-monospace); + font-size: 65%; +} + +.memdoc, dl.reflist dd { + border-bottom: 1px solid var(--memdef-border-color); + border-left: 1px solid var(--memdef-border-color); + border-right: 1px solid var(--memdef-border-color); + padding: 6px 10px 2px 10px; + border-top-width: 0; + background-image:url('nav_g.png'); + background-repeat:repeat-x; + background-color: var(--memdef-doc-background-color); + /* opera specific markup */ + border-bottom-left-radius: 4px; + border-bottom-right-radius: 4px; + box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); + /* firefox specific markup */ + -moz-border-radius-bottomleft: 4px; + -moz-border-radius-bottomright: 4px; + -moz-box-shadow: rgba(0, 0, 0, 0.15) 5px 5px 5px; + /* webkit specific markup */ + -webkit-border-bottom-left-radius: 4px; + -webkit-border-bottom-right-radius: 4px; + -webkit-box-shadow: 5px 5px 5px rgba(0, 0, 0, 0.15); +} + +dl.reflist dt { + padding: 5px; +} + +dl.reflist dd { + margin: 0px 0px 10px 0px; + padding: 5px; +} + +.paramkey { + text-align: right; +} + +.paramtype { + white-space: nowrap; +} + +.paramname { + color: var(--memdef-param-name-color); + white-space: nowrap; +} +.paramname em { + font-style: normal; +} +.paramname code { + line-height: 14px; +} + +.params, .retval, .exception, .tparams { + margin-left: 0px; + padding-left: 0px; +} + +.params .paramname, .retval .paramname, .tparams .paramname, .exception .paramname { + font-weight: bold; + vertical-align: top; +} + +.params .paramtype, .tparams .paramtype { + font-style: italic; + vertical-align: top; +} + +.params .paramdir, .tparams .paramdir { + font-family: var(--font-family-monospace); + vertical-align: top; +} + +table.mlabels { + border-spacing: 0px; +} + +td.mlabels-left { + width: 100%; + padding: 0px; +} + +td.mlabels-right { + vertical-align: bottom; + padding: 0px; + white-space: nowrap; +} + +span.mlabels { + margin-left: 8px; +} + +span.mlabel { + background-color: var(--label-background-color); + border-top:1px solid var(--label-left-top-border-color); + border-left:1px solid var(--label-left-top-border-color); + border-right:1px solid var(--label-right-bottom-border-color); + border-bottom:1px solid var(--label-right-bottom-border-color); + text-shadow: none; + color: var(--label-foreground-color); + margin-right: 4px; + padding: 2px 3px; + border-radius: 3px; + font-size: 7pt; + white-space: nowrap; + vertical-align: middle; +} + + + +/* @end */ + +/* these are for tree view inside a (index) page */ + +div.directory { + margin: 10px 0px; + border-top: 1px solid var(--directory-separator-color); + border-bottom: 1px solid var(--directory-separator-color); + width: 100%; +} + +.directory table { + border-collapse:collapse; +} + +.directory td { + margin: 0px; + padding: 0px; + vertical-align: top; +} + +.directory td.entry { + white-space: nowrap; + padding-right: 6px; + padding-top: 3px; +} + +.directory td.entry a { + outline:none; +} + +.directory td.entry a img { + border: none; +} + +.directory td.desc { + width: 100%; + padding-left: 6px; + padding-right: 6px; + padding-top: 3px; + border-left: 1px solid rgba(0,0,0,0.05); +} + +.directory tr.odd { + padding-left: 6px; + background-color: var(--index-odd-item-bg-color); +} + +.directory tr.even { + padding-left: 6px; + background-color: var(--index-even-item-bg-color); +} + +.directory img { + vertical-align: -30%; +} + +.directory .levels { + white-space: nowrap; + width: 100%; + text-align: right; + font-size: 9pt; +} + +.directory .levels span { + cursor: pointer; + padding-left: 2px; + padding-right: 2px; + color: var(--page-link-color); +} + +.arrow { + color: var(--nav-arrow-color); + -webkit-user-select: none; + -khtml-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; + cursor: pointer; + font-size: 80%; + display: inline-block; + width: 16px; + height: 22px; +} + +.icon { + font-family: var(--font-family-icon); + line-height: normal; + font-weight: bold; + font-size: 12px; + height: 14px; + width: 16px; + display: inline-block; + background-color: var(--icon-background-color); + color: var(--icon-foreground-color); + text-align: center; + border-radius: 4px; + margin-left: 2px; + margin-right: 2px; +} + +.icona { + width: 24px; + height: 22px; + display: inline-block; +} + +.iconfopen { + width: 24px; + height: 18px; + margin-bottom: 4px; + background-image:var(--icon-folder-open-image); + background-repeat: repeat-y; + vertical-align:top; + display: inline-block; +} + +.iconfclosed { + width: 24px; + height: 18px; + margin-bottom: 4px; + background-image:var(--icon-folder-closed-image); + background-repeat: repeat-y; + vertical-align:top; + display: inline-block; +} + +.icondoc { + width: 24px; + height: 18px; + margin-bottom: 4px; + background-image:var(--icon-doc-image); + background-position: 0px -4px; + background-repeat: repeat-y; + vertical-align:top; + display: inline-block; +} + +/* @end */ + +div.dynheader { + margin-top: 8px; + -webkit-touch-callout: none; + -webkit-user-select: none; + -khtml-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; +} + +address { + font-style: normal; + color: var(--footer-foreground-color); +} + +table.doxtable caption { + caption-side: top; +} + +table.doxtable { + border-collapse:collapse; + margin-top: 4px; + margin-bottom: 4px; +} + +table.doxtable td, table.doxtable th { + border: 1px solid var(--table-cell-border-color); + padding: 3px 7px 2px; +} + +table.doxtable th { + background-color: var(--table-header-background-color); + color: var(--table-header-foreground-color); + font-size: 110%; + padding-bottom: 4px; + padding-top: 5px; +} + +table.fieldtable { + margin-bottom: 10px; + border: 1px solid var(--memdef-border-color); + border-spacing: 0px; + border-radius: 4px; + box-shadow: 2px 2px 2px rgba(0, 0, 0, 0.15); +} + +.fieldtable td, .fieldtable th { + padding: 3px 7px 2px; +} + +.fieldtable td.fieldtype, .fieldtable td.fieldname { + white-space: nowrap; + border-right: 1px solid var(--memdef-border-color); + border-bottom: 1px solid var(--memdef-border-color); + vertical-align: top; +} + +.fieldtable td.fieldname { + padding-top: 3px; +} + +.fieldtable td.fielddoc { + border-bottom: 1px solid var(--memdef-border-color); +} + +.fieldtable td.fielddoc p:first-child { + margin-top: 0px; +} + +.fieldtable td.fielddoc p:last-child { + margin-bottom: 2px; +} + +.fieldtable tr:last-child td { + border-bottom: none; +} + +.fieldtable th { + background-image: var(--memdef-title-gradient-image); + background-repeat:repeat-x; + background-color: var(--memdef-title-background-color); + font-size: 90%; + color: var(--memdef-proto-text-color); + padding-bottom: 4px; + padding-top: 5px; + text-align:left; + font-weight: 400; + border-top-left-radius: 4px; + border-top-right-radius: 4px; + border-bottom: 1px solid var(--memdef-border-color); +} + + +.tabsearch { + top: 0px; + left: 10px; + height: 36px; + background-image: var(--nav-gradient-image); + z-index: 101; + overflow: hidden; + font-size: 13px; +} + +.navpath ul +{ + font-size: 11px; + background-image: var(--nav-gradient-image); + background-repeat:repeat-x; + background-position: 0 -5px; + height:30px; + line-height:30px; + color:var(--nav-text-normal-color); + border:solid 1px var(--nav-breadcrumb-border-color); + overflow:hidden; + margin:0px; + padding:0px; +} + +.navpath li +{ + list-style-type:none; + float:left; + padding-left:10px; + padding-right:15px; + background-image:var(--nav-breadcrumb-image); + background-repeat:no-repeat; + background-position:right; + color: var(--nav-foreground-color); +} + +.navpath li.navelem a +{ + height:32px; + display:block; + text-decoration: none; + outline: none; + color: var(--nav-text-normal-color); + font-family: var(--font-family-nav); + text-shadow: var(--nav-text-normal-shadow); + text-decoration: none; +} + +.navpath li.navelem a:hover +{ + color: var(--nav-text-hover-color); + text-shadow: var(--nav-text-hover-shadow); +} + +.navpath li.footer +{ + list-style-type:none; + float:right; + padding-left:10px; + padding-right:15px; + background-image:none; + background-repeat:no-repeat; + background-position:right; + color: var(--footer-foreground-color); + font-size: 8pt; +} + + +div.summary +{ + float: right; + font-size: 8pt; + padding-right: 5px; + width: 50%; + text-align: right; +} + +div.summary a +{ + white-space: nowrap; +} + +table.classindex +{ + margin: 10px; + white-space: nowrap; + margin-left: 3%; + margin-right: 3%; + width: 94%; + border: 0; + border-spacing: 0; + padding: 0; +} + +div.ingroups +{ + font-size: 8pt; + width: 50%; + text-align: left; +} + +div.ingroups a +{ + white-space: nowrap; +} + +div.header +{ + background-image: var(--header-gradient-image); + background-repeat:repeat-x; + background-color: var(--header-background-color); + margin: 0px; + border-bottom: 1px solid var(--header-separator-color); +} + +div.headertitle +{ + padding: 5px 5px 5px 10px; +} + +.PageDocRTL-title div.headertitle { + text-align: right; + direction: rtl; +} + +dl { + padding: 0 0 0 0; +} + +/* dl.note, dl.warning, dl.attention, dl.pre, dl.post, dl.invariant, dl.deprecated, dl.todo, dl.test, dl.bug, dl.examples */ +dl.section { + margin-left: 0px; + padding-left: 0px; +} + +dl.note { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #D0C000; +} + +dl.warning, dl.attention { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #FF0000; +} + +dl.pre, dl.post, dl.invariant { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #00D000; +} + +dl.deprecated { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #505050; +} + +dl.todo { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #00C0E0; +} + +dl.test { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #3030E0; +} + +dl.bug { + margin-left: -7px; + padding-left: 3px; + border-left: 4px solid; + border-color: #C08050; +} + +dl.section dd { + margin-bottom: 6px; +} + + +#projectrow +{ + height: 56px; +} + +#projectlogo +{ + text-align: center; + vertical-align: bottom; + border-collapse: separate; +} + +#projectlogo img +{ + border: 0px none; +} + +#projectalign +{ + vertical-align: middle; + padding-left: 0.5em; +} + +#projectname +{ + font-size: 200%; + font-family: var(--font-family-title); + margin: 0px; + padding: 2px 0px; +} + +#projectbrief +{ + font-size: 90%; + font-family: var(--font-family-title); + margin: 0px; + padding: 0px; +} + +#projectnumber +{ + font-size: 50%; + font-family: 50% var(--font-family-title); + margin: 0px; + padding: 0px; +} + +#titlearea +{ + padding: 0px; + margin: 0px; + width: 100%; + border-bottom: 1px solid var(--title-separator-color); + background-color: var(--title-background-color); +} + +.image +{ + text-align: center; +} + +.dotgraph +{ + text-align: center; +} + +.mscgraph +{ + text-align: center; +} + +.plantumlgraph +{ + text-align: center; +} + +.diagraph +{ + text-align: center; +} + +.caption +{ + font-weight: bold; +} + +dl.citelist { + margin-bottom:50px; +} + +dl.citelist dt { + color:var(--citation-label-color); + float:left; + font-weight:bold; + margin-right:10px; + padding:5px; + text-align:right; + width:52px; +} + +dl.citelist dd { + margin:2px 0 2px 72px; + padding:5px 0; +} + +div.toc { + padding: 14px 25px; + background-color: var(--toc-background-color); + border: 1px solid var(--toc-border-color); + border-radius: 7px 7px 7px 7px; + float: right; + height: auto; + margin: 0 8px 10px 10px; + width: 200px; +} + +div.toc li { + background: var(--toc-down-arrow-image) no-repeat scroll 0 5px transparent; + font: 10px/1.2 var(--font-family-toc); + margin-top: 5px; + padding-left: 10px; + padding-top: 2px; +} + +div.toc h3 { + font: bold 12px/1.2 var(--font-family-toc); + color: var(--toc-header-color); + border-bottom: 0 none; + margin: 0; +} + +div.toc ul { + list-style: none outside none; + border: medium none; + padding: 0px; +} + +div.toc li.level1 { + margin-left: 0px; +} + +div.toc li.level2 { + margin-left: 15px; +} + +div.toc li.level3 { + margin-left: 15px; +} + +div.toc li.level4 { + margin-left: 15px; +} + +span.emoji { + /* font family used at the site: https://unicode.org/emoji/charts/full-emoji-list.html + * font-family: "Noto Color Emoji", "Apple Color Emoji", "Segoe UI Emoji", Times, Symbola, Aegyptus, Code2000, Code2001, Code2002, Musica, serif, LastResort; + */ +} + +span.obfuscator { + display: none; +} + +.inherit_header { + font-weight: bold; + color: var(--inherit-header-color); + cursor: pointer; + -webkit-touch-callout: none; + -webkit-user-select: none; + -khtml-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; +} + +.inherit_header td { + padding: 6px 0px 2px 5px; +} + +.inherit { + display: none; +} + +tr.heading h2 { + margin-top: 12px; + margin-bottom: 4px; +} + +/* tooltip related style info */ + +.ttc { + position: absolute; + display: none; +} + +#powerTip { + cursor: default; + /*white-space: nowrap;*/ + color: var(--tooltip-foreground-color); + background-color: var(--tooltip-background-color); + border: 1px solid var(--tooltip-border-color); + border-radius: 4px 4px 4px 4px; + box-shadow: var(--tooltip-shadow); + display: none; + font-size: smaller; + max-width: 80%; + opacity: 0.9; + padding: 1ex 1em 1em; + position: absolute; + z-index: 2147483647; +} + +#powerTip div.ttdoc { + color: var(--tooltip-doc-color); + font-style: italic; +} + +#powerTip div.ttname a { + font-weight: bold; +} + +#powerTip a { + color: var(--tooltip-link-color); +} + +#powerTip div.ttname { + font-weight: bold; +} + +#powerTip div.ttdeci { + color: var(--tooltip-declaration-color); +} + +#powerTip div { + margin: 0px; + padding: 0px; + font-size: 12px; + font-family: var(--font-family-tooltip); + line-height: 16px; +} + +#powerTip:before, #powerTip:after { + content: ""; + position: absolute; + margin: 0px; +} + +#powerTip.n:after, #powerTip.n:before, +#powerTip.s:after, #powerTip.s:before, +#powerTip.w:after, #powerTip.w:before, +#powerTip.e:after, #powerTip.e:before, +#powerTip.ne:after, #powerTip.ne:before, +#powerTip.se:after, #powerTip.se:before, +#powerTip.nw:after, #powerTip.nw:before, +#powerTip.sw:after, #powerTip.sw:before { + border: solid transparent; + content: " "; + height: 0; + width: 0; + position: absolute; +} + +#powerTip.n:after, #powerTip.s:after, +#powerTip.w:after, #powerTip.e:after, +#powerTip.nw:after, #powerTip.ne:after, +#powerTip.sw:after, #powerTip.se:after { + border-color: rgba(255, 255, 255, 0); +} + +#powerTip.n:before, #powerTip.s:before, +#powerTip.w:before, #powerTip.e:before, +#powerTip.nw:before, #powerTip.ne:before, +#powerTip.sw:before, #powerTip.se:before { + border-color: rgba(128, 128, 128, 0); +} + +#powerTip.n:after, #powerTip.n:before, +#powerTip.ne:after, #powerTip.ne:before, +#powerTip.nw:after, #powerTip.nw:before { + top: 100%; +} + +#powerTip.n:after, #powerTip.ne:after, #powerTip.nw:after { + border-top-color: var(--tooltip-background-color); + border-width: 10px; + margin: 0px -10px; +} +#powerTip.n:before, #powerTip.ne:before, #powerTip.nw:before { + border-top-color: var(--tooltip-border-color); + border-width: 11px; + margin: 0px -11px; +} +#powerTip.n:after, #powerTip.n:before { + left: 50%; +} + +#powerTip.nw:after, #powerTip.nw:before { + right: 14px; +} + +#powerTip.ne:after, #powerTip.ne:before { + left: 14px; +} + +#powerTip.s:after, #powerTip.s:before, +#powerTip.se:after, #powerTip.se:before, +#powerTip.sw:after, #powerTip.sw:before { + bottom: 100%; +} + +#powerTip.s:after, #powerTip.se:after, #powerTip.sw:after { + border-bottom-color: var(--tooltip-background-color); + border-width: 10px; + margin: 0px -10px; +} + +#powerTip.s:before, #powerTip.se:before, #powerTip.sw:before { + border-bottom-color: var(--tooltip-border-color); + border-width: 11px; + margin: 0px -11px; +} + +#powerTip.s:after, #powerTip.s:before { + left: 50%; +} + +#powerTip.sw:after, #powerTip.sw:before { + right: 14px; +} + +#powerTip.se:after, #powerTip.se:before { + left: 14px; +} + +#powerTip.e:after, #powerTip.e:before { + left: 100%; +} +#powerTip.e:after { + border-left-color: var(--tooltip-border-color); + border-width: 10px; + top: 50%; + margin-top: -10px; +} +#powerTip.e:before { + border-left-color: var(--tooltip-border-color); + border-width: 11px; + top: 50%; + margin-top: -11px; +} + +#powerTip.w:after, #powerTip.w:before { + right: 100%; +} +#powerTip.w:after { + border-right-color: var(--tooltip-border-color); + border-width: 10px; + top: 50%; + margin-top: -10px; +} +#powerTip.w:before { + border-right-color: var(--tooltip-border-color); + border-width: 11px; + top: 50%; + margin-top: -11px; +} + +@media print +{ + #top { display: none; } + #side-nav { display: none; } + #nav-path { display: none; } + body { overflow:visible; } + h1, h2, h3, h4, h5, h6 { page-break-after: avoid; } + .summary { display: none; } + .memitem { page-break-inside: avoid; } + #doc-content + { + margin-left:0 !important; + height:auto !important; + width:auto !important; + overflow:inherit; + display:inline; + } +} + +/* @group Markdown */ + +table.markdownTable { + border-collapse:collapse; + margin-top: 4px; + margin-bottom: 4px; +} + +table.markdownTable td, table.markdownTable th { + border: 1px solid var(--table-cell-border-color); + padding: 3px 7px 2px; +} + +table.markdownTable tr { +} + +th.markdownTableHeadLeft, th.markdownTableHeadRight, th.markdownTableHeadCenter, th.markdownTableHeadNone { + background-color: var(--table-header-background-color); + color: var(--table-header-foreground-color); + font-size: 110%; + padding-bottom: 4px; + padding-top: 5px; +} + +th.markdownTableHeadLeft, td.markdownTableBodyLeft { + text-align: left +} + +th.markdownTableHeadRight, td.markdownTableBodyRight { + text-align: right +} + +th.markdownTableHeadCenter, td.markdownTableBodyCenter { + text-align: center +} + +tt, code, kbd, samp +{ + display: inline-block; +} +/* @end */ + +u { + text-decoration: underline; +} + +details>summary { + list-style-type: none; +} + +details > summary::-webkit-details-marker { + display: none; +} + +details>summary::before { + content: "\25ba"; + padding-right:4px; + font-size: 80%; +} + +details[open]>summary::before { + content: "\25bc"; + padding-right:4px; + font-size: 80%; +} + +body { + scrollbar-color: var(--scrollbar-thumb-color) var(--scrollbar-background-color); +} + +::-webkit-scrollbar { + background-color: var(--scrollbar-background-color); + height: 12px; + width: 12px; +} +::-webkit-scrollbar-thumb { + border-radius: 6px; + box-shadow: inset 0 0 12px 12px var(--scrollbar-thumb-color); + border: solid 2px transparent; +} +::-webkit-scrollbar-corner { + background-color: var(--scrollbar-background-color); +} + diff --git a/doc/api/doxygen.svg b/doc/api/doxygen.svg new file mode 100644 index 0000000..363aa45 --- /dev/null +++ b/doc/api/doxygen.svg @@ -0,0 +1,28 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/api/files.html b/doc/api/files.html new file mode 100644 index 0000000..459665c --- /dev/null +++ b/doc/api/files.html @@ -0,0 +1,74 @@ + + + + + + + +liblzma (XZ Utils): File List + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
File List
+
+
+
Here is a list of all documented files with brief descriptions:
+
[detail level 12]
+ + + + + + + + + + + + + + + + +
 ▼ lzma
 base.hData types and functions used in many places in liblzma API
 bcj.hBranch/Call/Jump conversion filters
 block.h.xz Block handling
 check.hIntegrity checks
 container.hFile formats
 delta.hDelta filter
 filter.hCommon filter related types and functions
 hardware.hHardware information
 index.hHandling of .xz Index and related information
 index_hash.hValidate Index by using a hash function
 lzma12.hLZMA1 and LZMA2 filters
 stream_flags.h.xz Stream Header and Stream Footer encoder and decoder
 version.hVersion number
 vli.hVariable-length integer handling
 lzma.hThe public API of liblzma data compression library
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/filter_8h.html b/doc/api/filter_8h.html new file mode 100644 index 0000000..7f2ffaa --- /dev/null +++ b/doc/api/filter_8h.html @@ -0,0 +1,1342 @@ + + + + + + + +liblzma (XZ Utils): lzma/filter.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Functions
+
filter.h File Reference
+
+
+ +

Common filter related types and functions. +More...

+ + + + + +

+Data Structures

struct  lzma_filter
 Filter options. More...
 
+ + + + + + + + + + + + + + + + + + + + + + +

+Macros

#define LZMA_FILTERS_MAX   4
 Maximum number of filters in a chain.
 
#define LZMA_STR_ALL_FILTERS   UINT32_C(0x01)
 Allow or show all filters.
 
#define LZMA_STR_NO_VALIDATION   UINT32_C(0x02)
 Do not validate the filter chain in lzma_str_to_filters()
 
#define LZMA_STR_ENCODER   UINT32_C(0x10)
 Stringify encoder options.
 
#define LZMA_STR_DECODER   UINT32_C(0x20)
 Stringify decoder options.
 
#define LZMA_STR_GETOPT_LONG   UINT32_C(0x40)
 Produce xz-compatible getopt_long() syntax.
 
#define LZMA_STR_NO_SPACES   UINT32_C(0x80)
 Use two dashes "--" instead of a space to separate filters.
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

lzma_bool lzma_filter_encoder_is_supported (lzma_vli id) lzma_nothrow lzma_attr_const
 Test if the given Filter ID is supported for encoding.
 
lzma_bool lzma_filter_decoder_is_supported (lzma_vli id) lzma_nothrow lzma_attr_const
 Test if the given Filter ID is supported for decoding.
 
lzma_ret lzma_filters_copy (const lzma_filter *src, lzma_filter *dest, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Copy the filters array.
 
void lzma_filters_free (lzma_filter *filters, const lzma_allocator *allocator) lzma_nothrow
 Free the options in the array of lzma_filter structures.
 
uint64_t lzma_raw_encoder_memusage (const lzma_filter *filters) lzma_nothrow lzma_attr_pure
 Calculate approximate memory requirements for raw encoder.
 
uint64_t lzma_raw_decoder_memusage (const lzma_filter *filters) lzma_nothrow lzma_attr_pure
 Calculate approximate memory requirements for raw decoder.
 
lzma_ret lzma_raw_encoder (lzma_stream *strm, const lzma_filter *filters) lzma_nothrow lzma_attr_warn_unused_result
 Initialize raw encoder.
 
lzma_ret lzma_raw_decoder (lzma_stream *strm, const lzma_filter *filters) lzma_nothrow lzma_attr_warn_unused_result
 Initialize raw decoder.
 
lzma_ret lzma_filters_update (lzma_stream *strm, const lzma_filter *filters) lzma_nothrow
 Update the filter chain in the encoder.
 
lzma_ret lzma_raw_buffer_encode (const lzma_filter *filters, const lzma_allocator *allocator, const uint8_t *in, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Single-call raw encoder.
 
lzma_ret lzma_raw_buffer_decode (const lzma_filter *filters, const lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Single-call raw decoder.
 
lzma_ret lzma_properties_size (uint32_t *size, const lzma_filter *filter) lzma_nothrow
 Get the size of the Filter Properties field.
 
lzma_ret lzma_properties_encode (const lzma_filter *filter, uint8_t *props) lzma_nothrow
 Encode the Filter Properties field.
 
lzma_ret lzma_properties_decode (lzma_filter *filter, const lzma_allocator *allocator, const uint8_t *props, size_t props_size) lzma_nothrow
 Decode the Filter Properties field.
 
lzma_ret lzma_filter_flags_size (uint32_t *size, const lzma_filter *filter) lzma_nothrow lzma_attr_warn_unused_result
 Calculate encoded size of a Filter Flags field.
 
lzma_ret lzma_filter_flags_encode (const lzma_filter *filter, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow lzma_attr_warn_unused_result
 Encode Filter Flags into given buffer.
 
lzma_ret lzma_filter_flags_decode (lzma_filter *filter, const lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size) lzma_nothrow lzma_attr_warn_unused_result
 Decode Filter Flags from given buffer.
 
const char * lzma_str_to_filters (const char *str, int *error_pos, lzma_filter *filters, uint32_t flags, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Convert a string to a filter chain.
 
lzma_ret lzma_str_from_filters (char **str, const lzma_filter *filters, uint32_t flags, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Convert a filter chain to a string.
 
lzma_ret lzma_str_list_filters (char **str, lzma_vli filter_id, uint32_t flags, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 List available filters and/or their options (for help message)
 
+

Detailed Description

+

Common filter related types and functions.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_FILTERS_MAX

+ +
+
+ + + + +
#define LZMA_FILTERS_MAX   4
+
+ +

Maximum number of filters in a chain.

+

A filter chain can have 1-4 filters, of which three are allowed to change the size of the data. Usually only one or two filters are needed.

+ +
+
+ +

◆ LZMA_STR_ALL_FILTERS

+ +
+
+ + + + +
#define LZMA_STR_ALL_FILTERS   UINT32_C(0x01)
+
+ +

Allow or show all filters.

+

By default only the filters supported in the .xz format are accept by lzma_str_to_filters() or shown by lzma_str_list_filters().

+ +
+
+ +

◆ LZMA_STR_NO_VALIDATION

+ +
+
+ + + + +
#define LZMA_STR_NO_VALIDATION   UINT32_C(0x02)
+
+ +

Do not validate the filter chain in lzma_str_to_filters()

+

By default lzma_str_to_filters() can return an error if the filter chain as a whole isn't usable in the .xz format or in the raw encoder or decoder. With this flag, this validation is skipped. This flag doesn't affect the handling of the individual filter options. To allow non-.xz filters also LZMA_STR_ALL_FILTERS is needed.

+ +
+
+ +

◆ LZMA_STR_ENCODER

+ +
+
+ + + + +
#define LZMA_STR_ENCODER   UINT32_C(0x10)
+
+ +

Stringify encoder options.

+

Show the filter-specific options that the encoder will use. This may be useful for verbose diagnostic messages.

+

Note that if options were decoded from .xz headers then the encoder options may be undefined. This flag shouldn't be used in such a situation.

+ +
+
+ +

◆ LZMA_STR_DECODER

+ +
+
+ + + + +
#define LZMA_STR_DECODER   UINT32_C(0x20)
+
+ +

Stringify decoder options.

+

Show the filter-specific options that the decoder will use. This may be useful for showing what filter options were decoded from file headers.

+ +
+
+ +

◆ LZMA_STR_GETOPT_LONG

+ +
+
+ + + + +
#define LZMA_STR_GETOPT_LONG   UINT32_C(0x40)
+
+ +

Produce xz-compatible getopt_long() syntax.

+

That is, "delta:dist=2 lzma2:dict=4MiB,pb=1,lp=1" becomes "--delta=dist=2 --lzma2=dict=4MiB,pb=1,lp=1".

+

This syntax is compatible with xz 5.0.0 as long as the filters and their options are supported too.

+ +
+
+ +

◆ LZMA_STR_NO_SPACES

+ +
+
+ + + + +
#define LZMA_STR_NO_SPACES   UINT32_C(0x80)
+
+ +

Use two dashes "--" instead of a space to separate filters.

+

That is, "delta:dist=2 lzma2:pb=1,lp=1" becomes "delta:dist=2--lzma2:pb=1,lp=1". This looks slightly odd but this kind of strings should be usable on the command line without quoting. However, it is possible that future versions with new filter options might produce strings that require shell quoting anyway as the exact set of possible characters isn't frozen for now.

+

It is guaranteed that the single quote (') will never be used in filter chain strings (even if LZMA_STR_NO_SPACES isn't used).

+ +
+
+

Function Documentation

+ +

◆ lzma_filter_encoder_is_supported()

+ +
+
+ + + + + + + + +
lzma_bool lzma_filter_encoder_is_supported (lzma_vli id) const
+
+ +

Test if the given Filter ID is supported for encoding.

+
Parameters
+ + +
idFilter ID
+
+
+
Returns
lzma_bool:
    +
  • true if the Filter ID is supported for encoding by this liblzma build.
    • +
  • false otherwise.
    • +
+
+ +
+
+ +

◆ lzma_filter_decoder_is_supported()

+ +
+
+ + + + + + + + +
lzma_bool lzma_filter_decoder_is_supported (lzma_vli id) const
+
+ +

Test if the given Filter ID is supported for decoding.

+
Parameters
+ + +
idFilter ID
+
+
+
Returns
lzma_bool:
    +
  • true if the Filter ID is supported for decoding by this liblzma build.
    • +
  • false otherwise.
    • +
+
+ +
+
+ +

◆ lzma_filters_copy()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_filters_copy (const lzma_filter * src,
lzma_filter * dest,
const lzma_allocator * allocator 
)
+
+ +

Copy the filters array.

+

Copy the Filter IDs and filter-specific options from src to dest. Up to LZMA_FILTERS_MAX filters are copied, plus the terminating .id == LZMA_VLI_UNKNOWN. Thus, dest should have at least LZMA_FILTERS_MAX + 1 elements space unless the caller knows that src is smaller than that.

+

Unless the filter-specific options is NULL, the Filter ID has to be supported by liblzma, because liblzma needs to know the size of every filter-specific options structure. The filter-specific options are not validated. If options is NULL, any unsupported Filter IDs are copied without returning an error.

+

Old filter-specific options in dest are not freed, so dest doesn't need to be initialized by the caller in any way.

+

If an error occurs, memory possibly already allocated by this function is always freed. liblzma versions older than 5.2.7 may modify the dest array and leave its contents in an undefined state if an error occurs. liblzma 5.2.7 and newer only modify the dest array when returning LZMA_OK.

+
Parameters
+ + + + +
srcArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
[out]destDestination filter array
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR: Unsupported Filter ID and its options is not NULL.
    • +
  • LZMA_PROG_ERROR: src or dest is NULL.
    • +
+
+ +
+
+ +

◆ lzma_filters_free()

+ +
+
+ + + + + + + + + + + + + + + + + + +
void lzma_filters_free (lzma_filter * filters,
const lzma_allocator * allocator 
)
+
+ +

Free the options in the array of lzma_filter structures.

+

This frees the filter chain options. The filters array itself is not freed.

+

The filters array must have at most LZMA_FILTERS_MAX + 1 elements including the terminating element which must have .id = LZMA_VLI_UNKNOWN. For all elements before the terminating element:

    +
  • options will be freed using the given lzma_allocator or, if allocator is NULL, using free().
    • +
  • options will be set to NULL.
    • +
  • id will be set to LZMA_VLI_UNKNOWN.
    • +
+

If filters is NULL, this does nothing. Again, this never frees the filters array itself.

+
Parameters
+ + + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+ +
+
+ +

◆ lzma_raw_encoder_memusage()

+ +
+
+ + + + + + + + +
uint64_t lzma_raw_encoder_memusage (const lzma_filter * filters)
+
+ +

Calculate approximate memory requirements for raw encoder.

+

This function can be used to calculate the memory requirements for Block and Stream encoders too because Block and Stream encoders don't need significantly more memory than raw encoder.

+
Parameters
+ + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
+
+
+
Returns
Number of bytes of memory required for the given filter chain when encoding or UINT64_MAX on error.
+ +
+
+ +

◆ lzma_raw_decoder_memusage()

+ +
+
+ + + + + + + + +
uint64_t lzma_raw_decoder_memusage (const lzma_filter * filters)
+
+ +

Calculate approximate memory requirements for raw decoder.

+

This function can be used to calculate the memory requirements for Block and Stream decoders too because Block and Stream decoders don't need significantly more memory than raw decoder.

+
Parameters
+ + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
+
+
+
Returns
Number of bytes of memory required for the given filter chain when decoding or UINT64_MAX on error.
+ +
+
+ +

◆ lzma_raw_encoder()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_raw_encoder (lzma_stream * strm,
const lzma_filter * filters 
)
+
+ +

Initialize raw encoder.

+

This function may be useful when implementing custom file formats.

+

The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the filter chain supports it), or LZMA_FINISH.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_raw_decoder()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_raw_decoder (lzma_stream * strm,
const lzma_filter * filters 
)
+
+ +

Initialize raw decoder.

+

The initialization of raw decoder goes similarly to raw encoder.

+

The `action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using LZMA_FINISH is not required, it is supported just for convenience.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_filters_update()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_filters_update (lzma_stream * strm,
const lzma_filter * filters 
)
+
+ +

Update the filter chain in the encoder.

+

This function may be called after lzma_code() has returned LZMA_STREAM_END when LZMA_FULL_BARRIER, LZMA_FULL_FLUSH, or LZMA_SYNC_FLUSH was used:

+
    +
  • After LZMA_FULL_BARRIER or LZMA_FULL_FLUSH: Single-threaded .xz Stream encoder (lzma_stream_encoder()) and (since liblzma 5.4.0) multi-threaded Stream encoder (lzma_stream_encoder_mt()) allow setting a new filter chain to be used for the next Block(s).
    • +
  • After LZMA_SYNC_FLUSH: Raw encoder (lzma_raw_encoder()), Block encoder (lzma_block_encoder()), and single-threaded .xz Stream encoder (lzma_stream_encoder()) allow changing certain filter-specific options in the middle of encoding. The actual filters in the chain (Filter IDs) must not be changed! Currently only the lc, lp, and pb options of LZMA2 (not LZMA1) can be changed this way.
    • +
  • In the future some filters might allow changing some of their options without any barrier or flushing but currently such filters don't exist.
    • +
+

This function may also be called when no data has been compressed yet although this is rarely useful. In that case, this function will behave as if LZMA_FULL_FLUSH (Stream encoders) or LZMA_SYNC_FLUSH (Raw or Block encoder) had been used right before calling this function.

+
Parameters
+ + + +
strmPointer to lzma_stream that is at least initialized with LZMA_STREAM_INIT.
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_MEMLIMIT_ERROR
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_raw_buffer_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_raw_buffer_encode (const lzma_filter * filters,
const lzma_allocator * allocator,
const uint8_t * in,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+
+ +

Single-call raw encoder.

+
Note
There is no function to calculate how big output buffer would surely be big enough. (lzma_stream_buffer_bound() works only for lzma_stream_buffer_encode(); raw encoder won't necessarily meet that bound.)
+
Parameters
+ + + + + + + + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_sizeSize of the input buffer
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • 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
    • +
+
+ +
+
+ +

◆ lzma_raw_buffer_decode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_raw_buffer_decode (const lzma_filter * filters,
const lzma_allocator * allocator,
const uint8_t * in,
size_t * in_pos,
size_t in_size,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+
+ +

Single-call raw decoder.

+
Parameters
+ + + + + + + + + +
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_posThe next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_sizeSize of the input buffer; the first byte that won't be read is in[in_size].
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful.
    • +
  • LZMA_BUF_ERROR: Not enough output buffer space.
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_properties_size()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_properties_size (uint32_t * size,
const lzma_filter * filter 
)
+
+ +

Get the size of the Filter Properties field.

+

This function may be useful when implementing custom file formats using the raw encoder and decoder.

+
Note
This function validates the Filter ID, but does not necessarily validate the options. Thus, it is possible that this returns LZMA_OK while the following call to lzma_properties_encode() returns LZMA_OPTIONS_ERROR.
+
Parameters
+ + + +
[out]sizePointer to uint32_t to hold the size of the properties
filterFilter ID and options (the size of the properties may vary depending on the options)
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_properties_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_properties_encode (const lzma_filter * filter,
uint8_t * props 
)
+
+ +

Encode the Filter Properties field.

+
Note
Even this function won't validate more options than actually necessary. Thus, it is possible that encoding the properties succeeds but using the same options to initialize the encoder will fail.
+
+If lzma_properties_size() indicated that the size of the Filter Properties field is zero, calling lzma_properties_encode() is not required, but it won't do any harm either.
+
Parameters
+ + + +
filterFilter ID and options
[out]propsBuffer to hold the encoded options. The size of the buffer must have been already determined with lzma_properties_size().
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_properties_decode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_properties_decode (lzma_filter * filter,
const lzma_allocator * allocator,
const uint8_t * props,
size_t props_size 
)
+
+ +

Decode the Filter Properties field.

+
Parameters
+ + + + + +
filterfilter->id must have been set to the correct Filter ID. filter->options doesn't need to be initialized (it's not freed by this function). The decoded options will be stored in filter->options; it's application's responsibility to free it when appropriate. filter->options is set to NULL if there are no properties or if an error occurs.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free(). and in case of an error, also free().
propsInput buffer containing the properties.
props_sizeSize of the properties. This must be the exact size; giving too much or too little input will return LZMA_OPTIONS_ERROR.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
+
+ +
+
+ +

◆ lzma_filter_flags_size()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_filter_flags_size (uint32_t * size,
const lzma_filter * filter 
)
+
+ +

Calculate encoded size of a Filter Flags field.

+

Knowing the size of Filter Flags is useful to know when allocating memory to hold the encoded Filter Flags.

+
Note
If you need to calculate size of List of Filter Flags, you need to loop over every lzma_filter entry.
+
Parameters
+ + + +
[out]sizePointer to integer to hold the calculated size
filterFilter ID and associated options whose encoded size is to be calculated
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: *size set successfully. Note that this doesn't guarantee that filter->options is valid, thus lzma_filter_flags_encode() may still fail.
    • +
  • LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
    • +
  • LZMA_PROG_ERROR: Invalid options
    • +
+
+ +
+
+ +

◆ lzma_filter_flags_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_filter_flags_encode (const lzma_filter * filter,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+
+ +

Encode Filter Flags into given buffer.

+

In contrast to some functions, this doesn't allocate the needed buffer. This is due to how this function is used internally by liblzma.

+
Parameters
+ + + + + +
filterFilter ID and options to be encoded
[out]outBeginning of the output buffer
[out]out_posout[*out_pos] is the next write position. This is updated by the encoder.
out_sizeout[out_size] is the first byte to not write.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_OPTIONS_ERROR: Invalid or unsupported options.
    • +
  • LZMA_PROG_ERROR: Invalid options or not enough output buffer space (you should have checked it with lzma_filter_flags_size()).
    • +
+
+ +
+
+ +

◆ lzma_filter_flags_decode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_filter_flags_decode (lzma_filter * filter,
const lzma_allocator * allocator,
const uint8_t * in,
size_t * in_pos,
size_t in_size 
)
+
+ +

Decode Filter Flags from given buffer.

+

The decoded result is stored into *filter. The old value of filter->options is not free()d. If anything other than LZMA_OK is returned, filter->options is set to NULL.

+
Parameters
+ + + + + + +
[out]filterDestination filter. The decoded Filter ID will be stored in filter->id. If options are needed they will be allocated and the pointer will be stored in filter->options.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
[out]in_posThe next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_sizeSize of the input buffer; the first byte that won't be read is in[in_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_str_to_filters()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
const char * lzma_str_to_filters (const char * str,
int * error_pos,
lzma_filter * filters,
uint32_t flags,
const lzma_allocator * allocator 
)
+
+ +

Convert a string to a filter chain.

+

This tries to make it easier to write applications that allow users to set custom compression options. This only handles the filter configuration (including presets) but not the number of threads, block size, check type, or memory limits.

+

The input string can be either a preset or a filter chain. Presets begin with a digit 0-9 and may be followed by zero or more flags which are lower-case letters. Currently only "e" is supported, matching LZMA_PRESET_EXTREME. For partial xz command line syntax compatibility, a preset string may start with a single dash "-".

+

A filter chain consists of one or more "filtername:opt1=value1,opt2=value2" strings separated by one or more spaces. Leading and trailing spaces are ignored. All names and values must be lower-case. Extra commas in the option list are ignored. The order of filters is significant: when encoding, the uncompressed input data goes to the leftmost filter first. Normally "lzma2" is the last filter in the chain.

+

If one wishes to avoid spaces, for example, to avoid shell quoting, it is possible to use two dashes "--" instead of spaces to separate the filters.

+

For xz command line compatibility, each filter may be prefixed with two dashes "--" and the colon ":" separating the filter name from the options may be replaced with an equals sign "=".

+

By default, only filters that can be used in the .xz format are accepted. To allow all filters (LZMA1) use the flag LZMA_STR_ALL_FILTERS.

+

By default, very basic validation is done for the filter chain as a whole, for example, that LZMA2 is only used as the last filter in the chain. The validation isn't perfect though and it's possible that this function succeeds but using the filter chain for encoding or decoding will still result in LZMA_OPTIONS_ERROR. To disable this validation, use the flag LZMA_STR_NO_VALIDATION.

+

The available filter names and their options are available via lzma_str_list_filters(). See the xz man page for the description of filter names and options.

+

For command line applications, below is an example how an error message can be displayed. Note the use of an empty string for the field width. If "^" was used there it would create an off-by-one error except at the very beginning of the line.

+
const char *str = ...; // From user
+
lzma_filter filters[LZMA_FILTERS_MAX + 1];
+
int pos;
+
const char *msg = lzma_str_to_filters(str, &pos, filters, 0, NULL);
+
if (msg != NULL) {
+
printf("%s: Error in XZ compression options:\n", argv[0]);
+
printf("%s: %s\n", argv[0], str);
+
printf("%s: %*s^\n", argv[0], errpos, "");
+
printf("%s: %s\n", argv[0], msg);
+
}
+
Parameters
+ + + + + + +
strUser-supplied string describing a preset or a filter chain. If a default value is needed and you don't know what would be good, use "6" since that is the default preset in xz too.
[out]error_posIf this isn't NULL, this value will be set on both success and on all errors. This tells the location of the error in the string. This is an int to make it straightforward to use this as printf() field width. The value is guaranteed to be in the range [0, INT_MAX] even if strlen(str) somehow was greater than INT_MAX.
[out]filtersAn array of lzma_filter structures. There must be LZMA_FILTERS_MAX + 1 (that is, five) elements in the array. The old contents are ignored so it doesn't need to be initialized. This array is modified only if this function returns NULL. Once the allocated filter options are no longer needed, lzma_filters_free() can be used to free the options (it doesn't free the filters array itself).
flagsBitwise-or of zero or more of the flags LZMA_STR_ALL_FILTERS and LZMA_STR_NO_VALIDATION.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
On success, NULL is returned. On error, a statically-allocated error message is returned which together with the error_pos should give some idea what is wrong.
+ +
+
+ +

◆ lzma_str_from_filters()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_str_from_filters (char ** str,
const lzma_filter * filters,
uint32_t flags,
const lzma_allocator * allocator 
)
+
+ +

Convert a filter chain to a string.

+

Use cases:

+
    +
  • Verbose output showing the full encoder options to the user (use LZMA_STR_ENCODER in flags)
    • +
  • Showing the filters and options that are required to decode a file (use LZMA_STR_DECODER in flags)
    • +
  • Showing the filter names without any options in informational messages where the technical details aren't important (no flags). In this case the .options in the filters array are ignored and may be NULL even if a filter has a mandatory options structure.
    • +
+

Note that even if the filter chain was specified using a preset, the resulting filter chain isn't reversed to a preset. So if you specify "6" to lzma_str_to_filters() then lzma_str_from_filters() will produce a string containing "lzma2".

+
Parameters
+ + + + + +
[out]strOn success *str will be set to point to an allocated string describing the given filter chain. Old value is ignored. On error *str is always set to NULL.
filtersArray of filters terminated with .id == LZMA_VLI_UNKNOWN.
flagsBitwise-or of zero or more of the flags LZMA_STR_ENCODER, LZMA_STR_DECODER, LZMA_STR_GETOPT_LONG, and LZMA_STR_NO_SPACES.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR: Empty filter chain (filters[0].id == LZMA_VLI_UNKNOWN) or the filter chain includes a Filter ID that is not supported by this function.
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_str_list_filters()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_str_list_filters (char ** str,
lzma_vli filter_id,
uint32_t flags,
const lzma_allocator * allocator 
)
+
+ +

List available filters and/or their options (for help message)

+

If a filter_id is given then only one line is created which contains the filter name. If LZMA_STR_ENCODER or LZMA_STR_DECODER is used then the options read by the encoder or decoder are printed on the same line.

+

If filter_id is LZMA_VLI_UNKNOWN then all supported .xz-compatible filters are listed:

+
    +
  • If neither LZMA_STR_ENCODER nor LZMA_STR_DECODER is used then the supported filter names are listed on a single line separated by spaces.
    • +
  • If LZMA_STR_ENCODER or LZMA_STR_DECODER is used then filters and the supported options are listed one filter per line. There won't be a newline after the last filter.
    • +
  • If LZMA_STR_ALL_FILTERS is used then the list will include also those filters that cannot be used in the .xz format (LZMA1).
    • +
+
Parameters
+ + + + + +
strOn success *str will be set to point to an allocated string listing the filters and options. Old value is ignored. On error *str is always set to NULL.
filter_idFilter ID or LZMA_VLI_UNKNOWN.
flagsBitwise-or of zero or more of the flags LZMA_STR_ALL_FILTERS, LZMA_STR_ENCODER, LZMA_STR_DECODER, and LZMA_STR_GETOPT_LONG.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR: Unsupported filter_id or flags
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/folderclosed.svg b/doc/api/folderclosed.svg new file mode 100644 index 0000000..47d22df --- /dev/null +++ b/doc/api/folderclosed.svg @@ -0,0 +1,11 @@ + + + + + + + + + + diff --git a/doc/api/folderclosedd.svg b/doc/api/folderclosedd.svg new file mode 100644 index 0000000..8fe0031 --- /dev/null +++ b/doc/api/folderclosedd.svg @@ -0,0 +1,11 @@ + + + + + + + + + + diff --git a/doc/api/folderopen.svg b/doc/api/folderopen.svg new file mode 100644 index 0000000..9565570 --- /dev/null +++ b/doc/api/folderopen.svg @@ -0,0 +1,17 @@ + + + + + + + + + + diff --git a/doc/api/folderopend.svg b/doc/api/folderopend.svg new file mode 100644 index 0000000..e72e225 --- /dev/null +++ b/doc/api/folderopend.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + diff --git a/doc/api/functions.html b/doc/api/functions.html new file mode 100644 index 0000000..b50cf73 --- /dev/null +++ b/doc/api/functions.html @@ -0,0 +1,210 @@ + + + + + + + +liblzma (XZ Utils): Data Fields + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + + +
+
+
Here is a list of all documented struct and union fields with links to the struct/union documentation for each field:
+ +

- a -

+ + +

- b -

+ + +

- c -

+ + +

- d -

+ + +

- e -

+ + +

- f -

+ + +

- h -

+ + +

- i -

+ + +

- l -

+ + +

- m -

+ + +

- n -

+ + +

- o -

+ + +

- p -

+ + +

- r -

+ + +

- s -

+ + +

- t -

+ + +

- u -

+ + +

- v -

+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/functions_vars.html b/doc/api/functions_vars.html new file mode 100644 index 0000000..f6d689c --- /dev/null +++ b/doc/api/functions_vars.html @@ -0,0 +1,210 @@ + + + + + + + +liblzma (XZ Utils): Data Fields - Variables + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + + +
+
+
Here is a list of all documented variables with links to the struct/union documentation for each field:
+ +

- a -

+ + +

- b -

+ + +

- c -

+ + +

- d -

+ + +

- e -

+ + +

- f -

+ + +

- h -

+ + +

- i -

+ + +

- l -

+ + +

- m -

+ + +

- n -

+ + +

- o -

+ + +

- p -

+ + +

- r -

+ + +

- s -

+ + +

- t -

+ + +

- u -

+ + +

- v -

+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/globals.html b/doc/api/globals.html new file mode 100644 index 0000000..f80423c --- /dev/null +++ b/doc/api/globals.html @@ -0,0 +1,272 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + + +
+
+
Here is a list of all documented functions, variables, defines, enums, and typedefs with links to the documentation:
+ +

- l -

+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/globals_defs.html b/doc/api/globals_defs.html new file mode 100644 index 0000000..a7b945c --- /dev/null +++ b/doc/api/globals_defs.html @@ -0,0 +1,119 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + + +
+
+
Here is a list of all documented macros with links to the documentation:
+ +

- l -

+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/globals_enum.html b/doc/api/globals_enum.html new file mode 100644 index 0000000..1820871 --- /dev/null +++ b/doc/api/globals_enum.html @@ -0,0 +1,71 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
Here is a list of all documented enums with links to the documentation:
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/globals_eval.html b/doc/api/globals_eval.html new file mode 100644 index 0000000..51424c7 --- /dev/null +++ b/doc/api/globals_eval.html @@ -0,0 +1,103 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + + +
+
+
Here is a list of all documented enum values with links to the documentation:
+ +

- l -

+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/globals_func.html b/doc/api/globals_func.html new file mode 100644 index 0000000..091e519 --- /dev/null +++ b/doc/api/globals_func.html @@ -0,0 +1,177 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + + +
+
+
Here is a list of all documented functions with links to the documentation:
+ +

- l -

+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/globals_type.html b/doc/api/globals_type.html new file mode 100644 index 0000000..cd7aa3f --- /dev/null +++ b/doc/api/globals_type.html @@ -0,0 +1,68 @@ + + + + + + + +liblzma (XZ Utils): Globals + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
Here is a list of all documented typedefs with links to the documentation:
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/hardware_8h.html b/doc/api/hardware_8h.html new file mode 100644 index 0000000..fd302e2 --- /dev/null +++ b/doc/api/hardware_8h.html @@ -0,0 +1,123 @@ + + + + + + + +liblzma (XZ Utils): lzma/hardware.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Functions
+
hardware.h File Reference
+
+
+ +

Hardware information. +More...

+ + + + + + + + +

+Functions

uint64_t lzma_physmem (void) lzma_nothrow
 Get the total amount of physical memory (RAM) in bytes.
 
uint32_t lzma_cputhreads (void) lzma_nothrow
 Get the number of processor cores or threads.
 
+

Detailed Description

+

Hardware information.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Since liblzma can consume a lot of system resources, it also provides ways to limit the resource usage. Applications linking against liblzma need to do the actual decisions how much resources to let liblzma to use. To ease making these decisions, liblzma provides functions to find out the relevant capabilities of the underlying hardware. Currently there is only a function to find out the amount of RAM, but in the future there will be also a function to detect how many concurrent threads the system can run.

+
Note
On some operating systems, these function may temporarily load a shared library or open file descriptor(s) to find out the requested hardware information. Unless the application assumes that specific file descriptors are not touched by other threads, this should have no effect on thread safety. Possible operations involving file descriptors will restart the syscalls if they return EINTR.
+

Function Documentation

+ +

◆ lzma_physmem()

+ +
+
+ + + + + + + + +
uint64_t lzma_physmem (void )
+
+ +

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

+

This function may be useful when determining a reasonable memory usage limit for decompressing or how much memory it is OK to use for compressing.

+
Returns
On success, the total amount of physical memory in bytes is returned. If the amount of RAM cannot be determined, zero is returned. This can happen if an error occurs or if there is no code in liblzma to detect the amount of RAM on the specific operating system.
+ +
+
+ +

◆ lzma_cputhreads()

+ +
+
+ + + + + + + + +
uint32_t lzma_cputhreads (void )
+
+ +

Get the number of processor cores or threads.

+

This function may be useful when determining how many threads to use. If the hardware supports more than one thread per CPU core, the number of hardware threads is returned if that information is available.

+
Returns
On success, the number of available CPU threads or cores is returned. If this information isn't available or an error occurs, zero is returned.
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/index.html b/doc/api/index.html new file mode 100644 index 0000000..b3f8cce --- /dev/null +++ b/doc/api/index.html @@ -0,0 +1,53 @@ + + + + + + + +liblzma (XZ Utils): liblzma (XZ Utils) + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + +
+
+
liblzma (XZ Utils)
+
+
+

liblzma is a public domain general-purpose data compression library with a zlib-like API. The native file format is .xz, but also the old .lzma format and raw (no headers) streams are supported. Multiple compression algorithms (filters) are supported. Currently LZMA2 is the primary filter.

+

liblzma is part of XZ Utils https://tukaani.org/xz/. XZ Utils includes a gzip-like command line tool named xz and some other tools. XZ Utils is developed and maintained by Lasse Collin and Jia Tan.

+

Major parts of liblzma are based on Igor Pavlov's public domain LZMA SDK https://7-zip.org/sdk.html.

+

The SHA-256 implementation is based on the public domain code found from 7-Zip https://7-zip.org/, which has a modified version of the public domain SHA-256 code found from Crypto++ https://www.cryptopp.com/. The SHA-256 code in Crypto++ was written by Kevin Springle and Wei Dai.

+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/index_8h.html b/doc/api/index_8h.html new file mode 100644 index 0000000..f0de050 --- /dev/null +++ b/doc/api/index_8h.html @@ -0,0 +1,1268 @@ + + + + + + + +liblzma (XZ Utils): lzma/index.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Data Structures | +Typedefs | +Enumerations | +Functions
+
index.h File Reference
+
+
+ +

Handling of .xz Index and related information. +More...

+ + + + + +

+Data Structures

struct  lzma_index_iter
 Iterator to get information about Blocks and Streams. More...
 
+ + + + +

+Typedefs

typedef struct lzma_index_s lzma_index
 Opaque data type to hold the Index(es) and other information.
 
+ + + + +

+Enumerations

enum  lzma_index_iter_mode { LZMA_INDEX_ITER_ANY = 0 +, LZMA_INDEX_ITER_STREAM = 1 +, LZMA_INDEX_ITER_BLOCK = 2 +, LZMA_INDEX_ITER_NONEMPTY_BLOCK = 3 + }
 Operation mode for lzma_index_iter_next() More...
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Functions

uint64_t lzma_index_memusage (lzma_vli streams, lzma_vli blocks) lzma_nothrow
 Calculate memory usage of lzma_index.
 
uint64_t lzma_index_memused (const lzma_index *i) lzma_nothrow
 Calculate the memory usage of an existing lzma_index.
 
lzma_index * lzma_index_init (const lzma_allocator *allocator) lzma_nothrow
 Allocate and initialize a new lzma_index structure.
 
void lzma_index_end (lzma_index *i, const lzma_allocator *allocator) lzma_nothrow
 Deallocate lzma_index.
 
lzma_ret lzma_index_append (lzma_index *i, const lzma_allocator *allocator, lzma_vli unpadded_size, lzma_vli uncompressed_size) lzma_nothrow lzma_attr_warn_unused_result
 Add a new Block to lzma_index.
 
lzma_ret lzma_index_stream_flags (lzma_index *i, const lzma_stream_flags *stream_flags) lzma_nothrow lzma_attr_warn_unused_result
 Set the Stream Flags.
 
uint32_t lzma_index_checks (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the types of integrity Checks.
 
lzma_ret lzma_index_stream_padding (lzma_index *i, lzma_vli stream_padding) lzma_nothrow lzma_attr_warn_unused_result
 Set the amount of Stream Padding.
 
lzma_vli lzma_index_stream_count (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the number of Streams.
 
lzma_vli lzma_index_block_count (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the number of Blocks.
 
lzma_vli lzma_index_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the size of the Index field as bytes.
 
lzma_vli lzma_index_stream_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the total size of the Stream.
 
lzma_vli lzma_index_total_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the total size of the Blocks.
 
lzma_vli lzma_index_file_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the total size of the file.
 
lzma_vli lzma_index_uncompressed_size (const lzma_index *i) lzma_nothrow lzma_attr_pure
 Get the uncompressed size of the file.
 
void lzma_index_iter_init (lzma_index_iter *iter, const lzma_index *i) lzma_nothrow
 Initialize an iterator.
 
void lzma_index_iter_rewind (lzma_index_iter *iter) lzma_nothrow
 Rewind the iterator.
 
lzma_bool lzma_index_iter_next (lzma_index_iter *iter, lzma_index_iter_mode mode) lzma_nothrow lzma_attr_warn_unused_result
 Get the next Block or Stream.
 
lzma_bool lzma_index_iter_locate (lzma_index_iter *iter, lzma_vli target) lzma_nothrow
 Locate a Block.
 
lzma_ret lzma_index_cat (lzma_index *dest, lzma_index *src, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Concatenate lzma_indexes.
 
lzma_index * lzma_index_dup (const lzma_index *i, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Duplicate lzma_index.
 
lzma_ret lzma_index_encoder (lzma_stream *strm, const lzma_index *i) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Index encoder.
 
lzma_ret lzma_index_decoder (lzma_stream *strm, lzma_index **i, uint64_t memlimit) lzma_nothrow lzma_attr_warn_unused_result
 Initialize .xz Index decoder.
 
lzma_ret lzma_index_buffer_encode (const lzma_index *i, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Single-call .xz Index encoder.
 
lzma_ret lzma_index_buffer_decode (lzma_index **i, uint64_t *memlimit, const lzma_allocator *allocator, const uint8_t *in, size_t *in_pos, size_t in_size) lzma_nothrow
 Single-call .xz Index decoder.
 
lzma_ret lzma_file_info_decoder (lzma_stream *strm, lzma_index **dest_index, uint64_t memlimit, uint64_t file_size) lzma_nothrow
 Initialize a .xz file information decoder.
 
+

Detailed Description

+

Handling of .xz Index and related information.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Typedef Documentation

+ +

◆ lzma_index

+ +
+
+ + + + +
typedef struct lzma_index_s lzma_index
+
+ +

Opaque data type to hold the Index(es) and other information.

+

lzma_index often holds just one .xz Index and possibly the Stream Flags of the same Stream and size of the Stream Padding field. However, multiple lzma_indexes can be concatenated with lzma_index_cat() and then there may be information about multiple Streams in the same lzma_index.

+

Notes about thread safety: Only one thread may modify lzma_index at a time. All functions that take non-const pointer to lzma_index modify it. As long as no thread is modifying the lzma_index, getting information from the same lzma_index can be done from multiple threads at the same time with functions that take a const pointer to lzma_index or use lzma_index_iter. The same iterator must be used only by one thread at a time, of course, but there can be as many iterators for the same lzma_index as needed.

+ +
+
+

Enumeration Type Documentation

+ +

◆ lzma_index_iter_mode

+ +
+
+ + + + +
enum lzma_index_iter_mode
+
+ +

Operation mode for lzma_index_iter_next()

+ + + + + +
Enumerator
LZMA_INDEX_ITER_ANY 

Get the next Block or Stream.

+

Go to the next Block if the current Stream has at least one Block left. Otherwise go to the next Stream even if it has no Blocks. If the Stream has no Blocks (lzma_index_iter.stream.block_count == 0), lzma_index_iter.block will have undefined values.

+
LZMA_INDEX_ITER_STREAM 

Get the next Stream.

+

Go to the next Stream even if the current Stream has unread Blocks left. If the next Stream has at least one Block, the iterator will point to the first Block. If there are no Blocks, lzma_index_iter.block will have undefined values.

+
LZMA_INDEX_ITER_BLOCK 

Get the next Block.

+

Go to the next Block if the current Stream has at least one Block left. If the current Stream has no Blocks left, the next Stream with at least one Block is located and the iterator will be made to point to the first Block of that Stream.

+
LZMA_INDEX_ITER_NONEMPTY_BLOCK 

Get the next non-empty Block.

+

This is like LZMA_INDEX_ITER_BLOCK except that it will skip Blocks whose Uncompressed Size is zero.

+
+ +
+
+

Function Documentation

+ +

◆ lzma_index_memusage()

+ +
+
+ + + + + + + + + + + + + + + + + + +
uint64_t lzma_index_memusage (lzma_vli streams,
lzma_vli blocks 
)
+
+ +

Calculate memory usage of 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
+ + + +
streamsNumber of Streams
blocksNumber of Blocks
+
+
+
Returns
Approximate memory in bytes needed in a lzma_index structure.
+ +
+
+ +

◆ lzma_index_memused()

+ +
+
+ + + + + + + + +
uint64_t lzma_index_memused (const lzma_index * i)
+
+ +

Calculate the memory usage of an existing lzma_index.

+

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

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Approximate memory in bytes used by the lzma_index structure.
+ +
+
+ +

◆ lzma_index_init()

+ +
+
+ + + + + + + + +
lzma_index * lzma_index_init (const lzma_allocator * allocator)
+
+ +

Allocate and initialize a new lzma_index structure.

+
Parameters
+ + +
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
On success, a pointer to an empty initialized lzma_index is returned. If allocation fails, NULL is returned.
+ +
+
+ +

◆ lzma_index_end()

+ +
+
+ + + + + + + + + + + + + + + + + + +
void lzma_index_end (lzma_index * i,
const lzma_allocator * allocator 
)
+
+ +

Deallocate lzma_index.

+

If i is NULL, this does nothing.

+
Parameters
+ + + +
iPointer to lzma_index structure to deallocate
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+ +
+
+ +

◆ lzma_index_append()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_append (lzma_index * i,
const lzma_allocator * allocator,
lzma_vli unpadded_size,
lzma_vli uncompressed_size 
)
+
+ +

Add a new Block to lzma_index.

+
Parameters
+ + + + + +
iPointer to a lzma_index structure
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
unpadded_sizeUnpadded Size of a Block. This can be calculated with lzma_block_unpadded_size() after encoding or decoding the Block.
uncompressed_sizeUncompressed Size of a Block. This can be taken directly from lzma_block structure after encoding or decoding the Block.
+
+
+

Appending a new Block does not invalidate iterators. For example, if an iterator was pointing to the end of the lzma_index, after lzma_index_append() it is possible to read the next Block with an existing iterator.

+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_DATA_ERROR: Compressed or uncompressed size of the Stream or size of the Index field would grow too big.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_stream_flags()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_stream_flags (lzma_index * i,
const lzma_stream_flags * stream_flags 
)
+
+ +

Set the Stream Flags.

+

Set the Stream Flags of the last (and typically the only) Stream in lzma_index. This can be useful when reading information from the lzma_index, because to decode Blocks, knowing the integrity check type is needed.

+
Parameters
+ + + +
iPointer to lzma_index structure
stream_flagsPointer to lzma_stream_flags structure. This is copied into the internal preallocated structure, so the caller doesn't need to keep the flags' data available after calling this function.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_OPTIONS_ERROR: Unsupported stream_flags->version.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_checks()

+ +
+
+ + + + + + + + +
uint32_t lzma_index_checks (const lzma_index * i)
+
+ +

Get the types of integrity Checks.

+

If lzma_index_stream_flags() is used to set the Stream Flags for every Stream, lzma_index_checks() can be used to get a bitmask to indicate which Check types have been used. It can be useful e.g. if showing the Check types to the user.

+

The bitmask is 1 << check_id, e.g. CRC32 is 1 << 1 and SHA-256 is 1 << 10.

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Bitmask indicating which Check types are used in the lzma_index
+ +
+
+ +

◆ lzma_index_stream_padding()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_stream_padding (lzma_index * i,
lzma_vli stream_padding 
)
+
+ +

Set the amount of Stream Padding.

+

Set the amount of Stream Padding of the last (and typically the only) Stream in the lzma_index. This is needed when planning to do random-access reading within multiple concatenated Streams.

+

By default, the amount of Stream Padding is assumed to be zero bytes.

+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_DATA_ERROR: The file size would grow too big.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_stream_count()

+ +
+
+ + + + + + + + +
lzma_vli lzma_index_stream_count (const lzma_index * i)
+
+ +

Get the number of Streams.

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Number of Streams in the lzma_index
+ +
+
+ +

◆ lzma_index_block_count()

+ +
+
+ + + + + + + + +
lzma_vli lzma_index_block_count (const lzma_index * i)
+
+ +

Get the number of Blocks.

+

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

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Number of blocks in the lzma_index
+ +
+
+ +

◆ lzma_index_size()

+ +
+
+ + + + + + + + +
lzma_vli lzma_index_size (const lzma_index * i)
+
+ +

Get the size of the Index field as bytes.

+

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

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Size in bytes of the Index
+ +
+
+ +

◆ lzma_index_stream_size()

+ +
+
+ + + + + + + + +
lzma_vli lzma_index_stream_size (const lzma_index * i)
+
+ +

Get the total size of the Stream.

+

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
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Size in bytes of the Stream (if all Blocks are combined into one Stream).
+ +
+
+ +

◆ lzma_index_total_size()

+ +
+
+ + + + + + + + +
lzma_vli lzma_index_total_size (const lzma_index * i)
+
+ +

Get the total size of the Blocks.

+

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

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Size in bytes of all Blocks in the Stream(s)
+ +
+
+ +

◆ lzma_index_file_size()

+ +
+
+ + + + + + + + +
lzma_vli lzma_index_file_size (const lzma_index * i)
+
+ +

Get the total size of the file.

+

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
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Total size of the .xz file in bytes
+ +
+
+ +

◆ lzma_index_uncompressed_size()

+ +
+
+ + + + + + + + +
lzma_vli lzma_index_uncompressed_size (const lzma_index * i)
+
+ +

Get the uncompressed size of the file.

+
Parameters
+ + +
iPointer to lzma_index structure
+
+
+
Returns
Size in bytes of the uncompressed data in the file
+ +
+
+ +

◆ lzma_index_iter_init()

+ +
+
+ + + + + + + + + + + + + + + + + + +
void lzma_index_iter_init (lzma_index_iter * iter,
const lzma_index * i 
)
+
+ +

Initialize an iterator.

+

This function associates the iterator with the given lzma_index, and calls lzma_index_iter_rewind() on the iterator.

+

This function doesn't allocate any memory, thus there is no lzma_index_iter_end(). The iterator is valid as long as the associated lzma_index is valid, that is, until lzma_index_end() or using it as source in lzma_index_cat(). Specifically, lzma_index doesn't become invalid if new Blocks are added to it with lzma_index_append() or if it is used as the destination in lzma_index_cat().

+

It is safe to make copies of an initialized lzma_index_iter, for example, to easily restart reading at some particular position.

+
Parameters
+ + + +
iterPointer to a lzma_index_iter structure
ilzma_index to which the iterator will be associated
+
+
+ +
+
+ +

◆ lzma_index_iter_rewind()

+ +
+
+ + + + + + + + +
void lzma_index_iter_rewind (lzma_index_iter * iter)
+
+ +

Rewind the iterator.

+

Rewind the iterator so that next call to lzma_index_iter_next() will return the first Block or Stream.

+
Parameters
+ + +
iterPointer to a lzma_index_iter structure
+
+
+ +
+
+ +

◆ lzma_index_iter_next()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_bool lzma_index_iter_next (lzma_index_iter * iter,
lzma_index_iter_mode mode 
)
+
+ +

Get the next Block or Stream.

+
Parameters
+ + + +
iterIterator initialized with lzma_index_iter_init()
modeSpecify what kind of information the caller wants to get. See lzma_index_iter_mode for details.
+
+
+
Returns
lzma_bool:
    +
  • true if no Block or Stream matching the mode is found. *iter is not updated (failure).
    • +
  • false if the next Block or Stream matching the mode was found. *iter is updated (success).
    • +
+
+ +
+
+ +

◆ lzma_index_iter_locate()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_bool lzma_index_iter_locate (lzma_index_iter * iter,
lzma_vli target 
)
+
+ +

Locate a Block.

+

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.

+

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.
    • +
+

If the target is greater than the uncompressed size of the Stream, *iter is not modified.

+
Parameters
+ + + +
iterIterator that was earlier initialized with lzma_index_iter_init().
targetUncompressed target offset which the caller would like to locate from the Stream
+
+
+
Returns
lzma_bool:
    +
  • true if the target is greater than or equal to the uncompressed size of the Stream (failure)
    • +
  • false if the target is smaller than the uncompressed size of the Stream (success)
    • +
+
+ +
+
+ +

◆ lzma_index_cat()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_cat (lzma_index * dest,
lzma_index * src,
const lzma_allocator * allocator 
)
+
+ +

Concatenate lzma_indexes.

+

Concatenating lzma_indexes is useful when doing random-access reading in multi-Stream .xz file, or when combining multiple Streams into single Stream.

+
Parameters
+ + + + +
[out]destlzma_index after which src is appended
srclzma_index to be appended after dest. If this function succeeds, the memory allocated for src is freed or moved to be part of dest, and all iterators pointing to src will become invalid.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: lzma_indexes were concatenated successfully. src is now a dangling pointer.
    • +
  • LZMA_DATA_ERROR: *dest would grow too big.
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_dup()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_index * lzma_index_dup (const lzma_index * i,
const lzma_allocator * allocator 
)
+
+ +

Duplicate lzma_index.

+
Parameters
+ + + +
iPointer to lzma_index structure to be duplicated
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
A copy of the lzma_index, or NULL if memory allocation failed.
+ +
+
+ +

◆ lzma_index_encoder()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_encoder (lzma_stream * strm,
const lzma_index * i 
)
+
+ +

Initialize .xz Index encoder.

+
Parameters
+ + + +
strmPointer to properly prepared lzma_stream
iPointer to lzma_index which should be encoded.
+
+
+

The valid `action' values for lzma_code() are LZMA_RUN and LZMA_FINISH. It is enough to use only one of them (you can choose freely).

+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization succeeded, continue with lzma_code().
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_decoder()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_decoder (lzma_stream * strm,
lzma_index ** i,
uint64_t memlimit 
)
+
+ +

Initialize .xz Index decoder.

+
Parameters
+ + + + +
strmPointer to properly prepared lzma_stream
[out]iThe decoded Index will be made available via this pointer. Initially this function will set *i to NULL (the old value is ignored). If decoding succeeds (lzma_code() returns LZMA_STREAM_END), *i will be set to point to a new lzma_index, which the application has to later free with lzma_index_end().
memlimitHow much memory the resulting lzma_index is allowed to require. liblzma 5.2.3 and earlier don't allow 0 here and return LZMA_PROG_ERROR; later versions treat 0 as if 1 had been specified.
+
+
+

Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. There is no need to use LZMA_FINISH, but it's allowed because it may simplify certain types of applications.

+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Initialization succeeded, continue with lzma_code().
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+
Note
liblzma 5.2.3 and older list also LZMA_MEMLIMIT_ERROR here but that error code has never been possible from this initialization function.
+ +
+
+ +

◆ lzma_index_buffer_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_buffer_encode (const lzma_index * i,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+
+ +

Single-call .xz Index encoder.

+
Note
This function doesn't take allocator argument since all the internal data is allocated on stack.
+
Parameters
+ + + + + +
ilzma_index to be encoded
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos]. *out_pos is updated only if encoding succeeds.
out_sizeSize of the out buffer; the first byte into which no data is written to is out[out_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_BUF_ERROR: Output buffer is too small. Use lzma_index_size() to find out how much output space is needed.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_buffer_decode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_buffer_decode (lzma_index ** i,
uint64_t * memlimit,
const lzma_allocator * allocator,
const uint8_t * in,
size_t * in_pos,
size_t in_size 
)
+
+ +

Single-call .xz Index decoder.

+
Parameters
+ + + + + + + +
[out]iIf decoding succeeds, *i will point to a new lzma_index, which the application has to later free with lzma_index_end(). If an error occurs, *i will be NULL. The old value of *i is always ignored and thus doesn't need to be initialized by the caller.
[out]memlimitPointer to how much memory the resulting lzma_index is allowed to require. The value pointed by this pointer is modified if and only if LZMA_MEMLIMIT_ERROR is returned.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
inBeginning of the input buffer
in_posThe next byte will be read from in[*in_pos]. *in_pos is updated only if decoding succeeds.
in_sizeSize of the input buffer; the first byte that won't be read is in[in_size].
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful.
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_MEMLIMIT_ERROR: Memory usage limit was reached. The minimum required memlimit value was stored to *memlimit.
    • +
  • LZMA_DATA_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_file_info_decoder()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_file_info_decoder (lzma_stream * strm,
lzma_index ** dest_index,
uint64_t memlimit,
uint64_t file_size 
)
+
+ +

Initialize a .xz file information decoder.

+

This decoder decodes the Stream Header, Stream Footer, Index, and Stream Padding field(s) from the input .xz file and stores the resulting combined index in *dest_index. This information can be used to get the uncompressed file size with lzma_index_uncompressed_size(*dest_index) or, for example, to implement random access reading by locating the Blocks in the Streams.

+

To get the required information from the .xz file, lzma_code() may ask the application to seek in the input file by returning LZMA_SEEK_NEEDED and having the target file position specified in lzma_stream.seek_pos. The number of seeks required depends on the input file and how big buffers the application provides. When possible, the decoder will seek backward and forward in the given buffer to avoid useless seek requests. Thus, if the application provides the whole file at once, no external seeking will be required (that is, lzma_code() won't return LZMA_SEEK_NEEDED).

+

The value in lzma_stream.total_in can be used to estimate how much data liblzma had to read to get the file information. However, due to seeking and the way total_in is updated, the value of total_in will be somewhat inaccurate (a little too big). Thus, total_in is a good estimate but don't expect to see the same exact value for the same file if you change the input buffer size or switch to a different liblzma version.

+

Valid `action' arguments to lzma_code() are LZMA_RUN and LZMA_FINISH. You only need to use LZMA_RUN; LZMA_FINISH is only supported because it might be convenient for some applications. If you use LZMA_FINISH and if lzma_code() asks the application to seek, remember to reset `action' back to LZMA_RUN unless you hit the end of the file again.

+

Possible return values from lzma_code():

    +
  • LZMA_OK: All OK so far, more input needed
    • +
  • LZMA_SEEK_NEEDED: Provide more input starting from the absolute file position strm->seek_pos
    • +
  • LZMA_STREAM_END: Decoding was successful, *dest_index has been set
    • +
  • LZMA_FORMAT_ERROR: The input file is not in the .xz format (the expected magic bytes were not found from the beginning of the file)
    • +
  • LZMA_OPTIONS_ERROR: File looks valid but contains headers that aren't supported by this version of liblzma
    • +
  • LZMA_DATA_ERROR: File is corrupt
    • +
  • LZMA_BUF_ERROR
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_MEMLIMIT_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
Parameters
+ + + + + +
strmPointer to a properly prepared lzma_stream
[out]dest_indexPointer to a pointer where the decoder will put the decoded lzma_index. The old value of *dest_index is ignored (not freed).
memlimitHow much memory the resulting lzma_index is allowed to require. Use UINT64_MAX to effectively disable the limiter.
file_sizeSize of the input .xz file
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_MEM_ERROR
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/index__hash_8h.html b/doc/api/index__hash_8h.html new file mode 100644 index 0000000..1f568ed --- /dev/null +++ b/doc/api/index__hash_8h.html @@ -0,0 +1,311 @@ + + + + + + + +liblzma (XZ Utils): lzma/index_hash.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Typedefs | +Functions
+
index_hash.h File Reference
+
+
+ +

Validate Index by using a hash function. +More...

+ + + + + +

+Typedefs

+typedef struct lzma_index_hash_s lzma_index_hash
 Opaque data type to hold the Index hash.
 
+ + + + + + + + + + + + + + + + +

+Functions

lzma_index_hash * lzma_index_hash_init (lzma_index_hash *index_hash, const lzma_allocator *allocator) lzma_nothrow lzma_attr_warn_unused_result
 Allocate and initialize a new lzma_index_hash structure.
 
void lzma_index_hash_end (lzma_index_hash *index_hash, const lzma_allocator *allocator) lzma_nothrow
 Deallocate lzma_index_hash structure.
 
lzma_ret lzma_index_hash_append (lzma_index_hash *index_hash, lzma_vli unpadded_size, lzma_vli uncompressed_size) lzma_nothrow lzma_attr_warn_unused_result
 Add a new Record to an Index hash.
 
lzma_ret lzma_index_hash_decode (lzma_index_hash *index_hash, const uint8_t *in, size_t *in_pos, size_t in_size) lzma_nothrow lzma_attr_warn_unused_result
 Decode and validate the Index field.
 
lzma_vli lzma_index_hash_size (const lzma_index_hash *index_hash) lzma_nothrow lzma_attr_pure
 Get the size of the Index field as bytes.
 
+

Detailed Description

+

Validate Index by using a hash function.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Hashing makes it possible to use constant amount of memory to validate Index of arbitrary size.

+

Function Documentation

+ +

◆ lzma_index_hash_init()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_index_hash * lzma_index_hash_init (lzma_index_hash * index_hash,
const lzma_allocator * allocator 
)
+
+ +

Allocate and initialize a new lzma_index_hash structure.

+

If index_hash is NULL, this function allocates and initializes a new lzma_index_hash structure and returns a pointer to it. If allocation fails, NULL is returned.

+

If index_hash is non-NULL, this function reinitializes the lzma_index_hash structure and returns the same pointer. In this case, return value cannot be NULL or a different pointer than the index_hash that was given as an argument.

+
Parameters
+ + + +
index_hashPointer to a lzma_index_hash structure or NULL.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+
Returns
Initialized lzma_index_hash structure on success or NULL on failure.
+ +
+
+ +

◆ lzma_index_hash_end()

+ +
+
+ + + + + + + + + + + + + + + + + + +
void lzma_index_hash_end (lzma_index_hash * index_hash,
const lzma_allocator * allocator 
)
+
+ +

Deallocate lzma_index_hash structure.

+
Parameters
+ + + +
index_hashPointer to a lzma_index_hash structure to free.
allocatorlzma_allocator for custom allocator functions. Set to NULL to use malloc() and free().
+
+
+ +
+
+ +

◆ lzma_index_hash_append()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_hash_append (lzma_index_hash * index_hash,
lzma_vli unpadded_size,
lzma_vli uncompressed_size 
)
+
+ +

Add a new Record to an Index hash.

+
Parameters
+ + + + +
index_hashPointer to a lzma_index_hash structure
unpadded_sizeUnpadded Size of a Block
uncompressed_sizeUncompressed Size of a Block
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK
    • +
  • LZMA_DATA_ERROR: Compressed or uncompressed size of the Stream or size of the Index field would grow too big.
    • +
  • LZMA_PROG_ERROR: Invalid arguments or this function is being used when lzma_index_hash_decode() has already been used.
    • +
+
+ +
+
+ +

◆ lzma_index_hash_decode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_index_hash_decode (lzma_index_hash * index_hash,
const uint8_t * in,
size_t * in_pos,
size_t in_size 
)
+
+ +

Decode and validate the Index field.

+

After telling the sizes of all Blocks with lzma_index_hash_append(), the actual Index field is decoded with this function. Specifically, once decoding of the Index field has been started, no more Records can be added using lzma_index_hash_append().

+

This function doesn't use lzma_stream structure to pass the input data. Instead, the input buffer is specified using three arguments. This is because it matches better the internal APIs of liblzma.

+
Parameters
+ + + + + +
index_hashPointer to a lzma_index_hash structure
inPointer to the beginning of the input buffer
[out]in_posin[*in_pos] is the next byte to process
in_sizein[in_size] is the first byte not to process
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: So far good, but more input is needed.
    • +
  • LZMA_STREAM_END: Index decoded successfully and it matches the Records given with lzma_index_hash_append().
    • +
  • LZMA_DATA_ERROR: Index is corrupt or doesn't match the information given with lzma_index_hash_append().
    • +
  • LZMA_BUF_ERROR: Cannot progress because *in_pos >= in_size.
    • +
  • LZMA_PROG_ERROR
    • +
+
+ +
+
+ +

◆ lzma_index_hash_size()

+ +
+
+ + + + + + + + +
lzma_vli lzma_index_hash_size (const lzma_index_hash * index_hash)
+
+ +

Get the size of the Index field as bytes.

+

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

+
Parameters
+ + +
index_hashPointer to a lzma_index_hash structure
+
+
+
Returns
Size of the Index field in bytes.
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/lzma12_8h.html b/doc/api/lzma12_8h.html new file mode 100644 index 0000000..1d8330c --- /dev/null +++ b/doc/api/lzma12_8h.html @@ -0,0 +1,436 @@ + + + + + + + +liblzma (XZ Utils): lzma/lzma12.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Enumerations | +Functions
+
lzma12.h File Reference
+
+
+ +

LZMA1 and LZMA2 filters. +More...

+ + + + + +

+Data Structures

struct  lzma_options_lzma
 Options specific to the LZMA1 and LZMA2 filters. More...
 
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Macros

#define LZMA_FILTER_LZMA1   LZMA_VLI_C(0x4000000000000001)
 LZMA1 Filter ID (for raw encoder/decoder only, not in .xz)
 
#define LZMA_FILTER_LZMA1EXT   LZMA_VLI_C(0x4000000000000002)
 LZMA1 Filter ID with extended options (for raw encoder/decoder)
 
#define LZMA_FILTER_LZMA2   LZMA_VLI_C(0x21)
 LZMA2 Filter ID.
 
+#define LZMA_DICT_SIZE_MIN   UINT32_C(4096)
 
+#define LZMA_DICT_SIZE_DEFAULT   (UINT32_C(1) << 23)
 
+#define LZMA_LCLP_MIN   0
 
+#define LZMA_LCLP_MAX   4
 
+#define LZMA_LC_DEFAULT   3
 
+#define LZMA_LP_DEFAULT   0
 
+#define LZMA_PB_MIN   0
 
+#define LZMA_PB_MAX   4
 
+#define LZMA_PB_DEFAULT   2
 
+#define LZMA_LZMA1EXT_ALLOW_EOPM   UINT32_C(0x01)
 
#define lzma_set_ext_size(opt_lzma2, u64size)
 Macro to set the 64-bit uncompressed size in ext_size_*.
 
+ + + + + + + +

+Enumerations

enum  lzma_match_finder {
+  LZMA_MF_HC3 = 0x03 +, LZMA_MF_HC4 = 0x04 +, LZMA_MF_BT2 = 0x12 +, LZMA_MF_BT3 = 0x13 +,
+  LZMA_MF_BT4 = 0x14 +
+ }
 Match finders. More...
 
enum  lzma_mode { LZMA_MODE_FAST = 1 +, LZMA_MODE_NORMAL = 2 + }
 Compression modes. More...
 
+ + + + + + + + + + +

+Functions

lzma_bool lzma_mf_is_supported (lzma_match_finder match_finder) lzma_nothrow lzma_attr_const
 Test if given match finder is supported.
 
lzma_bool lzma_mode_is_supported (lzma_mode mode) lzma_nothrow lzma_attr_const
 Test if given compression mode is supported.
 
lzma_bool lzma_lzma_preset (lzma_options_lzma *options, uint32_t preset) lzma_nothrow
 Set a compression preset to lzma_options_lzma structure.
 
+

Detailed Description

+

LZMA1 and LZMA2 filters.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_FILTER_LZMA1

+ +
+
+ + + + +
#define LZMA_FILTER_LZMA1   LZMA_VLI_C(0x4000000000000001)
+
+ +

LZMA1 Filter ID (for raw encoder/decoder only, not in .xz)

+

LZMA1 is the very same thing as what was called just LZMA in LZMA Utils, 7-Zip, and LZMA SDK. It's called LZMA1 here to prevent developers from accidentally using LZMA when they actually want LZMA2.

+ +
+
+ +

◆ LZMA_FILTER_LZMA1EXT

+ +
+
+ + + + +
#define LZMA_FILTER_LZMA1EXT   LZMA_VLI_C(0x4000000000000002)
+
+ +

LZMA1 Filter ID with extended options (for raw encoder/decoder)

+

This is like LZMA_FILTER_LZMA1 but with this ID a few extra options are supported in the lzma_options_lzma structure:

+
    +
  • A flag to tell the encoder if the end of payload marker (EOPM) alias end of stream (EOS) marker must be written at the end of the stream. In contrast, LZMA_FILTER_LZMA1 always writes the end marker.
    • +
  • Decoder needs to be told the uncompressed size of the stream or that it is unknown (using the special value UINT64_MAX). If the size is known, a flag can be set to allow the presence of the end marker anyway. In contrast, LZMA_FILTER_LZMA1 always behaves as if the uncompressed size was unknown.
    • +
+

This allows handling file formats where LZMA1 streams are used but where the end marker isn't allowed or where it might not (always) be present. This extended LZMA1 functionality is provided as a Filter ID for raw encoder and decoder instead of adding new encoder and decoder initialization functions because this way it is possible to also use extra filters, for example, LZMA_FILTER_X86 in a filter chain with LZMA_FILTER_LZMA1EXT, which might be needed to handle some file formats.

+ +
+
+ +

◆ LZMA_FILTER_LZMA2

+ +
+
+ + + + +
#define LZMA_FILTER_LZMA2   LZMA_VLI_C(0x21)
+
+ +

LZMA2 Filter ID.

+

Usually you want this instead of LZMA1. Compared to LZMA1, LZMA2 adds support for LZMA_SYNC_FLUSH, uncompressed chunks (smaller expansion when trying to compress incompressible data), possibility to change lc/lp/pb in the middle of encoding, and some other internal improvements.

+ +
+
+ +

◆ lzma_set_ext_size

+ +
+
+ + + + + + + + + + + + + + + + + + +
#define lzma_set_ext_size( opt_lzma2,
 u64size 
)
+
+Value:
do { \
+
(opt_lzma2).ext_size_low = (uint32_t)(u64size); \
+
(opt_lzma2).ext_size_high = (uint32_t)((uint64_t)(u64size) >> 32); \
+
} while (0)
+
+

Macro to set the 64-bit uncompressed size in ext_size_*.

+

This might be convenient when decoding using LZMA_FILTER_LZMA1EXT. This isn't used with LZMA_FILTER_LZMA1 or LZMA_FILTER_LZMA2.

+ +
+
+

Enumeration Type Documentation

+ +

◆ lzma_match_finder

+ +
+
+ + + + +
enum lzma_match_finder
+
+ +

Match finders.

+

Match finder has major effect on both speed and compression ratio. Usually hash chains are faster than binary trees.

+

If you will use LZMA_SYNC_FLUSH often, the hash chains may be a better choice, because binary trees get much higher compression ratio penalty with LZMA_SYNC_FLUSH.

+

The memory usage formulas are only rough estimates, which are closest to reality when dict_size is a power of two. The formulas are more complex in reality, and can also change a little between liblzma versions. Use lzma_raw_encoder_memusage() to get more accurate estimate of memory usage.

+ + + + + + +
Enumerator
LZMA_MF_HC3 

Hash Chain with 2- and 3-byte hashing.

+

Minimum nice_len: 3

+

Memory usage:

    +
  • dict_size <= 16 MiB: dict_size * 7.5
    • +
  • dict_size > 16 MiB: dict_size * 5.5 + 64 MiB
    • +
+
LZMA_MF_HC4 

Hash Chain with 2-, 3-, and 4-byte hashing.

+

Minimum nice_len: 4

+

Memory usage:

    +
  • dict_size <= 32 MiB: dict_size * 7.5
    • +
  • dict_size > 32 MiB: dict_size * 6.5
    • +
+
LZMA_MF_BT2 

Binary Tree with 2-byte hashing.

+

Minimum nice_len: 2

+

Memory usage: dict_size * 9.5

+
LZMA_MF_BT3 

Binary Tree with 2- and 3-byte hashing.

+

Minimum nice_len: 3

+

Memory usage:

    +
  • dict_size <= 16 MiB: dict_size * 11.5
    • +
  • dict_size > 16 MiB: dict_size * 9.5 + 64 MiB
    • +
+
LZMA_MF_BT4 

Binary Tree with 2-, 3-, and 4-byte hashing.

+

Minimum nice_len: 4

+

Memory usage:

    +
  • dict_size <= 32 MiB: dict_size * 11.5
    • +
  • dict_size > 32 MiB: dict_size * 10.5
    • +
+
+ +
+
+ +

◆ lzma_mode

+ +
+
+ + + + +
enum lzma_mode
+
+ +

Compression modes.

+

This selects the function used to analyze the data produced by the match finder.

+ + + +
Enumerator
LZMA_MODE_FAST 

Fast compression.

+

Fast mode is usually at its best when combined with a hash chain match finder.

+
LZMA_MODE_NORMAL 

Normal compression.

+

This is usually notably slower than fast mode. Use this together with binary tree match finders to expose the full potential of the LZMA1 or LZMA2 encoder.

+
+ +
+
+

Function Documentation

+ +

◆ lzma_mf_is_supported()

+ +
+
+ + + + + + + + +
lzma_bool lzma_mf_is_supported (lzma_match_finder match_finder) const
+
+ +

Test if given match finder is supported.

+

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.

+
Parameters
+ + +
match_finderMatch finder ID
+
+
+
Returns
lzma_bool:
    +
  • true if the match finder is supported by this liblzma build.
    • +
  • false otherwise.
    • +
+
+ +
+
+ +

◆ lzma_mode_is_supported()

+ +
+
+ + + + + + + + +
lzma_bool lzma_mode_is_supported (lzma_mode mode) const
+
+ +

Test if given compression mode is supported.

+

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.

+
Parameters
+ + +
modeMode ID.
+
+
+
Returns
lzma_bool:
    +
  • true if the compression mode is supported by this liblzma build.
    • +
  • false otherwise.
    • +
+
+ +
+
+ +

◆ lzma_lzma_preset()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_bool lzma_lzma_preset (lzma_options_lzma * options,
uint32_t preset 
)
+
+ +

Set a compression preset to lzma_options_lzma structure.

+

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 levels are subject to changes between liblzma versions.

+

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

+

If features (like certain match finders) have been disabled at build time, then the function may return success (false) even though the resulting LZMA1/LZMA2 options may not be usable for encoder initialization (LZMA_OPTIONS_ERROR).

+
Parameters
+ + + +
[out]optionsPointer to LZMA1 or LZMA2 options to be filled
presetPreset level bitwse-ORed with preset flags
+
+
+
Returns
lzma_bool:
    +
  • true if the preset is not supported (failure).
    • +
  • false otherwise (success).
    • +
+
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/lzma_8h.html b/doc/api/lzma_8h.html new file mode 100644 index 0000000..ec417c6 --- /dev/null +++ b/doc/api/lzma_8h.html @@ -0,0 +1,109 @@ + + + + + + + +liblzma (XZ Utils): lzma.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
+Macros
+
lzma.h File Reference
+
+
+ +

The public API of liblzma data compression library. +More...

+
#include <stddef.h>
+#include <inttypes.h>
+#include <limits.h>
+#include "lzma/version.h"
+#include "lzma/base.h"
+#include "lzma/vli.h"
+#include "lzma/check.h"
+#include "lzma/filter.h"
+#include "lzma/bcj.h"
+#include "lzma/delta.h"
+#include "lzma/lzma12.h"
+#include "lzma/container.h"
+#include "lzma/stream_flags.h"
+#include "lzma/block.h"
+#include "lzma/index.h"
+#include "lzma/index_hash.h"
+#include "lzma/hardware.h"
+
+ + + + + + + + + + + + + + + + + + + +

+Macros

+#define UINT32_C(n)   n ## U
 
+#define UINT64_C(n)   n ## UL
 
+#define UINT32_MAX   (UINT32_C(4294967295))
 
+#define UINT64_MAX   (UINT64_C(18446744073709551615))
 
+#define lzma_nothrow
 
+#define lzma_attr_pure   lzma_attribute((__pure__))
 
+#define lzma_attr_const   lzma_attribute((__const__))
 
+#define lzma_attr_warn_unused_result    lzma_attribute((__warn_unused_result__))
 
+#define LZMA_H_INTERNAL   1
 
+

Detailed Description

+

The public API of liblzma data compression library.

+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/nav_f.png b/doc/api/nav_f.png new file mode 100644 index 0000000..113913e Binary files /dev/null and b/doc/api/nav_f.png differ diff --git a/doc/api/nav_fd.png b/doc/api/nav_fd.png new file mode 100644 index 0000000..978df01 Binary files /dev/null and b/doc/api/nav_fd.png differ diff --git a/doc/api/nav_g.png b/doc/api/nav_g.png new file mode 100644 index 0000000..2093a23 Binary files /dev/null and b/doc/api/nav_g.png differ diff --git a/doc/api/nav_h.png b/doc/api/nav_h.png new file mode 100644 index 0000000..4e34efd Binary files /dev/null and b/doc/api/nav_h.png differ diff --git a/doc/api/nav_hd.png b/doc/api/nav_hd.png new file mode 100644 index 0000000..b717d93 Binary files /dev/null and b/doc/api/nav_hd.png differ diff --git a/doc/api/open.png b/doc/api/open.png new file mode 100644 index 0000000..b4e49d8 Binary files /dev/null and b/doc/api/open.png differ diff --git a/doc/api/splitbar.png b/doc/api/splitbar.png new file mode 100644 index 0000000..ee781cf Binary files /dev/null and b/doc/api/splitbar.png differ diff --git a/doc/api/splitbard.png b/doc/api/splitbard.png new file mode 100644 index 0000000..aa4d029 Binary files /dev/null and b/doc/api/splitbard.png differ diff --git a/doc/api/stream__flags_8h.html b/doc/api/stream__flags_8h.html new file mode 100644 index 0000000..5cc0df9 --- /dev/null +++ b/doc/api/stream__flags_8h.html @@ -0,0 +1,348 @@ + + + + + + + +liblzma (XZ Utils): lzma/stream_flags.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Data Structures | +Macros | +Functions
+
stream_flags.h File Reference
+
+
+ +

.xz Stream Header and Stream Footer encoder and decoder +More...

+ + + + + +

+Data Structures

struct  lzma_stream_flags
 Options for encoding/decoding Stream Header and Stream Footer. More...
 
+ + + + + + + + + + +

+Macros

#define LZMA_STREAM_HEADER_SIZE   12
 Size of Stream Header and Stream Footer.
 
+#define LZMA_BACKWARD_SIZE_MIN   4
 Minimum value for lzma_stream_flags.backward_size.
 
+#define LZMA_BACKWARD_SIZE_MAX   (LZMA_VLI_C(1) << 34)
 Maximum value for lzma_stream_flags.backward_size.
 
+ + + + + + + + + + + + + + + + +

+Functions

lzma_ret lzma_stream_header_encode (const lzma_stream_flags *options, uint8_t *out) lzma_nothrow lzma_attr_warn_unused_result
 Encode Stream Header.
 
lzma_ret lzma_stream_footer_encode (const lzma_stream_flags *options, uint8_t *out) lzma_nothrow lzma_attr_warn_unused_result
 Encode Stream Footer.
 
lzma_ret lzma_stream_header_decode (lzma_stream_flags *options, const uint8_t *in) lzma_nothrow lzma_attr_warn_unused_result
 Decode Stream Header.
 
lzma_ret lzma_stream_footer_decode (lzma_stream_flags *options, const uint8_t *in) lzma_nothrow lzma_attr_warn_unused_result
 Decode Stream Footer.
 
lzma_ret lzma_stream_flags_compare (const lzma_stream_flags *a, const lzma_stream_flags *b) lzma_nothrow lzma_attr_pure
 Compare two lzma_stream_flags structures.
 
+

Detailed Description

+

.xz Stream Header and Stream Footer encoder and decoder

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_STREAM_HEADER_SIZE

+ +
+
+ + + + +
#define LZMA_STREAM_HEADER_SIZE   12
+
+ +

Size of Stream Header and Stream Footer.

+

Stream Header and Stream Footer have the same size and they are not going to change even if a newer version of the .xz file format is developed in future.

+ +
+
+

Function Documentation

+ +

◆ lzma_stream_header_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_header_encode (const lzma_stream_flags * options,
uint8_t * out 
)
+
+ +

Encode Stream Header.

+
Parameters
+ + + +
optionsStream Header options to be encoded. options->backward_size is ignored and doesn't need to be initialized.
[out]outBeginning of the output buffer of LZMA_STREAM_HEADER_SIZE bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_OPTIONS_ERROR: options->version is not supported by this liblzma version.
    • +
  • LZMA_PROG_ERROR: Invalid options.
    • +
+
+ +
+
+ +

◆ lzma_stream_footer_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_footer_encode (const lzma_stream_flags * options,
uint8_t * out 
)
+
+ +

Encode Stream Footer.

+
Parameters
+ + + +
optionsStream Footer options to be encoded.
[out]outBeginning of the output buffer of LZMA_STREAM_HEADER_SIZE bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Encoding was successful.
    • +
  • LZMA_OPTIONS_ERROR: options->version is not supported by this liblzma version.
    • +
  • LZMA_PROG_ERROR: Invalid options.
    • +
+
+ +
+
+ +

◆ lzma_stream_header_decode()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_header_decode (lzma_stream_flags * options,
const uint8_t * in 
)
+
+ +

Decode Stream Header.

+

options->backward_size is always set to LZMA_VLI_UNKNOWN. This is to help comparing Stream Flags from Stream Header and Stream Footer with lzma_stream_flags_compare().

+
Note
When decoding .xz files that contain multiple Streams, it may make sense to print "file format not recognized" only if decoding of the Stream Header of the first Stream gives LZMA_FORMAT_ERROR. If non-first Stream Header gives LZMA_FORMAT_ERROR, the message used for LZMA_DATA_ERROR is probably more appropriate. For example, the Stream decoder in liblzma uses LZMA_DATA_ERROR if LZMA_FORMAT_ERROR is returned by lzma_stream_header_decode() when decoding non-first Stream.
+
Parameters
+ + + +
[out]optionsTarget for the decoded Stream Header options.
inBeginning of the input buffer of LZMA_STREAM_HEADER_SIZE bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful.
    • +
  • LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given buffer cannot be Stream Header.
    • +
  • LZMA_DATA_ERROR: CRC32 doesn't match, thus the header is corrupt.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported options are present in the header.
    • +
+
+ +
+
+ +

◆ lzma_stream_footer_decode()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_footer_decode (lzma_stream_flags * options,
const uint8_t * in 
)
+
+ +

Decode Stream Footer.

+
Note
If Stream Header was already decoded successfully, but decoding Stream Footer returns LZMA_FORMAT_ERROR, the application should probably report some other error message than "file format not recognized". The file likely is corrupt (possibly truncated). The Stream decoder in liblzma uses LZMA_DATA_ERROR in this situation.
+
Parameters
+ + + +
[out]optionsTarget for the decoded Stream Footer options.
inBeginning of the input buffer of LZMA_STREAM_HEADER_SIZE bytes.
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Decoding was successful.
    • +
  • LZMA_FORMAT_ERROR: Magic bytes don't match, thus the given buffer cannot be Stream Footer.
    • +
  • LZMA_DATA_ERROR: CRC32 doesn't match, thus the Stream Footer is corrupt.
    • +
  • LZMA_OPTIONS_ERROR: Unsupported options are present in Stream Footer.
    • +
+
+ +
+
+ +

◆ lzma_stream_flags_compare()

+ +
+
+ + + + + + + + + + + + + + + + + + +
lzma_ret lzma_stream_flags_compare (const lzma_stream_flags * a,
const lzma_stream_flags * b 
)
+
+ +

Compare two lzma_stream_flags structures.

+

backward_size values are compared only if both are not LZMA_VLI_UNKNOWN.

+
Parameters
+ + + +
aPointer to lzma_stream_flags structure
bPointer to lzma_stream_flags structure
+
+
+
Returns
Possible lzma_ret values:
    +
  • LZMA_OK: Both are equal. If either had backward_size set to LZMA_VLI_UNKNOWN, backward_size values were not compared or validated.
    • +
  • LZMA_DATA_ERROR: The structures differ.
    • +
  • LZMA_OPTIONS_ERROR: version in either structure is greater than the maximum supported version (currently zero).
    • +
  • LZMA_PROG_ERROR: Invalid value, e.g. invalid check or backward_size.
    • +
+
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/structlzma__allocator.html b/doc/api/structlzma__allocator.html new file mode 100644 index 0000000..593647b --- /dev/null +++ b/doc/api/structlzma__allocator.html @@ -0,0 +1,153 @@ + + + + + + + +liblzma (XZ Utils): lzma_allocator Struct Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_allocator Struct Reference
+
+
+ +

Custom functions for memory handling. + More...

+ +

#include <base.h>

+ + + + + + + + + + + +

+Data Fields

void *(* alloc )(void *opaque, size_t nmemb, size_t size)
 Pointer to a custom memory allocation function.
 
void(* free )(void *opaque, void *ptr)
 Pointer to a custom memory freeing function.
 
void * opaque
 Pointer passed to .alloc() and .free()
 
+

Detailed Description

+

Custom functions for memory handling.

+

A pointer to lzma_allocator may be passed via lzma_stream structure to liblzma, and some advanced functions take a pointer to lzma_allocator as a separate function argument. The library will use the functions specified in lzma_allocator for memory handling instead of the default malloc() and free(). C++ users should note that the custom memory handling functions must not throw exceptions.

+

Single-threaded mode only: liblzma doesn't make an internal copy of lzma_allocator. Thus, it is OK to change these function pointers in the middle of the coding process, but obviously it must be done carefully to make sure that the replacement `free' can deallocate memory allocated by the earlier `alloc' function(s).

+

Multithreaded mode: liblzma might internally store pointers to the lzma_allocator given via the lzma_stream structure. The application must not change the allocator pointer in lzma_stream or the contents of the pointed lzma_allocator structure until lzma_end() has been used to free the memory associated with that lzma_stream. The allocation functions might be called simultaneously from multiple threads, and thus they must be thread safe.

+

Field Documentation

+ +

◆ alloc

+ +
+
+ + + + +
void *(* lzma_allocator::alloc) (void *opaque, size_t nmemb, size_t size)
+
+ +

Pointer to a custom memory allocation function.

+

If you don't want a custom allocator, but still want custom free(), set this to NULL and liblzma will use the standard malloc().

+
Parameters
+ + + + +
opaquelzma_allocator.opaque (see below)
nmembNumber of elements like in calloc(). liblzma will always set nmemb to 1, so it is safe to ignore nmemb in a custom allocator if you like. The nmemb argument exists only for compatibility with zlib and libbzip2.
sizeSize of an element in bytes. liblzma never sets this to zero.
+
+
+
Returns
Pointer to the beginning of a memory block of `size' bytes, or NULL if allocation fails for some reason. When allocation fails, functions of liblzma return LZMA_MEM_ERROR.
+

The allocator should not waste time zeroing the allocated buffers. This is not only about speed, but also memory usage, since the operating system kernel doesn't necessarily allocate the requested memory in physical memory until it is actually used. With small input files, liblzma may actually need only a fraction of the memory that it requested for allocation.

+
Note
LZMA_MEM_ERROR is also used when the size of the allocation would be greater than SIZE_MAX. Thus, don't assume that the custom allocator must have returned NULL if some function from liblzma returns LZMA_MEM_ERROR.
+ +
+
+ +

◆ free

+ +
+
+ + + + +
void(* lzma_allocator::free) (void *opaque, void *ptr)
+
+ +

Pointer to a custom memory freeing function.

+

If you don't want a custom freeing function, but still want a custom allocator, set this to NULL and liblzma will use the standard free().

+
Parameters
+ + + +
opaquelzma_allocator.opaque (see below)
ptrPointer returned by lzma_allocator.alloc(), or when it is set to NULL, a pointer returned by the standard malloc().
+
+
+ +
+
+ +

◆ opaque

+ +
+
+ + + + +
void* lzma_allocator::opaque
+
+ +

Pointer passed to .alloc() and .free()

+

opaque is passed as the first argument to lzma_allocator.alloc() and lzma_allocator.free(). This intended to ease implementing custom memory allocation functions for use with liblzma.

+

If you don't need this, you should set this to NULL.

+ +
+
+
The documentation for this struct was generated from the following file: +
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/structlzma__block.html b/doc/api/structlzma__block.html new file mode 100644 index 0000000..69aa245 --- /dev/null +++ b/doc/api/structlzma__block.html @@ -0,0 +1,347 @@ + + + + + + + +liblzma (XZ Utils): lzma_block Struct Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_block Struct Reference
+
+
+ +

Options for the Block and Block Header encoders and decoders. + More...

+ +

#include <block.h>

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

+Data Fields

uint32_t version
 Block format version.
 
uint32_t header_size
 Size of the Block Header field in bytes.
 
lzma_check check
 Type of integrity Check.
 
lzma_vli compressed_size
 Size of the Compressed Data in bytes.
 
lzma_vli uncompressed_size
 Uncompressed Size in bytes.
 
lzma_filter * filters
 Array of filters.
 
uint8_t raw_check [LZMA_CHECK_SIZE_MAX]
 Raw value stored in the Check field.
 
lzma_bool ignore_check
 A flag to Block decoder to not verify the Check field.
 
+

Detailed Description

+

Options for the Block and Block Header encoders and decoders.

+

Different Block handling functions use different parts of this structure. Some read some members, other functions write, and some do both. Only the members listed for reading need to be initialized when the specified functions are called. The members marked for writing will be assigned new values at some point either by calling the given function or by later calls to lzma_code().

+

Field Documentation

+ +

◆ version

+ +
+
+ + + + +
uint32_t lzma_block::version
+
+ +

Block format version.

+

To prevent API and ABI breakages when new features are needed, a version number is used to indicate which members in this structure are in use:

    +
  • liblzma >= 5.0.0: version = 0 is supported.
    • +
  • liblzma >= 5.1.4beta: Support for version = 1 was added, which adds the ignore_check member.
    • +
+

If version is greater than one, most Block related functions will return LZMA_OPTIONS_ERROR (lzma_block_header_decode() works with any version value).

+

Read by:

+

Written by:

+ +
+
+ +

◆ header_size

+ +
+
+ + + + +
uint32_t lzma_block::header_size
+
+ +

Size of the Block Header field in bytes.

+

This is always a multiple of four.

+

Read by:

+

Written by:

+ +
+
+ +

◆ check

+ +
+
+ + + + +
lzma_check lzma_block::check
+
+ +

Type of integrity Check.

+

The Check ID is not stored into the Block Header, thus its value must be provided also when decoding.

+

Read by:

+ +
+
+ +

◆ compressed_size

+ +
+
+ + + + +
lzma_vli lzma_block::compressed_size
+
+ +

Size of the Compressed Data in bytes.

+

Encoding: If this is not LZMA_VLI_UNKNOWN, Block Header encoder will store this value to the Block Header. Block encoder doesn't care about this value, but will set it once the encoding has been finished.

+

Decoding: If this is not LZMA_VLI_UNKNOWN, Block decoder will verify that the size of the Compressed Data field matches compressed_size.

+

Usually you don't know this value when encoding in streamed mode, and thus cannot write this field into the Block Header.

+

In non-streamed mode you can reserve space for this field before encoding the actual Block. After encoding the data, finish the Block by encoding the Block Header. Steps in detail:

+
    +
  • Set compressed_size to some big enough value. If you don't know better, use LZMA_VLI_MAX, but remember that bigger values take more space in Block Header.
    • +
  • Call lzma_block_header_size() to see how much space you need to reserve for the Block Header.
    • +
  • Encode the Block using lzma_block_encoder() and lzma_code(). It sets compressed_size to the correct value.
    • +
  • Use lzma_block_header_encode() to encode the Block Header. Because space was reserved in the first step, you don't need to call lzma_block_header_size() anymore, because due to reserving, header_size has to be big enough. If it is "too big", lzma_block_header_encode() will add enough Header Padding to make Block Header to match the size specified by header_size.
    • +
+

Read by:

+

Written by:

+ +
+
+ +

◆ uncompressed_size

+ +
+
+ + + + +
lzma_vli lzma_block::uncompressed_size
+
+ +

Uncompressed Size in bytes.

+

This is handled very similarly to compressed_size above.

+

uncompressed_size is needed by fewer functions than compressed_size. This is because uncompressed_size isn't needed to validate that Block stays within proper limits.

+

Read by:

+

Written by:

+ +
+
+ +

◆ filters

+ +
+
+ + + + +
lzma_filter* lzma_block::filters
+
+ +

Array of filters.

+

There can be 1-4 filters. The end of the array is marked with .id = LZMA_VLI_UNKNOWN.

+

Read by:

+

Written by:

    +
  • lzma_block_header_decode(): Note that this does NOT free() the old filter options structures. All unused filters[] will have .id == LZMA_VLI_UNKNOWN and .options == NULL. If decoding fails, all filters[] are guaranteed to be LZMA_VLI_UNKNOWN and NULL.
    • +
+
Note
Because of the array is terminated with .id = LZMA_VLI_UNKNOWN, the actual array must have LZMA_FILTERS_MAX + 1 members or the Block Header decoder will overflow the buffer.
+ +
+
+ +

◆ raw_check

+ +
+
+ + + + +
uint8_t lzma_block::raw_check[LZMA_CHECK_SIZE_MAX]
+
+ +

Raw value stored in the Check field.

+

After successful coding, the first lzma_check_size(check) bytes of this array contain the raw value stored in the Check field.

+

Note that CRC32 and CRC64 are stored in little endian byte order. Take it into account if you display the Check values to the user.

+

Written by:

+ +
+
+ +

◆ ignore_check

+ +
+
+ + + + +
lzma_bool lzma_block::ignore_check
+
+ +

A flag to Block decoder to not verify the Check field.

+

This member is supported by liblzma >= 5.1.4beta if .version >= 1.

+

If this is set to true, the integrity check won't be calculated and verified. Unless you know what you are doing, you should leave this to false. (A reason to set this to true is when the file integrity is verified externally anyway and you want to speed up the decompression, which matters mostly when using SHA-256 as the integrity check.)

+

If .version >= 1, read by:

+

Written by (.version is ignored):

+ +
+
+
The documentation for this struct was generated from the following file: +
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/structlzma__filter.html b/doc/api/structlzma__filter.html new file mode 100644 index 0000000..b78081c --- /dev/null +++ b/doc/api/structlzma__filter.html @@ -0,0 +1,114 @@ + + + + + + + +liblzma (XZ Utils): lzma_filter Struct Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_filter Struct Reference
+
+
+ +

Filter options. + More...

+ +

#include <filter.h>

+ + + + + + + + +

+Data Fields

lzma_vli id
 Filter ID.
 
void * options
 Pointer to filter-specific options structure.
 
+

Detailed Description

+

Filter options.

+

This structure is used to pass a Filter ID and a pointer to the filter's options to liblzma. A few functions work with a single lzma_filter structure, while most functions expect a filter chain.

+

A filter chain is indicated with an array of lzma_filter structures. The array is terminated with .id = LZMA_VLI_UNKNOWN. Thus, the filter array must have LZMA_FILTERS_MAX + 1 elements (that is, five) to be able to hold any arbitrary filter chain. This is important when using lzma_block_header_decode() from block.h, because a filter array that is too small would make liblzma write past the end of the array.

+

Field Documentation

+ +

◆ id

+ +
+
+ + + + +
lzma_vli lzma_filter::id
+
+ +

Filter ID.

+

Use constants whose name begin with `LZMA_FILTER_' to specify different filters. In an array of lzma_filter structures, use LZMA_VLI_UNKNOWN to indicate end of filters.

+
Note
This is not an enum, because on some systems enums cannot be 64-bit.
+ +
+
+ +

◆ options

+ +
+
+ + + + +
void* lzma_filter::options
+
+ +

Pointer to filter-specific options structure.

+

If the filter doesn't need options, set this to NULL. If id is set to LZMA_VLI_UNKNOWN, options is ignored, and thus doesn't need be initialized.

+ +
+
+
The documentation for this struct was generated from the following file: +
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/structlzma__index__iter.html b/doc/api/structlzma__index__iter.html new file mode 100644 index 0000000..d75595a --- /dev/null +++ b/doc/api/structlzma__index__iter.html @@ -0,0 +1,407 @@ + + + + + + + +liblzma (XZ Utils): lzma_index_iter Struct Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_index_iter Struct Reference
+
+
+ +

Iterator to get information about Blocks and Streams. + More...

+ +

#include <index.h>

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Data Fields

+struct { 
 
   const lzma_stream_flags *   flags 
 Pointer to Stream Flags. More...
 
   lzma_vli   number 
 Stream number in the lzma_index. More...
 
   lzma_vli   block_count 
 Number of Blocks in the Stream. More...
 
   lzma_vli   compressed_offset 
 Compressed start offset of this Stream. More...
 
   lzma_vli   uncompressed_offset 
 Uncompressed start offset of this Stream. More...
 
   lzma_vli   compressed_size 
 Compressed size of this Stream. More...
 
+   lzma_vli   uncompressed_size 
 Uncompressed size of this Stream.
 
   lzma_vli   padding 
 Size of Stream Padding after this Stream. More...
 
} stream 
 
+struct { 
 
   lzma_vli   number_in_file 
 Block number in the file. More...
 
   lzma_vli   compressed_file_offset 
 Compressed start offset of this Block. More...
 
   lzma_vli   uncompressed_file_offset 
 Uncompressed start offset of this Block. More...
 
   lzma_vli   number_in_stream 
 Block number in this Stream. More...
 
   lzma_vli   compressed_stream_offset 
 Compressed start offset of this Block. More...
 
   lzma_vli   uncompressed_stream_offset 
 Uncompressed start offset of this Block. More...
 
   lzma_vli   uncompressed_size 
 Uncompressed size of this Block. More...
 
   lzma_vli   unpadded_size 
 Unpadded size of this Block. More...
 
   lzma_vli   total_size 
 Total compressed size. More...
 
} block 
 
+

Detailed Description

+

Iterator to get information about Blocks and Streams.

+

Field Documentation

+ +

◆ flags

+ +
+
+ + + + +
const lzma_stream_flags* lzma_index_iter::flags
+
+ +

Pointer to Stream Flags.

+

This is NULL if Stream Flags have not been set for this Stream with lzma_index_stream_flags().

+ +
+
+ +

◆ number

+ +
+
+ + + + +
lzma_vli lzma_index_iter::number
+
+ +

Stream number in the lzma_index.

+

The first Stream is 1.

+ +
+
+ +

◆ block_count

+ +
+
+ + + + +
lzma_vli lzma_index_iter::block_count
+
+ +

Number of Blocks in the Stream.

+

If this is zero, the block structure below has undefined values.

+ +
+
+ +

◆ compressed_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::compressed_offset
+
+ +

Compressed start offset of this Stream.

+

The offset is relative to the beginning of the lzma_index (i.e. usually the beginning of the .xz file).

+ +
+
+ +

◆ uncompressed_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::uncompressed_offset
+
+ +

Uncompressed start offset of this Stream.

+

The offset is relative to the beginning of the lzma_index (i.e. usually the beginning of the .xz file).

+ +
+
+ +

◆ compressed_size

+ +
+
+ + + + +
lzma_vli lzma_index_iter::compressed_size
+
+ +

Compressed size of this Stream.

+

This includes all headers except the possible Stream Padding after this Stream.

+ +
+
+ +

◆ uncompressed_size

+ +
+
+ + + + +
lzma_vli lzma_index_iter::uncompressed_size
+
+ +

Uncompressed size of this Stream.

+

Uncompressed size of this Block.

+

You should pass this to the Block decoder if you will decode this Block. It will allow the Block decoder to validate the uncompressed size.

+ +
+
+ +

◆ padding

+ +
+
+ + + + +
lzma_vli lzma_index_iter::padding
+
+ +

Size of Stream Padding after this Stream.

+

If it hasn't been set with lzma_index_stream_padding(), this defaults to zero. Stream Padding is always a multiple of four bytes.

+ +
+
+ +

◆ number_in_file

+ +
+
+ + + + +
lzma_vli lzma_index_iter::number_in_file
+
+ +

Block number in the file.

+

The first Block is 1.

+ +
+
+ +

◆ compressed_file_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::compressed_file_offset
+
+ +

Compressed start offset of this Block.

+

This offset is relative to the beginning of the lzma_index (i.e. usually the beginning of the .xz file). Normally this is where you should seek in the .xz file to start decompressing this Block.

+ +
+
+ +

◆ uncompressed_file_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::uncompressed_file_offset
+
+ +

Uncompressed start offset of this Block.

+

This offset is relative to the beginning of the lzma_index (i.e. usually the beginning of the .xz file).

+

When doing random-access reading, it is possible that the target offset is not exactly at Block boundary. One will need to compare the target offset against uncompressed_file_offset or uncompressed_stream_offset, and possibly decode and throw away some amount of data before reaching the target offset.

+ +
+
+ +

◆ number_in_stream

+ +
+
+ + + + +
lzma_vli lzma_index_iter::number_in_stream
+
+ +

Block number in this Stream.

+

The first Block is 1.

+ +
+
+ +

◆ compressed_stream_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::compressed_stream_offset
+
+ +

Compressed start offset of this Block.

+

This offset is relative to the beginning of the Stream containing this Block.

+ +
+
+ +

◆ uncompressed_stream_offset

+ +
+
+ + + + +
lzma_vli lzma_index_iter::uncompressed_stream_offset
+
+ +

Uncompressed start offset of this Block.

+

This offset is relative to the beginning of the Stream containing this Block.

+ +
+
+ +

◆ unpadded_size

+ +
+
+ + + + +
lzma_vli lzma_index_iter::unpadded_size
+
+ +

Unpadded size of this Block.

+

You should pass this to the Block decoder if you will decode this Block. It will allow the Block decoder to validate the unpadded size.

+ +
+
+ +

◆ total_size

+ +
+
+ + + + +
lzma_vli lzma_index_iter::total_size
+
+ +

Total compressed size.

+

This includes all headers and padding in this Block. This is useful if you need to know how many bytes the Block decoder will actually read.

+ +
+
+
The documentation for this struct was generated from the following file: +
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/structlzma__mt.html b/doc/api/structlzma__mt.html new file mode 100644 index 0000000..17a16cc --- /dev/null +++ b/doc/api/structlzma__mt.html @@ -0,0 +1,256 @@ + + + + + + + +liblzma (XZ Utils): lzma_mt Struct Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_mt Struct Reference
+
+
+ +

Multithreading options. + More...

+ +

#include <container.h>

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Data Fields

uint32_t flags
 Flags.
 
+uint32_t threads
 Number of worker threads to use.
 
uint64_t block_size
 Encoder only: Maximum uncompressed size of a Block.
 
uint32_t timeout
 Timeout to allow lzma_code() to return early.
 
uint32_t preset
 Encoder only: Compression preset.
 
const lzma_filter * filters
 Encoder only: Filter chain (alternative to a preset)
 
lzma_check check
 Encoder only: Integrity check type.
 
uint64_t memlimit_threading
 Memory usage limit to reduce the number of threads.
 
uint64_t memlimit_stop
 Memory usage limit that should never be exceeded.
 
+

Detailed Description

+

Multithreading options.

+

Field Documentation

+ +

◆ flags

+ +
+
+ + + + +
uint32_t lzma_mt::flags
+
+ +

Flags.

+

Set this to zero if no flags are wanted.

+

Encoder: No flags are currently supported.

+

Decoder: Bitwise-or of zero or more of the decoder flags:

    +
  • LZMA_TELL_NO_CHECK
    • +
  • LZMA_TELL_UNSUPPORTED_CHECK
    • +
  • LZMA_TELL_ANY_CHECK
    • +
  • LZMA_IGNORE_CHECK
    • +
  • LZMA_CONCATENATED
    • +
  • LZMA_FAIL_FAST
    • +
+ +
+
+ +

◆ block_size

+ +
+
+ + + + +
uint64_t lzma_mt::block_size
+
+ +

Encoder only: Maximum uncompressed size of a Block.

+

The encoder will start a new .xz Block every block_size bytes. Using LZMA_FULL_FLUSH or LZMA_FULL_BARRIER with lzma_code() the caller may tell liblzma to start a new Block earlier.

+

With LZMA2, a recommended block size is 2-4 times the LZMA2 dictionary size. With very small dictionaries, it is recommended to use at least 1 MiB block size for good compression ratio, even if this is more than four times the dictionary size. Note that these are only recommendations for typical use cases; feel free to use other values. Just keep in mind that using a block size less than the LZMA2 dictionary size is waste of RAM.

+

Set this to 0 to let liblzma choose the block size depending on the compression options. For LZMA2 it will be 3*dict_size or 1 MiB, whichever is more.

+

For each thread, about 3 * block_size bytes of memory will be allocated. This may change in later liblzma versions. If so, the memory usage will probably be reduced, not increased.

+ +
+
+ +

◆ timeout

+ +
+
+ + + + +
uint32_t lzma_mt::timeout
+
+ +

Timeout to allow lzma_code() to return early.

+

Multithreading can make liblzma consume input and produce output in a very bursty way: it may first read a lot of input to fill internal buffers, then no input or output occurs for a while.

+

In single-threaded mode, lzma_code() won't return until it has either consumed all the input or filled the output buffer. If this is done in multithreaded mode, it may cause a call lzma_code() to take even tens of seconds, which isn't acceptable in all applications.

+

To avoid very long blocking times in lzma_code(), a timeout (in milliseconds) may be set here. If lzma_code() would block longer than this number of milliseconds, it will return with LZMA_OK. Reasonable values are 100 ms or more. The xz command line tool uses 300 ms.

+

If long blocking times are acceptable, set timeout to a special value of 0. This will disable the timeout mechanism and will make lzma_code() block until all the input is consumed or the output buffer has been filled.

+
Note
Even with a timeout, lzma_code() might sometimes take a long time to return. No timing guarantees are made.
+ +
+
+ +

◆ preset

+ +
+
+ + + + +
uint32_t lzma_mt::preset
+
+ +

Encoder only: Compression preset.

+

The preset is set just like with lzma_easy_encoder(). The preset is ignored if filters below is non-NULL.

+ +
+
+ +

◆ filters

+ +
+
+ + + + +
const lzma_filter* lzma_mt::filters
+
+ +

Encoder only: Filter chain (alternative to a preset)

+

If this is NULL, the preset above is used. Otherwise the preset is ignored and the filter chain specified here is used.

+ +
+
+ +

◆ check

+ +
+
+ + + + +
lzma_check lzma_mt::check
+
+ +

Encoder only: Integrity check type.

+

See check.h for available checks. The xz command line tool defaults to LZMA_CHECK_CRC64, which is a good choice if you are unsure.

+ +
+
+ +

◆ memlimit_threading

+ +
+
+ + + + +
uint64_t lzma_mt::memlimit_threading
+
+ +

Memory usage limit to reduce the number of threads.

+

Encoder: Ignored.

+

Decoder:

+

If the number of threads has been set so high that more than memlimit_threading bytes of memory would be needed, the number of threads will be reduced so that the memory usage will not exceed memlimit_threading bytes. However, if memlimit_threading cannot be met even in single-threaded mode, then decoding will continue in single-threaded mode and memlimit_threading may be exceeded even by a large amount. That is, memlimit_threading will never make lzma_code() return LZMA_MEMLIMIT_ERROR. To truly cap the memory usage, see memlimit_stop below.

+

Setting memlimit_threading to UINT64_MAX or a similar huge value means that liblzma is allowed to keep the whole compressed file and the whole uncompressed file in memory in addition to the memory needed by the decompressor data structures used by each thread! In other words, a reasonable value limit must be set here or it will cause problems sooner or later. If you have no idea what a reasonable value could be, try lzma_physmem() / 4 as a starting point. Setting this limit will never prevent decompression of a file; this will only reduce the number of threads.

+

If memlimit_threading is greater than memlimit_stop, then the value of memlimit_stop will be used for both.

+ +
+
+ +

◆ memlimit_stop

+ +
+
+ + + + +
uint64_t lzma_mt::memlimit_stop
+
+ +

Memory usage limit that should never be exceeded.

+

Encoder: Ignored.

+

Decoder: If decompressing will need more than this amount of memory even in the single-threaded mode, then lzma_code() will return LZMA_MEMLIMIT_ERROR.

+ +
+
+
The documentation for this struct was generated from the following file: +
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/structlzma__options__bcj.html b/doc/api/structlzma__options__bcj.html new file mode 100644 index 0000000..b962092 --- /dev/null +++ b/doc/api/structlzma__options__bcj.html @@ -0,0 +1,95 @@ + + + + + + + +liblzma (XZ Utils): lzma_options_bcj Struct Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_options_bcj Struct Reference
+
+
+ +

Options for BCJ filters. + More...

+ +

#include <bcj.h>

+ + + + + +

+Data Fields

uint32_t start_offset
 Start offset for conversions.
 
+

Detailed Description

+

Options for BCJ filters.

+

The BCJ filters never change the size of the data. Specifying options for them is optional: if pointer to options is NULL, default value is used. You probably never need to specify options to BCJ filters, so just set the options pointer to NULL and be happy.

+

If options with non-default values have been specified when encoding, the same options must also be specified when decoding.

+
Note
At the moment, none of the BCJ filters support LZMA_SYNC_FLUSH. If LZMA_SYNC_FLUSH is specified, LZMA_OPTIONS_ERROR will be returned. If there is need, partial support for LZMA_SYNC_FLUSH can be added in future. Partial means that flushing would be possible only at offsets that are multiple of 2, 4, or 16 depending on the filter, except x86 which cannot be made to support LZMA_SYNC_FLUSH predictably.
+

Field Documentation

+ +

◆ start_offset

+ +
+
+ + + + +
uint32_t lzma_options_bcj::start_offset
+
+ +

Start offset for conversions.

+

This setting is useful only when the same filter is used _separately_ for multiple sections of the same executable file, and the sections contain cross-section branch/call/jump instructions. In that case it is beneficial to set the start offset of the non-first sections so that the relative addresses of the cross-section branch/call/jump instructions will use the same absolute addresses as in the first section.

+

When the pointer to options is NULL, the default value (zero) is used.

+ +
+
+
The documentation for this struct was generated from the following file: +
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/structlzma__options__delta.html b/doc/api/structlzma__options__delta.html new file mode 100644 index 0000000..294586d --- /dev/null +++ b/doc/api/structlzma__options__delta.html @@ -0,0 +1,113 @@ + + + + + + + +liblzma (XZ Utils): lzma_options_delta Struct Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_options_delta Struct Reference
+
+
+ +

Options for the Delta filter. + More...

+ +

#include <delta.h>

+ + + + + + + +

+Data Fields

lzma_delta_type type
 
uint32_t dist
 Delta distance.
 
+

Detailed Description

+

Options for the Delta filter.

+

These options are needed by both encoder and decoder.

+

Field Documentation

+ +

◆ type

+ +
+
+ + + + +
lzma_delta_type lzma_options_delta::type
+
+

For now, this must always be LZMA_DELTA_TYPE_BYTE.

+ +
+
+ +

◆ dist

+ +
+
+ + + + +
uint32_t lzma_options_delta::dist
+
+ +

Delta distance.

+

With the only currently supported type, LZMA_DELTA_TYPE_BYTE, the distance is as bytes.

+

Examples:

    +
  • 16-bit stereo audio: distance = 4 bytes
    • +
  • 24-bit RGB image data: distance = 3 bytes
    • +
+ +
+
+
The documentation for this struct was generated from the following file: +
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/structlzma__options__lzma.html b/doc/api/structlzma__options__lzma.html new file mode 100644 index 0000000..f8e3adf --- /dev/null +++ b/doc/api/structlzma__options__lzma.html @@ -0,0 +1,363 @@ + + + + + + + +liblzma (XZ Utils): lzma_options_lzma Struct Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_options_lzma Struct Reference
+
+
+ +

Options specific to the LZMA1 and LZMA2 filters. + More...

+ +

#include <lzma12.h>

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Data Fields

uint32_t dict_size
 Dictionary size in bytes.
 
const uint8_t * preset_dict
 Pointer to an initial dictionary.
 
uint32_t preset_dict_size
 Size of the preset dictionary.
 
uint32_t lc
 Number of literal context bits.
 
uint32_t lp
 Number of literal position bits.
 
uint32_t pb
 Number of position bits.
 
lzma_mode mode
 
uint32_t nice_len
 Nice length of a match.
 
lzma_match_finder mf
 
uint32_t depth
 Maximum search depth in the match finder.
 
uint32_t ext_flags
 For LZMA_FILTER_LZMA1EXT: Extended flags.
 
uint32_t ext_size_low
 For LZMA_FILTER_LZMA1EXT: Uncompressed size (low bits)
 
uint32_t ext_size_high
 For LZMA_FILTER_LZMA1EXT: Uncompressed size (high bits)
 
+

Detailed Description

+

Options specific to the LZMA1 and LZMA2 filters.

+

Since LZMA1 and LZMA2 share most of the code, it's simplest to share the options structure too. For encoding, all but the reserved variables need to be initialized unless specifically mentioned otherwise. lzma_lzma_preset() can be used to get a good starting point.

+

For raw decoding, both LZMA1 and LZMA2 need dict_size, preset_dict, and preset_dict_size (if preset_dict != NULL). LZMA1 needs also lc, lp, and pb.

+

Field Documentation

+ +

◆ dict_size

+ +
+
+ + + + +
uint32_t lzma_options_lzma::dict_size
+
+ +

Dictionary size in bytes.

+

Dictionary size indicates how many bytes of the recently processed uncompressed data is kept in memory. One method to reduce size of the uncompressed data is to store distance-length pairs, which indicate what data to repeat from the dictionary buffer. Thus, the bigger the dictionary, the better the compression ratio usually is.

+

Maximum size of the dictionary depends on multiple things:

    +
  • Memory usage limit
    • +
  • Available address space (not a problem on 64-bit systems)
    • +
  • Selected match finder (encoder only)
    • +
+

Currently the maximum dictionary size for encoding is 1.5 GiB (i.e. (UINT32_C(1) << 30) + (UINT32_C(1) << 29)) even on 64-bit systems for certain match finder implementation reasons. In the future, there may be match finders that support bigger dictionaries.

+

Decoder already supports dictionaries up to 4 GiB - 1 B (i.e. UINT32_MAX), so increasing the maximum dictionary size of the encoder won't cause problems for old decoders.

+

Because extremely small dictionaries sizes would have unneeded overhead in the decoder, the minimum dictionary size is 4096 bytes.

+
Note
When decoding, too big dictionary does no other harm than wasting memory.
+ +
+
+ +

◆ preset_dict

+ +
+
+ + + + +
const uint8_t* lzma_options_lzma::preset_dict
+
+ +

Pointer to an initial dictionary.

+

It is possible to initialize the LZ77 history window using a preset dictionary. It is useful when compressing many similar, relatively small chunks of data independently from each other. The preset dictionary should contain typical strings that occur in the files being compressed. The most probable strings should be near the end of the preset dictionary.

+

This feature should be used only in special situations. For now, it works correctly only with raw encoding and decoding. Currently none of the container formats supported by liblzma allow preset dictionary when decoding, thus if you create a .xz or .lzma file with preset dictionary, it cannot be decoded with the regular decoder functions. In the future, the .xz format will likely get support for preset dictionary though.

+ +
+
+ +

◆ preset_dict_size

+ +
+
+ + + + +
uint32_t lzma_options_lzma::preset_dict_size
+
+ +

Size of the preset dictionary.

+

Specifies the size of the preset dictionary. If the size is bigger than dict_size, only the last dict_size bytes are processed.

+

This variable is read only when preset_dict is not NULL. If preset_dict is not NULL but preset_dict_size is zero, no preset dictionary is used (identical to only setting preset_dict to NULL).

+ +
+
+ +

◆ lc

+ +
+
+ + + + +
uint32_t lzma_options_lzma::lc
+
+ +

Number of literal context bits.

+

How many of the highest bits of the previous uncompressed eight-bit byte (also known as `literal') are taken into account when predicting the bits of the next literal.

+

E.g. in typical English text, an upper-case letter is often followed by a lower-case letter, and a lower-case letter is usually followed by another lower-case letter. In the US-ASCII character set, the highest three bits are 010 for upper-case letters and 011 for lower-case letters. When lc is at least 3, the literal coding can take advantage of this property in the uncompressed data.

+

There is a limit that applies to literal context bits and literal position bits together: lc + lp <= 4. Without this limit the decoding could become very slow, which could have security related results in some cases like email servers doing virus scanning. This limit also simplifies the internal implementation in liblzma.

+

There may be LZMA1 streams that have lc + lp > 4 (maximum possible lc would be 8). It is not possible to decode such streams with liblzma.

+ +
+
+ +

◆ lp

+ +
+
+ + + + +
uint32_t lzma_options_lzma::lp
+
+ +

Number of literal position bits.

+

lp affects what kind of alignment in the uncompressed data is assumed when encoding literals. A literal is a single 8-bit byte. See pb below for more information about alignment.

+ +
+
+ +

◆ pb

+ +
+
+ + + + +
uint32_t lzma_options_lzma::pb
+
+ +

Number of position bits.

+

pb affects what kind of alignment in the uncompressed data is assumed in general. The default means four-byte alignment (2^ pb =2^2=4), which is often a good choice when there's no better guess.

+

When the alignment is known, setting pb accordingly may reduce the file size a little. E.g. with text files having one-byte alignment (US-ASCII, ISO-8859-*, UTF-8), setting pb=0 can improve compression slightly. For UTF-16 text, pb=1 is a good choice. If the alignment is an odd number like 3 bytes, pb=0 might be the best choice.

+

Even though the assumed alignment can be adjusted with pb and lp, LZMA1 and LZMA2 still slightly favor 16-byte alignment. It might be worth taking into account when designing file formats that are likely to be often compressed with LZMA1 or LZMA2.

+ +
+
+ +

◆ mode

+ +
+
+ + + + +
lzma_mode lzma_options_lzma::mode
+
+

Compression mode

+ +
+
+ +

◆ nice_len

+ +
+
+ + + + +
uint32_t lzma_options_lzma::nice_len
+
+ +

Nice length of a match.

+

This determines how many bytes the encoder compares from the match candidates when looking for the best match. Once a match of at least nice_len bytes long is found, the encoder stops looking for better candidates and encodes the match. (Naturally, if the found match is actually longer than nice_len, the actual length is encoded; it's not truncated to nice_len.)

+

Bigger values usually increase the compression ratio and compression time. For most files, 32 to 128 is a good value, which gives very good compression ratio at good speed.

+

The exact minimum value depends on the match finder. The maximum is 273, which is the maximum length of a match that LZMA1 and LZMA2 can encode.

+ +
+
+ +

◆ mf

+ +
+
+ + + + +
lzma_match_finder lzma_options_lzma::mf
+
+

Match finder ID

+ +
+
+ +

◆ depth

+ +
+
+ + + + +
uint32_t lzma_options_lzma::depth
+
+ +

Maximum search depth in the match finder.

+

For every input byte, match finder searches through the hash chain or binary tree in a loop, each iteration going one step deeper in the chain or tree. The searching stops if

    +
  • a match of at least nice_len bytes long is found;
    • +
  • all match candidates from the hash chain or binary tree have been checked; or
    • +
  • maximum search depth is reached.
    • +
+

Maximum search depth is needed to prevent the match finder from wasting too much time in case there are lots of short match candidates. On the other hand, stopping the search before all candidates have been checked can reduce compression ratio.

+

Setting depth to zero tells liblzma to use an automatic default value, that depends on the selected match finder and nice_len. The default is in the range [4, 200] or so (it may vary between liblzma versions).

+

Using a bigger depth value than the default can increase compression ratio in some cases. There is no strict maximum value, but high values (thousands or millions) should be used with care: the encoder could remain fast enough with typical input, but malicious input could cause the match finder to slow down dramatically, possibly creating a denial of service attack.

+ +
+
+ +

◆ ext_flags

+ +
+
+ + + + +
uint32_t lzma_options_lzma::ext_flags
+
+ +

For LZMA_FILTER_LZMA1EXT: Extended flags.

+

This is used only with LZMA_FILTER_LZMA1EXT.

+

Currently only one flag is supported, LZMA_LZMA1EXT_ALLOW_EOPM:

+
    +
  • Encoder: If the flag is set, then end marker is written just like it is with LZMA_FILTER_LZMA1. Without this flag the end marker isn't written and the application has to store the uncompressed size somewhere outside the compressed stream. To decompress streams without the end marker, the application has to set the correct uncompressed size in ext_size_low and ext_size_high.
    • +

  • Decoder: If the uncompressed size in ext_size_low and ext_size_high is set to the special value UINT64_MAX (indicating unknown uncompressed size) then this flag is ignored and the end marker must always be present, that is, the behavior is identical to LZMA_FILTER_LZMA1.

    +

    Otherwise, if this flag isn't set, then the input stream must not have the end marker; if the end marker is detected then it will result in LZMA_DATA_ERROR. This is useful when it is known that the stream must not have the end marker and strict validation is wanted.

    +

    If this flag is set, then it is autodetected if the end marker is present after the specified number of uncompressed bytes has been decompressed (ext_size_low and ext_size_high). The end marker isn't allowed in any other position. This behavior is useful when uncompressed size is known but the end marker may or may not be present. This is the case, for example, in .7z files (valid .7z files that have the end marker in LZMA1 streams are rare but they do exist).

    +
    • +
+ +
+
+ +

◆ ext_size_low

+ +
+
+ + + + +
uint32_t lzma_options_lzma::ext_size_low
+
+ +

For LZMA_FILTER_LZMA1EXT: Uncompressed size (low bits)

+

The 64-bit uncompressed size is needed for decompression with LZMA_FILTER_LZMA1EXT. The size is ignored by the encoder.

+

The special value UINT64_MAX indicates that the uncompressed size is unknown and that the end of payload marker (also known as end of stream marker) must be present to indicate the end of the LZMA1 stream. Any other value indicates the expected uncompressed size of the LZMA1 stream. (If LZMA1 was used together with filters that change the size of the data then the uncompressed size of the LZMA1 stream could be different than the final uncompressed size of the filtered stream.)

+

ext_size_low holds the least significant 32 bits of the uncompressed size. The most significant 32 bits must be set in ext_size_high. The macro lzma_ext_size_set(opt_lzma, u64size) can be used to set these members.

+

The 64-bit uncompressed size is split into two uint32_t variables because there were no reserved uint64_t members and using the same options structure for LZMA_FILTER_LZMA1, LZMA_FILTER_LZMA1EXT, and LZMA_FILTER_LZMA2 was otherwise more convenient than having a new options structure for LZMA_FILTER_LZMA1EXT. (Replacing two uint32_t members with one uint64_t changes the ABI on some systems as the alignment of this struct can increase from 4 bytes to 8.)

+ +
+
+ +

◆ ext_size_high

+ +
+
+ + + + +
uint32_t lzma_options_lzma::ext_size_high
+
+ +

For LZMA_FILTER_LZMA1EXT: Uncompressed size (high bits)

+

This holds the most significant 32 bits of the uncompressed size.

+ +
+
+
The documentation for this struct was generated from the following file: +
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/structlzma__stream.html b/doc/api/structlzma__stream.html new file mode 100644 index 0000000..5a0c784 --- /dev/null +++ b/doc/api/structlzma__stream.html @@ -0,0 +1,251 @@ + + + + + + + +liblzma (XZ Utils): lzma_stream Struct Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_stream Struct Reference
+
+
+ +

Passing data to and from liblzma. + More...

+ +

#include <base.h>

+ + + + + + + + + + + + + + + + + + + + + + +

+Data Fields

const uint8_t * next_in
 
size_t avail_in
 
uint64_t total_in
 
uint8_t * next_out
 
size_t avail_out
 
uint64_t total_out
 
const lzma_allocator * allocator
 Custom memory allocation functions.
 
lzma_internal * internal
 
uint64_t seek_pos
 New seek input position for LZMA_SEEK_NEEDED.
 
+

Detailed Description

+

Passing data to and from liblzma.

+

The lzma_stream structure is used for

    +
  • passing pointers to input and output buffers to liblzma;
    • +
  • defining custom memory handler functions; and
    • +
  • holding a pointer to coder-specific internal data structures.
    • +
+

Typical usage:

+
    +
  • After allocating lzma_stream (on stack or with malloc()), it must be initialized to LZMA_STREAM_INIT (see LZMA_STREAM_INIT for details).
    • +
  • Initialize a coder to the lzma_stream, for example by using lzma_easy_encoder() or lzma_auto_decoder(). Some notes:
      +
    • In contrast to zlib, strm->next_in and strm->next_out are ignored by all initialization functions, thus it is safe to not initialize them yet.
      • +
    • The initialization functions always set strm->total_in and strm->total_out to zero.
      • +
    • If the initialization function fails, no memory is left allocated that would require freeing with lzma_end() even if some memory was associated with the lzma_stream structure when the initialization function was called.
      • +
    +
    • +
  • Use lzma_code() to do the actual work.
    • +
  • Once the coding has been finished, the existing lzma_stream can be reused. It is OK to reuse lzma_stream with different initialization function without calling lzma_end() first. Old allocations are automatically freed.
    • +
  • Finally, use lzma_end() to free the allocated memory. lzma_end() never frees the lzma_stream structure itself.
    • +
+

Application may modify the values of total_in and total_out as it wants. They are updated by liblzma to match the amount of data read and written but aren't used for anything else except as a possible return values from lzma_get_progress().

+

Field Documentation

+ +

◆ next_in

+ +
+
+ + + + +
const uint8_t* lzma_stream::next_in
+
+

Pointer to the next input byte.

+ +
+
+ +

◆ avail_in

+ +
+
+ + + + +
size_t lzma_stream::avail_in
+
+

Number of available input bytes in next_in.

+ +
+
+ +

◆ total_in

+ +
+
+ + + + +
uint64_t lzma_stream::total_in
+
+

Total number of bytes read by liblzma.

+ +
+
+ +

◆ next_out

+ +
+
+ + + + +
uint8_t* lzma_stream::next_out
+
+

Pointer to the next output position.

+ +
+
+ +

◆ avail_out

+ +
+
+ + + + +
size_t lzma_stream::avail_out
+
+

Amount of free space in next_out.

+ +
+
+ +

◆ total_out

+ +
+
+ + + + +
uint64_t lzma_stream::total_out
+
+

Total number of bytes written by liblzma.

+ +
+
+ +

◆ allocator

+ +
+
+ + + + +
const lzma_allocator* lzma_stream::allocator
+
+ +

Custom memory allocation functions.

+

In most cases this is NULL which makes liblzma use the standard malloc() and free().

+
Note
In 5.0.x this is not a const pointer.
+ +
+
+ +

◆ internal

+ +
+
+ + + + +
lzma_internal* lzma_stream::internal
+
+

Internal state is not visible to applications.

+ +
+
+ +

◆ seek_pos

+ +
+
+ + + + +
uint64_t lzma_stream::seek_pos
+
+ +

New seek input position for LZMA_SEEK_NEEDED.

+

When lzma_code() returns LZMA_SEEK_NEEDED, the new input position needed by liblzma will be available seek_pos. The value is guaranteed to not exceed the file size that was specified when this lzma_stream was initialized.

+

In all other situations the value of this variable is undefined.

+ +
+
+
The documentation for this struct was generated from the following file: +
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/structlzma__stream__flags.html b/doc/api/structlzma__stream__flags.html new file mode 100644 index 0000000..9098ff3 --- /dev/null +++ b/doc/api/structlzma__stream__flags.html @@ -0,0 +1,134 @@ + + + + + + + +liblzma (XZ Utils): lzma_stream_flags Struct Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + +
+
+
+Data Fields
+
lzma_stream_flags Struct Reference
+
+
+ +

Options for encoding/decoding Stream Header and Stream Footer. + More...

+ +

#include <stream_flags.h>

+ + + + + + + + + + + +

+Data Fields

uint32_t version
 Stream Flags format version.
 
lzma_vli backward_size
 Backward Size.
 
lzma_check check
 Check ID.
 
+

Detailed Description

+

Options for encoding/decoding Stream Header and Stream Footer.

+

Field Documentation

+ +

◆ version

+ +
+
+ + + + +
uint32_t lzma_stream_flags::version
+
+ +

Stream Flags format version.

+

To prevent API and ABI breakages if new features are needed in Stream Header or Stream Footer, a version number is used to indicate which members in this structure are in use. For now, version must always be zero. With non-zero version, the lzma_stream_header_encode() and lzma_stream_footer_encode() will return LZMA_OPTIONS_ERROR.

+

lzma_stream_header_decode() and lzma_stream_footer_decode() will always set this to the lowest value that supports all the features indicated by the Stream Flags field. The application must check that the version number set by the decoding functions is supported by the application. Otherwise it is possible that the application will decode the Stream incorrectly.

+ +
+
+ +

◆ backward_size

+ +
+
+ + + + +
lzma_vli lzma_stream_flags::backward_size
+
+ +

Backward Size.

+

Backward Size must be a multiple of four bytes. In this Stream format version, Backward Size is the size of the Index field.

+

Backward Size isn't actually part of the Stream Flags field, but it is convenient to include in this structure anyway. Backward Size is present only in the Stream Footer. There is no need to initialize backward_size when encoding Stream Header.

+

lzma_stream_header_decode() always sets backward_size to LZMA_VLI_UNKNOWN so that it is convenient to use lzma_stream_flags_compare() when both Stream Header and Stream Footer have been decoded.

+ +
+
+ +

◆ check

+ +
+
+ + + + +
lzma_check lzma_stream_flags::check
+
+ +

Check ID.

+

This indicates the type of the integrity check calculated from uncompressed data.

+ +
+
+
The documentation for this struct was generated from the following file: +
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/sync_off.png b/doc/api/sync_off.png new file mode 100644 index 0000000..9b04abe Binary files /dev/null and b/doc/api/sync_off.png differ diff --git a/doc/api/sync_on.png b/doc/api/sync_on.png new file mode 100644 index 0000000..34a5b8b Binary files /dev/null and b/doc/api/sync_on.png differ diff --git a/doc/api/tab_a.png b/doc/api/tab_a.png new file mode 100644 index 0000000..3181cdf Binary files /dev/null and b/doc/api/tab_a.png differ diff --git a/doc/api/tab_ad.png b/doc/api/tab_ad.png new file mode 100644 index 0000000..3615386 Binary files /dev/null and b/doc/api/tab_ad.png differ diff --git a/doc/api/tab_b.png b/doc/api/tab_b.png new file mode 100644 index 0000000..3feec4f Binary files /dev/null and b/doc/api/tab_b.png differ diff --git a/doc/api/tab_bd.png b/doc/api/tab_bd.png new file mode 100644 index 0000000..9fd6635 Binary files /dev/null and b/doc/api/tab_bd.png differ diff --git a/doc/api/tab_h.png b/doc/api/tab_h.png new file mode 100644 index 0000000..abb3d3d Binary files /dev/null and b/doc/api/tab_h.png differ diff --git a/doc/api/tab_hd.png b/doc/api/tab_hd.png new file mode 100644 index 0000000..c59e413 Binary files /dev/null and b/doc/api/tab_hd.png differ diff --git a/doc/api/tab_s.png b/doc/api/tab_s.png new file mode 100644 index 0000000..a3f26f5 Binary files /dev/null and b/doc/api/tab_s.png differ diff --git a/doc/api/tab_sd.png b/doc/api/tab_sd.png new file mode 100644 index 0000000..5d4917a Binary files /dev/null and b/doc/api/tab_sd.png differ diff --git a/doc/api/tabs.css b/doc/api/tabs.css new file mode 100644 index 0000000..b56f46e --- /dev/null +++ b/doc/api/tabs.css @@ -0,0 +1,62 @@ +.tabs, .tabs2, .tabs3 { + background-image: var(--nav-gradient-image); + width: 100%; + z-index: 101; + font-size: var(--nav-font-size-level1); + font-family: var(--font-family-nav); + display: table; +} + +.tabs2 { + font-size: var(--nav-font-size-level2); +} +.tabs3 { + font-size: var(--nav-font-size-level3); +} + +.tablist { + margin: 0; + padding: 0; + display: block; +} + +.tablist li { + float: left; + display: table-cell; + background-image: var(--nav-gradient-image); + line-height: 36px; + list-style: none; +} + +.tablist a { + display: block; + padding: 0 20px; + font-weight: bold; + background-image:var(--nav-separator-image); + background-repeat:no-repeat; + background-position:right; + color: var(--nav-text-normal-color); + text-shadow: var(--nav-text-normal-shadow); + text-decoration: none; + outline: none; +} + +.tabs3 .tablist a { + padding: 0 10px; +} + +.tablist a:hover { + background-image: var(--nav-gradient-hover-image); + background-repeat:repeat-x; + color: var(--nav-text-hover-color); + text-shadow: var(--nav-text-hover-shadow); + text-decoration: none; +} + +.tablist li.current a { + background-image: var(--nav-gradient-active-image); + background-repeat:repeat-x; + color: var(--nav-text-active-color); + text-shadow: var(--nav-text-active-shadow); +} + diff --git a/doc/api/version_8h.html b/doc/api/version_8h.html new file mode 100644 index 0000000..fd27466 --- /dev/null +++ b/doc/api/version_8h.html @@ -0,0 +1,239 @@ + + + + + + + +liblzma (XZ Utils): lzma/version.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Macros | +Functions
+
version.h File Reference
+
+
+ +

Version number. +More...

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Macros

+#define LZMA_VERSION_MAJOR   5
 Major version number of the liblzma release.
 
+#define LZMA_VERSION_MINOR   4
 Minor version number of the liblzma release.
 
+#define LZMA_VERSION_PATCH   5
 Patch version number of the liblzma release.
 
#define LZMA_VERSION_STABILITY   LZMA_VERSION_STABILITY_STABLE
 Version stability marker.
 
+#define LZMA_VERSION_COMMIT   ""
 Commit version number of the liblzma release.
 
+#define LZMA_VERSION_STABILITY_ALPHA   0
 
+#define LZMA_VERSION_STABILITY_BETA   1
 
+#define LZMA_VERSION_STABILITY_STABLE   2
 
#define LZMA_VERSION
 Compile-time version number.
 
+#define LZMA_VERSION_STABILITY_STRING   "alpha"
 
+#define LZMA_VERSION_STRING_C_(major, minor, patch, stability, commit)    #major "." #minor "." #patch stability commit
 
+#define LZMA_VERSION_STRING_C(major, minor, patch, stability, commit)    LZMA_VERSION_STRING_C_(major, minor, patch, stability, commit)
 
#define LZMA_VERSION_STRING
 Compile-time version as a string.
 
+ + + + + + + +

+Functions

uint32_t lzma_version_number (void) lzma_nothrow lzma_attr_const
 Run-time version number as an integer.
 
const char * lzma_version_string (void) lzma_nothrow lzma_attr_const
 Run-time version as a string.
 
+

Detailed Description

+

Version number.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

Macro Definition Documentation

+ +

◆ LZMA_VERSION_STABILITY

+ +
+
+ + + + +
#define LZMA_VERSION_STABILITY   LZMA_VERSION_STABILITY_STABLE
+
+ +

Version stability marker.

+

This will always be one of three values:

    +
  • LZMA_VERSION_STABILITY_ALPHA
    • +
  • LZMA_VERSION_STABILITY_BETA
    • +
  • LZMA_VERSION_STABILITY_STABLE
    • +
+ +
+
+ +

◆ LZMA_VERSION

+ +
+
+ + + + +
#define LZMA_VERSION
+
+Value:
(LZMA_VERSION_MAJOR * UINT32_C(10000000) \
+
+ LZMA_VERSION_MINOR * UINT32_C(10000) \
+
+ LZMA_VERSION_PATCH * UINT32_C(10) \
+
+ LZMA_VERSION_STABILITY)
+
+

Compile-time version number.

+

The version number is of format xyyyzzzs where

    +
  • x = major
    • +
  • yyy = minor
    • +
  • zzz = revision
    • +
  • s indicates stability: 0 = alpha, 1 = beta, 2 = stable
    • +
+

The same xyyyzzz triplet is never reused with different stability levels. For example, if 5.1.0alpha has been released, there will never be 5.1.0beta or 5.1.0 stable.

+
Note
The version number of liblzma has nothing to with the version number of Igor Pavlov's LZMA SDK.
+ +
+
+ +

◆ LZMA_VERSION_STRING

+ +
+
+ + + + +
#define LZMA_VERSION_STRING
+
+Value:
LZMA_VERSION_STRING_C( \
+
LZMA_VERSION_MAJOR, LZMA_VERSION_MINOR, \
+
LZMA_VERSION_PATCH, LZMA_VERSION_STABILITY_STRING, \
+
LZMA_VERSION_COMMIT)
+
+

Compile-time version as a string.

+

This can be for example "4.999.5alpha", "4.999.8beta", or "5.0.0" (stable versions don't have any "stable" suffix). In future, a snapshot built from source code repository may include an additional suffix, for example "4.999.8beta-21-g1d92". The commit ID won't be available in numeric form in LZMA_VERSION macro.

+ +
+
+

Function Documentation

+ +

◆ lzma_version_number()

+ +
+
+ + + + + + + + +
uint32_t lzma_version_number (void ) const
+
+ +

Run-time version number as an integer.

+

This allows an application to compare if it was built against the same, older, or newer version of liblzma that is currently running.

+
Returns
The value of LZMA_VERSION macro at the compile time of liblzma
+ +
+
+ +

◆ lzma_version_string()

+ +
+
+ + + + + + + + +
const char * lzma_version_string (void ) const
+
+ +

Run-time version as a string.

+

This function may be useful to display which version of liblzma an application is currently using.

+
Returns
Run-time version of liblzma
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/api/vli_8h.html b/doc/api/vli_8h.html new file mode 100644 index 0000000..4e3da1f --- /dev/null +++ b/doc/api/vli_8h.html @@ -0,0 +1,323 @@ + + + + + + + +liblzma (XZ Utils): lzma/vli.h File Reference + + + + + + +
+
+ + + + + + +
+
liblzma (XZ Utils) 5.4.5 +
+
+
+ + + + + +
+
+
+Macros | +Typedefs | +Functions
+
vli.h File Reference
+
+
+ +

Variable-length integer handling. +More...

+ + + + + + + + + + + + + + + + + +

+Macros

+#define LZMA_VLI_MAX   (UINT64_MAX / 2)
 Maximum supported value of a 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 encoded 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)
 Validate a variable-length integer.
 
+ + + + +

+Typedefs

typedef uint64_t lzma_vli
 Variable-length integer type.
 
+ + + + + + + + + + +

+Functions

lzma_ret lzma_vli_encode (lzma_vli vli, size_t *vli_pos, uint8_t *out, size_t *out_pos, size_t out_size) lzma_nothrow
 Encode a variable-length integer.
 
lzma_ret lzma_vli_decode (lzma_vli *vli, size_t *vli_pos, const uint8_t *in, size_t *in_pos, size_t in_size) lzma_nothrow
 Decode a variable-length integer.
 
uint32_t lzma_vli_size (lzma_vli vli) lzma_nothrow lzma_attr_pure
 Get the number of bytes required to encode a VLI.
 
+

Detailed Description

+

Variable-length integer handling.

+
Note
Never include this file directly. Use <lzma.h> instead.
+

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 less than or equal to UINT64_MAX / 2. You should use LZMA_VLI_MAX for clarity.

+

Macro Definition Documentation

+ +

◆ lzma_vli_is_valid

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

Validate a 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. False if the integer cannot be represented as VLI.
+ +
+
+

Typedef Documentation

+ +

◆ lzma_vli

+ +
+
+ + + + +
typedef uint64_t lzma_vli
+
+ +

Variable-length integer type.

+

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 underlying integer type.

+

lzma_vli will be uint64_t for the foreseeable future. If a bigger size is needed in the future, it is guaranteed that 2 * LZMA_VLI_MAX will not overflow lzma_vli. This simplifies integer overflow detection.

+ +
+
+

Function Documentation

+ +

◆ lzma_vli_encode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_vli_encode (lzma_vli vli,
size_t * vli_pos,
uint8_t * out,
size_t * out_pos,
size_t out_size 
)
+
+ +

Encode a variable-length integer.

+

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
+ + + + + + +
vliInteger to be encoded
[out]vli_posHow many VLI-encoded bytes have already been written out. When starting to encode a new integer in multi-call mode, *vli_pos must be set to zero. To use single-call encoding, set vli_pos to NULL.
[out]outBeginning of the output buffer
[out]out_posThe next byte will be written to out[*out_pos].
out_sizeSize 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.
    • +
+ +
+
+ +

◆ lzma_vli_decode()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
lzma_ret lzma_vli_decode (lzma_vli * vli,
size_t * vli_pos,
const uint8_t * in,
size_t * in_pos,
size_t in_size 
)
+
+ +

Decode a variable-length integer.

+

Like lzma_vli_encode(), this function has single-call and multi-call modes.

+
Parameters
+ + + + + + +
[out]vliPointer to decoded integer. The decoder will initialize it to zero when *vli_pos == 0, so application isn't required to initialize *vli.
[out]vli_posHow many bytes have already been decoded. When starting to decode a new integer in multi-call mode, *vli_pos must be initialized to zero. To use single-call decoding, set vli_pos to NULL.
inBeginning of the input buffer
[out]in_posThe next byte will be read from in[*in_pos].
in_sizeSize 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_vli_size()

+ +
+
+ + + + + + + + +
uint32_t lzma_vli_size (lzma_vli vli)
+
+ +

Get the number of bytes required to encode a VLI.

+
Parameters
+ + +
vliInteger whose encoded size is to be determined
+
+
+
Returns
Number of bytes on success (1-9). If vli isn't valid, zero is returned.
+ +
+
+
+ +
+Generated by doxygen 1.9.7 +
+ + diff --git a/doc/examples/00_README.txt b/doc/examples/00_README.txt new file mode 100644 index 0000000..120e1eb --- /dev/null +++ b/doc/examples/00_README.txt @@ -0,0 +1,31 @@ + +liblzma example programs +======================== + +Introduction + + The examples are written so that the same comments aren't + repeated (much) in later files. + + On POSIX systems, the examples should build by just typing "make". + + The examples that use stdin or stdout don't set stdin and stdout + to binary mode. On systems where it matters (e.g. Windows) it is + possible that the examples won't work without modification. + + +List of examples + + 01_compress_easy.c Multi-call compression using + a compression preset + + 02_decompress.c Multi-call decompression + + 03_compress_custom.c Like 01_compress_easy.c but using + a custom filter chain + (x86 BCJ + LZMA2) + + 04_compress_easy_mt.c Multi-threaded multi-call + compression using a compression + preset + diff --git a/doc/examples/01_compress_easy.c b/doc/examples/01_compress_easy.c new file mode 100644 index 0000000..ec32a37 --- /dev/null +++ b/doc/examples/01_compress_easy.c @@ -0,0 +1,297 @@ +/////////////////////////////////////////////////////////////////////////////// +// +/// \file 01_compress_easy.c +/// \brief Compress from stdin to stdout in multi-call mode +/// +/// Usage: ./01_compress_easy PRESET < INFILE > OUTFILE +/// +/// Example: ./01_compress_easy 6 < foo > foo.xz +// +// Author: Lasse Collin +// +// This file has been put into the public domain. +// You can do whatever you want with this file. +// +/////////////////////////////////////////////////////////////////////////////// + +#include +#include +#include +#include +#include +#include + + +static void +show_usage_and_exit(const char *argv0) +{ + fprintf(stderr, "Usage: %s PRESET < INFILE > OUTFILE\n" + "PRESET is a number 0-9 and can optionally be " + "followed by `e' to indicate extreme preset\n", + argv0); + exit(EXIT_FAILURE); +} + + +static uint32_t +get_preset(int argc, char **argv) +{ + // One argument whose first char must be 0-9. + if (argc != 2 || argv[1][0] < '0' || argv[1][0] > '9') + show_usage_and_exit(argv[0]); + + // Calculate the preste level 0-9. + uint32_t preset = argv[1][0] - '0'; + + // If there is a second char, it must be 'e'. It will set + // the LZMA_PRESET_EXTREME flag. + if (argv[1][1] != '\0') { + if (argv[1][1] != 'e' || argv[1][2] != '\0') + show_usage_and_exit(argv[0]); + + preset |= LZMA_PRESET_EXTREME; + } + + return preset; +} + + +static bool +init_encoder(lzma_stream *strm, uint32_t preset) +{ + // Initialize the encoder using a preset. Set the integrity to check + // to CRC64, which is the default in the xz command line tool. If + // the .xz file needs to be decompressed with XZ Embedded, use + // LZMA_CHECK_CRC32 instead. + lzma_ret ret = lzma_easy_encoder(strm, preset, LZMA_CHECK_CRC64); + + // Return successfully if the initialization went fine. + if (ret == LZMA_OK) + return true; + + // Something went wrong. The possible errors are documented in + // lzma/container.h (src/liblzma/api/lzma/container.h in the source + // package or e.g. /usr/include/lzma/container.h depending on the + // install prefix). + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_OPTIONS_ERROR: + msg = "Specified preset is not supported"; + break; + + case LZMA_UNSUPPORTED_CHECK: + msg = "Specified integrity check is not supported"; + break; + + default: + // This is most likely LZMA_PROG_ERROR indicating a bug in + // this program or in liblzma. It is inconvenient to have a + // separate error message for errors that should be impossible + // to occur, but knowing the error code is important for + // debugging. That's why it is good to print the error code + // at least when there is no good error message to show. + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Error initializing the encoder: %s (error code %u)\n", + msg, ret); + return false; +} + + +static bool +compress(lzma_stream *strm, FILE *infile, FILE *outfile) +{ + // This will be LZMA_RUN until the end of the input file is reached. + // This tells lzma_code() when there will be no more input. + lzma_action action = LZMA_RUN; + + // Buffers to temporarily hold uncompressed input + // and compressed output. + uint8_t inbuf[BUFSIZ]; + uint8_t outbuf[BUFSIZ]; + + // Initialize the input and output pointers. Initializing next_in + // and avail_in isn't really necessary when we are going to encode + // just one file since LZMA_STREAM_INIT takes care of initializing + // those already. But it doesn't hurt much and it will be needed + // if encoding more than one file like we will in 02_decompress.c. + // + // While we don't care about strm->total_in or strm->total_out in this + // example, it is worth noting that initializing the encoder will + // always reset total_in and total_out to zero. But the encoder + // initialization doesn't touch next_in, avail_in, next_out, or + // avail_out. + strm->next_in = NULL; + strm->avail_in = 0; + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + + // Loop until the file has been successfully compressed or until + // an error occurs. + while (true) { + // Fill the input buffer if it is empty. + if (strm->avail_in == 0 && !feof(infile)) { + strm->next_in = inbuf; + strm->avail_in = fread(inbuf, 1, sizeof(inbuf), + infile); + + if (ferror(infile)) { + fprintf(stderr, "Read error: %s\n", + strerror(errno)); + return false; + } + + // Once the end of the input file has been reached, + // we need to tell lzma_code() that no more input + // will be coming and that it should finish the + // encoding. + if (feof(infile)) + action = LZMA_FINISH; + } + + // Tell liblzma do the actual encoding. + // + // This reads up to strm->avail_in bytes of input starting + // from strm->next_in. avail_in will be decremented and + // next_in incremented by an equal amount to match the + // number of input bytes consumed. + // + // Up to strm->avail_out bytes of compressed output will be + // written starting from strm->next_out. avail_out and next_out + // will be incremented by an equal amount to match the number + // of output bytes written. + // + // The encoder has to do internal buffering, which means that + // it may take quite a bit of input before the same data is + // available in compressed form in the output buffer. + lzma_ret ret = lzma_code(strm, action); + + // If the output buffer is full or if the compression finished + // successfully, write the data from the output buffer to + // the output file. + if (strm->avail_out == 0 || ret == LZMA_STREAM_END) { + // When lzma_code() has returned LZMA_STREAM_END, + // the output buffer is likely to be only partially + // full. Calculate how much new data there is to + // be written to the output file. + size_t write_size = sizeof(outbuf) - strm->avail_out; + + if (fwrite(outbuf, 1, write_size, outfile) + != write_size) { + fprintf(stderr, "Write error: %s\n", + strerror(errno)); + return false; + } + + // Reset next_out and avail_out. + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + } + + // Normally the return value of lzma_code() will be LZMA_OK + // until everything has been encoded. + if (ret != LZMA_OK) { + // Once everything has been encoded successfully, the + // return value of lzma_code() will be LZMA_STREAM_END. + // + // It is important to check for LZMA_STREAM_END. Do not + // assume that getting ret != LZMA_OK would mean that + // everything has gone well. + if (ret == LZMA_STREAM_END) + return true; + + // It's not LZMA_OK nor LZMA_STREAM_END, + // so it must be an error code. See lzma/base.h + // (src/liblzma/api/lzma/base.h in the source package + // or e.g. /usr/include/lzma/base.h depending on the + // install prefix) for the list and documentation of + // possible values. Most values listen in lzma_ret + // enumeration aren't possible in this example. + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_DATA_ERROR: + // This error is returned if the compressed + // or uncompressed size get near 8 EiB + // (2^63 bytes) because that's where the .xz + // file format size limits currently are. + // That is, the possibility of this error + // is mostly theoretical unless you are doing + // something very unusual. + // + // Note that strm->total_in and strm->total_out + // have nothing to do with this error. Changing + // those variables won't increase or decrease + // the chance of getting this error. + msg = "File size limits exceeded"; + break; + + default: + // This is most likely LZMA_PROG_ERROR, but + // if this program is buggy (or liblzma has + // a bug), it may be e.g. LZMA_BUF_ERROR or + // LZMA_OPTIONS_ERROR too. + // + // It is inconvenient to have a separate + // error message for errors that should be + // impossible to occur, but knowing the error + // code is important for debugging. That's why + // it is good to print the error code at least + // when there is no good error message to show. + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Encoder error: %s (error code %u)\n", + msg, ret); + return false; + } + } +} + + +extern int +main(int argc, char **argv) +{ + // Get the preset number from the command line. + uint32_t preset = get_preset(argc, argv); + + // Initialize a lzma_stream structure. When it is allocated on stack, + // it is simplest to use LZMA_STREAM_INIT macro like below. When it + // is allocated on heap, using memset(strmptr, 0, sizeof(*strmptr)) + // works (as long as NULL pointers are represented with zero bits + // as they are on practically all computers today). + lzma_stream strm = LZMA_STREAM_INIT; + + // Initialize the encoder. If it succeeds, compress from + // stdin to stdout. + bool success = init_encoder(&strm, preset); + if (success) + success = compress(&strm, stdin, stdout); + + // Free the memory allocated for the encoder. If we were encoding + // multiple files, this would only need to be done after the last + // file. See 02_decompress.c for handling of multiple files. + // + // It is OK to call lzma_end() multiple times or when it hasn't been + // actually used except initialized with LZMA_STREAM_INIT. + lzma_end(&strm); + + // Close stdout to catch possible write errors that can occur + // when pending data is flushed from the stdio buffers. + if (fclose(stdout)) { + fprintf(stderr, "Write error: %s\n", strerror(errno)); + success = false; + } + + return success ? EXIT_SUCCESS : EXIT_FAILURE; +} diff --git a/doc/examples/02_decompress.c b/doc/examples/02_decompress.c new file mode 100644 index 0000000..98339be --- /dev/null +++ b/doc/examples/02_decompress.c @@ -0,0 +1,287 @@ +/////////////////////////////////////////////////////////////////////////////// +// +/// \file 02_decompress.c +/// \brief Decompress .xz files to stdout +/// +/// Usage: ./02_decompress INPUT_FILES... > OUTFILE +/// +/// Example: ./02_decompress foo.xz bar.xz > foobar +// +// Author: Lasse Collin +// +// This file has been put into the public domain. +// You can do whatever you want with this file. +// +/////////////////////////////////////////////////////////////////////////////// + +#include +#include +#include +#include +#include +#include + + +static bool +init_decoder(lzma_stream *strm) +{ + // Initialize a .xz decoder. The decoder supports a memory usage limit + // and a set of flags. + // + // The memory usage of the decompressor depends on the settings used + // to compress a .xz file. It can vary from less than a megabyte to + // a few gigabytes, but in practice (at least for now) it rarely + // exceeds 65 MiB because that's how much memory is required to + // decompress files created with "xz -9". Settings requiring more + // memory take extra effort to use and don't (at least for now) + // provide significantly better compression in most cases. + // + // Memory usage limit is useful if it is important that the + // decompressor won't consume gigabytes of memory. The need + // for limiting depends on the application. In this example, + // no memory usage limiting is used. This is done by setting + // the limit to UINT64_MAX. + // + // The .xz format allows concatenating compressed files as is: + // + // echo foo | xz > foobar.xz + // echo bar | xz >> foobar.xz + // + // When decompressing normal standalone .xz files, LZMA_CONCATENATED + // should always be used to support decompression of concatenated + // .xz files. If LZMA_CONCATENATED isn't used, the decoder will stop + // after the first .xz stream. This can be useful when .xz data has + // been embedded inside another file format. + // + // Flags other than LZMA_CONCATENATED are supported too, and can + // be combined with bitwise-or. See lzma/container.h + // (src/liblzma/api/lzma/container.h in the source package or e.g. + // /usr/include/lzma/container.h depending on the install prefix) + // for details. + lzma_ret ret = lzma_stream_decoder( + strm, UINT64_MAX, LZMA_CONCATENATED); + + // Return successfully if the initialization went fine. + if (ret == LZMA_OK) + return true; + + // Something went wrong. The possible errors are documented in + // lzma/container.h (src/liblzma/api/lzma/container.h in the source + // package or e.g. /usr/include/lzma/container.h depending on the + // install prefix). + // + // Note that LZMA_MEMLIMIT_ERROR is never possible here. If you + // specify a very tiny limit, the error will be delayed until + // the first headers have been parsed by a call to lzma_code(). + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_OPTIONS_ERROR: + msg = "Unsupported decompressor flags"; + break; + + default: + // This is most likely LZMA_PROG_ERROR indicating a bug in + // this program or in liblzma. It is inconvenient to have a + // separate error message for errors that should be impossible + // to occur, but knowing the error code is important for + // debugging. That's why it is good to print the error code + // at least when there is no good error message to show. + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Error initializing the decoder: %s (error code %u)\n", + msg, ret); + return false; +} + + +static bool +decompress(lzma_stream *strm, const char *inname, FILE *infile, FILE *outfile) +{ + // When LZMA_CONCATENATED flag was used when initializing the decoder, + // we need to tell lzma_code() when there will be no more input. + // This is done by setting action to LZMA_FINISH instead of LZMA_RUN + // in the same way as it is done when encoding. + // + // When LZMA_CONCATENATED isn't used, there is no need to use + // LZMA_FINISH to tell when all the input has been read, but it + // is still OK to use it if you want. When LZMA_CONCATENATED isn't + // used, the decoder will stop after the first .xz stream. In that + // case some unused data may be left in strm->next_in. + lzma_action action = LZMA_RUN; + + uint8_t inbuf[BUFSIZ]; + uint8_t outbuf[BUFSIZ]; + + strm->next_in = NULL; + strm->avail_in = 0; + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + + while (true) { + if (strm->avail_in == 0 && !feof(infile)) { + strm->next_in = inbuf; + strm->avail_in = fread(inbuf, 1, sizeof(inbuf), + infile); + + if (ferror(infile)) { + fprintf(stderr, "%s: Read error: %s\n", + inname, strerror(errno)); + return false; + } + + // Once the end of the input file has been reached, + // we need to tell lzma_code() that no more input + // will be coming. As said before, this isn't required + // if the LZMA_CONCATENATED flag isn't used when + // initializing the decoder. + if (feof(infile)) + action = LZMA_FINISH; + } + + lzma_ret ret = lzma_code(strm, action); + + if (strm->avail_out == 0 || ret == LZMA_STREAM_END) { + size_t write_size = sizeof(outbuf) - strm->avail_out; + + if (fwrite(outbuf, 1, write_size, outfile) + != write_size) { + fprintf(stderr, "Write error: %s\n", + strerror(errno)); + return false; + } + + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + } + + if (ret != LZMA_OK) { + // Once everything has been decoded successfully, the + // return value of lzma_code() will be LZMA_STREAM_END. + // + // It is important to check for LZMA_STREAM_END. Do not + // assume that getting ret != LZMA_OK would mean that + // everything has gone well or that when you aren't + // getting more output it must have successfully + // decoded everything. + if (ret == LZMA_STREAM_END) + return true; + + // It's not LZMA_OK nor LZMA_STREAM_END, + // so it must be an error code. See lzma/base.h + // (src/liblzma/api/lzma/base.h in the source package + // or e.g. /usr/include/lzma/base.h depending on the + // install prefix) for the list and documentation of + // possible values. Many values listen in lzma_ret + // enumeration aren't possible in this example, but + // can be made possible by enabling memory usage limit + // or adding flags to the decoder initialization. + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_FORMAT_ERROR: + // .xz magic bytes weren't found. + msg = "The input is not in the .xz format"; + break; + + case LZMA_OPTIONS_ERROR: + // For example, the headers specify a filter + // that isn't supported by this liblzma + // version (or it hasn't been enabled when + // building liblzma, but no-one sane does + // that unless building liblzma for an + // embedded system). Upgrading to a newer + // liblzma might help. + // + // Note that it is unlikely that the file has + // accidentally became corrupt if you get this + // error. The integrity of the .xz headers is + // always verified with a CRC32, so + // unintentionally corrupt files can be + // distinguished from unsupported files. + msg = "Unsupported compression options"; + break; + + case LZMA_DATA_ERROR: + msg = "Compressed file is corrupt"; + break; + + case LZMA_BUF_ERROR: + // Typically this error means that a valid + // file has got truncated, but it might also + // be a damaged part in the file that makes + // the decoder think the file is truncated. + // If you prefer, you can use the same error + // message for this as for LZMA_DATA_ERROR. + msg = "Compressed file is truncated or " + "otherwise corrupt"; + break; + + default: + // This is most likely LZMA_PROG_ERROR. + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "%s: Decoder error: " + "%s (error code %u)\n", + inname, msg, ret); + return false; + } + } +} + + +extern int +main(int argc, char **argv) +{ + if (argc <= 1) { + fprintf(stderr, "Usage: %s FILES...\n", argv[0]); + return EXIT_FAILURE; + } + + lzma_stream strm = LZMA_STREAM_INIT; + + bool success = true; + + // Try to decompress all files. + for (int i = 1; i < argc; ++i) { + if (!init_decoder(&strm)) { + // Decoder initialization failed. There's no point + // to retry it so we need to exit. + success = false; + break; + } + + FILE *infile = fopen(argv[i], "rb"); + + if (infile == NULL) { + fprintf(stderr, "%s: Error opening the " + "input file: %s\n", + argv[i], strerror(errno)); + success = false; + } else { + success &= decompress(&strm, argv[i], infile, stdout); + fclose(infile); + } + } + + // Free the memory allocated for the decoder. This only needs to be + // done after the last file. + lzma_end(&strm); + + if (fclose(stdout)) { + fprintf(stderr, "Write error: %s\n", strerror(errno)); + success = false; + } + + return success ? EXIT_SUCCESS : EXIT_FAILURE; +} diff --git a/doc/examples/03_compress_custom.c b/doc/examples/03_compress_custom.c new file mode 100644 index 0000000..40c85e3 --- /dev/null +++ b/doc/examples/03_compress_custom.c @@ -0,0 +1,193 @@ +/////////////////////////////////////////////////////////////////////////////// +// +/// \file 03_compress_custom.c +/// \brief Compress in multi-call mode using x86 BCJ and LZMA2 +/// +/// Usage: ./03_compress_custom < INFILE > OUTFILE +/// +/// Example: ./03_compress_custom < foo > foo.xz +// +// Author: Lasse Collin +// +// This file has been put into the public domain. +// You can do whatever you want with this file. +// +/////////////////////////////////////////////////////////////////////////////// + +#include +#include +#include +#include +#include +#include + + +static bool +init_encoder(lzma_stream *strm) +{ + // Use the default preset (6) for LZMA2. + // + // The lzma_options_lzma structure and the lzma_lzma_preset() function + // are declared in lzma/lzma12.h (src/liblzma/api/lzma/lzma12.h in the + // source package or e.g. /usr/include/lzma/lzma12.h depending on + // the install prefix). + lzma_options_lzma opt_lzma2; + if (lzma_lzma_preset(&opt_lzma2, LZMA_PRESET_DEFAULT)) { + // It should never fail because the default preset + // (and presets 0-9 optionally with LZMA_PRESET_EXTREME) + // are supported by all stable liblzma versions. + // + // (The encoder initialization later in this function may + // still fail due to unsupported preset *if* the features + // required by the preset have been disabled at build time, + // but no-one does such things except on embedded systems.) + fprintf(stderr, "Unsupported preset, possibly a bug\n"); + return false; + } + + // Now we could customize the LZMA2 options if we wanted. For example, + // we could set the the dictionary size (opt_lzma2.dict_size) to + // something else than the default (8 MiB) of the default preset. + // See lzma/lzma12.h for details of all LZMA2 options. + // + // The x86 BCJ filter will try to modify the x86 instruction stream so + // that LZMA2 can compress it better. The x86 BCJ filter doesn't need + // any options so it will be set to NULL below. + // + // Construct the filter chain. The uncompressed data goes first to + // the first filter in the array, in this case the x86 BCJ filter. + // The array is always terminated by setting .id = LZMA_VLI_UNKNOWN. + // + // See lzma/filter.h for more information about the lzma_filter + // structure. + lzma_filter filters[] = { + { .id = LZMA_FILTER_X86, .options = NULL }, + { .id = LZMA_FILTER_LZMA2, .options = &opt_lzma2 }, + { .id = LZMA_VLI_UNKNOWN, .options = NULL }, + }; + + // Initialize the encoder using the custom filter chain. + lzma_ret ret = lzma_stream_encoder(strm, filters, LZMA_CHECK_CRC64); + + if (ret == LZMA_OK) + return true; + + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_OPTIONS_ERROR: + // We are no longer using a plain preset so this error + // message has been edited accordingly compared to + // 01_compress_easy.c. + msg = "Specified filter chain is not supported"; + break; + + case LZMA_UNSUPPORTED_CHECK: + msg = "Specified integrity check is not supported"; + break; + + default: + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Error initializing the encoder: %s (error code %u)\n", + msg, ret); + return false; +} + + +// This function is identical to the one in 01_compress_easy.c. +static bool +compress(lzma_stream *strm, FILE *infile, FILE *outfile) +{ + lzma_action action = LZMA_RUN; + + uint8_t inbuf[BUFSIZ]; + uint8_t outbuf[BUFSIZ]; + + strm->next_in = NULL; + strm->avail_in = 0; + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + + while (true) { + if (strm->avail_in == 0 && !feof(infile)) { + strm->next_in = inbuf; + strm->avail_in = fread(inbuf, 1, sizeof(inbuf), + infile); + + if (ferror(infile)) { + fprintf(stderr, "Read error: %s\n", + strerror(errno)); + return false; + } + + if (feof(infile)) + action = LZMA_FINISH; + } + + lzma_ret ret = lzma_code(strm, action); + + if (strm->avail_out == 0 || ret == LZMA_STREAM_END) { + size_t write_size = sizeof(outbuf) - strm->avail_out; + + if (fwrite(outbuf, 1, write_size, outfile) + != write_size) { + fprintf(stderr, "Write error: %s\n", + strerror(errno)); + return false; + } + + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + } + + if (ret != LZMA_OK) { + if (ret == LZMA_STREAM_END) + return true; + + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_DATA_ERROR: + msg = "File size limits exceeded"; + break; + + default: + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Encoder error: %s (error code %u)\n", + msg, ret); + return false; + } + } +} + + +extern int +main(void) +{ + lzma_stream strm = LZMA_STREAM_INIT; + + bool success = init_encoder(&strm); + if (success) + success = compress(&strm, stdin, stdout); + + lzma_end(&strm); + + if (fclose(stdout)) { + fprintf(stderr, "Write error: %s\n", strerror(errno)); + success = false; + } + + return success ? EXIT_SUCCESS : EXIT_FAILURE; +} diff --git a/doc/examples/04_compress_easy_mt.c b/doc/examples/04_compress_easy_mt.c new file mode 100644 index 0000000..efe5697 --- /dev/null +++ b/doc/examples/04_compress_easy_mt.c @@ -0,0 +1,206 @@ +/////////////////////////////////////////////////////////////////////////////// +// +/// \file 04_compress_easy_mt.c +/// \brief Compress in multi-call mode using LZMA2 in multi-threaded mode +/// +/// Usage: ./04_compress_easy_mt < INFILE > OUTFILE +/// +/// Example: ./04_compress_easy_mt < foo > foo.xz +// +// Author: Lasse Collin +// +// This file has been put into the public domain. +// You can do whatever you want with this file. +// +/////////////////////////////////////////////////////////////////////////////// + +#include +#include +#include +#include +#include +#include + + +static bool +init_encoder(lzma_stream *strm) +{ + // The threaded encoder takes the options as pointer to + // a lzma_mt structure. + lzma_mt mt = { + // No flags are needed. + .flags = 0, + + // Let liblzma determine a sane block size. + .block_size = 0, + + // Use no timeout for lzma_code() calls by setting timeout + // to zero. That is, sometimes lzma_code() might block for + // a long time (from several seconds to even minutes). + // If this is not OK, for example due to progress indicator + // needing updates, specify a timeout in milliseconds here. + // See the documentation of lzma_mt in lzma/container.h for + // information how to choose a reasonable timeout. + .timeout = 0, + + // Use the default preset (6) for LZMA2. + // To use a preset, filters must be set to NULL. + .preset = LZMA_PRESET_DEFAULT, + .filters = NULL, + + // Use CRC64 for integrity checking. See also + // 01_compress_easy.c about choosing the integrity check. + .check = LZMA_CHECK_CRC64, + }; + + // Detect how many threads the CPU supports. + mt.threads = lzma_cputhreads(); + + // If the number of CPU cores/threads cannot be detected, + // use one thread. Note that this isn't the same as the normal + // single-threaded mode as this will still split the data into + // blocks and use more RAM than the normal single-threaded mode. + // You may want to consider using lzma_easy_encoder() or + // lzma_stream_encoder() instead of lzma_stream_encoder_mt() if + // lzma_cputhreads() returns 0 or 1. + if (mt.threads == 0) + mt.threads = 1; + + // If the number of CPU cores/threads exceeds threads_max, + // limit the number of threads to keep memory usage lower. + // The number 8 is arbitrarily chosen and may be too low or + // high depending on the compression preset and the computer + // being used. + // + // FIXME: A better way could be to check the amount of RAM + // (or available RAM) and use lzma_stream_encoder_mt_memusage() + // to determine if the number of threads should be reduced. + const uint32_t threads_max = 8; + if (mt.threads > threads_max) + mt.threads = threads_max; + + // Initialize the threaded encoder. + lzma_ret ret = lzma_stream_encoder_mt(strm, &mt); + + if (ret == LZMA_OK) + return true; + + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_OPTIONS_ERROR: + // We are no longer using a plain preset so this error + // message has been edited accordingly compared to + // 01_compress_easy.c. + msg = "Specified filter chain is not supported"; + break; + + case LZMA_UNSUPPORTED_CHECK: + msg = "Specified integrity check is not supported"; + break; + + default: + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Error initializing the encoder: %s (error code %u)\n", + msg, ret); + return false; +} + + +// This function is identical to the one in 01_compress_easy.c. +static bool +compress(lzma_stream *strm, FILE *infile, FILE *outfile) +{ + lzma_action action = LZMA_RUN; + + uint8_t inbuf[BUFSIZ]; + uint8_t outbuf[BUFSIZ]; + + strm->next_in = NULL; + strm->avail_in = 0; + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + + while (true) { + if (strm->avail_in == 0 && !feof(infile)) { + strm->next_in = inbuf; + strm->avail_in = fread(inbuf, 1, sizeof(inbuf), + infile); + + if (ferror(infile)) { + fprintf(stderr, "Read error: %s\n", + strerror(errno)); + return false; + } + + if (feof(infile)) + action = LZMA_FINISH; + } + + lzma_ret ret = lzma_code(strm, action); + + if (strm->avail_out == 0 || ret == LZMA_STREAM_END) { + size_t write_size = sizeof(outbuf) - strm->avail_out; + + if (fwrite(outbuf, 1, write_size, outfile) + != write_size) { + fprintf(stderr, "Write error: %s\n", + strerror(errno)); + return false; + } + + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + } + + if (ret != LZMA_OK) { + if (ret == LZMA_STREAM_END) + return true; + + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_DATA_ERROR: + msg = "File size limits exceeded"; + break; + + default: + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Encoder error: %s (error code %u)\n", + msg, ret); + return false; + } + } +} + + +extern int +main(void) +{ + lzma_stream strm = LZMA_STREAM_INIT; + + bool success = init_encoder(&strm); + if (success) + success = compress(&strm, stdin, stdout); + + lzma_end(&strm); + + if (fclose(stdout)) { + fprintf(stderr, "Write error: %s\n", strerror(errno)); + success = false; + } + + return success ? EXIT_SUCCESS : EXIT_FAILURE; +} diff --git a/doc/examples/Makefile b/doc/examples/Makefile new file mode 100644 index 0000000..e8839d8 --- /dev/null +++ b/doc/examples/Makefile @@ -0,0 +1,25 @@ +# +# Author: Lasse Collin +# +# This file has been put into the public domain. +# You can do whatever you want with this file. +# + +CC = c99 +CFLAGS = -g +LDFLAGS = -llzma + +PROGS = \ + 01_compress_easy \ + 02_decompress \ + 03_compress_custom \ + 04_compress_easy_mt \ + 11_file_info + +all: $(PROGS) + +.c: + $(CC) $(CFLAGS) -o $@ $< $(LDFLAGS) + +clean: + -rm -f $(PROGS) diff --git a/doc/examples_old/xz_pipe_comp.c b/doc/examples_old/xz_pipe_comp.c new file mode 100644 index 0000000..9f9224b --- /dev/null +++ b/doc/examples_old/xz_pipe_comp.c @@ -0,0 +1,127 @@ +/* + * xz_pipe_comp.c + * A simple example of pipe-only xz compressor implementation. + * version: 2010-07-12 - by Daniel Mealha Cabrita + * Not copyrighted -- provided to the public domain. + * + * Compiling: + * Link with liblzma. GCC example: + * $ gcc -llzma xz_pipe_comp.c -o xz_pipe_comp + * + * Usage example: + * $ cat some_file | ./xz_pipe_comp > some_file.xz + */ + +#include +#include +#include +#include +#include + + +/* COMPRESSION SETTINGS */ + +/* analogous to xz CLI options: -0 to -9 */ +#define COMPRESSION_LEVEL 6 + +/* boolean setting, analogous to xz CLI option: -e */ +#define COMPRESSION_EXTREME true + +/* see: /usr/include/lzma/check.h LZMA_CHECK_* */ +#define INTEGRITY_CHECK LZMA_CHECK_CRC64 + + +/* read/write buffer sizes */ +#define IN_BUF_MAX 4096 +#define OUT_BUF_MAX 4096 + +/* error codes */ +#define RET_OK 0 +#define RET_ERROR_INIT 1 +#define RET_ERROR_INPUT 2 +#define RET_ERROR_OUTPUT 3 +#define RET_ERROR_COMPRESSION 4 + + +/* note: in_file and out_file must be open already */ +int xz_compress (FILE *in_file, FILE *out_file) +{ + uint32_t preset = COMPRESSION_LEVEL | (COMPRESSION_EXTREME ? LZMA_PRESET_EXTREME : 0); + lzma_check check = INTEGRITY_CHECK; + lzma_stream strm = LZMA_STREAM_INIT; /* alloc and init lzma_stream struct */ + uint8_t in_buf [IN_BUF_MAX]; + uint8_t out_buf [OUT_BUF_MAX]; + size_t in_len; /* length of useful data in in_buf */ + size_t out_len; /* length of useful data in out_buf */ + bool in_finished = false; + bool out_finished = false; + lzma_action action; + lzma_ret ret_xz; + int ret; + + ret = RET_OK; + + /* initialize xz encoder */ + ret_xz = lzma_easy_encoder (&strm, preset, check); + if (ret_xz != LZMA_OK) { + fprintf (stderr, "lzma_easy_encoder error: %d\n", (int) ret_xz); + return RET_ERROR_INIT; + } + + while ((! in_finished) && (! out_finished)) { + /* read incoming data */ + in_len = fread (in_buf, 1, IN_BUF_MAX, in_file); + + if (feof (in_file)) { + in_finished = true; + } + if (ferror (in_file)) { + in_finished = true; + ret = RET_ERROR_INPUT; + } + + strm.next_in = in_buf; + strm.avail_in = in_len; + + /* if no more data from in_buf, flushes the + internal xz buffers and closes the xz data + with LZMA_FINISH */ + action = in_finished ? LZMA_FINISH : LZMA_RUN; + + /* loop until there's no pending compressed output */ + do { + /* out_buf is clean at this point */ + strm.next_out = out_buf; + strm.avail_out = OUT_BUF_MAX; + + /* compress data */ + ret_xz = lzma_code (&strm, action); + + if ((ret_xz != LZMA_OK) && (ret_xz != LZMA_STREAM_END)) { + fprintf (stderr, "lzma_code error: %d\n", (int) ret_xz); + out_finished = true; + ret = RET_ERROR_COMPRESSION; + } else { + /* write compressed data */ + out_len = OUT_BUF_MAX - strm.avail_out; + fwrite (out_buf, 1, out_len, out_file); + if (ferror (out_file)) { + out_finished = true; + ret = RET_ERROR_OUTPUT; + } + } + } while (strm.avail_out == 0); + } + + lzma_end (&strm); + return ret; +} + +int main () +{ + int ret; + + ret = xz_compress (stdin, stdout); + return ret; +} + diff --git a/doc/examples_old/xz_pipe_decomp.c b/doc/examples_old/xz_pipe_decomp.c new file mode 100644 index 0000000..fb5ad89 --- /dev/null +++ b/doc/examples_old/xz_pipe_decomp.c @@ -0,0 +1,123 @@ +/* + * xz_pipe_decomp.c + * A simple example of pipe-only xz decompressor implementation. + * version: 2012-06-14 - by Daniel Mealha Cabrita + * Not copyrighted -- provided to the public domain. + * + * Compiling: + * Link with liblzma. GCC example: + * $ gcc -llzma xz_pipe_decomp.c -o xz_pipe_decomp + * + * Usage example: + * $ cat some_file.xz | ./xz_pipe_decomp > some_file + */ + +#include +#include +#include +#include +#include + + +/* read/write buffer sizes */ +#define IN_BUF_MAX 4096 +#define OUT_BUF_MAX 4096 + +/* error codes */ +#define RET_OK 0 +#define RET_ERROR_INIT 1 +#define RET_ERROR_INPUT 2 +#define RET_ERROR_OUTPUT 3 +#define RET_ERROR_DECOMPRESSION 4 + + +/* note: in_file and out_file must be open already */ +int xz_decompress (FILE *in_file, FILE *out_file) +{ + lzma_stream strm = LZMA_STREAM_INIT; /* alloc and init lzma_stream struct */ + const uint32_t flags = LZMA_TELL_UNSUPPORTED_CHECK | LZMA_CONCATENATED; + const uint64_t memory_limit = UINT64_MAX; /* no memory limit */ + uint8_t in_buf [IN_BUF_MAX]; + uint8_t out_buf [OUT_BUF_MAX]; + size_t in_len; /* length of useful data in in_buf */ + size_t out_len; /* length of useful data in out_buf */ + bool in_finished = false; + bool out_finished = false; + lzma_action action; + lzma_ret ret_xz; + int ret; + + ret = RET_OK; + + /* initialize xz decoder */ + ret_xz = lzma_stream_decoder (&strm, memory_limit, flags); + if (ret_xz != LZMA_OK) { + fprintf (stderr, "lzma_stream_decoder error: %d\n", (int) ret_xz); + return RET_ERROR_INIT; + } + + while ((! in_finished) && (! out_finished)) { + /* read incoming data */ + in_len = fread (in_buf, 1, IN_BUF_MAX, in_file); + + if (feof (in_file)) { + in_finished = true; + } + if (ferror (in_file)) { + in_finished = true; + ret = RET_ERROR_INPUT; + } + + strm.next_in = in_buf; + strm.avail_in = in_len; + + /* if no more data from in_buf, flushes the + internal xz buffers and closes the decompressed data + with LZMA_FINISH */ + action = in_finished ? LZMA_FINISH : LZMA_RUN; + + /* loop until there's no pending decompressed output */ + do { + /* out_buf is clean at this point */ + strm.next_out = out_buf; + strm.avail_out = OUT_BUF_MAX; + + /* decompress data */ + ret_xz = lzma_code (&strm, action); + + if ((ret_xz != LZMA_OK) && (ret_xz != LZMA_STREAM_END)) { + fprintf (stderr, "lzma_code error: %d\n", (int) ret_xz); + out_finished = true; + ret = RET_ERROR_DECOMPRESSION; + } else { + /* write decompressed data */ + out_len = OUT_BUF_MAX - strm.avail_out; + fwrite (out_buf, 1, out_len, out_file); + if (ferror (out_file)) { + out_finished = true; + ret = RET_ERROR_OUTPUT; + } + } + } while (strm.avail_out == 0); + } + + /* Bug fix (2012-06-14): If no errors were detected, check + that the last lzma_code() call returned LZMA_STREAM_END. + If not, the file is probably truncated. */ + if ((ret == RET_OK) && (ret_xz != LZMA_STREAM_END)) { + fprintf (stderr, "Input truncated or corrupt\n"); + ret = RET_ERROR_DECOMPRESSION; + } + + lzma_end (&strm); + return ret; +} + +int main () +{ + int ret; + + ret = xz_decompress (stdin, stdout); + return ret; +} + diff --git a/doc/faq.txt b/doc/faq.txt new file mode 100644 index 0000000..3f9068b --- /dev/null +++ b/doc/faq.txt @@ -0,0 +1,244 @@ + +XZ Utils FAQ +============ + +Q: What do the letters XZ mean? + +A: Nothing. They are just two letters, which come from the file format + suffix .xz. The .xz suffix was selected, because it seemed to be + pretty much unused. It has no deeper meaning. + + +Q: What are LZMA and LZMA2? + +A: LZMA stands for Lempel-Ziv-Markov chain-Algorithm. It is the name + of the compression algorithm designed by Igor Pavlov for 7-Zip. + LZMA is based on LZ77 and range encoding. + + LZMA2 is an updated version of the original LZMA to fix a couple of + practical issues. In context of XZ Utils, LZMA is called LZMA1 to + emphasize that LZMA is not the same thing as LZMA2. LZMA2 is the + primary compression algorithm in the .xz file format. + + +Q: There are many LZMA related projects. How does XZ Utils relate to them? + +A: 7-Zip and LZMA SDK are the original projects. LZMA SDK is roughly + a subset of the 7-Zip source tree. + + p7zip is 7-Zip's command-line tools ported to POSIX-like systems. + + LZMA Utils provide a gzip-like lzma tool for POSIX-like systems. + LZMA Utils are based on LZMA SDK. XZ Utils are the successor to + LZMA Utils. + + There are several other projects using LZMA. Most are more or less + based on LZMA SDK. See . + + +Q: Why is liblzma named liblzma if its primary file format is .xz? + Shouldn't it be e.g. libxz? + +A: When the designing of the .xz format began, the idea was to replace + the .lzma format and use the same .lzma suffix. It would have been + quite OK to reuse the suffix when there were very few .lzma files + around. However, the old .lzma format became popular before the + new format was finished. The new format was renamed to .xz but the + name of liblzma wasn't changed. + + +Q: Do XZ Utils support the .7z format? + +A: No. Use 7-Zip (Windows) or p7zip (POSIX-like systems) to handle .7z + files. + + +Q: I have many .tar.7z files. Can I convert them to .tar.xz without + spending hours recompressing the data? + +A: In the "extra" directory, there is a script named 7z2lzma.bash which + is able to convert some .7z files to the .lzma format (not .xz). It + needs the 7za (or 7z) command from p7zip. The script may silently + produce corrupt output if certain assumptions are not met, so + decompress the resulting .lzma file and compare it against the + original before deleting the original file! + + +Q: I have many .lzma files. Can I quickly convert them to the .xz format? + +A: For now, no. Since XZ Utils supports the .lzma format, it's usually + not too bad to keep the old files in the old format. If you want to + do the conversion anyway, you need to decompress the .lzma files and + then recompress to the .xz format. + + Technically, there is a way to make the conversion relatively fast + (roughly twice the time that normal decompression takes). Writing + such a tool would take quite a bit of time though, and would probably + be useful to only a few people. If you really want such a conversion + tool, contact Lasse Collin and offer some money. + + +Q: I have installed xz, but my tar doesn't recognize .tar.xz files. + How can I extract .tar.xz files? + +A: xz -dc foo.tar.xz | tar xf - + + +Q: Can I recover parts of a broken .xz file (e.g. a corrupted CD-R)? + +A: It may be possible if the file consists of multiple blocks, which + typically is not the case if the file was created in single-threaded + mode. There is no recovery program yet. + + +Q: Is (some part of) XZ Utils patented? + +A: Lasse Collin is not aware of any patents that could affect XZ Utils. + However, due to the nature of software patents, it's not possible to + guarantee that XZ Utils isn't affected by any third party patent(s). + + +Q: Where can I find documentation about the file format and algorithms? + +A: The .xz format is documented in xz-file-format.txt. It is a container + format only, and doesn't include descriptions of any non-trivial + filters. + + Documenting LZMA and LZMA2 is planned, but for now, there is no other + documentation than the source code. Before you begin, you should know + the basics of LZ77 and range-coding algorithms. LZMA is based on LZ77, + but LZMA is a lot more complex. Range coding is used to compress + the final bitstream like Huffman coding is used in Deflate. + + +Q: I cannot find BCJ and BCJ2 filters. Don't they exist in liblzma? + +A: BCJ filter is called "x86" in liblzma. BCJ2 is not included, + because it requires using more than one encoded output stream. + + +Q: I need to use a script that runs "xz -9". On a system with 256 MiB + of RAM, xz says that it cannot allocate memory. Can I make the + script work without modifying it? + +A: Set a default memory usage limit for compression. You can do it e.g. + in a shell initialization script such as ~/.bashrc or /etc/profile: + + XZ_DEFAULTS=--memlimit-compress=150MiB + export XZ_DEFAULTS + + xz will then scale the compression settings down so that the given + memory usage limit is not reached. This way xz shouldn't run out + of memory. + + Check also that memory-related resource limits are high enough. + On most systems, "ulimit -a" will show the current resource limits. + + +Q: How do I create files that can be decompressed with XZ Embedded? + +A: See the documentation in XZ Embedded. In short, something like + this is a good start: + + xz --check=crc32 --lzma2=preset=6e,dict=64KiB + + Or if a BCJ filter is needed too, e.g. if compressing + a kernel image for PowerPC: + + xz --check=crc32 --powerpc --lzma2=preset=6e,dict=64KiB + + Adjust the dictionary size to get a good compromise between + compression ratio and decompressor memory usage. Note that + in single-call decompression mode of XZ Embedded, a big + dictionary doesn't increase memory usage. + + +Q: How is multi-threaded compression implemented in XZ Utils? + +A: The simplest method is splitting the uncompressed data into blocks + and compressing them in parallel independent from each other. + This is currently the only threading method supported in XZ Utils. + Since the blocks are compressed independently, they can also be + decompressed independently. Together with the index feature in .xz, + this allows using threads to create .xz files for random-access + reading. This also makes threaded decompression possible. + + The independent blocks method has a couple of disadvantages too. It + will compress worse than a single-block method. Often the difference + is not too big (maybe 1-2 %) but sometimes it can be too big. Also, + the memory usage of the compressor increases linearly when adding + threads. + + At least two other threading methods are possible but these haven't + been implemented in XZ Utils: + + Match finder parallelization has been in 7-Zip for ages. It doesn't + affect compression ratio or memory usage significantly. Among the + three threading methods, only this is useful when compressing small + files (files that are not significantly bigger than the dictionary). + Unfortunately this method scales only to about two CPU cores. + + The third method is pigz-style threading (I use that name, because + pigz uses that method). It doesn't + affect compression ratio significantly and scales to many cores. + The memory usage scales linearly when threads are added. This isn't + significant with pigz, because Deflate uses only a 32 KiB dictionary, + but with LZMA2 the memory usage will increase dramatically just like + with the independent-blocks method. There is also a constant + computational overhead, which may make pigz-method a bit dull on + dual-core compared to the parallel match finder method, but with more + cores the overhead is not a big deal anymore. + + Combining the threading methods will be possible and also useful. + For example, combining match finder parallelization with pigz-style + threading or independent-blocks-threading can cut the memory usage + by 50 %. + + +Q: I told xz to use many threads but it is using only one or two + processor cores. What is wrong? + +A: Since multi-threaded compression is done by splitting the data into + blocks that are compressed individually, if the input file is too + small for the block size, then many threads cannot be used. The + default block size increases when the compression level is + increased. For example, xz -6 uses 8 MiB LZMA2 dictionary and + 24 MiB blocks, and xz -9 uses 64 MiB LZMA dictionary and 192 MiB + blocks. If the input file is 100 MiB, xz -6 can use five threads + of which one will finish quickly as it has only 4 MiB to compress. + However, for the same file, xz -9 can only use one thread. + + One can adjust block size with --block-size=SIZE but making the + block size smaller than LZMA2 dictionary is waste of RAM: using + xz -9 with 6 MiB blocks isn't any better than using xz -6 with + 6 MiB blocks. The default settings use a block size bigger than + the LZMA2 dictionary size because this was seen as a reasonable + compromise between RAM usage and compression ratio. + + When decompressing, the ability to use threads depends on how the + file was created. If it was created in multi-threaded mode then + it can be decompressed in multi-threaded mode too if there are + multiple blocks in the file. + + +Q: How do I build a program that needs liblzmadec (lzmadec.h)? + +A: liblzmadec is part of LZMA Utils. XZ Utils has liblzma, but no + liblzmadec. The code using liblzmadec should be ported to use + liblzma instead. If you cannot or don't want to do that, download + LZMA Utils from . + + +Q: The default build of liblzma is too big. How can I make it smaller? + +A: Give --enable-small to the configure script. Use also appropriate + --enable or --disable options to include only those filter encoders + and decoders and integrity checks that you actually need. Use + CFLAGS=-Os (with GCC) or equivalent to tell your compiler to optimize + for size. See INSTALL for information about configure options. + + If the result is still too big, take a look at XZ Embedded. It is + a separate project, which provides a limited but significantly + smaller XZ decoder implementation than XZ Utils. You can find it + at . + diff --git a/doc/history.txt b/doc/history.txt new file mode 100644 index 0000000..8545e23 --- /dev/null +++ b/doc/history.txt @@ -0,0 +1,150 @@ + +History of LZMA Utils and XZ Utils +================================== + +Tukaani distribution + + In 2005, there was a small group working on the Tukaani distribution, + which was a Slackware fork. One of the project's goals was to fit the + distro on a single 700 MiB ISO-9660 image. Using LZMA instead of gzip + helped a lot. Roughly speaking, one could fit data that took 1000 MiB + in gzipped form into 700 MiB with LZMA. Naturally, the compression + ratio varied across packages, but this was what we got on average. + + Slackware packages have traditionally had .tgz as the filename suffix, + which is an abbreviation of .tar.gz. A logical naming for LZMA + compressed packages was .tlz, being an abbreviation of .tar.lzma. + + At the end of the year 2007, there was no distribution under the + Tukaani project anymore, but development of LZMA Utils was kept going. + Still, there were .tlz packages around, because at least Vector Linux + (a Slackware based distribution) used LZMA for its packages. + + First versions of the modified pkgtools used the LZMA_Alone tool from + Igor Pavlov's LZMA SDK as is. It was fine, because users wouldn't need + to interact with LZMA_Alone directly. But people soon wanted to use + LZMA for other files too, and the interface of LZMA_Alone wasn't + comfortable for those used to gzip and bzip2. + + +First steps of LZMA Utils + + The first version of LZMA Utils (4.22.0) included a shell script called + lzmash. It was a wrapper that had a gzip-like command-line interface. It + used the LZMA_Alone tool from LZMA SDK to do all the real work. zgrep, + zdiff, and related scripts from gzip were adapted to work with LZMA and + were part of the first LZMA Utils release too. + + LZMA Utils 4.22.0 included also lzmadec, which was a small (less than + 10 KiB) decoder-only command-line tool. It was written on top of the + decoder-only C code found from the LZMA SDK. lzmadec was convenient in + situations where LZMA_Alone (a few hundred KiB) would be too big. + + lzmash and lzmadec were written by Lasse Collin. + + +Second generation + + The lzmash script was an ugly and not very secure hack. The last + version of LZMA Utils to use lzmash was 4.27.1. + + LZMA Utils 4.32.0beta1 introduced a new lzma command-line tool written + by Ville Koskinen. It was written in C++, and used the encoder and + decoder from C++ LZMA SDK with some little modifications. This tool + replaced both the lzmash script and the LZMA_Alone command-line tool + in LZMA Utils. + + Introducing this new tool caused some temporary incompatibilities, + because the LZMA_Alone executable was simply named lzma like the new + command-line tool, but they had a completely different command-line + interface. The file format was still the same. + + Lasse wrote liblzmadec, which was a small decoder-only library based + on the C code found from LZMA SDK. liblzmadec had an API similar to + zlib, although there were some significant differences, which made it + non-trivial to use it in some applications designed for zlib and + libbzip2. + + The lzmadec command-line tool was converted to use liblzmadec. + + Alexandre Sauvé helped converting the build system to use GNU + Autotools. This made it easier to test for certain less portable + features needed by the new command-line tool. + + Since the new command-line tool never got completely finished (for + example, it didn't support the LZMA_OPT environment variable), the + intent was to not call 4.32.x stable. Similarly, liblzmadec wasn't + polished, but appeared to work well enough, so some people started + using it too. + + Because the development of the third generation of LZMA Utils was + delayed considerably (3-4 years), the 4.32.x branch had to be kept + maintained. It got some bug fixes now and then, and finally it was + decided to call it stable, although most of the missing features were + never added. + + +File format problems + + The file format used by LZMA_Alone was primitive. It was designed with + embedded systems in mind, and thus provided only a minimal set of + features. The two biggest problems for non-embedded use were the lack + of magic bytes and an integrity check. + + Igor and Lasse started developing a new file format with some help + from Ville Koskinen. Also Mark Adler, Mikko Pouru, H. Peter Anvin, + and Lars Wirzenius helped with some minor things at some point of the + development. Designing the new format took quite a long time (actually, + too long a time would be a more appropriate expression). It was mostly + because Lasse was quite slow at getting things done due to personal + reasons. + + Originally the new format was supposed to use the same .lzma suffix + that was already used by the old file format. Switching to the new + format wouldn't have caused much trouble when the old format wasn't + used by many people. But since the development of the new format took + such a long time, the old format got quite popular, and it was decided + that the new file format must use a different suffix. + + It was decided to use .xz as the suffix of the new file format. The + first stable .xz file format specification was finally released in + December 2008. In addition to fixing the most obvious problems of + the old .lzma format, the .xz format added some new features like + support for multiple filters (compression algorithms), filter chaining + (like piping on the command line), and limited random-access reading. + + Currently the primary compression algorithm used in .xz is LZMA2. + It is an extension on top of the original LZMA to fix some practical + problems: LZMA2 adds support for flushing the encoder, uncompressed + chunks, eases stateful decoder implementations, and improves support + for multithreading. Since LZMA2 is better than the original LZMA, the + original LZMA is not supported in .xz. + + +Transition to XZ Utils + + The early versions of XZ Utils were called LZMA Utils. The first + releases were 4.42.0alphas. They dropped the rest of the C++ LZMA SDK. + The code was still directly based on LZMA SDK but ported to C and + converted from a callback API to a stateful API. Later, Igor Pavlov + made a C version of the LZMA encoder too; these ports from C++ to C + were independent in LZMA SDK and LZMA Utils. + + The core of the new LZMA Utils was liblzma, a compression library with + a zlib-like API. liblzma supported both the old and new file format. + The gzip-like lzma command-line tool was rewritten to use liblzma. + + The new LZMA Utils code base was renamed to XZ Utils when the name + of the new file format had been decided. The liblzma compression + library retained its name though, because changing it would have + caused unnecessary breakage in applications already using the early + liblzma snapshots. + + The xz command-line tool can emulate the gzip-like lzma tool by + creating appropriate symlinks (e.g. lzma -> xz). Thus, practically + all scripts using the lzma tool from LZMA Utils will work as is with + XZ Utils (and will keep using the old .lzma format). Still, the .lzma + format is more or less deprecated. XZ Utils will keep supporting it, + but new applications should use the .xz format, and migrating old + applications to .xz is often a good idea too. + diff --git a/doc/lzma-file-format.txt b/doc/lzma-file-format.txt new file mode 100644 index 0000000..4865def --- /dev/null +++ b/doc/lzma-file-format.txt @@ -0,0 +1,173 @@ + +The .lzma File Format +===================== + + 0. Preface + 0.1. Notices and Acknowledgements + 0.2. Changes + 1. File Format + 1.1. Header + 1.1.1. Properties + 1.1.2. Dictionary Size + 1.1.3. Uncompressed Size + 1.2. LZMA Compressed Data + 2. References + + +0. Preface + + This document describes the .lzma file format, which is + sometimes also called LZMA_Alone format. It is a legacy file + format, which is being or has been replaced by the .xz format. + The MIME type of the .lzma format is `application/x-lzma'. + + The most commonly used software to handle .lzma files are + LZMA SDK, LZMA Utils, 7-Zip, and XZ Utils. This document + describes some of the differences between these implementations + and gives hints what subset of the .lzma format is the most + portable. + + +0.1. Notices and Acknowledgements + + This file format was designed by Igor Pavlov for use in + LZMA SDK. This document was written by Lasse Collin + using the documentation found + from the LZMA SDK. + + This document has been put into the public domain. + + +0.2. Changes + + Last modified: 2022-07-13 21:00+0300 + + Compared to the previous version (2011-04-12 11:55+0300) + the section 1.1.3 was modified to allow End of Payload Marker + with a known Uncompressed Size. + + +1. File Format + + +-+-+-+-+-+-+-+-+-+-+-+-+-+==========================+ + | Header | LZMA Compressed Data | + +-+-+-+-+-+-+-+-+-+-+-+-+-+==========================+ + + The .lzma format file consist of 13-byte Header followed by + the LZMA Compressed Data. + + Unlike the .gz, .bz2, and .xz formats, it is not possible to + concatenate multiple .lzma files as is and expect the + decompression tool to decode the resulting file as if it were + a single .lzma file. + + For example, the command line tools from LZMA Utils and + LZMA SDK silently ignore all the data after the first .lzma + stream. In contrast, the command line tool from XZ Utils + considers the .lzma file to be corrupt if there is data after + the first .lzma stream. + + +1.1. Header + + +------------+----+----+----+----+--+--+--+--+--+--+--+--+ + | Properties | Dictionary Size | Uncompressed Size | + +------------+----+----+----+----+--+--+--+--+--+--+--+--+ + + +1.1.1. Properties + + The Properties field contains three properties. An abbreviation + is given in parentheses, followed by the value range of the + property. The field consists of + + 1) the number of literal context bits (lc, [0, 8]); + 2) the number of literal position bits (lp, [0, 4]); and + 3) the number of position bits (pb, [0, 4]). + + The properties are encoded using the following formula: + + Properties = (pb * 5 + lp) * 9 + lc + + The following C code illustrates a straightforward way to + decode the Properties field: + + uint8_t lc, lp, pb; + uint8_t prop = get_lzma_properties(); + if (prop > (4 * 5 + 4) * 9 + 8) + return LZMA_PROPERTIES_ERROR; + + pb = prop / (9 * 5); + prop -= pb * 9 * 5; + lp = prop / 9; + lc = prop - lp * 9; + + XZ Utils has an additional requirement: lc + lp <= 4. Files + which don't follow this requirement cannot be decompressed + with XZ Utils. Usually this isn't a problem since the most + common lc/lp/pb values are 3/0/2. It is the only lc/lp/pb + combination that the files created by LZMA Utils can have, + but LZMA Utils can decompress files with any lc/lp/pb. + + +1.1.2. Dictionary Size + + Dictionary Size is stored as an unsigned 32-bit little endian + integer. Any 32-bit value is possible, but for maximum + portability, only sizes of 2^n and 2^n + 2^(n-1) should be + used. + + LZMA Utils creates only files with dictionary size 2^n, + 16 <= n <= 25. LZMA Utils can decompress files with any + dictionary size. + + XZ Utils creates and decompresses .lzma files only with + dictionary sizes 2^n and 2^n + 2^(n-1). If some other + dictionary size is specified when compressing, the value + stored in the Dictionary Size field is a rounded up, but the + specified value is still used in the actual compression code. + + +1.1.3. Uncompressed Size + + Uncompressed Size is stored as unsigned 64-bit little endian + integer. A special value of 0xFFFF_FFFF_FFFF_FFFF indicates + that Uncompressed Size is unknown. End of Payload Marker (*) + is used if Uncompressed Size is unknown. End of Payload Marker + is allowed but rarely used if Uncompressed Size is known. + XZ Utils 5.2.5 and older don't support .lzma files that have + End of Payload Marker together with a known Uncompressed Size. + + XZ Utils rejects files whose Uncompressed Size field specifies + a known size that is 256 GiB or more. This is to reject false + positives when trying to guess if the input file is in the + .lzma format. When Uncompressed Size is unknown, there is no + limit for the uncompressed size of the file. + + (*) Some tools use the term End of Stream (EOS) marker + instead of End of Payload Marker. + + +1.2. LZMA Compressed Data + + Detailed description of the format of this field is out of + scope of this document. + + +2. References + + LZMA SDK - The original LZMA implementation + http://7-zip.org/sdk.html + + 7-Zip + http://7-zip.org/ + + LZMA Utils - LZMA adapted to POSIX-like systems + http://tukaani.org/lzma/ + + XZ Utils - The next generation of LZMA Utils + http://tukaani.org/xz/ + + The .xz file format - The successor of the .lzma format + http://tukaani.org/xz/xz-file-format.txt + diff --git a/doc/man/pdf-a4/lzmainfo-a4.pdf b/doc/man/pdf-a4/lzmainfo-a4.pdf new file mode 100644 index 0000000..0ee526f Binary files /dev/null and b/doc/man/pdf-a4/lzmainfo-a4.pdf differ diff --git a/doc/man/pdf-a4/xz-a4.pdf b/doc/man/pdf-a4/xz-a4.pdf new file mode 100644 index 0000000..5f1a30c Binary files /dev/null and b/doc/man/pdf-a4/xz-a4.pdf differ diff --git a/doc/man/pdf-a4/xzdec-a4.pdf b/doc/man/pdf-a4/xzdec-a4.pdf new file mode 100644 index 0000000..35f2059 Binary files /dev/null and b/doc/man/pdf-a4/xzdec-a4.pdf differ diff --git a/doc/man/pdf-a4/xzdiff-a4.pdf b/doc/man/pdf-a4/xzdiff-a4.pdf new file mode 100644 index 0000000..1189d84 Binary files /dev/null and b/doc/man/pdf-a4/xzdiff-a4.pdf differ diff --git a/doc/man/pdf-a4/xzgrep-a4.pdf b/doc/man/pdf-a4/xzgrep-a4.pdf new file mode 100644 index 0000000..2cb3528 Binary files /dev/null and b/doc/man/pdf-a4/xzgrep-a4.pdf differ diff --git a/doc/man/pdf-a4/xzless-a4.pdf b/doc/man/pdf-a4/xzless-a4.pdf new file mode 100644 index 0000000..4a8e8e6 Binary files /dev/null and b/doc/man/pdf-a4/xzless-a4.pdf differ diff --git a/doc/man/pdf-a4/xzmore-a4.pdf b/doc/man/pdf-a4/xzmore-a4.pdf new file mode 100644 index 0000000..687074b Binary files /dev/null and b/doc/man/pdf-a4/xzmore-a4.pdf differ diff --git a/doc/man/pdf-letter/lzmainfo-letter.pdf b/doc/man/pdf-letter/lzmainfo-letter.pdf new file mode 100644 index 0000000..d953045 Binary files /dev/null and b/doc/man/pdf-letter/lzmainfo-letter.pdf differ diff --git a/doc/man/pdf-letter/xz-letter.pdf b/doc/man/pdf-letter/xz-letter.pdf new file mode 100644 index 0000000..440f294 Binary files /dev/null and b/doc/man/pdf-letter/xz-letter.pdf differ diff --git a/doc/man/pdf-letter/xzdec-letter.pdf b/doc/man/pdf-letter/xzdec-letter.pdf new file mode 100644 index 0000000..83c6bb2 Binary files /dev/null and b/doc/man/pdf-letter/xzdec-letter.pdf differ diff --git a/doc/man/pdf-letter/xzdiff-letter.pdf b/doc/man/pdf-letter/xzdiff-letter.pdf new file mode 100644 index 0000000..9c7ab61 Binary files /dev/null and b/doc/man/pdf-letter/xzdiff-letter.pdf differ diff --git a/doc/man/pdf-letter/xzgrep-letter.pdf b/doc/man/pdf-letter/xzgrep-letter.pdf new file mode 100644 index 0000000..8303764 Binary files /dev/null and b/doc/man/pdf-letter/xzgrep-letter.pdf differ diff --git a/doc/man/pdf-letter/xzless-letter.pdf b/doc/man/pdf-letter/xzless-letter.pdf new file mode 100644 index 0000000..9a8e231 Binary files /dev/null and b/doc/man/pdf-letter/xzless-letter.pdf differ diff --git a/doc/man/pdf-letter/xzmore-letter.pdf b/doc/man/pdf-letter/xzmore-letter.pdf new file mode 100644 index 0000000..ef60bbc Binary files /dev/null and b/doc/man/pdf-letter/xzmore-letter.pdf differ diff --git a/doc/man/txt/lzmainfo.txt b/doc/man/txt/lzmainfo.txt new file mode 100644 index 0000000..fa4e51c --- /dev/null +++ b/doc/man/txt/lzmainfo.txt @@ -0,0 +1,40 @@ +LZMAINFO(1) XZ Utils LZMAINFO(1) + + + +NAME + lzmainfo - show information stored in the .lzma file header + +SYNOPSIS + lzmainfo [--help] [--version] [file...] + +DESCRIPTION + lzmainfo shows information stored in the .lzma file header. It reads + the first 13 bytes from the specified file, decodes the header, and + prints it to standard output in human readable format. If no files are + given or file is -, standard input is read. + + Usually the most interesting information is the uncompressed size and + the dictionary size. Uncompressed size can be shown only if the file + is in the non-streamed .lzma format variant. The amount of memory re- + quired to decompress the file is a few dozen kilobytes plus the dictio- + nary size. + + lzmainfo is included in XZ Utils primarily for backward compatibility + with LZMA Utils. + +EXIT STATUS + 0 All is good. + + 1 An error occurred. + +BUGS + lzmainfo uses MB while the correct suffix would be MiB (2^20 bytes). + This is to keep the output compatible with LZMA Utils. + +SEE ALSO + xz(1) + + + +Tukaani 2013-06-30 LZMAINFO(1) diff --git a/doc/man/txt/xz.txt b/doc/man/txt/xz.txt new file mode 100644 index 0000000..4fec85b --- /dev/null +++ b/doc/man/txt/xz.txt @@ -0,0 +1,1586 @@ +XZ(1) XZ Utils XZ(1) + + + +NAME + xz, unxz, xzcat, lzma, unlzma, lzcat - Compress or decompress .xz and + .lzma files + +SYNOPSIS + xz [option...] [file...] + +COMMAND ALIASES + unxz is equivalent to xz --decompress. + xzcat is equivalent to xz --decompress --stdout. + lzma is equivalent to xz --format=lzma. + unlzma is equivalent to xz --format=lzma --decompress. + lzcat is equivalent to xz --format=lzma --decompress --stdout. + + When writing scripts that need to decompress files, it is recommended + to always use the name xz with appropriate arguments (xz -d or xz -dc) + instead of the names unxz and xzcat. + +DESCRIPTION + xz is a general-purpose data compression tool with command line syntax + similar to gzip(1) and bzip2(1). The native file format is the .xz + format, but the legacy .lzma format used by LZMA Utils and raw com- + pressed streams with no container format headers are also supported. + In addition, decompression of the .lz format used by lzip is supported. + + xz compresses or decompresses each file according to the selected oper- + ation mode. If no files are given or file is -, xz reads from standard + input and writes the processed data to standard output. xz will refuse + (display an error and skip the file) to write compressed data to stan- + dard output if it is a terminal. Similarly, xz will refuse to read + compressed data from standard input if it is a terminal. + + Unless --stdout is specified, files other than - are written to a new + file whose name is derived from the source file name: + + o When compressing, the suffix of the target file format (.xz or + .lzma) is appended to the source filename to get the target file- + name. + + o When decompressing, the .xz, .lzma, or .lz suffix is removed from + the filename to get the target filename. xz also recognizes the + suffixes .txz and .tlz, and replaces them with the .tar suffix. + + If the target file already exists, an error is displayed and the file + is skipped. + + Unless writing to standard output, xz will display a warning and skip + the file if any of the following applies: + + o File is not a regular file. Symbolic links are not followed, and + thus they are not considered to be regular files. + + o File has more than one hard link. + + o File has setuid, setgid, or sticky bit set. + + o The operation mode is set to compress and the file already has a + suffix of the target file format (.xz or .txz when compressing to + the .xz format, and .lzma or .tlz when compressing to the .lzma for- + mat). + + o The operation mode is set to decompress and the file doesn't have a + suffix of any of the supported file formats (.xz, .txz, .lzma, .tlz, + or .lz). + + After successfully compressing or decompressing the file, xz copies the + owner, group, permissions, access time, and modification time from the + source file to the target file. If copying the group fails, the per- + missions are modified so that the target file doesn't become accessible + to users who didn't have permission to access the source file. xz + doesn't support copying other metadata like access control lists or ex- + tended attributes yet. + + Once the target file has been successfully closed, the source file is + removed unless --keep was specified. The source file is never removed + if the output is written to standard output or if an error occurs. + + Sending SIGINFO or SIGUSR1 to the xz process makes it print progress + information to standard error. This has only limited use since when + standard error is a terminal, using --verbose will display an automati- + cally updating progress indicator. + + Memory usage + The memory usage of xz varies from a few hundred kilobytes to several + gigabytes depending on the compression settings. The settings used + when compressing a file determine the memory requirements of the decom- + pressor. Typically the decompressor needs 5 % to 20 % of the amount of + memory that the compressor needed when creating the file. For example, + decompressing a file created with xz -9 currently requires 65 MiB of + memory. Still, it is possible to have .xz files that require several + gigabytes of memory to decompress. + + Especially users of older systems may find the possibility of very + large memory usage annoying. To prevent uncomfortable surprises, xz + has a built-in memory usage limiter, which is disabled by default. + While some operating systems provide ways to limit the memory usage of + processes, relying on it wasn't deemed to be flexible enough (for exam- + ple, using ulimit(1) to limit virtual memory tends to cripple mmap(2)). + + The memory usage limiter can be enabled with the command line option + --memlimit=limit. Often it is more convenient to enable the limiter by + default by setting the environment variable XZ_DEFAULTS, for example, + XZ_DEFAULTS=--memlimit=150MiB. It is possible to set the limits sepa- + rately for compression and decompression by using --memlimit-com- + press=limit and --memlimit-decompress=limit. Using these two options + outside XZ_DEFAULTS is rarely useful because a single run of xz cannot + do both compression and decompression and --memlimit=limit (or -M + limit) is shorter to type on the command line. + + If the specified memory usage limit is exceeded when decompressing, xz + will display an error and decompressing the file will fail. If the + limit is exceeded when compressing, xz will try to scale the settings + down so that the limit is no longer exceeded (except when using --for- + mat=raw or --no-adjust). This way the operation won't fail unless the + limit is very small. The scaling of the settings is done in steps that + don't match the compression level presets, for example, if the limit is + only slightly less than the amount required for xz -9, the settings + will be scaled down only a little, not all the way down to xz -8. + + Concatenation and padding with .xz files + It is possible to concatenate .xz files as is. xz will decompress such + files as if they were a single .xz file. + + It is possible to insert padding between the concatenated parts or af- + ter the last part. The padding must consist of null bytes and the size + of the padding must be a multiple of four bytes. This can be useful, + for example, if the .xz file is stored on a medium that measures file + sizes in 512-byte blocks. + + Concatenation and padding are not allowed with .lzma files or raw + streams. + +OPTIONS + Integer suffixes and special values + In most places where an integer argument is expected, an optional suf- + fix is supported to easily indicate large integers. There must be no + space between the integer and the suffix. + + KiB Multiply the integer by 1,024 (2^10). Ki, k, kB, K, and KB are + accepted as synonyms for KiB. + + MiB Multiply the integer by 1,048,576 (2^20). Mi, m, M, and MB are + accepted as synonyms for MiB. + + GiB Multiply the integer by 1,073,741,824 (2^30). Gi, g, G, and GB + are accepted as synonyms for GiB. + + The special value max can be used to indicate the maximum integer value + supported by the option. + + Operation mode + If multiple operation mode options are given, the last one takes ef- + fect. + + -z, --compress + Compress. This is the default operation mode when no operation + mode option is specified and no other operation mode is implied + from the command name (for example, unxz implies --decompress). + + -d, --decompress, --uncompress + Decompress. + + -t, --test + Test the integrity of compressed files. This option is equiva- + lent to --decompress --stdout except that the decompressed data + is discarded instead of being written to standard output. No + files are created or removed. + + -l, --list + Print information about compressed files. No uncompressed out- + put is produced, and no files are created or removed. In list + mode, the program cannot read the compressed data from standard + input or from other unseekable sources. + + The default listing shows basic information about files, one + file per line. To get more detailed information, use also the + --verbose option. For even more information, use --verbose + twice, but note that this may be slow, because getting all the + extra information requires many seeks. The width of verbose + output exceeds 80 characters, so piping the output to, for exam- + ple, less -S may be convenient if the terminal isn't wide + enough. + + The exact output may vary between xz versions and different lo- + cales. For machine-readable output, --robot --list should be + used. + + Operation modifiers + -k, --keep + Don't delete the input files. + + Since xz 5.2.6, this option also makes xz compress or decompress + even if the input is a symbolic link to a regular file, has more + than one hard link, or has the setuid, setgid, or sticky bit + set. The setuid, setgid, and sticky bits are not copied to the + target file. In earlier versions this was only done with + --force. + + -f, --force + This option has several effects: + + o If the target file already exists, delete it before compress- + ing or decompressing. + + o Compress or decompress even if the input is a symbolic link + to a regular file, has more than one hard link, or has the + setuid, setgid, or sticky bit set. The setuid, setgid, and + sticky bits are not copied to the target file. + + o When used with --decompress --stdout and xz cannot recognize + the type of the source file, copy the source file as is to + standard output. This allows xzcat --force to be used like + cat(1) for files that have not been compressed with xz. Note + that in future, xz might support new compressed file formats, + which may make xz decompress more types of files instead of + copying them as is to standard output. --format=format can + be used to restrict xz to decompress only a single file for- + mat. + + -c, --stdout, --to-stdout + Write the compressed or decompressed data to standard output in- + stead of a file. This implies --keep. + + --single-stream + Decompress only the first .xz stream, and silently ignore possi- + ble remaining input data following the stream. Normally such + trailing garbage makes xz display an error. + + xz never decompresses more than one stream from .lzma files or + raw streams, but this option still makes xz ignore the possible + trailing data after the .lzma file or raw stream. + + This option has no effect if the operation mode is not --decom- + press or --test. + + --no-sparse + Disable creation of sparse files. By default, if decompressing + into a regular file, xz tries to make the file sparse if the de- + compressed data contains long sequences of binary zeros. It + also works when writing to standard output as long as standard + output is connected to a regular file and certain additional + conditions are met to make it safe. Creating sparse files may + save disk space and speed up the decompression by reducing the + amount of disk I/O. + + -S .suf, --suffix=.suf + When compressing, use .suf as the suffix for the target file in- + stead of .xz or .lzma. If not writing to standard output and + the source file already has the suffix .suf, a warning is dis- + played and the file is skipped. + + When decompressing, recognize files with the suffix .suf in ad- + dition to files with the .xz, .txz, .lzma, .tlz, or .lz suffix. + If the source file has the suffix .suf, the suffix is removed to + get the target filename. + + When compressing or decompressing raw streams (--format=raw), + the suffix must always be specified unless writing to standard + output, because there is no default suffix for raw streams. + + --files[=file] + Read the filenames to process from file; if file is omitted, + filenames are read from standard input. Filenames must be ter- + minated with the newline character. A dash (-) is taken as a + regular filename; it doesn't mean standard input. If filenames + are given also as command line arguments, they are processed be- + fore the filenames read from file. + + --files0[=file] + This is identical to --files[=file] except that each filename + must be terminated with the null character. + + Basic file format and compression options + -F format, --format=format + Specify the file format to compress or decompress: + + auto This is the default. When compressing, auto is equiva- + lent to xz. When decompressing, the format of the input + file is automatically detected. Note that raw streams + (created with --format=raw) cannot be auto-detected. + + xz Compress to the .xz file format, or accept only .xz files + when decompressing. + + lzma, alone + Compress to the legacy .lzma file format, or accept only + .lzma files when decompressing. The alternative name + alone is provided for backwards compatibility with LZMA + Utils. + + lzip Accept only .lz files when decompressing. Compression is + not supported. + + The .lz format version 0 and the unextended version 1 are + supported. Version 0 files were produced by lzip 1.3 and + older. Such files aren't common but may be found from + file archives as a few source packages were released in + this format. People might have old personal files in + this format too. Decompression support for the format + version 0 was removed in lzip 1.18. + + lzip 1.4 and later create files in the format version 1. + The sync flush marker extension to the format version 1 + was added in lzip 1.6. This extension is rarely used and + isn't supported by xz (diagnosed as corrupt input). + + raw Compress or uncompress a raw stream (no headers). This + is meant for advanced users only. To decode raw streams, + you need use --format=raw and explicitly specify the fil- + ter chain, which normally would have been stored in the + container headers. + + -C check, --check=check + Specify the type of the integrity check. The check is calcu- + lated from the uncompressed data and stored in the .xz file. + This option has an effect only when compressing into the .xz + format; the .lzma format doesn't support integrity checks. The + integrity check (if any) is verified when the .xz file is decom- + pressed. + + Supported check types: + + none Don't calculate an integrity check at all. This is usu- + ally a bad idea. This can be useful when integrity of + the data is verified by other means anyway. + + crc32 Calculate CRC32 using the polynomial from IEEE-802.3 + (Ethernet). + + crc64 Calculate CRC64 using the polynomial from ECMA-182. This + is the default, since it is slightly better than CRC32 at + detecting damaged files and the speed difference is neg- + ligible. + + sha256 Calculate SHA-256. This is somewhat slower than CRC32 + and CRC64. + + Integrity of the .xz headers is always verified with CRC32. It + is not possible to change or disable it. + + --ignore-check + Don't verify the integrity check of the compressed data when de- + compressing. The CRC32 values in the .xz headers will still be + verified normally. + + Do not use this option unless you know what you are doing. Pos- + sible reasons to use this option: + + o Trying to recover data from a corrupt .xz file. + + o Speeding up decompression. This matters mostly with SHA-256 + or with files that have compressed extremely well. It's rec- + ommended to not use this option for this purpose unless the + file integrity is verified externally in some other way. + + -0 ... -9 + Select a compression preset level. The default is -6. If mul- + tiple preset levels are specified, the last one takes effect. + If a custom filter chain was already specified, setting a com- + pression preset level clears the custom filter chain. + + The differences between the presets are more significant than + with gzip(1) and bzip2(1). The selected compression settings + determine the memory requirements of the decompressor, thus us- + ing a too high preset level might make it painful to decompress + the file on an old system with little RAM. Specifically, it's + not a good idea to blindly use -9 for everything like it often + is with gzip(1) and bzip2(1). + + -0 ... -3 + These are somewhat fast presets. -0 is sometimes faster + than gzip -9 while compressing much better. The higher + ones often have speed comparable to bzip2(1) with compa- + rable or better compression ratio, although the results + depend a lot on the type of data being compressed. + + -4 ... -6 + Good to very good compression while keeping decompressor + memory usage reasonable even for old systems. -6 is the + default, which is usually a good choice for distributing + files that need to be decompressible even on systems with + only 16 MiB RAM. (-5e or -6e may be worth considering + too. See --extreme.) + + -7 ... -9 + These are like -6 but with higher compressor and decom- + pressor memory requirements. These are useful only when + compressing files bigger than 8 MiB, 16 MiB, and 32 MiB, + respectively. + + On the same hardware, the decompression speed is approximately a + constant number of bytes of compressed data per second. In + other words, the better the compression, the faster the decom- + pression will usually be. This also means that the amount of + uncompressed output produced per second can vary a lot. + + The following table summarises the features of the presets: + + Preset DictSize CompCPU CompMem DecMem + -0 256 KiB 0 3 MiB 1 MiB + -1 1 MiB 1 9 MiB 2 MiB + -2 2 MiB 2 17 MiB 3 MiB + -3 4 MiB 3 32 MiB 5 MiB + -4 4 MiB 4 48 MiB 5 MiB + -5 8 MiB 5 94 MiB 9 MiB + -6 8 MiB 6 94 MiB 9 MiB + -7 16 MiB 6 186 MiB 17 MiB + -8 32 MiB 6 370 MiB 33 MiB + -9 64 MiB 6 674 MiB 65 MiB + + Column descriptions: + + o DictSize is the LZMA2 dictionary size. It is waste of memory + to use a dictionary bigger than the size of the uncompressed + file. This is why it is good to avoid using the presets -7 + ... -9 when there's no real need for them. At -6 and lower, + the amount of memory wasted is usually low enough to not mat- + ter. + + o CompCPU is a simplified representation of the LZMA2 settings + that affect compression speed. The dictionary size affects + speed too, so while CompCPU is the same for levels -6 ... -9, + higher levels still tend to be a little slower. To get even + slower and thus possibly better compression, see --extreme. + + o CompMem contains the compressor memory requirements in the + single-threaded mode. It may vary slightly between xz ver- + sions. Memory requirements of some of the future multi- + threaded modes may be dramatically higher than that of the + single-threaded mode. + + o DecMem contains the decompressor memory requirements. That + is, the compression settings determine the memory require- + ments of the decompressor. The exact decompressor memory us- + age is slightly more than the LZMA2 dictionary size, but the + values in the table have been rounded up to the next full + MiB. + + -e, --extreme + Use a slower variant of the selected compression preset level + (-0 ... -9) to hopefully get a little bit better compression ra- + tio, but with bad luck this can also make it worse. Decompres- + sor memory usage is not affected, but compressor memory usage + increases a little at preset levels -0 ... -3. + + Since there are two presets with dictionary sizes 4 MiB and + 8 MiB, the presets -3e and -5e use slightly faster settings + (lower CompCPU) than -4e and -6e, respectively. That way no two + presets are identical. + + Preset DictSize CompCPU CompMem DecMem + -0e 256 KiB 8 4 MiB 1 MiB + -1e 1 MiB 8 13 MiB 2 MiB + -2e 2 MiB 8 25 MiB 3 MiB + -3e 4 MiB 7 48 MiB 5 MiB + -4e 4 MiB 8 48 MiB 5 MiB + -5e 8 MiB 7 94 MiB 9 MiB + -6e 8 MiB 8 94 MiB 9 MiB + -7e 16 MiB 8 186 MiB 17 MiB + -8e 32 MiB 8 370 MiB 33 MiB + -9e 64 MiB 8 674 MiB 65 MiB + + For example, there are a total of four presets that use 8 MiB + dictionary, whose order from the fastest to the slowest is -5, + -6, -5e, and -6e. + + --fast + --best These are somewhat misleading aliases for -0 and -9, respec- + tively. These are provided only for backwards compatibility + with LZMA Utils. Avoid using these options. + + --block-size=size + When compressing to the .xz format, split the input data into + blocks of size bytes. The blocks are compressed independently + from each other, which helps with multi-threading and makes lim- + ited random-access decompression possible. This option is typi- + cally used to override the default block size in multi-threaded + mode, but this option can be used in single-threaded mode too. + + In multi-threaded mode about three times size bytes will be al- + located in each thread for buffering input and output. The de- + fault size is three times the LZMA2 dictionary size or 1 MiB, + whichever is more. Typically a good value is 2-4 times the size + of the LZMA2 dictionary or at least 1 MiB. Using size less than + the LZMA2 dictionary size is waste of RAM because then the LZMA2 + dictionary buffer will never get fully used. The sizes of the + blocks are stored in the block headers, which a future version + of xz will use for multi-threaded decompression. + + In single-threaded mode no block splitting is done by default. + Setting this option doesn't affect memory usage. No size infor- + mation is stored in block headers, thus files created in single- + threaded mode won't be identical to files created in multi- + threaded mode. The lack of size information also means that a + future version of xz won't be able decompress the files in + multi-threaded mode. + + --block-list=sizes + When compressing to the .xz format, start a new block after the + given intervals of uncompressed data. + + The uncompressed sizes of the blocks are specified as a comma- + separated list. Omitting a size (two or more consecutive com- + mas) is a shorthand to use the size of the previous block. + + If the input file is bigger than the sum of sizes, the last + value in sizes is repeated until the end of the file. A special + value of 0 may be used as the last value to indicate that the + rest of the file should be encoded as a single block. + + If one specifies sizes that exceed the encoder's block size (ei- + ther the default value in threaded mode or the value specified + with --block-size=size), the encoder will create additional + blocks while keeping the boundaries specified in sizes. For ex- + ample, if one specifies --block-size=10MiB + --block-list=5MiB,10MiB,8MiB,12MiB,24MiB and the input file is + 80 MiB, one will get 11 blocks: 5, 10, 8, 10, 2, 10, 10, 4, 10, + 10, and 1 MiB. + + In multi-threaded mode the sizes of the blocks are stored in the + block headers. This isn't done in single-threaded mode, so the + encoded output won't be identical to that of the multi-threaded + mode. + + --flush-timeout=timeout + When compressing, if more than timeout milliseconds (a positive + integer) has passed since the previous flush and reading more + input would block, all the pending input data is flushed from + the encoder and made available in the output stream. This can + be useful if xz is used to compress data that is streamed over a + network. Small timeout values make the data available at the + receiving end with a small delay, but large timeout values give + better compression ratio. + + This feature is disabled by default. If this option is speci- + fied more than once, the last one takes effect. The special + timeout value of 0 can be used to explicitly disable this fea- + ture. + + This feature is not available on non-POSIX systems. + + This feature is still experimental. Currently xz is unsuitable + for decompressing the stream in real time due to how xz does + buffering. + + --memlimit-compress=limit + Set a memory usage limit for compression. If this option is + specified multiple times, the last one takes effect. + + If the compression settings exceed the limit, xz will attempt to + adjust the settings downwards so that the limit is no longer ex- + ceeded and display a notice that automatic adjustment was done. + The adjustments are done in this order: reducing the number of + threads, switching to single-threaded mode if even one thread in + multi-threaded mode exceeds the limit, and finally reducing the + LZMA2 dictionary size. + + When compressing with --format=raw or if --no-adjust has been + specified, only the number of threads may be reduced since it + can be done without affecting the compressed output. + + If the limit cannot be met even with the adjustments described + above, an error is displayed and xz will exit with exit status + 1. + + The limit can be specified in multiple ways: + + o The limit can be an absolute value in bytes. Using an inte- + ger suffix like MiB can be useful. Example: --memlimit-com- + press=80MiB + + o The limit can be specified as a percentage of total physical + memory (RAM). This can be useful especially when setting the + XZ_DEFAULTS environment variable in a shell initialization + script that is shared between different computers. That way + the limit is automatically bigger on systems with more mem- + ory. Example: --memlimit-compress=70% + + o The limit can be reset back to its default value by setting + it to 0. This is currently equivalent to setting the limit + to max (no memory usage limit). + + For 32-bit xz there is a special case: if the limit would be + over 4020 MiB, the limit is set to 4020 MiB. On MIPS32 2000 MiB + is used instead. (The values 0 and max aren't affected by this. + A similar feature doesn't exist for decompression.) This can be + helpful when a 32-bit executable has access to 4 GiB address + space (2 GiB on MIPS32) while hopefully doing no harm in other + situations. + + See also the section Memory usage. + + --memlimit-decompress=limit + Set a memory usage limit for decompression. This also affects + the --list mode. If the operation is not possible without ex- + ceeding the limit, xz will display an error and decompressing + the file will fail. See --memlimit-compress=limit for possible + ways to specify the limit. + + --memlimit-mt-decompress=limit + Set a memory usage limit for multi-threaded decompression. This + can only affect the number of threads; this will never make xz + refuse to decompress a file. If limit is too low to allow any + multi-threading, the limit is ignored and xz will continue in + single-threaded mode. Note that if also --memlimit-decompress + is used, it will always apply to both single-threaded and multi- + threaded modes, and so the effective limit for multi-threading + will never be higher than the limit set with --memlimit-decom- + press. + + In contrast to the other memory usage limit options, --mem- + limit-mt-decompress=limit has a system-specific default limit. + xz --info-memory can be used to see the current value. + + This option and its default value exist because without any + limit the threaded decompressor could end up allocating an in- + sane amount of memory with some input files. If the default + limit is too low on your system, feel free to increase the limit + but never set it to a value larger than the amount of usable RAM + as with appropriate input files xz will attempt to use that + amount of memory even with a low number of threads. Running out + of memory or swapping will not improve decompression perfor- + mance. + + See --memlimit-compress=limit for possible ways to specify the + limit. Setting limit to 0 resets the limit to the default sys- + tem-specific value. + + -M limit, --memlimit=limit, --memory=limit + This is equivalent to specifying --memlimit-compress=limit + --memlimit-decompress=limit --memlimit-mt-decompress=limit. + + --no-adjust + Display an error and exit if the memory usage limit cannot be + met without adjusting settings that affect the compressed out- + put. That is, this prevents xz from switching the encoder from + multi-threaded mode to single-threaded mode and from reducing + the LZMA2 dictionary size. Even when this option is used the + number of threads may be reduced to meet the memory usage limit + as that won't affect the compressed output. + + Automatic adjusting is always disabled when creating raw streams + (--format=raw). + + -T threads, --threads=threads + Specify the number of worker threads to use. Setting threads to + a special value 0 makes xz use up to as many threads as the pro- + cessor(s) on the system support. The actual number of threads + can be fewer than threads if the input file is not big enough + for threading with the given settings or if using more threads + would exceed the memory usage limit. + + The single-threaded and multi-threaded compressors produce dif- + ferent output. Single-threaded compressor will give the small- + est file size but only the output from the multi-threaded com- + pressor can be decompressed using multiple threads. Setting + threads to 1 will use the single-threaded mode. Setting threads + to any other value, including 0, will use the multi-threaded + compressor even if the system supports only one hardware thread. + (xz 5.2.x used single-threaded mode in this situation.) + + To use multi-threaded mode with only one thread, set threads to + +1. The + prefix has no effect with values other than 1. A + memory usage limit can still make xz switch to single-threaded + mode unless --no-adjust is used. Support for the + prefix was + added in xz 5.4.0. + + If an automatic number of threads has been requested and no mem- + ory usage limit has been specified, then a system-specific de- + fault soft limit will be used to possibly limit the number of + threads. It is a soft limit in sense that it is ignored if the + number of threads becomes one, thus a soft limit will never stop + xz from compressing or decompressing. This default soft limit + will not make xz switch from multi-threaded mode to single- + threaded mode. The active limits can be seen with xz + --info-memory. + + Currently the only threading method is to split the input into + blocks and compress them independently from each other. The de- + fault block size depends on the compression level and can be + overridden with the --block-size=size option. + + Threaded decompression only works on files that contain multiple + blocks with size information in block headers. All large enough + files compressed in multi-threaded mode meet this condition, but + files compressed in single-threaded mode don't even if + --block-size=size has been used. + + Custom compressor filter chains + A custom filter chain allows specifying the compression settings in de- + tail instead of relying on the settings associated to the presets. + When a custom filter chain is specified, preset options (-0 ... -9 and + --extreme) earlier on the command line are forgotten. If a preset op- + tion is specified after one or more custom filter chain options, the + new preset takes effect and the custom filter chain options specified + earlier are forgotten. + + A filter chain is comparable to piping on the command line. When com- + pressing, the uncompressed input goes to the first filter, whose output + goes to the next filter (if any). The output of the last filter gets + written to the compressed file. The maximum number of filters in the + chain is four, but typically a filter chain has only one or two fil- + ters. + + Many filters have limitations on where they can be in the filter chain: + some filters can work only as the last filter in the chain, some only + as a non-last filter, and some work in any position in the chain. De- + pending on the filter, this limitation is either inherent to the filter + design or exists to prevent security issues. + + A custom filter chain is specified by using one or more filter options + in the order they are wanted in the filter chain. That is, the order + of filter options is significant! When decoding raw streams (--for- + mat=raw), the filter chain is specified in the same order as it was + specified when compressing. + + Filters take filter-specific options as a comma-separated list. Extra + commas in options are ignored. Every option has a default value, so + you need to specify only those you want to change. + + To see the whole filter chain and options, use xz -vv (that is, use + --verbose twice). This works also for viewing the filter chain options + used by presets. + + --lzma1[=options] + --lzma2[=options] + Add LZMA1 or LZMA2 filter to the filter chain. These filters + can be used only as the last filter in the chain. + + LZMA1 is a legacy filter, which is supported almost solely due + to the legacy .lzma file format, which supports only LZMA1. + LZMA2 is an updated version of LZMA1 to fix some practical is- + sues of LZMA1. The .xz format uses LZMA2 and doesn't support + LZMA1 at all. Compression speed and ratios of LZMA1 and LZMA2 + are practically the same. + + LZMA1 and LZMA2 share the same set of options: + + preset=preset + Reset all LZMA1 or LZMA2 options to preset. Preset con- + sist of an integer, which may be followed by single-let- + ter preset modifiers. The integer can be from 0 to 9, + matching the command line options -0 ... -9. The only + supported modifier is currently e, which matches --ex- + treme. If no preset is specified, the default values of + LZMA1 or LZMA2 options are taken from the preset 6. + + dict=size + Dictionary (history buffer) size indicates how many bytes + of the recently processed uncompressed data is kept in + memory. The algorithm tries to find repeating byte se- + quences (matches) in the uncompressed data, and replace + them with references to the data currently in the dictio- + nary. The bigger the dictionary, the higher is the + chance to find a match. Thus, increasing dictionary size + usually improves compression ratio, but a dictionary big- + ger than the uncompressed file is waste of memory. + + Typical dictionary size is from 64 KiB to 64 MiB. The + minimum is 4 KiB. The maximum for compression is cur- + rently 1.5 GiB (1536 MiB). The decompressor already sup- + ports dictionaries up to one byte less than 4 GiB, which + is the maximum for the LZMA1 and LZMA2 stream formats. + + Dictionary size and match finder (mf) together determine + the memory usage of the LZMA1 or LZMA2 encoder. The same + (or bigger) dictionary size is required for decompressing + that was used when compressing, thus the memory usage of + the decoder is determined by the dictionary size used + when compressing. The .xz headers store the dictionary + size either as 2^n or 2^n + 2^(n-1), so these sizes are + somewhat preferred for compression. Other sizes will get + rounded up when stored in the .xz headers. + + lc=lc Specify the number of literal context bits. The minimum + is 0 and the maximum is 4; the default is 3. In addi- + tion, the sum of lc and lp must not exceed 4. + + All bytes that cannot be encoded as matches are encoded + as literals. That is, literals are simply 8-bit bytes + that are encoded one at a time. + + The literal coding makes an assumption that the highest + lc bits of the previous uncompressed byte correlate with + the next byte. For example, in typical English text, an + upper-case letter is often followed by a lower-case let- + ter, and a lower-case letter is usually followed by an- + other lower-case letter. In the US-ASCII character set, + the highest three bits are 010 for upper-case letters and + 011 for lower-case letters. When lc is at least 3, the + literal coding can take advantage of this property in the + uncompressed data. + + The default value (3) is usually good. If you want maxi- + mum compression, test lc=4. Sometimes it helps a little, + and sometimes it makes compression worse. If it makes it + worse, test lc=2 too. + + lp=lp Specify the number of literal position bits. The minimum + is 0 and the maximum is 4; the default is 0. + + Lp affects what kind of alignment in the uncompressed + data is assumed when encoding literals. See pb below for + more information about alignment. + + pb=pb Specify the number of position bits. The minimum is 0 + and the maximum is 4; the default is 2. + + Pb affects what kind of alignment in the uncompressed + data is assumed in general. The default means four-byte + alignment (2^pb=2^2=4), which is often a good choice when + there's no better guess. + + When the alignment is known, setting pb accordingly may + reduce the file size a little. For example, with text + files having one-byte alignment (US-ASCII, ISO-8859-*, + UTF-8), setting pb=0 can improve compression slightly. + For UTF-16 text, pb=1 is a good choice. If the alignment + is an odd number like 3 bytes, pb=0 might be the best + choice. + + Even though the assumed alignment can be adjusted with pb + and lp, LZMA1 and LZMA2 still slightly favor 16-byte + alignment. It might be worth taking into account when + designing file formats that are likely to be often com- + pressed with LZMA1 or LZMA2. + + mf=mf Match finder has a major effect on encoder speed, memory + usage, and compression ratio. Usually Hash Chain match + finders are faster than Binary Tree match finders. The + default depends on the preset: 0 uses hc3, 1-3 use hc4, + and the rest use bt4. + + The following match finders are supported. The memory + usage formulas below are rough approximations, which are + closest to the reality when dict is a power of two. + + hc3 Hash Chain with 2- and 3-byte hashing + Minimum value for nice: 3 + Memory usage: + dict * 7.5 (if dict <= 16 MiB); + dict * 5.5 + 64 MiB (if dict > 16 MiB) + + hc4 Hash Chain with 2-, 3-, and 4-byte hashing + Minimum value for nice: 4 + Memory usage: + dict * 7.5 (if dict <= 32 MiB); + dict * 6.5 (if dict > 32 MiB) + + bt2 Binary Tree with 2-byte hashing + Minimum value for nice: 2 + Memory usage: dict * 9.5 + + bt3 Binary Tree with 2- and 3-byte hashing + Minimum value for nice: 3 + Memory usage: + dict * 11.5 (if dict <= 16 MiB); + dict * 9.5 + 64 MiB (if dict > 16 MiB) + + bt4 Binary Tree with 2-, 3-, and 4-byte hashing + Minimum value for nice: 4 + Memory usage: + dict * 11.5 (if dict <= 32 MiB); + dict * 10.5 (if dict > 32 MiB) + + mode=mode + Compression mode specifies the method to analyze the data + produced by the match finder. Supported modes are fast + and normal. The default is fast for presets 0-3 and nor- + mal for presets 4-9. + + Usually fast is used with Hash Chain match finders and + normal with Binary Tree match finders. This is also what + the presets do. + + nice=nice + Specify what is considered to be a nice length for a + match. Once a match of at least nice bytes is found, the + algorithm stops looking for possibly better matches. + + Nice can be 2-273 bytes. Higher values tend to give bet- + ter compression ratio at the expense of speed. The de- + fault depends on the preset. + + depth=depth + Specify the maximum search depth in the match finder. + The default is the special value of 0, which makes the + compressor determine a reasonable depth from mf and nice. + + Reasonable depth for Hash Chains is 4-100 and 16-1000 for + Binary Trees. Using very high values for depth can make + the encoder extremely slow with some files. Avoid set- + ting the depth over 1000 unless you are prepared to in- + terrupt the compression in case it is taking far too + long. + + When decoding raw streams (--format=raw), LZMA2 needs only the + dictionary size. LZMA1 needs also lc, lp, and pb. + + --x86[=options] + --arm[=options] + --armthumb[=options] + --arm64[=options] + --powerpc[=options] + --ia64[=options] + --sparc[=options] + Add a branch/call/jump (BCJ) filter to the filter chain. These + filters can be used only as a non-last filter in the filter + chain. + + A BCJ filter converts relative addresses in the machine code to + their absolute counterparts. This doesn't change the size of + the data but it increases redundancy, which can help LZMA2 to + produce 0-15 % smaller .xz file. The BCJ filters are always re- + versible, so using a BCJ filter for wrong type of data doesn't + cause any data loss, although it may make the compression ratio + slightly worse. The BCJ filters are very fast and use an in- + significant amount of memory. + + These BCJ filters have known problems related to the compression + ratio: + + o Some types of files containing executable code (for example, + object files, static libraries, and Linux kernel modules) + have the addresses in the instructions filled with filler + values. These BCJ filters will still do the address conver- + sion, which will make the compression worse with these files. + + o If a BCJ filter is applied on an archive, it is possible that + it makes the compression ratio worse than not using a BCJ + filter. For example, if there are similar or even identical + executables then filtering will likely make the files less + similar and thus compression is worse. The contents of non- + executable files in the same archive can matter too. In + practice one has to try with and without a BCJ filter to see + which is better in each situation. + + Different instruction sets have different alignment: the exe- + cutable file must be aligned to a multiple of this value in the + input data to make the filter work. + + Filter Alignment Notes + x86 1 32-bit or 64-bit x86 + ARM 4 + ARM-Thumb 2 + ARM64 4 4096-byte alignment is best + PowerPC 4 Big endian only + IA-64 16 Itanium + SPARC 4 + + Since the BCJ-filtered data is usually compressed with LZMA2, + the compression ratio may be improved slightly if the LZMA2 op- + tions are set to match the alignment of the selected BCJ filter. + For example, with the IA-64 filter, it's good to set pb=4 or + even pb=4,lp=4,lc=0 with LZMA2 (2^4=16). The x86 filter is an + exception; it's usually good to stick to LZMA2's default four- + byte alignment when compressing x86 executables. + + All BCJ filters support the same options: + + start=offset + Specify the start offset that is used when converting be- + tween relative and absolute addresses. The offset must + be a multiple of the alignment of the filter (see the ta- + ble above). The default is zero. In practice, the de- + fault is good; specifying a custom offset is almost never + useful. + + --delta[=options] + Add the Delta filter to the filter chain. The Delta filter can + be only used as a non-last filter in the filter chain. + + Currently only simple byte-wise delta calculation is supported. + It can be useful when compressing, for example, uncompressed + bitmap images or uncompressed PCM audio. However, special pur- + pose algorithms may give significantly better results than Delta + + LZMA2. This is true especially with audio, which compresses + faster and better, for example, with flac(1). + + Supported options: + + dist=distance + Specify the distance of the delta calculation in bytes. + distance must be 1-256. The default is 1. + + For example, with dist=2 and eight-byte input A1 B1 A2 B3 + A3 B5 A4 B7, the output will be A1 B1 01 02 01 02 01 02. + + Other options + -q, --quiet + Suppress warnings and notices. Specify this twice to suppress + errors too. This option has no effect on the exit status. That + is, even if a warning was suppressed, the exit status to indi- + cate a warning is still used. + + -v, --verbose + Be verbose. If standard error is connected to a terminal, xz + will display a progress indicator. Specifying --verbose twice + will give even more verbose output. + + The progress indicator shows the following information: + + o Completion percentage is shown if the size of the input file + is known. That is, the percentage cannot be shown in pipes. + + o Amount of compressed data produced (compressing) or consumed + (decompressing). + + o Amount of uncompressed data consumed (compressing) or pro- + duced (decompressing). + + o Compression ratio, which is calculated by dividing the amount + of compressed data processed so far by the amount of uncom- + pressed data processed so far. + + o Compression or decompression speed. This is measured as the + amount of uncompressed data consumed (compression) or pro- + duced (decompression) per second. It is shown after a few + seconds have passed since xz started processing the file. + + o Elapsed time in the format M:SS or H:MM:SS. + + o Estimated remaining time is shown only when the size of the + input file is known and a couple of seconds have already + passed since xz started processing the file. The time is + shown in a less precise format which never has any colons, + for example, 2 min 30 s. + + When standard error is not a terminal, --verbose will make xz + print the filename, compressed size, uncompressed size, compres- + sion ratio, and possibly also the speed and elapsed time on a + single line to standard error after compressing or decompressing + the file. The speed and elapsed time are included only when the + operation took at least a few seconds. If the operation didn't + finish, for example, due to user interruption, also the comple- + tion percentage is printed if the size of the input file is + known. + + -Q, --no-warn + Don't set the exit status to 2 even if a condition worth a warn- + ing was detected. This option doesn't affect the verbosity + level, thus both --quiet and --no-warn have to be used to not + display warnings and to not alter the exit status. + + --robot + Print messages in a machine-parsable format. This is intended + to ease writing frontends that want to use xz instead of li- + blzma, which may be the case with various scripts. The output + with this option enabled is meant to be stable across xz re- + leases. See the section ROBOT MODE for details. + + --info-memory + Display, in human-readable format, how much physical memory + (RAM) and how many processor threads xz thinks the system has + and the memory usage limits for compression and decompression, + and exit successfully. + + -h, --help + Display a help message describing the most commonly used op- + tions, and exit successfully. + + -H, --long-help + Display a help message describing all features of xz, and exit + successfully + + -V, --version + Display the version number of xz and liblzma in human readable + format. To get machine-parsable output, specify --robot before + --version. + +ROBOT MODE + The robot mode is activated with the --robot option. It makes the out- + put of xz easier to parse by other programs. Currently --robot is sup- + ported only together with --version, --info-memory, and --list. It + will be supported for compression and decompression in the future. + + Version + xz --robot --version prints the version number of xz and liblzma in the + following format: + + XZ_VERSION=XYYYZZZS + LIBLZMA_VERSION=XYYYZZZS + + X Major version. + + YYY Minor version. Even numbers are stable. Odd numbers are alpha + or beta versions. + + ZZZ Patch level for stable releases or just a counter for develop- + ment releases. + + S Stability. 0 is alpha, 1 is beta, and 2 is stable. S should be + always 2 when YYY is even. + + XYYYZZZS are the same on both lines if xz and liblzma are from the same + XZ Utils release. + + Examples: 4.999.9beta is 49990091 and 5.0.0 is 50000002. + + Memory limit information + xz --robot --info-memory prints a single line with multiple tab-sepa- + rated columns: + + 1. Total amount of physical memory (RAM) in bytes. + + 2. Memory usage limit for compression in bytes (--memlimit-compress). + A special value of 0 indicates the default setting which for sin- + gle-threaded mode is the same as no limit. + + 3. Memory usage limit for decompression in bytes (--memlimit-decom- + press). A special value of 0 indicates the default setting which + for single-threaded mode is the same as no limit. + + 4. Since xz 5.3.4alpha: Memory usage for multi-threaded decompression + in bytes (--memlimit-mt-decompress). This is never zero because a + system-specific default value shown in the column 5 is used if no + limit has been specified explicitly. This is also never greater + than the value in the column 3 even if a larger value has been + specified with --memlimit-mt-decompress. + + 5. Since xz 5.3.4alpha: A system-specific default memory usage limit + that is used to limit the number of threads when compressing with + an automatic number of threads (--threads=0) and no memory usage + limit has been specified (--memlimit-compress). This is also used + as the default value for --memlimit-mt-decompress. + + 6. Since xz 5.3.4alpha: Number of available processor threads. + + In the future, the output of xz --robot --info-memory may have more + columns, but never more than a single line. + + List mode + xz --robot --list uses tab-separated output. The first column of every + line has a string that indicates the type of the information found on + that line: + + name This is always the first line when starting to list a file. The + second column on the line is the filename. + + file This line contains overall information about the .xz file. This + line is always printed after the name line. + + stream This line type is used only when --verbose was specified. There + are as many stream lines as there are streams in the .xz file. + + block This line type is used only when --verbose was specified. There + are as many block lines as there are blocks in the .xz file. + The block lines are shown after all the stream lines; different + line types are not interleaved. + + summary + This line type is used only when --verbose was specified twice. + This line is printed after all block lines. Like the file line, + the summary line contains overall information about the .xz + file. + + totals This line is always the very last line of the list output. It + shows the total counts and sizes. + + The columns of the file lines: + 2. Number of streams in the file + 3. Total number of blocks in the stream(s) + 4. Compressed size of the file + 5. Uncompressed size of the file + 6. Compression ratio, for example, 0.123. If ratio is over + 9.999, three dashes (---) are displayed instead of the ra- + tio. + 7. Comma-separated list of integrity check names. The follow- + ing strings are used for the known check types: None, CRC32, + CRC64, and SHA-256. For unknown check types, Unknown-N is + used, where N is the Check ID as a decimal number (one or + two digits). + 8. Total size of stream padding in the file + + The columns of the stream lines: + 2. Stream number (the first stream is 1) + 3. Number of blocks in the stream + 4. Compressed start offset + 5. Uncompressed start offset + 6. Compressed size (does not include stream padding) + 7. Uncompressed size + 8. Compression ratio + 9. Name of the integrity check + 10. Size of stream padding + + The columns of the block lines: + 2. Number of the stream containing this block + 3. Block number relative to the beginning of the stream (the + first block is 1) + 4. Block number relative to the beginning of the file + 5. Compressed start offset relative to the beginning of the + file + 6. Uncompressed start offset relative to the beginning of the + file + 7. Total compressed size of the block (includes headers) + 8. Uncompressed size + 9. Compression ratio + 10. Name of the integrity check + + If --verbose was specified twice, additional columns are included on + the block lines. These are not displayed with a single --verbose, be- + cause getting this information requires many seeks and can thus be + slow: + 11. Value of the integrity check in hexadecimal + 12. Block header size + 13. Block flags: c indicates that compressed size is present, + and u indicates that uncompressed size is present. If the + flag is not set, a dash (-) is shown instead to keep the + string length fixed. New flags may be added to the end of + the string in the future. + 14. Size of the actual compressed data in the block (this ex- + cludes the block header, block padding, and check fields) + 15. Amount of memory (in bytes) required to decompress this + block with this xz version + 16. Filter chain. Note that most of the options used at com- + pression time cannot be known, because only the options that + are needed for decompression are stored in the .xz headers. + + The columns of the summary lines: + 2. Amount of memory (in bytes) required to decompress this file + with this xz version + 3. yes or no indicating if all block headers have both com- + pressed size and uncompressed size stored in them + Since xz 5.1.2alpha: + 4. Minimum xz version required to decompress the file + + The columns of the totals line: + 2. Number of streams + 3. Number of blocks + 4. Compressed size + 5. Uncompressed size + 6. Average compression ratio + 7. Comma-separated list of integrity check names that were + present in the files + 8. Stream padding size + 9. Number of files. This is here to keep the order of the ear- + lier columns the same as on file lines. + + If --verbose was specified twice, additional columns are included on + the totals line: + 10. Maximum amount of memory (in bytes) required to decompress + the files with this xz version + 11. yes or no indicating if all block headers have both com- + pressed size and uncompressed size stored in them + Since xz 5.1.2alpha: + 12. Minimum xz version required to decompress the file + + Future versions may add new line types and new columns can be added to + the existing line types, but the existing columns won't be changed. + +EXIT STATUS + 0 All is good. + + 1 An error occurred. + + 2 Something worth a warning occurred, but no actual errors oc- + curred. + + Notices (not warnings or errors) printed on standard error don't affect + the exit status. + +ENVIRONMENT + xz parses space-separated lists of options from the environment vari- + ables XZ_DEFAULTS and XZ_OPT, in this order, before parsing the options + from the command line. Note that only options are parsed from the en- + vironment variables; all non-options are silently ignored. Parsing is + done with getopt_long(3) which is used also for the command line argu- + ments. + + XZ_DEFAULTS + User-specific or system-wide default options. Typically this is + set in a shell initialization script to enable xz's memory usage + limiter by default. Excluding shell initialization scripts and + similar special cases, scripts must never set or unset XZ_DE- + FAULTS. + + XZ_OPT This is for passing options to xz when it is not possible to set + the options directly on the xz command line. This is the case + when xz is run by a script or tool, for example, GNU tar(1): + + XZ_OPT=-2v tar caf foo.tar.xz foo + + Scripts may use XZ_OPT, for example, to set script-specific de- + fault compression options. It is still recommended to allow + users to override XZ_OPT if that is reasonable. For example, in + sh(1) scripts one may use something like this: + + XZ_OPT=${XZ_OPT-"-7e"} + export XZ_OPT + +LZMA UTILS COMPATIBILITY + The command line syntax of xz is practically a superset of lzma, un- + lzma, and lzcat as found from LZMA Utils 4.32.x. In most cases, it is + possible to replace LZMA Utils with XZ Utils without breaking existing + scripts. There are some incompatibilities though, which may sometimes + cause problems. + + Compression preset levels + The numbering of the compression level presets is not identical in xz + and LZMA Utils. The most important difference is how dictionary sizes + are mapped to different presets. Dictionary size is roughly equal to + the decompressor memory usage. + + Level xz LZMA Utils + -0 256 KiB N/A + -1 1 MiB 64 KiB + -2 2 MiB 1 MiB + -3 4 MiB 512 KiB + -4 4 MiB 1 MiB + -5 8 MiB 2 MiB + -6 8 MiB 4 MiB + -7 16 MiB 8 MiB + -8 32 MiB 16 MiB + -9 64 MiB 32 MiB + + The dictionary size differences affect the compressor memory usage too, + but there are some other differences between LZMA Utils and XZ Utils, + which make the difference even bigger: + + Level xz LZMA Utils 4.32.x + -0 3 MiB N/A + -1 9 MiB 2 MiB + -2 17 MiB 12 MiB + -3 32 MiB 12 MiB + -4 48 MiB 16 MiB + -5 94 MiB 26 MiB + -6 94 MiB 45 MiB + -7 186 MiB 83 MiB + -8 370 MiB 159 MiB + -9 674 MiB 311 MiB + + The default preset level in LZMA Utils is -7 while in XZ Utils it is + -6, so both use an 8 MiB dictionary by default. + + Streamed vs. non-streamed .lzma files + The uncompressed size of the file can be stored in the .lzma header. + LZMA Utils does that when compressing regular files. The alternative + is to mark that uncompressed size is unknown and use end-of-payload + marker to indicate where the decompressor should stop. LZMA Utils uses + this method when uncompressed size isn't known, which is the case, for + example, in pipes. + + xz supports decompressing .lzma files with or without end-of-payload + marker, but all .lzma files created by xz will use end-of-payload + marker and have uncompressed size marked as unknown in the .lzma + header. This may be a problem in some uncommon situations. For exam- + ple, a .lzma decompressor in an embedded device might work only with + files that have known uncompressed size. If you hit this problem, you + need to use LZMA Utils or LZMA SDK to create .lzma files with known un- + compressed size. + + Unsupported .lzma files + The .lzma format allows lc values up to 8, and lp values up to 4. LZMA + Utils can decompress files with any lc and lp, but always creates files + with lc=3 and lp=0. Creating files with other lc and lp is possible + with xz and with LZMA SDK. + + The implementation of the LZMA1 filter in liblzma requires that the sum + of lc and lp must not exceed 4. Thus, .lzma files, which exceed this + limitation, cannot be decompressed with xz. + + LZMA Utils creates only .lzma files which have a dictionary size of 2^n + (a power of 2) but accepts files with any dictionary size. liblzma ac- + cepts only .lzma files which have a dictionary size of 2^n or 2^n + + 2^(n-1). This is to decrease false positives when detecting .lzma + files. + + These limitations shouldn't be a problem in practice, since practically + all .lzma files have been compressed with settings that liblzma will + accept. + + Trailing garbage + When decompressing, LZMA Utils silently ignore everything after the + first .lzma stream. In most situations, this is a bug. This also + means that LZMA Utils don't support decompressing concatenated .lzma + files. + + If there is data left after the first .lzma stream, xz considers the + file to be corrupt unless --single-stream was used. This may break ob- + scure scripts which have assumed that trailing garbage is ignored. + +NOTES + Compressed output may vary + The exact compressed output produced from the same uncompressed input + file may vary between XZ Utils versions even if compression options are + identical. This is because the encoder can be improved (faster or bet- + ter compression) without affecting the file format. The output can + vary even between different builds of the same XZ Utils version, if + different build options are used. + + The above means that once --rsyncable has been implemented, the result- + ing files won't necessarily be rsyncable unless both old and new files + have been compressed with the same xz version. This problem can be + fixed if a part of the encoder implementation is frozen to keep rsynca- + ble output stable across xz versions. + + Embedded .xz decompressors + Embedded .xz decompressor implementations like XZ Embedded don't neces- + sarily support files created with integrity check types other than none + and crc32. Since the default is --check=crc64, you must use + --check=none or --check=crc32 when creating files for embedded systems. + + Outside embedded systems, all .xz format decompressors support all the + check types, or at least are able to decompress the file without veri- + fying the integrity check if the particular check is not supported. + + XZ Embedded supports BCJ filters, but only with the default start off- + set. + +EXAMPLES + Basics + Compress the file foo into foo.xz using the default compression level + (-6), and remove foo if compression is successful: + + xz foo + + Decompress bar.xz into bar and don't remove bar.xz even if decompres- + sion is successful: + + xz -dk bar.xz + + Create baz.tar.xz with the preset -4e (-4 --extreme), which is slower + than the default -6, but needs less memory for compression and decom- + pression (48 MiB and 5 MiB, respectively): + + tar cf - baz | xz -4e > baz.tar.xz + + A mix of compressed and uncompressed files can be decompressed to stan- + dard output with a single command: + + xz -dcf a.txt b.txt.xz c.txt d.txt.lzma > abcd.txt + + Parallel compression of many files + On GNU and *BSD, find(1) and xargs(1) can be used to parallelize com- + pression of many files: + + find . -type f \! -name '*.xz' -print0 \ + | xargs -0r -P4 -n16 xz -T1 + + The -P option to xargs(1) sets the number of parallel xz processes. + The best value for the -n option depends on how many files there are to + be compressed. If there are only a couple of files, the value should + probably be 1; with tens of thousands of files, 100 or even more may be + appropriate to reduce the number of xz processes that xargs(1) will + eventually create. + + The option -T1 for xz is there to force it to single-threaded mode, be- + cause xargs(1) is used to control the amount of parallelization. + + Robot mode + Calculate how many bytes have been saved in total after compressing + multiple files: + + xz --robot --list *.xz | awk '/^totals/{print $5-$4}' + + A script may want to know that it is using new enough xz. The follow- + ing sh(1) script checks that the version number of the xz tool is at + least 5.0.0. This method is compatible with old beta versions, which + didn't support the --robot option: + + if ! eval "$(xz --robot --version 2> /dev/null)" || + [ "$XZ_VERSION" -lt 50000002 ]; then + echo "Your xz is too old." + fi + unset XZ_VERSION LIBLZMA_VERSION + + Set a memory usage limit for decompression using XZ_OPT, but if a limit + has already been set, don't increase it: + + NEWLIM=$((123 << 20)) # 123 MiB + OLDLIM=$(xz --robot --info-memory | cut -f3) + if [ $OLDLIM -eq 0 -o $OLDLIM -gt $NEWLIM ]; then + XZ_OPT="$XZ_OPT --memlimit-decompress=$NEWLIM" + export XZ_OPT + fi + + Custom compressor filter chains + The simplest use for custom filter chains is customizing a LZMA2 pre- + set. This can be useful, because the presets cover only a subset of + the potentially useful combinations of compression settings. + + The CompCPU columns of the tables from the descriptions of the options + -0 ... -9 and --extreme are useful when customizing LZMA2 presets. + Here are the relevant parts collected from those two tables: + + Preset CompCPU + -0 0 + -1 1 + -2 2 + -3 3 + -4 4 + -5 5 + -6 6 + -5e 7 + -6e 8 + + If you know that a file requires somewhat big dictionary (for example, + 32 MiB) to compress well, but you want to compress it quicker than xz + -8 would do, a preset with a low CompCPU value (for example, 1) can be + modified to use a bigger dictionary: + + xz --lzma2=preset=1,dict=32MiB foo.tar + + With certain files, the above command may be faster than xz -6 while + compressing significantly better. However, it must be emphasized that + only some files benefit from a big dictionary while keeping the CompCPU + value low. The most obvious situation, where a big dictionary can help + a lot, is an archive containing very similar files of at least a few + megabytes each. The dictionary size has to be significantly bigger + than any individual file to allow LZMA2 to take full advantage of the + similarities between consecutive files. + + If very high compressor and decompressor memory usage is fine, and the + file being compressed is at least several hundred megabytes, it may be + useful to use an even bigger dictionary than the 64 MiB that xz -9 + would use: + + xz -vv --lzma2=dict=192MiB big_foo.tar + + Using -vv (--verbose --verbose) like in the above example can be useful + to see the memory requirements of the compressor and decompressor. Re- + member that using a dictionary bigger than the size of the uncompressed + file is waste of memory, so the above command isn't useful for small + files. + + Sometimes the compression time doesn't matter, but the decompressor + memory usage has to be kept low, for example, to make it possible to + decompress the file on an embedded system. The following command uses + -6e (-6 --extreme) as a base and sets the dictionary to only 64 KiB. + The resulting file can be decompressed with XZ Embedded (that's why + there is --check=crc32) using about 100 KiB of memory. + + xz --check=crc32 --lzma2=preset=6e,dict=64KiB foo + + If you want to squeeze out as many bytes as possible, adjusting the + number of literal context bits (lc) and number of position bits (pb) + can sometimes help. Adjusting the number of literal position bits (lp) + might help too, but usually lc and pb are more important. For example, + a source code archive contains mostly US-ASCII text, so something like + the following might give slightly (like 0.1 %) smaller file than xz -6e + (try also without lc=4): + + xz --lzma2=preset=6e,pb=0,lc=4 source_code.tar + + Using another filter together with LZMA2 can improve compression with + certain file types. For example, to compress a x86-32 or x86-64 shared + library using the x86 BCJ filter: + + xz --x86 --lzma2 libfoo.so + + Note that the order of the filter options is significant. If --x86 is + specified after --lzma2, xz will give an error, because there cannot be + any filter after LZMA2, and also because the x86 BCJ filter cannot be + used as the last filter in the chain. + + The Delta filter together with LZMA2 can give good results with bitmap + images. It should usually beat PNG, which has a few more advanced fil- + ters than simple delta but uses Deflate for the actual compression. + + The image has to be saved in uncompressed format, for example, as un- + compressed TIFF. The distance parameter of the Delta filter is set to + match the number of bytes per pixel in the image. For example, 24-bit + RGB bitmap needs dist=3, and it is also good to pass pb=0 to LZMA2 to + accommodate the three-byte alignment: + + xz --delta=dist=3 --lzma2=pb=0 foo.tiff + + If multiple images have been put into a single archive (for example, + .tar), the Delta filter will work on that too as long as all images + have the same number of bytes per pixel. + +SEE ALSO + xzdec(1), xzdiff(1), xzgrep(1), xzless(1), xzmore(1), gzip(1), + bzip2(1), 7z(1) + + XZ Utils: + XZ Embedded: + LZMA SDK: + + + +Tukaani 2023-07-17 XZ(1) diff --git a/doc/man/txt/xzdec.txt b/doc/man/txt/xzdec.txt new file mode 100644 index 0000000..a914e20 --- /dev/null +++ b/doc/man/txt/xzdec.txt @@ -0,0 +1,80 @@ +XZDEC(1) XZ Utils XZDEC(1) + + + +NAME + xzdec, lzmadec - Small .xz and .lzma decompressors + +SYNOPSIS + xzdec [option...] [file...] + lzmadec [option...] [file...] + +DESCRIPTION + xzdec is a liblzma-based decompression-only tool for .xz (and only .xz) + files. xzdec is intended to work as a drop-in replacement for xz(1) in + the most common situations where a script has been written to use xz + --decompress --stdout (and possibly a few other commonly used options) + to decompress .xz files. lzmadec is identical to xzdec except that lz- + madec supports .lzma files instead of .xz files. + + To reduce the size of the executable, xzdec doesn't support multi- + threading or localization, and doesn't read options from XZ_DEFAULTS + and XZ_OPT environment variables. xzdec doesn't support displaying in- + termediate progress information: sending SIGINFO to xzdec does nothing, + but sending SIGUSR1 terminates the process instead of displaying + progress information. + +OPTIONS + -d, --decompress, --uncompress + Ignored for xz(1) compatibility. xzdec supports only decompres- + sion. + + -k, --keep + Ignored for xz(1) compatibility. xzdec never creates or removes + any files. + + -c, --stdout, --to-stdout + Ignored for xz(1) compatibility. xzdec always writes the decom- + pressed data to standard output. + + -q, --quiet + Specifying this once does nothing since xzdec never displays any + warnings or notices. Specify this twice to suppress errors. + + -Q, --no-warn + Ignored for xz(1) compatibility. xzdec never uses the exit sta- + tus 2. + + -h, --help + Display a help message and exit successfully. + + -V, --version + Display the version number of xzdec and liblzma. + +EXIT STATUS + 0 All was good. + + 1 An error occurred. + + xzdec doesn't have any warning messages like xz(1) has, thus the exit + status 2 is not used by xzdec. + +NOTES + Use xz(1) instead of xzdec or lzmadec for normal everyday use. xzdec + or lzmadec are meant only for situations where it is important to have + a smaller decompressor than the full-featured xz(1). + + xzdec and lzmadec are not really that small. The size can be reduced + further by dropping features from liblzma at compile time, but that + shouldn't usually be done for executables distributed in typical non- + embedded operating system distributions. If you need a truly small .xz + decompressor, consider using XZ Embedded. + +SEE ALSO + xz(1) + + XZ Embedded: + + + +Tukaani 2017-04-19 XZDEC(1) diff --git a/doc/man/txt/xzdiff.txt b/doc/man/txt/xzdiff.txt new file mode 100644 index 0000000..681b00c --- /dev/null +++ b/doc/man/txt/xzdiff.txt @@ -0,0 +1,37 @@ +XZDIFF(1) XZ Utils XZDIFF(1) + + + +NAME + xzcmp, xzdiff, lzcmp, lzdiff - compare compressed files + +SYNOPSIS + xzcmp [cmp_options] file1 [file2] + xzdiff [diff_options] file1 [file2] + lzcmp [cmp_options] file1 [file2] + lzdiff [diff_options] file1 [file2] + +DESCRIPTION + xzcmp and xzdiff invoke cmp(1) or diff(1) on files compressed with + xz(1), lzma(1), gzip(1), bzip2(1), lzop(1), or zstd(1). All options + specified are passed directly to cmp(1) or diff(1). If only one file + is specified, then the files compared are file1 (which must have a suf- + fix of a supported compression format) and file1 from which the com- + pression format suffix has been stripped. If two files are specified, + then they are uncompressed if necessary and fed to cmp(1) or diff(1). + The exit status from cmp(1) or diff(1) is preserved unless a decompres- + sion error occurs; then exit status is 2. + + The names lzcmp and lzdiff are provided for backward compatibility with + LZMA Utils. + +SEE ALSO + cmp(1), diff(1), xz(1), gzip(1), bzip2(1), lzop(1), zstd(1), zdiff(1) + +BUGS + Messages from the cmp(1) or diff(1) programs refer to temporary file- + names instead of those specified. + + + +Tukaani 2021-06-04 XZDIFF(1) diff --git a/doc/man/txt/xzgrep.txt b/doc/man/txt/xzgrep.txt new file mode 100644 index 0000000..596520c --- /dev/null +++ b/doc/man/txt/xzgrep.txt @@ -0,0 +1,49 @@ +XZGREP(1) XZ Utils XZGREP(1) + + + +NAME + xzgrep - search compressed files for a regular expression + +SYNOPSIS + xzgrep [grep_options] [-e] pattern [file...] + xzegrep ... + xzfgrep ... + lzgrep ... + lzegrep ... + lzfgrep ... + +DESCRIPTION + xzgrep invokes grep(1) on files which may be either uncompressed or + compressed with xz(1), lzma(1), gzip(1), bzip2(1), lzop(1), or zstd(1). + All options specified are passed directly to grep(1). + + If no file is specified, then standard input is decompressed if neces- + sary and fed to grep(1). When reading from standard input, gzip(1), + bzip2(1), lzop(1), and zstd(1) compressed files are not supported. + + If xzgrep is invoked as xzegrep or xzfgrep then grep -E or grep -F is + used instead of grep(1). The same applies to names lzgrep, lzegrep, + and lzfgrep, which are provided for backward compatibility with LZMA + Utils. + +EXIT STATUS + 0 At least one match was found from at least one of the input + files. No errors occurred. + + 1 No matches were found from any of the input files. No errors + occurred. + + >1 One or more errors occurred. It is unknown if matches were + found. + +ENVIRONMENT + GREP If the GREP environment variable is set, xzgrep uses it instead + of grep(1), grep -E, or grep -F. + +SEE ALSO + grep(1), xz(1), gzip(1), bzip2(1), lzop(1), zstd(1), zgrep(1) + + + +Tukaani 2022-07-19 XZGREP(1) diff --git a/doc/man/txt/xzless.txt b/doc/man/txt/xzless.txt new file mode 100644 index 0000000..5c14c80 --- /dev/null +++ b/doc/man/txt/xzless.txt @@ -0,0 +1,39 @@ +XZLESS(1) XZ Utils XZLESS(1) + + + +NAME + xzless, lzless - view xz or lzma compressed (text) files + +SYNOPSIS + xzless [file...] + lzless [file...] + +DESCRIPTION + xzless is a filter that displays text from compressed files to a termi- + nal. It works on files compressed with xz(1) or lzma(1). If no files + are given, xzless reads from standard input. + + xzless uses less(1) to present its output. Unlike xzmore, its choice + of pager cannot be altered by setting an environment variable. Com- + mands are based on both more(1) and vi(1) and allow back and forth + movement and searching. See the less(1) manual for more information. + + The command named lzless is provided for backward compatibility with + LZMA Utils. + +ENVIRONMENT + LESSMETACHARS + A list of characters special to the shell. Set by xzless unless + it is already set in the environment. + + LESSOPEN + Set to a command line to invoke the xz(1) decompressor for pre- + processing the input files to less(1). + +SEE ALSO + less(1), xz(1), xzmore(1), zless(1) + + + +Tukaani 2010-09-27 XZLESS(1) diff --git a/doc/man/txt/xzmore.txt b/doc/man/txt/xzmore.txt new file mode 100644 index 0000000..5a9d86c --- /dev/null +++ b/doc/man/txt/xzmore.txt @@ -0,0 +1,34 @@ +XZMORE(1) XZ Utils XZMORE(1) + + + +NAME + xzmore, lzmore - view xz or lzma compressed (text) files + +SYNOPSIS + xzmore [file...] + lzmore [file...] + +DESCRIPTION + xzmore is a filter which allows examination of xz(1) or lzma(1) com- + pressed text files one screenful at a time on a soft-copy terminal. + + To use a pager other than the default more, set environment variable + PAGER to the name of the desired program. The name lzmore is provided + for backward compatibility with LZMA Utils. + + e or q When the prompt --More--(Next file: file) is printed, this com- + mand causes xzmore to exit. + + s When the prompt --More--(Next file: file) is printed, this com- + mand causes xzmore to skip the next file and continue. + + For list of keyboard commands supported while actually viewing the con- + tent of a file, refer to manual of the pager you use, usually more(1). + +SEE ALSO + more(1), xz(1), xzless(1), zmore(1) + + + +Tukaani 2013-06-30 XZMORE(1) diff --git a/doc/xz-file-format.txt b/doc/xz-file-format.txt new file mode 100644 index 0000000..09c83e0 --- /dev/null +++ b/doc/xz-file-format.txt @@ -0,0 +1,1165 @@ + +The .xz File Format +=================== + +Version 1.1.0 (2022-12-11) + + + 0. Preface + 0.1. Notices and Acknowledgements + 0.2. Getting the Latest Version + 0.3. Version History + 1. Conventions + 1.1. Byte and Its Representation + 1.2. Multibyte Integers + 2. Overall Structure of .xz File + 2.1. Stream + 2.1.1. Stream Header + 2.1.1.1. Header Magic Bytes + 2.1.1.2. Stream Flags + 2.1.1.3. CRC32 + 2.1.2. Stream Footer + 2.1.2.1. CRC32 + 2.1.2.2. Backward Size + 2.1.2.3. Stream Flags + 2.1.2.4. Footer Magic Bytes + 2.2. Stream Padding + 3. Block + 3.1. Block Header + 3.1.1. Block Header Size + 3.1.2. Block Flags + 3.1.3. Compressed Size + 3.1.4. Uncompressed Size + 3.1.5. List of Filter Flags + 3.1.6. Header Padding + 3.1.7. CRC32 + 3.2. Compressed Data + 3.3. Block Padding + 3.4. Check + 4. Index + 4.1. Index Indicator + 4.2. Number of Records + 4.3. List of Records + 4.3.1. Unpadded Size + 4.3.2. Uncompressed Size + 4.4. Index Padding + 4.5. CRC32 + 5. Filter Chains + 5.1. Alignment + 5.2. Security + 5.3. Filters + 5.3.1. LZMA2 + 5.3.2. Branch/Call/Jump Filters for Executables + 5.3.3. Delta + 5.3.3.1. Format of the Encoded Output + 5.4. Custom Filter IDs + 5.4.1. Reserved Custom Filter ID Ranges + 6. Cyclic Redundancy Checks + 7. References + + +0. Preface + + This document describes the .xz file format (filename suffix + ".xz", MIME type "application/x-xz"). It is intended that this + this format replace the old .lzma format used by LZMA SDK and + LZMA Utils. + + +0.1. Notices and Acknowledgements + + This file format was designed by Lasse Collin + and Igor Pavlov. + + Special thanks for helping with this document goes to + Ville Koskinen. Thanks for helping with this document goes to + Mark Adler, H. Peter Anvin, Mikko Pouru, and Lars Wirzenius. + + This document has been put into the public domain. + + +0.2. Getting the Latest Version + + The latest official version of this document can be downloaded + from . + + Specific versions of this document have a filename + xz-file-format-X.Y.Z.txt where X.Y.Z is the version number. + For example, the version 1.0.0 of this document is available + at . + + +0.3. Version History + + Version Date Description + + 1.1.0 2022-12-11 Added ARM64 filter and clarified 32-bit + ARM endianness in Section 5.3.2, + language improvements in Section 5.4 + + 1.0.4 2009-08-27 Language improvements in Sections 1.2, + 2.1.1.2, 3.1.1, 3.1.2, and 5.3.1 + + 1.0.3 2009-06-05 Spelling fixes in Sections 5.1 and 5.4 + + 1.0.2 2009-06-04 Typo fixes in Sections 4 and 5.3.1 + + 1.0.1 2009-06-01 Typo fix in Section 0.3 and minor + clarifications to Sections 2, 2.2, + 3.3, 4.4, and 5.3.2 + + 1.0.0 2009-01-14 The first official version + + +1. Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", + "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC-2119]. + + Indicating a warning means displaying a message, returning + appropriate exit status, or doing something else to let the + user know that something worth warning occurred. The operation + SHOULD still finish if a warning is indicated. + + Indicating an error means displaying a message, returning + appropriate exit status, or doing something else to let the + user know that something prevented successfully finishing the + operation. The operation MUST be aborted once an error has + been indicated. + + +1.1. Byte and Its Representation + + In this document, byte is always 8 bits. + + A "null byte" has all bits unset. That is, the value of a null + byte is 0x00. + + To represent byte blocks, this document uses notation that + is similar to the notation used in [RFC-1952]: + + +-------+ + | Foo | One byte. + +-------+ + + +---+---+ + | Foo | Two bytes; that is, some of the vertical bars + +---+---+ can be missing. + + +=======+ + | Foo | Zero or more bytes. + +=======+ + + In this document, a boxed byte or a byte sequence declared + using this notation is called "a field". The example field + above would be called "the Foo field" or plain "Foo". + + If there are many fields, they may be split to multiple lines. + This is indicated with an arrow ("--->"): + + +=====+ + | Foo | + +=====+ + + +=====+ + ---> | Bar | + +=====+ + + The above is equivalent to this: + + +=====+=====+ + | Foo | Bar | + +=====+=====+ + + +1.2. Multibyte Integers + + Multibyte integers of static length, such as CRC values, + are stored in little endian byte order (least significant + byte first). + + When smaller values are more likely than bigger values (for + example file sizes), multibyte integers are encoded in a + variable-length representation: + - Numbers in the range [0, 127] are copied as is, and take + one byte of space. + - Bigger numbers will occupy two or more bytes. All but the + last byte of the multibyte representation have the highest + (eighth) bit set. + + For now, the value of the variable-length integers is limited + to 63 bits, which limits the encoded size of the integer to + nine bytes. These limits may be increased in the future if + needed. + + The following C code illustrates encoding and decoding of + variable-length integers. The functions return the number of + bytes occupied by the integer (1-9), or zero on error. + + #include + #include + + size_t + encode(uint8_t buf[static 9], uint64_t num) + { + if (num > UINT64_MAX / 2) + return 0; + + size_t i = 0; + + while (num >= 0x80) { + buf[i++] = (uint8_t)(num) | 0x80; + num >>= 7; + } + + buf[i++] = (uint8_t)(num); + + return i; + } + + size_t + decode(const uint8_t buf[], size_t size_max, uint64_t *num) + { + if (size_max == 0) + return 0; + + if (size_max > 9) + size_max = 9; + + *num = buf[0] & 0x7F; + size_t i = 0; + + while (buf[i++] & 0x80) { + if (i >= size_max || buf[i] == 0x00) + return 0; + + *num |= (uint64_t)(buf[i] & 0x7F) << (i * 7); + } + + return i; + } + + +2. Overall Structure of .xz File + + A standalone .xz files consist of one or more Streams which may + have Stream Padding between or after them: + + +========+================+========+================+ + | Stream | Stream Padding | Stream | Stream Padding | ... + +========+================+========+================+ + + The sizes of Stream and Stream Padding are always multiples + of four bytes, thus the size of every valid .xz file MUST be + a multiple of four bytes. + + While a typical file contains only one Stream and no Stream + Padding, a decoder handling standalone .xz files SHOULD support + files that have more than one Stream or Stream Padding. + + In contrast to standalone .xz files, when the .xz file format + is used as an internal part of some other file format or + communication protocol, it usually is expected that the decoder + stops after the first Stream, and doesn't look for Stream + Padding or possibly other Streams. + + +2.1. Stream + + +-+-+-+-+-+-+-+-+-+-+-+-+=======+=======+ +=======+ + | Stream Header | Block | Block | ... | Block | + +-+-+-+-+-+-+-+-+-+-+-+-+=======+=======+ +=======+ + + +=======+-+-+-+-+-+-+-+-+-+-+-+-+ + ---> | Index | Stream Footer | + +=======+-+-+-+-+-+-+-+-+-+-+-+-+ + + All the above fields have a size that is a multiple of four. If + Stream is used as an internal part of another file format, it + is RECOMMENDED to make the Stream start at an offset that is + a multiple of four bytes. + + Stream Header, Index, and Stream Footer are always present in + a Stream. The maximum size of the Index field is 16 GiB (2^34). + + There are zero or more Blocks. The maximum number of Blocks is + limited only by the maximum size of the Index field. + + Total size of a Stream MUST be less than 8 EiB (2^63 bytes). + The same limit applies to the total amount of uncompressed + data stored in a Stream. + + If an implementation supports handling .xz files with multiple + concatenated Streams, it MAY apply the above limits to the file + as a whole instead of limiting per Stream basis. + + +2.1.1. Stream Header + + +---+---+---+---+---+---+-------+------+--+--+--+--+ + | Header Magic Bytes | Stream Flags | CRC32 | + +---+---+---+---+---+---+-------+------+--+--+--+--+ + + +2.1.1.1. Header Magic Bytes + + The first six (6) bytes of the Stream are so called Header + Magic Bytes. They can be used to identify the file type. + + Using a C array and ASCII: + const uint8_t HEADER_MAGIC[6] + = { 0xFD, '7', 'z', 'X', 'Z', 0x00 }; + + In plain hexadecimal: + FD 37 7A 58 5A 00 + + Notes: + - The first byte (0xFD) was chosen so that the files cannot + be erroneously detected as being in .lzma format, in which + the first byte is in the range [0x00, 0xE0]. + - The sixth byte (0x00) was chosen to prevent applications + from misdetecting the file as a text file. + + If the Header Magic Bytes don't match, the decoder MUST + indicate an error. + + +2.1.1.2. Stream Flags + + The first byte of Stream Flags is always a null byte. In the + future, this byte may be used to indicate a new Stream version + or other Stream properties. + + The second byte of Stream Flags is a bit field: + + Bit(s) Mask Description + 0-3 0x0F Type of Check (see Section 3.4): + ID Size Check name + 0x00 0 bytes None + 0x01 4 bytes CRC32 + 0x02 4 bytes (Reserved) + 0x03 4 bytes (Reserved) + 0x04 8 bytes CRC64 + 0x05 8 bytes (Reserved) + 0x06 8 bytes (Reserved) + 0x07 16 bytes (Reserved) + 0x08 16 bytes (Reserved) + 0x09 16 bytes (Reserved) + 0x0A 32 bytes SHA-256 + 0x0B 32 bytes (Reserved) + 0x0C 32 bytes (Reserved) + 0x0D 64 bytes (Reserved) + 0x0E 64 bytes (Reserved) + 0x0F 64 bytes (Reserved) + 4-7 0xF0 Reserved for future use; MUST be zero for now. + + Implementations SHOULD support at least the Check IDs 0x00 + (None) and 0x01 (CRC32). Supporting other Check IDs is + OPTIONAL. If an unsupported Check is used, the decoder SHOULD + indicate a warning or error. + + If any reserved bit is set, the decoder MUST indicate an error. + It is possible that there is a new field present which the + decoder is not aware of, and can thus parse the Stream Header + incorrectly. + + +2.1.1.3. CRC32 + + The CRC32 is calculated from the Stream Flags field. It is + stored as an unsigned 32-bit little endian integer. If the + calculated value does not match the stored one, the decoder + MUST indicate an error. + + The idea is that Stream Flags would always be two bytes, even + if new features are needed. This way old decoders will be able + to verify the CRC32 calculated from Stream Flags, and thus + distinguish between corrupt files (CRC32 doesn't match) and + files that the decoder doesn't support (CRC32 matches but + Stream Flags has reserved bits set). + + +2.1.2. Stream Footer + + +-+-+-+-+---+---+---+---+-------+------+----------+---------+ + | CRC32 | Backward Size | Stream Flags | Footer Magic Bytes | + +-+-+-+-+---+---+---+---+-------+------+----------+---------+ + + +2.1.2.1. CRC32 + + The CRC32 is calculated from the Backward Size and Stream Flags + fields. It is stored as an unsigned 32-bit little endian + integer. If the calculated value does not match the stored one, + the decoder MUST indicate an error. + + The reason to have the CRC32 field before the Backward Size and + Stream Flags fields is to keep the four-byte fields aligned to + a multiple of four bytes. + + +2.1.2.2. Backward Size + + Backward Size is stored as a 32-bit little endian integer, + which indicates the size of the Index field as multiple of + four bytes, minimum value being four bytes: + + real_backward_size = (stored_backward_size + 1) * 4; + + If the stored value does not match the real size of the Index + field, the decoder MUST indicate an error. + + Using a fixed-size integer to store Backward Size makes + it slightly simpler to parse the Stream Footer when the + application needs to parse the Stream backwards. + + +2.1.2.3. Stream Flags + + This is a copy of the Stream Flags field from the Stream + Header. The information stored to Stream Flags is needed + when parsing the Stream backwards. The decoder MUST compare + the Stream Flags fields in both Stream Header and Stream + Footer, and indicate an error if they are not identical. + + +2.1.2.4. Footer Magic Bytes + + As the last step of the decoding process, the decoder MUST + verify the existence of Footer Magic Bytes. If they don't + match, an error MUST be indicated. + + Using a C array and ASCII: + const uint8_t FOOTER_MAGIC[2] = { 'Y', 'Z' }; + + In hexadecimal: + 59 5A + + The primary reason to have Footer Magic Bytes is to make + it easier to detect incomplete files quickly, without + uncompressing. If the file does not end with Footer Magic Bytes + (excluding Stream Padding described in Section 2.2), it cannot + be undamaged, unless someone has intentionally appended garbage + after the end of the Stream. + + +2.2. Stream Padding + + Only the decoders that support decoding of concatenated Streams + MUST support Stream Padding. + + Stream Padding MUST contain only null bytes. To preserve the + four-byte alignment of consecutive Streams, the size of Stream + Padding MUST be a multiple of four bytes. Empty Stream Padding + is allowed. If these requirements are not met, the decoder MUST + indicate an error. + + Note that non-empty Stream Padding is allowed at the end of the + file; there doesn't need to be a new Stream after non-empty + Stream Padding. This can be convenient in certain situations + [GNU-tar]. + + The possibility of Stream Padding MUST be taken into account + when designing an application that parses Streams backwards, + and the application supports concatenated Streams. + + +3. Block + + +==============+=================+===============+=======+ + | Block Header | Compressed Data | Block Padding | Check | + +==============+=================+===============+=======+ + + +3.1. Block Header + + +-------------------+-------------+=================+ + | Block Header Size | Block Flags | Compressed Size | + +-------------------+-------------+=================+ + + +===================+======================+ + ---> | Uncompressed Size | List of Filter Flags | + +===================+======================+ + + +================+--+--+--+--+ + ---> | Header Padding | CRC32 | + +================+--+--+--+--+ + + +3.1.1. Block Header Size + + This field overlaps with the Index Indicator field (see + Section 4.1). + + This field contains the size of the Block Header field, + including the Block Header Size field itself. Valid values are + in the range [0x01, 0xFF], which indicate the size of the Block + Header as multiples of four bytes, minimum size being eight + bytes: + + real_header_size = (encoded_header_size + 1) * 4; + + If a Block Header bigger than 1024 bytes is needed in the + future, a new field can be added between the Block Header and + Compressed Data fields. The presence of this new field would + be indicated in the Block Header field. + + +3.1.2. Block Flags + + The Block Flags field is a bit field: + + Bit(s) Mask Description + 0-1 0x03 Number of filters (1-4) + 2-5 0x3C Reserved for future use; MUST be zero for now. + 6 0x40 The Compressed Size field is present. + 7 0x80 The Uncompressed Size field is present. + + If any reserved bit is set, the decoder MUST indicate an error. + It is possible that there is a new field present which the + decoder is not aware of, and can thus parse the Block Header + incorrectly. + + +3.1.3. Compressed Size + + This field is present only if the appropriate bit is set in + the Block Flags field (see Section 3.1.2). + + The Compressed Size field contains the size of the Compressed + Data field, which MUST be non-zero. Compressed Size is stored + using the encoding described in Section 1.2. If the Compressed + Size doesn't match the size of the Compressed Data field, the + decoder MUST indicate an error. + + +3.1.4. Uncompressed Size + + This field is present only if the appropriate bit is set in + the Block Flags field (see Section 3.1.2). + + The Uncompressed Size field contains the size of the Block + after uncompressing. Uncompressed Size is stored using the + encoding described in Section 1.2. If the Uncompressed Size + does not match the real uncompressed size, the decoder MUST + indicate an error. + + Storing the Compressed Size and Uncompressed Size fields serves + several purposes: + - The decoder knows how much memory it needs to allocate + for a temporary buffer in multithreaded mode. + - Simple error detection: wrong size indicates a broken file. + - Seeking forwards to a specific location in streamed mode. + + It should be noted that the only reliable way to determine + the real uncompressed size is to uncompress the Block, + because the Block Header and Index fields may contain + (intentionally or unintentionally) invalid information. + + +3.1.5. List of Filter Flags + + +================+================+ +================+ + | Filter 0 Flags | Filter 1 Flags | ... | Filter n Flags | + +================+================+ +================+ + + The number of Filter Flags fields is stored in the Block Flags + field (see Section 3.1.2). + + The format of each Filter Flags field is as follows: + + +===========+====================+===================+ + | Filter ID | Size of Properties | Filter Properties | + +===========+====================+===================+ + + Both Filter ID and Size of Properties are stored using the + encoding described in Section 1.2. Size of Properties indicates + the size of the Filter Properties field as bytes. The list of + officially defined Filter IDs and the formats of their Filter + Properties are described in Section 5.3. + + Filter IDs greater than or equal to 0x4000_0000_0000_0000 + (2^62) are reserved for implementation-specific internal use. + These Filter IDs MUST never be used in List of Filter Flags. + + +3.1.6. Header Padding + + This field contains as many null byte as it is needed to make + the Block Header have the size specified in Block Header Size. + If any of the bytes are not null bytes, the decoder MUST + indicate an error. It is possible that there is a new field + present which the decoder is not aware of, and can thus parse + the Block Header incorrectly. + + +3.1.7. CRC32 + + The CRC32 is calculated over everything in the Block Header + field except the CRC32 field itself. It is stored as an + unsigned 32-bit little endian integer. If the calculated + value does not match the stored one, the decoder MUST indicate + an error. + + By verifying the CRC32 of the Block Header before parsing the + actual contents allows the decoder to distinguish between + corrupt and unsupported files. + + +3.2. Compressed Data + + The format of Compressed Data depends on Block Flags and List + of Filter Flags. Excluding the descriptions of the simplest + filters in Section 5.3, the format of the filter-specific + encoded data is out of scope of this document. + + +3.3. Block Padding + + Block Padding MUST contain 0-3 null bytes to make the size of + the Block a multiple of four bytes. This can be needed when + the size of Compressed Data is not a multiple of four. If any + of the bytes in Block Padding are not null bytes, the decoder + MUST indicate an error. + + +3.4. Check + + The type and size of the Check field depends on which bits + are set in the Stream Flags field (see Section 2.1.1.2). + + The Check, when used, is calculated from the original + uncompressed data. If the calculated Check does not match the + stored one, the decoder MUST indicate an error. If the selected + type of Check is not supported by the decoder, it SHOULD + indicate a warning or error. + + +4. Index + + +-----------------+===================+ + | Index Indicator | Number of Records | + +-----------------+===================+ + + +=================+===============+-+-+-+-+ + ---> | List of Records | Index Padding | CRC32 | + +=================+===============+-+-+-+-+ + + Index serves several purposes. Using it, one can + - verify that all Blocks in a Stream have been processed; + - find out the uncompressed size of a Stream; and + - quickly access the beginning of any Block (random access). + + +4.1. Index Indicator + + This field overlaps with the Block Header Size field (see + Section 3.1.1). The value of Index Indicator is always 0x00. + + +4.2. Number of Records + + This field indicates how many Records there are in the List + of Records field, and thus how many Blocks there are in the + Stream. The value is stored using the encoding described in + Section 1.2. If the decoder has decoded all the Blocks of the + Stream, and then notices that the Number of Records doesn't + match the real number of Blocks, the decoder MUST indicate an + error. + + +4.3. List of Records + + List of Records consists of as many Records as indicated by the + Number of Records field: + + +========+========+ + | Record | Record | ... + +========+========+ + + Each Record contains information about one Block: + + +===============+===================+ + | Unpadded Size | Uncompressed Size | + +===============+===================+ + + If the decoder has decoded all the Blocks of the Stream, it + MUST verify that the contents of the Records match the real + Unpadded Size and Uncompressed Size of the respective Blocks. + + Implementation hint: It is possible to verify the Index with + constant memory usage by calculating for example SHA-256 of + both the real size values and the List of Records, then + comparing the hash values. Implementing this using + non-cryptographic hash like CRC32 SHOULD be avoided unless + small code size is important. + + If the decoder supports random-access reading, it MUST verify + that Unpadded Size and Uncompressed Size of every completely + decoded Block match the sizes stored in the Index. If only + partial Block is decoded, the decoder MUST verify that the + processed sizes don't exceed the sizes stored in the Index. + + +4.3.1. Unpadded Size + + This field indicates the size of the Block excluding the Block + Padding field. That is, Unpadded Size is the size of the Block + Header, Compressed Data, and Check fields. Unpadded Size is + stored using the encoding described in Section 1.2. The value + MUST never be zero; with the current structure of Blocks, the + actual minimum value for Unpadded Size is five. + + Implementation note: Because the size of the Block Padding + field is not included in Unpadded Size, calculating the total + size of a Stream or doing random-access reading requires + calculating the actual size of the Blocks by rounding Unpadded + Sizes up to the next multiple of four. + + The reason to exclude Block Padding from Unpadded Size is to + ease making a raw copy of Compressed Data without Block + Padding. This can be useful, for example, if someone wants + to convert Streams to some other file format quickly. + + +4.3.2. Uncompressed Size + + This field indicates the Uncompressed Size of the respective + Block as bytes. The value is stored using the encoding + described in Section 1.2. + + +4.4. Index Padding + + This field MUST contain 0-3 null bytes to pad the Index to + a multiple of four bytes. If any of the bytes are not null + bytes, the decoder MUST indicate an error. + + +4.5. CRC32 + + The CRC32 is calculated over everything in the Index field + except the CRC32 field itself. The CRC32 is stored as an + unsigned 32-bit little endian integer. If the calculated + value does not match the stored one, the decoder MUST indicate + an error. + + +5. Filter Chains + + The Block Flags field defines how many filters are used. When + more than one filter is used, the filters are chained; that is, + the output of one filter is the input of another filter. The + following figure illustrates the direction of data flow. + + v Uncompressed Data ^ + | Filter 0 | + Encoder | Filter 1 | Decoder + | Filter n | + v Compressed Data ^ + + +5.1. Alignment + + Alignment of uncompressed input data is usually the job of + the application producing the data. For example, to get the + best results, an archiver tool should make sure that all + PowerPC executable files in the archive stream start at + offsets that are multiples of four bytes. + + Some filters, for example LZMA2, can be configured to take + advantage of specified alignment of input data. Note that + taking advantage of aligned input can be beneficial also when + a filter is not the first filter in the chain. For example, + if you compress PowerPC executables, you may want to use the + PowerPC filter and chain that with the LZMA2 filter. Because + not only the input but also the output alignment of the PowerPC + filter is four bytes, it is now beneficial to set LZMA2 + settings so that the LZMA2 encoder can take advantage of its + four-byte-aligned input data. + + The output of the last filter in the chain is stored to the + Compressed Data field, which is is guaranteed to be aligned + to a multiple of four bytes relative to the beginning of the + Stream. This can increase + - speed, if the filtered data is handled multiple bytes at + a time by the filter-specific encoder and decoder, + because accessing aligned data in computer memory is + usually faster; and + - compression ratio, if the output data is later compressed + with an external compression tool. + + +5.2. Security + + If filters would be allowed to be chained freely, it would be + possible to create malicious files, that would be very slow to + decode. Such files could be used to create denial of service + attacks. + + Slow files could occur when multiple filters are chained: + + v Compressed input data + | Filter 1 decoder (last filter) + | Filter 0 decoder (non-last filter) + v Uncompressed output data + + The decoder of the last filter in the chain produces a lot of + output from little input. Another filter in the chain takes the + output of the last filter, and produces very little output + while consuming a lot of input. As a result, a lot of data is + moved inside the filter chain, but the filter chain as a whole + gets very little work done. + + To prevent this kind of slow files, there are restrictions on + how the filters can be chained. These restrictions MUST be + taken into account when designing new filters. + + The maximum number of filters in the chain has been limited to + four, thus there can be at maximum of three non-last filters. + Of these three non-last filters, only two are allowed to change + the size of the data. + + The non-last filters, that change the size of the data, MUST + have a limit how much the decoder can compress the data: the + decoder SHOULD produce at least n bytes of output when the + filter is given 2n bytes of input. This limit is not + absolute, but significant deviations MUST be avoided. + + The above limitations guarantee that if the last filter in the + chain produces 4n bytes of output, the chain as a whole will + produce at least n bytes of output. + + +5.3. Filters + +5.3.1. LZMA2 + + LZMA (Lempel-Ziv-Markov chain-Algorithm) is a general-purpose + compression algorithm with high compression ratio and fast + decompression. LZMA is based on LZ77 and range coding + algorithms. + + LZMA2 is an extension on top of the original LZMA. LZMA2 uses + LZMA internally, but adds support for flushing the encoder, + uncompressed chunks, eases stateful decoder implementations, + and improves support for multithreading. Thus, the plain LZMA + will not be supported in this file format. + + Filter ID: 0x21 + Size of Filter Properties: 1 byte + Changes size of data: Yes + Allow as a non-last filter: No + Allow as the last filter: Yes + + Preferred alignment: + Input data: Adjustable to 1/2/4/8/16 byte(s) + Output data: 1 byte + + The format of the one-byte Filter Properties field is as + follows: + + Bits Mask Description + 0-5 0x3F Dictionary Size + 6-7 0xC0 Reserved for future use; MUST be zero for now. + + Dictionary Size is encoded with one-bit mantissa and five-bit + exponent. The smallest dictionary size is 4 KiB and the biggest + is 4 GiB. + + Raw value Mantissa Exponent Dictionary size + 0 2 11 4 KiB + 1 3 11 6 KiB + 2 2 12 8 KiB + 3 3 12 12 KiB + 4 2 13 16 KiB + 5 3 13 24 KiB + 6 2 14 32 KiB + ... ... ... ... + 35 3 27 768 MiB + 36 2 28 1024 MiB + 37 3 29 1536 MiB + 38 2 30 2048 MiB + 39 3 30 3072 MiB + 40 2 31 4096 MiB - 1 B + + Instead of having a table in the decoder, the dictionary size + can be decoded using the following C code: + + const uint8_t bits = get_dictionary_flags() & 0x3F; + if (bits > 40) + return DICTIONARY_TOO_BIG; // Bigger than 4 GiB + + uint32_t dictionary_size; + if (bits == 40) { + dictionary_size = UINT32_MAX; + } else { + dictionary_size = 2 | (bits & 1); + dictionary_size <<= bits / 2 + 11; + } + + +5.3.2. Branch/Call/Jump Filters for Executables + + These filters convert relative branch, call, and jump + instructions to their absolute counterparts in executable + files. This conversion increases redundancy and thus + compression ratio. + + Size of Filter Properties: 0 or 4 bytes + Changes size of data: No + Allow as a non-last filter: Yes + Allow as the last filter: No + + Below is the list of filters in this category. The alignment + is the same for both input and output data. + + Filter ID Alignment Description + 0x04 1 byte x86 filter (BCJ) + 0x05 4 bytes PowerPC (big endian) filter + 0x06 16 bytes IA64 filter + 0x07 4 bytes ARM filter [1] + 0x08 2 bytes ARM Thumb filter [1] + 0x09 4 bytes SPARC filter + 0x0A 4 bytes ARM64 filter [2] + + [1] These are for little endian instruction encoding. + This must not be confused with data endianness. + A processor configured for big endian data access + may still use little endian instruction encoding. + The filters don't care about the data endianness. + + [2] 4096-byte alignment gives the best results + because the address in the ADRP instruction + is a multiple of 4096 bytes. + + If the size of Filter Properties is four bytes, the Filter + Properties field contains the start offset used for address + conversions. It is stored as an unsigned 32-bit little endian + integer. The start offset MUST be a multiple of the alignment + of the filter as listed in the table above; if it isn't, the + decoder MUST indicate an error. If the size of Filter + Properties is zero, the start offset is zero. + + Setting the start offset may be useful if an executable has + multiple sections, and there are many cross-section calls. + Taking advantage of this feature usually requires usage of + the Subblock filter, whose design is not complete yet. + + +5.3.3. Delta + + The Delta filter may increase compression ratio when the value + of the next byte correlates with the value of an earlier byte + at specified distance. + + Filter ID: 0x03 + Size of Filter Properties: 1 byte + Changes size of data: No + Allow as a non-last filter: Yes + Allow as the last filter: No + + Preferred alignment: + Input data: 1 byte + Output data: Same as the original input data + + The Properties byte indicates the delta distance, which can be + 1-256 bytes backwards from the current byte: 0x00 indicates + distance of 1 byte and 0xFF distance of 256 bytes. + + +5.3.3.1. Format of the Encoded Output + + The code below illustrates both encoding and decoding with + the Delta filter. + + // Distance is in the range [1, 256]. + const unsigned int distance = get_properties_byte() + 1; + uint8_t pos = 0; + uint8_t delta[256]; + + memset(delta, 0, sizeof(delta)); + + while (1) { + const int byte = read_byte(); + if (byte == EOF) + break; + + uint8_t tmp = delta[(uint8_t)(distance + pos)]; + if (is_encoder) { + tmp = (uint8_t)(byte) - tmp; + delta[pos] = (uint8_t)(byte); + } else { + tmp = (uint8_t)(byte) + tmp; + delta[pos] = tmp; + } + + write_byte(tmp); + --pos; + } + + +5.4. Custom Filter IDs + + If a developer wants to use custom Filter IDs, there are two + choices. The first choice is to contact Lasse Collin and ask + him to allocate a range of IDs for the developer. + + The second choice is to generate a 40-bit random integer + which the developer can use as a personal Developer ID. + To minimize the risk of collisions, Developer ID has to be + a randomly generated integer, not manually selected "hex word". + The following command, which works on many free operating + systems, can be used to generate Developer ID: + + dd if=/dev/urandom bs=5 count=1 | hexdump + + The developer can then use the Developer ID to create unique + (well, hopefully unique) Filter IDs. + + Bits Mask Description + 0-15 0x0000_0000_0000_FFFF Filter ID + 16-55 0x00FF_FFFF_FFFF_0000 Developer ID + 56-62 0x3F00_0000_0000_0000 Static prefix: 0x3F + + The resulting 63-bit integer will use 9 bytes of space when + stored using the encoding described in Section 1.2. To get + a shorter ID, see the beginning of this Section how to + request a custom ID range. + + +5.4.1. Reserved Custom Filter ID Ranges + + Range Description + 0x0000_0300 - 0x0000_04FF Reserved to ease .7z compatibility + 0x0002_0000 - 0x0007_FFFF Reserved to ease .7z compatibility + 0x0200_0000 - 0x07FF_FFFF Reserved to ease .7z compatibility + + +6. Cyclic Redundancy Checks + + There are several incompatible variations to calculate CRC32 + and CRC64. For simplicity and clarity, complete examples are + provided to calculate the checks as they are used in this file + format. Implementations MAY use different code as long as it + gives identical results. + + The program below reads data from standard input, calculates + the CRC32 and CRC64 values, and prints the calculated values + as big endian hexadecimal strings to standard output. + + #include + #include + #include + + uint32_t crc32_table[256]; + uint64_t crc64_table[256]; + + void + init(void) + { + static const uint32_t poly32 = UINT32_C(0xEDB88320); + static const uint64_t poly64 + = UINT64_C(0xC96C5795D7870F42); + + for (size_t i = 0; i < 256; ++i) { + uint32_t crc32 = i; + uint64_t crc64 = i; + + for (size_t j = 0; j < 8; ++j) { + if (crc32 & 1) + crc32 = (crc32 >> 1) ^ poly32; + else + crc32 >>= 1; + + if (crc64 & 1) + crc64 = (crc64 >> 1) ^ poly64; + else + crc64 >>= 1; + } + + crc32_table[i] = crc32; + crc64_table[i] = crc64; + } + } + + uint32_t + crc32(const uint8_t *buf, size_t size, uint32_t crc) + { + crc = ~crc; + for (size_t i = 0; i < size; ++i) + crc = crc32_table[buf[i] ^ (crc & 0xFF)] + ^ (crc >> 8); + return ~crc; + } + + uint64_t + crc64(const uint8_t *buf, size_t size, uint64_t crc) + { + crc = ~crc; + for (size_t i = 0; i < size; ++i) + crc = crc64_table[buf[i] ^ (crc & 0xFF)] + ^ (crc >> 8); + return ~crc; + } + + int + main() + { + init(); + + uint32_t value32 = 0; + uint64_t value64 = 0; + uint64_t total_size = 0; + uint8_t buf[8192]; + + while (1) { + const size_t buf_size + = fread(buf, 1, sizeof(buf), stdin); + if (buf_size == 0) + break; + + total_size += buf_size; + value32 = crc32(buf, buf_size, value32); + value64 = crc64(buf, buf_size, value64); + } + + printf("Bytes: %" PRIu64 "\n", total_size); + printf("CRC-32: 0x%08" PRIX32 "\n", value32); + printf("CRC-64: 0x%016" PRIX64 "\n", value64); + + return 0; + } + + +7. References + + LZMA SDK - The original LZMA implementation + http://7-zip.org/sdk.html + + LZMA Utils - LZMA adapted to POSIX-like systems + http://tukaani.org/lzma/ + + XZ Utils - The next generation of LZMA Utils + http://tukaani.org/xz/ + + [RFC-1952] + GZIP file format specification version 4.3 + http://www.ietf.org/rfc/rfc1952.txt + - Notation of byte boxes in section "2.1. Overall conventions" + + [RFC-2119] + Key words for use in RFCs to Indicate Requirement Levels + http://www.ietf.org/rfc/rfc2119.txt + + [GNU-tar] + GNU tar 1.21 manual + http://www.gnu.org/software/tar/manual/html_node/Blocking-Factor.html + - Node 9.4.2 "Blocking Factor", paragraph that begins + "gzip will complain about trailing garbage" + - Note that this URL points to the latest version of the + manual, and may some day not contain the note which is in + 1.21. For the exact version of the manual, download GNU + tar 1.21: ftp://ftp.gnu.org/pub/gnu/tar/tar-1.21.tar.gz + -- cgit v1.2.3