michael@0: LZMA SDK 4.40
michael@0: -------------
michael@0: 
michael@0: LZMA SDK   Copyright (C) 1999-2006 Igor Pavlov
michael@0: 
michael@0: LZMA SDK provides the documentation, samples, header files, libraries, 
michael@0: and tools you need to develop applications that use LZMA compression.
michael@0: 
michael@0: LZMA is default and general compression method of 7z format
michael@0: in 7-Zip compression program (www.7-zip.org). LZMA provides high 
michael@0: compression ratio and very fast decompression.
michael@0: 
michael@0: LZMA is an improved version of famous LZ77 compression algorithm. 
michael@0: It was improved in way of maximum increasing of compression ratio,
michael@0: keeping high decompression speed and low memory requirements for 
michael@0: decompressing.
michael@0: 
michael@0: 
michael@0: 
michael@0: LICENSE
michael@0: -------
michael@0: 
michael@0: LZMA SDK is available under any of the following licenses:
michael@0: 
michael@0: 1) GNU Lesser General Public License (GNU LGPL)
michael@0: 2) Common Public License (CPL)
michael@0: 3) Simplified license for unmodified code (read SPECIAL EXCEPTION) 
michael@0: 4) Proprietary license 
michael@0: 
michael@0: It means that you can select one of these four options and follow rules of that license.
michael@0: 
michael@0: 
michael@0: 1,2) GNU LGPL and CPL licenses are pretty similar and both these
michael@0: licenses are classified as 
michael@0:  - "Free software licenses" at http://www.gnu.org/ 
michael@0:  - "OSI-approved" at http://www.opensource.org/
michael@0: 
michael@0: 
michael@0: 3) SPECIAL EXCEPTION
michael@0: 
michael@0: Igor Pavlov, as the author of this code, expressly permits you 
michael@0: to statically or dynamically link your code (or bind by name) 
michael@0: to the files from LZMA SDK without subjecting your linked 
michael@0: code to the terms of the CPL or GNU LGPL. 
michael@0: Any modifications or additions to files from LZMA SDK, however, 
michael@0: are subject to the GNU LGPL or CPL terms.
michael@0: 
michael@0: SPECIAL EXCEPTION allows you to use LZMA SDK in applications with closed code, 
michael@0: while you keep LZMA SDK code unmodified.
michael@0: 
michael@0: 
michael@0: SPECIAL EXCEPTION #2: Igor Pavlov, as the author of this code, expressly permits 
michael@0: you to use this code under the same terms and conditions contained in the License 
michael@0: Agreement you have for any previous version of LZMA SDK developed by Igor Pavlov.
michael@0: 
michael@0: SPECIAL EXCEPTION #2 allows owners of proprietary licenses to use latest version 
michael@0: of LZMA SDK as update for previous versions.
michael@0: 
michael@0: 
michael@0: SPECIAL EXCEPTION #3: Igor Pavlov, as the author of this code, expressly permits 
michael@0: you to use code of the following files: 
michael@0: BranchTypes.h, LzmaTypes.h, LzmaTest.c, LzmaStateTest.c, LzmaAlone.cpp, 
michael@0: LzmaAlone.cs, LzmaAlone.java
michael@0: as public domain code. 
michael@0: 
michael@0: 
michael@0: 4) Proprietary license
michael@0: 
michael@0: LZMA SDK also can be available under a proprietary license which 
michael@0: can include:
michael@0: 
michael@0: 1) Right to modify code without subjecting modified code to the 
michael@0: terms of the CPL or GNU LGPL
michael@0: 2) Technical support for code
michael@0: 
michael@0: To request such proprietary license or any additional consultations,
michael@0: send email message from that page:
michael@0: http://www.7-zip.org/support.html
michael@0: 
michael@0: 
michael@0: You should have received a copy of the GNU Lesser General Public
michael@0: License along with this library; if not, write to the Free Software
michael@0: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
michael@0: 
michael@0: You should have received a copy of the Common Public License
michael@0: along with this library.
michael@0: 
michael@0: 
michael@0: LZMA SDK Contents
michael@0: -----------------
michael@0: 
michael@0: LZMA SDK includes:
michael@0: 
michael@0:   - C++ source code of LZMA compressing and decompressing
michael@0:   - ANSI-C compatible source code for LZMA decompressing
michael@0:   - C# source code for LZMA compressing and decompressing
michael@0:   - Java source code for LZMA compressing and decompressing
michael@0:   - Compiled file->file LZMA compressing/decompressing program for Windows system
michael@0: 
michael@0: ANSI-C LZMA decompression code was ported from original C++ sources to C.
michael@0: Also it was simplified and optimized for code size. 
michael@0: But it is fully compatible with LZMA from 7-Zip.
michael@0: 
michael@0: 
michael@0: UNIX/Linux version 
michael@0: ------------------
michael@0: To compile C++ version of file->file LZMA, go to directory
michael@0: C/7zip/Compress/LZMA_Alone 
michael@0: and type "make" or "make clean all" to recompile all.
michael@0: 
michael@0: In some UNIX/Linux versions you must compile LZMA with static libraries.
michael@0: To compile with static libraries, change string in makefile
michael@0: LIB = -lm
michael@0: to string  
michael@0: LIB = -lm -static
michael@0: 
michael@0: 
michael@0: Files
michael@0: ---------------------
michael@0: C        - C / CPP source code
michael@0: CS       - C# source code
michael@0: Java     - Java source code
michael@0: lzma.txt - LZMA SDK description (this file)
michael@0: 7zFormat.txt - 7z Format description
michael@0: 7zC.txt  - 7z ANSI-C Decoder description (this file)
michael@0: methods.txt  - Compression method IDs for .7z
michael@0: LGPL.txt - GNU Lesser General Public License
michael@0: CPL.html - Common Public License
michael@0: lzma.exe - Compiled file->file LZMA encoder/decoder for Windows
michael@0: history.txt - history of the LZMA SDK
michael@0: 
michael@0: 
michael@0: Source code structure
michael@0: ---------------------
michael@0: 
michael@0: C  - C / CPP files
michael@0:   Common  - common files for C++ projects
michael@0:   Windows - common files for Windows related code
michael@0:   7zip    - files related to 7-Zip Project
michael@0:     Common   - common files for 7-Zip
michael@0:     Compress - files related to compression/decompression
michael@0:       LZ     - files related to LZ (Lempel-Ziv) compression algorithm
michael@0:         BinTree    - Binary Tree Match Finder for LZ algorithm
michael@0:         HashChain  - Hash Chain Match Finder for LZ algorithm
michael@0:         Patricia   - Patricia Match Finder for LZ algorithm
michael@0:       RangeCoder   - Range Coder (special code of compression/decompression)
michael@0:       LZMA         - LZMA compression/decompression on C++
michael@0:       LZMA_Alone   - file->file LZMA compression/decompression
michael@0:       LZMA_C       - ANSI-C compatible LZMA decompressor
michael@0:         LzmaDecode.h  - interface for LZMA decoding on ANSI-C
michael@0:         LzmaDecode.c      - LZMA decoding on ANSI-C (new fastest version)
michael@0:         LzmaDecodeSize.c  - LZMA decoding on ANSI-C (old size-optimized version)
michael@0:         LzmaTest.c        - test application that decodes LZMA encoded file
michael@0:         LzmaTypes.h       - basic types for LZMA Decoder
michael@0:         LzmaStateDecode.h - interface for LZMA decoding (State version)
michael@0:         LzmaStateDecode.c - LZMA decoding on ANSI-C (State version)
michael@0:         LzmaStateTest.c   - test application (State version)
michael@0:       Branch       - Filters for x86, IA-64, ARM, ARM-Thumb, PowerPC and SPARC code
michael@0:     Archive - files related to archiving
michael@0:       7z_C     - 7z ANSI-C Decoder
michael@0: 
michael@0: CS - C# files
michael@0:   7zip
michael@0:     Common   - some common files for 7-Zip
michael@0:     Compress - files related to compression/decompression
michael@0:       LZ     - files related to LZ (Lempel-Ziv) compression algorithm
michael@0:       LZMA         - LZMA compression/decompression
michael@0:       LzmaAlone    - file->file LZMA compression/decompression
michael@0:       RangeCoder   - Range Coder (special code of compression/decompression)
michael@0: 
michael@0: Java  - Java files
michael@0:   SevenZip
michael@0:     Compression    - files related to compression/decompression
michael@0:       LZ           - files related to LZ (Lempel-Ziv) compression algorithm
michael@0:       LZMA         - LZMA compression/decompression
michael@0:       RangeCoder   - Range Coder (special code of compression/decompression)
michael@0: 
michael@0: C/C++ source code of LZMA SDK is part of 7-Zip project.
michael@0: 
michael@0: You can find ANSI-C LZMA decompressing code at folder 
michael@0:   C/7zip/Compress/LZMA_C
michael@0: 7-Zip doesn't use that ANSI-C LZMA code and that code was developed 
michael@0: specially for this SDK. And files from LZMA_C do not need files from 
michael@0: other directories of SDK for compiling.
michael@0: 
michael@0: 7-Zip source code can be downloaded from 7-Zip's SourceForge page:
michael@0: 
michael@0:   http://sourceforge.net/projects/sevenzip/
michael@0: 
michael@0: 
michael@0: LZMA features
michael@0: -------------
michael@0:   - Variable dictionary size (up to 1 GB)
michael@0:   - Estimated compressing speed: about 1 MB/s on 1 GHz CPU
michael@0:   - Estimated decompressing speed: 
michael@0:       - 8-12 MB/s on 1 GHz Intel Pentium 3 or AMD Athlon
michael@0:       - 500-1000 KB/s on 100 MHz ARM, MIPS, PowerPC or other simple RISC
michael@0:   - Small memory requirements for decompressing (8-32 KB + DictionarySize)
michael@0:   - Small code size for decompressing: 2-8 KB (depending from 
michael@0:     speed optimizations) 
michael@0: 
michael@0: LZMA decoder uses only integer operations and can be 
michael@0: implemented in any modern 32-bit CPU (or on 16-bit CPU with some conditions).
michael@0: 
michael@0: Some critical operations that affect to speed of LZMA decompression:
michael@0:   1) 32*16 bit integer multiply
michael@0:   2) Misspredicted branches (penalty mostly depends from pipeline length)
michael@0:   3) 32-bit shift and arithmetic operations
michael@0: 
michael@0: Speed of LZMA decompressing mostly depends from CPU speed.
michael@0: Memory speed has no big meaning. But if your CPU has small data cache, 
michael@0: overall weight of memory speed will slightly increase.
michael@0: 
michael@0: 
michael@0: How To Use
michael@0: ----------
michael@0: 
michael@0: Using LZMA encoder/decoder executable
michael@0: --------------------------------------
michael@0: 
michael@0: Usage:  LZMA <e|d> inputFile outputFile [<switches>...]
michael@0: 
michael@0:   e: encode file
michael@0: 
michael@0:   d: decode file
michael@0: 
michael@0:   b: Benchmark. There are two tests: compressing and decompressing 
michael@0:      with LZMA method. Benchmark shows rating in MIPS (million 
michael@0:      instructions per second). Rating value is calculated from 
michael@0:      measured speed and it is normalized with AMD Athlon 64 X2 CPU
michael@0:      results. Also Benchmark checks possible hardware errors (RAM 
michael@0:      errors in most cases). Benchmark uses these settings:
michael@0:      (-a1, -d21, -fb32, -mfbt4). You can change only -d. Also you 
michael@0:      can change number of iterations. Example for 30 iterations:
michael@0: 	LZMA b 30
michael@0:      Default number of iterations is 10.
michael@0: 
michael@0: <Switches>
michael@0:   
michael@0: 
michael@0:   -a{N}:  set compression mode 0 = fast, 1 = normal
michael@0:           default: 1 (normal)
michael@0: 
michael@0:   d{N}:   Sets Dictionary size - [0, 30], default: 23 (8MB)
michael@0:           The maximum value for dictionary size is 1 GB = 2^30 bytes.
michael@0:           Dictionary size is calculated as DictionarySize = 2^N bytes. 
michael@0:           For decompressing file compressed by LZMA method with dictionary 
michael@0:           size D = 2^N you need about D bytes of memory (RAM).
michael@0: 
michael@0:   -fb{N}: set number of fast bytes - [5, 273], default: 128
michael@0:           Usually big number gives a little bit better compression ratio 
michael@0:           and slower compression process.
michael@0: 
michael@0:   -lc{N}: set number of literal context bits - [0, 8], default: 3
michael@0:           Sometimes lc=4 gives gain for big files.
michael@0: 
michael@0:   -lp{N}: set number of literal pos bits - [0, 4], default: 0
michael@0:           lp switch is intended for periodical data when period is 
michael@0:           equal 2^N. For example, for 32-bit (4 bytes) 
michael@0:           periodical data you can use lp=2. Often it's better to set lc0, 
michael@0:           if you change lp switch.
michael@0: 
michael@0:   -pb{N}: set number of pos bits - [0, 4], default: 2
michael@0:           pb switch is intended for periodical data 
michael@0:           when period is equal 2^N.
michael@0: 
michael@0:   -mf{MF_ID}: set Match Finder. Default: bt4. 
michael@0:               Algorithms from hc* group doesn't provide good compression 
michael@0:               ratio, but they often works pretty fast in combination with 
michael@0:               fast mode (-a0).
michael@0: 
michael@0:               Memory requirements depend from dictionary size 
michael@0:               (parameter "d" in table below). 
michael@0: 
michael@0:                MF_ID     Memory                   Description
michael@0: 
michael@0:                 bt2    d *  9.5 + 4MB  Binary Tree with 2 bytes hashing.
michael@0:                 bt3    d * 11.5 + 4MB  Binary Tree with 3 bytes hashing.
michael@0:                 bt4    d * 11.5 + 4MB  Binary Tree with 4 bytes hashing.
michael@0:                 hc4    d *  7.5 + 4MB  Hash Chain with 4 bytes hashing.
michael@0: 
michael@0:   -eos:   write End Of Stream marker. By default LZMA doesn't write 
michael@0:           eos marker, since LZMA decoder knows uncompressed size 
michael@0:           stored in .lzma file header.
michael@0: 
michael@0:   -si:    Read data from stdin (it will write End Of Stream marker).
michael@0:   -so:    Write data to stdout
michael@0: 
michael@0: 
michael@0: Examples:
michael@0: 
michael@0: 1) LZMA e file.bin file.lzma -d16 -lc0 
michael@0: 
michael@0: compresses file.bin to file.lzma with 64 KB dictionary (2^16=64K)  
michael@0: and 0 literal context bits. -lc0 allows to reduce memory requirements 
michael@0: for decompression.
michael@0: 
michael@0: 
michael@0: 2) LZMA e file.bin file.lzma -lc0 -lp2
michael@0: 
michael@0: compresses file.bin to file.lzma with settings suitable 
michael@0: for 32-bit periodical data (for example, ARM or MIPS code).
michael@0: 
michael@0: 3) LZMA d file.lzma file.bin
michael@0: 
michael@0: decompresses file.lzma to file.bin.
michael@0: 
michael@0: 
michael@0: Compression ratio hints
michael@0: -----------------------
michael@0: 
michael@0: Recommendations
michael@0: ---------------
michael@0: 
michael@0: To increase compression ratio for LZMA compressing it's desirable 
michael@0: to have aligned data (if it's possible) and also it's desirable to locate
michael@0: data in such order, where code is grouped in one place and data is 
michael@0: grouped in other place (it's better than such mixing: code, data, code,
michael@0: data, ...).
michael@0: 
michael@0: 
michael@0: Using Filters
michael@0: -------------
michael@0: You can increase compression ratio for some data types, using
michael@0: special filters before compressing. For example, it's possible to 
michael@0: increase compression ratio on 5-10% for code for those CPU ISAs: 
michael@0: x86, IA-64, ARM, ARM-Thumb, PowerPC, SPARC.
michael@0: 
michael@0: You can find C/C++ source code of such filters in folder "7zip/Compress/Branch"
michael@0: 
michael@0: You can check compression ratio gain of these filters with such 
michael@0: 7-Zip commands (example for ARM code):
michael@0: No filter:
michael@0:   7z a a1.7z a.bin -m0=lzma
michael@0: 
michael@0: With filter for little-endian ARM code:
michael@0:   7z a a2.7z a.bin -m0=bc_arm -m1=lzma        
michael@0: 
michael@0: With filter for big-endian ARM code (using additional Swap4 filter):
michael@0:   7z a a3.7z a.bin -m0=swap4 -m1=bc_arm -m2=lzma
michael@0: 
michael@0: It works in such manner:
michael@0: Compressing    = Filter_encoding + LZMA_encoding
michael@0: Decompressing  = LZMA_decoding + Filter_decoding
michael@0: 
michael@0: Compressing and decompressing speed of such filters is very high,
michael@0: so it will not increase decompressing time too much.
michael@0: Moreover, it reduces decompression time for LZMA_decoding, 
michael@0: since compression ratio with filtering is higher.
michael@0: 
michael@0: These filters convert CALL (calling procedure) instructions 
michael@0: from relative offsets to absolute addresses, so such data becomes more 
michael@0: compressible. Source code of these CALL filters is pretty simple
michael@0: (about 20 lines of C++), so you can convert it from C++ version yourself.
michael@0: 
michael@0: For some ISAs (for example, for MIPS) it's impossible to get gain from such filter.
michael@0: 
michael@0: 
michael@0: LZMA compressed file format
michael@0: ---------------------------
michael@0: Offset Size Description
michael@0:   0     1   Special LZMA properties for compressed data
michael@0:   1     4   Dictionary size (little endian)
michael@0:   5     8   Uncompressed size (little endian). -1 means unknown size
michael@0:  13         Compressed data
michael@0: 
michael@0: 
michael@0: ANSI-C LZMA Decoder
michael@0: ~~~~~~~~~~~~~~~~~~~
michael@0: 
michael@0: To compile ANSI-C LZMA Decoder you can use one of the following files sets:
michael@0: 1) LzmaDecode.h + LzmaDecode.c + LzmaTest.c  (fastest version)
michael@0: 2) LzmaDecode.h + LzmaDecodeSize.c + LzmaTest.c  (old size-optimized version)
michael@0: 3) LzmaStateDecode.h + LzmaStateDecode.c + LzmaStateTest.c  (zlib-like interface)
michael@0: 
michael@0: 
michael@0: Memory requirements for LZMA decoding
michael@0: -------------------------------------
michael@0: 
michael@0: LZMA decoder doesn't allocate memory itself, so you must 
michael@0: allocate memory and send it to LZMA.
michael@0: 
michael@0: Stack usage of LZMA decoding function for local variables is not 
michael@0: larger than 200 bytes.
michael@0: 
michael@0: How To decompress data
michael@0: ----------------------
michael@0: 
michael@0: LZMA Decoder (ANSI-C version) now supports 5 interfaces:
michael@0: 1) Single-call Decompressing
michael@0: 2) Single-call Decompressing with input stream callback
michael@0: 3) Multi-call Decompressing with output buffer
michael@0: 4) Multi-call Decompressing with input callback and output buffer
michael@0: 5) Multi-call State Decompressing (zlib-like interface)
michael@0: 
michael@0: Variant-5 is similar to Variant-4, but Variant-5 doesn't use callback functions.
michael@0: 
michael@0: Decompressing steps
michael@0: -------------------
michael@0: 
michael@0: 1) read LZMA properties (5 bytes):
michael@0:    unsigned char properties[LZMA_PROPERTIES_SIZE];
michael@0: 
michael@0: 2) read uncompressed size (8 bytes, little-endian)
michael@0: 
michael@0: 3) Decode properties:
michael@0: 
michael@0:   CLzmaDecoderState state;  /* it's 24-140 bytes structure, if int is 32-bit */
michael@0: 
michael@0:   if (LzmaDecodeProperties(&state.Properties, properties, LZMA_PROPERTIES_SIZE) != LZMA_RESULT_OK)
michael@0:     return PrintError(rs, "Incorrect stream properties");
michael@0: 
michael@0: 4) Allocate memory block for internal Structures:
michael@0: 
michael@0:   state.Probs = (CProb *)malloc(LzmaGetNumProbs(&state.Properties) * sizeof(CProb));
michael@0:   if (state.Probs == 0)
michael@0:     return PrintError(rs, kCantAllocateMessage);
michael@0: 
michael@0:   LZMA decoder uses array of CProb variables as internal structure.
michael@0:   By default, CProb is unsigned_short. But you can define _LZMA_PROB32 to make 
michael@0:   it unsigned_int. It can increase speed on some 32-bit CPUs, but memory 
michael@0:   usage will be doubled in that case.
michael@0: 
michael@0: 
michael@0: 5) Main Decompressing
michael@0: 
michael@0: You must use one of the following interfaces:
michael@0: 
michael@0: 5.1 Single-call Decompressing
michael@0: -----------------------------
michael@0: When to use: RAM->RAM decompressing
michael@0: Compile files: LzmaDecode.h, LzmaDecode.c
michael@0: Compile defines: no defines
michael@0: Memory Requirements:
michael@0:   - Input buffer: compressed size
michael@0:   - Output buffer: uncompressed size
michael@0:   - LZMA Internal Structures (~16 KB for default settings) 
michael@0: 
michael@0: Interface:
michael@0:   int res = LzmaDecode(&state, 
michael@0:       inStream, compressedSize, &inProcessed,
michael@0:       outStream, outSize, &outProcessed);
michael@0: 
michael@0: 
michael@0: 5.2 Single-call Decompressing with input stream callback
michael@0: --------------------------------------------------------
michael@0: When to use: File->RAM or Flash->RAM decompressing.
michael@0: Compile files: LzmaDecode.h, LzmaDecode.c
michael@0: Compile defines: _LZMA_IN_CB
michael@0: Memory Requirements:
michael@0:   - Buffer for input stream: any size (for example, 16 KB)
michael@0:   - Output buffer: uncompressed size
michael@0:   - LZMA Internal Structures (~16 KB for default settings) 
michael@0: 
michael@0: Interface:
michael@0:   typedef struct _CBuffer
michael@0:   {
michael@0:     ILzmaInCallback InCallback;
michael@0:     FILE *File;
michael@0:     unsigned char Buffer[kInBufferSize];
michael@0:   } CBuffer;
michael@0: 
michael@0:   int LzmaReadCompressed(void *object, const unsigned char **buffer, SizeT *size)
michael@0:   {
michael@0:     CBuffer *bo = (CBuffer *)object;
michael@0:     *buffer = bo->Buffer;
michael@0:     *size = MyReadFile(bo->File, bo->Buffer, kInBufferSize);
michael@0:     return LZMA_RESULT_OK;
michael@0:   }
michael@0: 
michael@0:   CBuffer g_InBuffer;
michael@0: 
michael@0:   g_InBuffer.File = inFile;
michael@0:   g_InBuffer.InCallback.Read = LzmaReadCompressed;
michael@0:   int res = LzmaDecode(&state, 
michael@0:       &g_InBuffer.InCallback,
michael@0:       outStream, outSize, &outProcessed);
michael@0: 
michael@0: 
michael@0: 5.3 Multi-call decompressing with output buffer
michael@0: -----------------------------------------------
michael@0: When to use: RAM->File decompressing 
michael@0: Compile files: LzmaDecode.h, LzmaDecode.c
michael@0: Compile defines: _LZMA_OUT_READ
michael@0: Memory Requirements:
michael@0:  - Input buffer: compressed size
michael@0:  - Buffer for output stream: any size (for example, 16 KB)
michael@0:  - LZMA Internal Structures (~16 KB for default settings) 
michael@0:  - LZMA dictionary (dictionary size is encoded in stream properties)
michael@0:  
michael@0: Interface:
michael@0: 
michael@0:   state.Dictionary = (unsigned char *)malloc(state.Properties.DictionarySize);
michael@0: 
michael@0:   LzmaDecoderInit(&state);
michael@0:   do
michael@0:   {
michael@0:     LzmaDecode(&state,
michael@0:       inBuffer, inAvail, &inProcessed,
michael@0:       g_OutBuffer, outAvail, &outProcessed);
michael@0:     inAvail -= inProcessed;
michael@0:     inBuffer += inProcessed;
michael@0:   }
michael@0:   while you need more bytes
michael@0: 
michael@0:   see LzmaTest.c for more details.
michael@0: 
michael@0: 
michael@0: 5.4 Multi-call decompressing with input callback and output buffer
michael@0: ------------------------------------------------------------------
michael@0: When to use: File->File decompressing 
michael@0: Compile files: LzmaDecode.h, LzmaDecode.c
michael@0: Compile defines: _LZMA_IN_CB, _LZMA_OUT_READ
michael@0: Memory Requirements:
michael@0:  - Buffer for input stream: any size (for example, 16 KB)
michael@0:  - Buffer for output stream: any size (for example, 16 KB)
michael@0:  - LZMA Internal Structures (~16 KB for default settings) 
michael@0:  - LZMA dictionary (dictionary size is encoded in stream properties)
michael@0:  
michael@0: Interface:
michael@0: 
michael@0:   state.Dictionary = (unsigned char *)malloc(state.Properties.DictionarySize);
michael@0:  
michael@0:   LzmaDecoderInit(&state);
michael@0:   do
michael@0:   {
michael@0:     LzmaDecode(&state,
michael@0:       &bo.InCallback,
michael@0:       g_OutBuffer, outAvail, &outProcessed);
michael@0:   }
michael@0:   while you need more bytes
michael@0: 
michael@0:   see LzmaTest.c for more details:
michael@0: 
michael@0: 
michael@0: 5.5 Multi-call State Decompressing (zlib-like interface)
michael@0: ------------------------------------------------------------------
michael@0: When to use: file->file decompressing 
michael@0: Compile files: LzmaStateDecode.h, LzmaStateDecode.c
michael@0: Compile defines:
michael@0: Memory Requirements:
michael@0:  - Buffer for input stream: any size (for example, 16 KB)
michael@0:  - Buffer for output stream: any size (for example, 16 KB)
michael@0:  - LZMA Internal Structures (~16 KB for default settings) 
michael@0:  - LZMA dictionary (dictionary size is encoded in stream properties)
michael@0:  
michael@0: Interface:
michael@0: 
michael@0:   state.Dictionary = (unsigned char *)malloc(state.Properties.DictionarySize);
michael@0: 
michael@0:   
michael@0:   LzmaDecoderInit(&state);
michael@0:   do
michael@0:   {
michael@0:     res = LzmaDecode(&state,
michael@0:       inBuffer, inAvail, &inProcessed,
michael@0:       g_OutBuffer, outAvail, &outProcessed,
michael@0:       finishDecoding);
michael@0:     inAvail -= inProcessed;
michael@0:     inBuffer += inProcessed;
michael@0:   }
michael@0:   while you need more bytes
michael@0: 
michael@0:   see LzmaStateTest.c for more details:
michael@0: 
michael@0: 
michael@0: 6) Free all allocated blocks
michael@0: 
michael@0: 
michael@0: Note
michael@0: ----
michael@0: LzmaDecodeSize.c is size-optimized version of LzmaDecode.c.
michael@0: But compiled code of LzmaDecodeSize.c can be larger than 
michael@0: compiled code of LzmaDecode.c. So it's better to use 
michael@0: LzmaDecode.c in most cases.
michael@0: 
michael@0: 
michael@0: EXIT codes
michael@0: -----------
michael@0: 
michael@0: LZMA decoder can return one of the following codes:
michael@0: 
michael@0: #define LZMA_RESULT_OK 0
michael@0: #define LZMA_RESULT_DATA_ERROR 1
michael@0: 
michael@0: If you use callback function for input data and you return some 
michael@0: error code, LZMA Decoder also returns that code.
michael@0: 
michael@0: 
michael@0: 
michael@0: LZMA Defines
michael@0: ------------
michael@0: 
michael@0: _LZMA_IN_CB    - Use callback for input data
michael@0: 
michael@0: _LZMA_OUT_READ - Use read function for output data
michael@0: 
michael@0: _LZMA_LOC_OPT  - Enable local speed optimizations inside code.
michael@0:                  _LZMA_LOC_OPT is only for LzmaDecodeSize.c (size-optimized version).
michael@0:                  _LZMA_LOC_OPT doesn't affect LzmaDecode.c (speed-optimized version)
michael@0:                  and LzmaStateDecode.c
michael@0: 
michael@0: _LZMA_PROB32   - It can increase speed on some 32-bit CPUs, 
michael@0:                  but memory usage will be doubled in that case
michael@0: 
michael@0: _LZMA_UINT32_IS_ULONG  - Define it if int is 16-bit on your compiler
michael@0:                          and long is 32-bit.
michael@0: 
michael@0: _LZMA_SYSTEM_SIZE_T  - Define it if you want to use system's size_t.
michael@0:                        You can use it to enable 64-bit sizes supporting
michael@0: 
michael@0: 
michael@0: 
michael@0: C++ LZMA Encoder/Decoder 
michael@0: ~~~~~~~~~~~~~~~~~~~~~~~~
michael@0: C++ LZMA code use COM-like interfaces. So if you want to use it, 
michael@0: you can study basics of COM/OLE.
michael@0: 
michael@0: By default, LZMA Encoder contains all Match Finders.
michael@0: But for compressing it's enough to have just one of them.
michael@0: So for reducing size of compressing code you can define:
michael@0:   #define COMPRESS_MF_BT
michael@0:   #define COMPRESS_MF_BT4
michael@0: and it will use only bt4 match finder.
michael@0: 
michael@0: 
michael@0: ---
michael@0: 
michael@0: http://www.7-zip.org
michael@0: http://www.7-zip.org/support.html