4 LZMA SDK Copyright (C) 1999-2007 Igor Pavlov
6 LZMA SDK provides the documentation, samples, header files, libraries,
7 and tools you need to develop applications that use LZMA compression.
9 LZMA is default and general compression method of 7z format
10 in 7-Zip compression program (www.7-zip.org). LZMA provides high
11 compression ratio and very fast decompression.
13 LZMA is an improved version of famous LZ77 compression algorithm.
14 It was improved in way of maximum increasing of compression ratio,
15 keeping high decompression speed and low memory requirements for
23 LZMA SDK is available under any of the following licenses:
25 1) GNU Lesser General Public License (GNU LGPL)
26 2) Common Public License (CPL)
27 3) Simplified license for unmodified code (read SPECIAL EXCEPTION)
28 4) Proprietary license
30 It means that you can select one of these four options and follow rules of that license.
33 1,2) GNU LGPL and CPL licenses are pretty similar and both these
34 licenses are classified as
35 - "Free software licenses" at http://www.gnu.org/
36 - "OSI-approved" at http://www.opensource.org/
41 Igor Pavlov, as the author of this code, expressly permits you
42 to statically or dynamically link your code (or bind by name)
43 to the files from LZMA SDK without subjecting your linked
44 code to the terms of the CPL or GNU LGPL.
45 Any modifications or additions to files from LZMA SDK, however,
46 are subject to the GNU LGPL or CPL terms.
48 SPECIAL EXCEPTION allows you to use LZMA SDK in applications with closed code,
49 while you keep LZMA SDK code unmodified.
52 SPECIAL EXCEPTION #2: Igor Pavlov, as the author of this code, expressly permits
53 you to use this code under the same terms and conditions contained in the License
54 Agreement you have for any previous version of LZMA SDK developed by Igor Pavlov.
56 SPECIAL EXCEPTION #2 allows owners of proprietary licenses to use latest version
57 of LZMA SDK as update for previous versions.
60 SPECIAL EXCEPTION #3: Igor Pavlov, as the author of this code, expressly permits
61 you to use code of the following files:
62 BranchTypes.h, LzmaTypes.h, LzmaTest.c, LzmaStateTest.c, LzmaAlone.cpp,
63 LzmaAlone.cs, LzmaAlone.java
64 as public domain code.
67 4) Proprietary license
69 LZMA SDK also can be available under a proprietary license which
72 1) Right to modify code without subjecting modified code to the
73 terms of the CPL or GNU LGPL
74 2) Technical support for code
76 To request such proprietary license or any additional consultations,
77 send email message from that page:
78 http://www.7-zip.org/support.html
81 You should have received a copy of the GNU Lesser General Public
82 License along with this library; if not, write to the Free Software
83 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
85 You should have received a copy of the Common Public License
86 along with this library.
94 - C++ source code of LZMA compressing and decompressing
95 - ANSI-C compatible source code for LZMA decompressing
96 - C# source code for LZMA compressing and decompressing
97 - Java source code for LZMA compressing and decompressing
98 - Compiled file->file LZMA compressing/decompressing program for Windows system
100 ANSI-C LZMA decompression code was ported from original C++ sources to C.
101 Also it was simplified and optimized for code size.
102 But it is fully compatible with LZMA from 7-Zip.
107 To compile C++ version of file->file LZMA, go to directory
108 C/7zip/Compress/LZMA_Alone
109 and type "make" or "make clean all" to recompile all.
111 In some UNIX/Linux versions you must compile LZMA with static libraries.
112 To compile with static libraries, change string in makefile
119 ---------------------
121 CPP - CPP source code
123 Java - Java source code
124 lzma.txt - LZMA SDK description (this file)
125 7zFormat.txt - 7z Format description
126 7zC.txt - 7z ANSI-C Decoder description (this file)
127 methods.txt - Compression method IDs for .7z
128 LGPL.txt - GNU Lesser General Public License
129 CPL.html - Common Public License
130 lzma.exe - Compiled file->file LZMA encoder/decoder for Windows
131 history.txt - history of the LZMA SDK
134 Source code structure
135 ---------------------
138 Compress - files related to compression/decompression
139 Lz - files related to LZ (Lempel-Ziv) compression algorithm
140 Lzma - ANSI-C compatible LZMA decompressor
142 LzmaDecode.h - interface for LZMA decoding on ANSI-C
143 LzmaDecode.c - LZMA decoding on ANSI-C (new fastest version)
144 LzmaDecodeSize.c - LZMA decoding on ANSI-C (old size-optimized version)
145 LzmaTest.c - test application that decodes LZMA encoded file
146 LzmaTypes.h - basic types for LZMA Decoder
147 LzmaStateDecode.h - interface for LZMA decoding (State version)
148 LzmaStateDecode.c - LZMA decoding on ANSI-C (State version)
149 LzmaStateTest.c - test application (State version)
151 Branch - Filters for x86, IA-64, ARM, ARM-Thumb, PowerPC and SPARC code
153 Archive - files related to archiving
154 7z_C - 7z ANSI-C Decoder
159 Common - common files for C++ projects
160 Windows - common files for Windows related code
161 7zip - files related to 7-Zip Project
163 Common - common files for 7-Zip
165 Compress - files related to compression/decompression
167 LZ - files related to LZ (Lempel-Ziv) compression algorithm
170 RangeCoder - Range Coder (special code of compression/decompression)
171 LZMA - LZMA compression/decompression on C++
172 LZMA_Alone - file->file LZMA compression/decompression
174 Branch - Filters for x86, IA-64, ARM, ARM-Thumb, PowerPC and SPARC code
176 Archive - files related to archiving
178 Common - common files for archive handling
179 7z - 7z C++ Encoder/Decoder
181 Bundles - Modules that are bundles of other modules
183 Alone7z - 7zr.exe: Standalone version of 7z.exe that supports only 7z/LZMA/BCJ/BCJ2
184 Format7zR - 7zr.dll: Reduced version of 7za.dll: extracting/compressing to 7z/LZMA/BCJ/BCJ2
185 Format7zExtractR - 7zxr.dll: Reduced version of 7zxa.dll: extracting from 7z/LZMA/BCJ/BCJ2.
187 UI - User Interface files
189 Client7z - Test application for 7za.dll, 7zr.dll, 7zxr.dll
190 Common - Common UI files
191 Console - Code for console archiver
197 Common - some common files for 7-Zip
198 Compress - files related to compression/decompression
199 LZ - files related to LZ (Lempel-Ziv) compression algorithm
200 LZMA - LZMA compression/decompression
201 LzmaAlone - file->file LZMA compression/decompression
202 RangeCoder - Range Coder (special code of compression/decompression)
206 Compression - files related to compression/decompression
207 LZ - files related to LZ (Lempel-Ziv) compression algorithm
208 LZMA - LZMA compression/decompression
209 RangeCoder - Range Coder (special code of compression/decompression)
211 C/C++ source code of LZMA SDK is part of 7-Zip project.
213 You can find ANSI-C LZMA decompressing code at folder
215 7-Zip doesn't use that ANSI-C LZMA code and that code was developed
216 specially for this SDK. And files from C/7zip/Compress/Lzma do not need
217 files from other directories of SDK for compiling.
219 7-Zip source code can be downloaded from 7-Zip's SourceForge page:
221 http://sourceforge.net/projects/sevenzip/
226 - Variable dictionary size (up to 1 GB)
227 - Estimated compressing speed: about 1 MB/s on 1 GHz CPU
228 - Estimated decompressing speed:
229 - 8-12 MB/s on 1 GHz Intel Pentium 3 or AMD Athlon
230 - 500-1000 KB/s on 100 MHz ARM, MIPS, PowerPC or other simple RISC
231 - Small memory requirements for decompressing (8-32 KB + DictionarySize)
232 - Small code size for decompressing: 2-8 KB (depending from
235 LZMA decoder uses only integer operations and can be
236 implemented in any modern 32-bit CPU (or on 16-bit CPU with some conditions).
238 Some critical operations that affect to speed of LZMA decompression:
239 1) 32*16 bit integer multiply
240 2) Misspredicted branches (penalty mostly depends from pipeline length)
241 3) 32-bit shift and arithmetic operations
243 Speed of LZMA decompressing mostly depends from CPU speed.
244 Memory speed has no big meaning. But if your CPU has small data cache,
245 overall weight of memory speed will slightly increase.
251 Using LZMA encoder/decoder executable
252 --------------------------------------
254 Usage: LZMA <e|d> inputFile outputFile [<switches>...]
260 b: Benchmark. There are two tests: compressing and decompressing
261 with LZMA method. Benchmark shows rating in MIPS (million
262 instructions per second). Rating value is calculated from
263 measured speed and it is normalized with AMD Athlon 64 X2 CPU
264 results. Also Benchmark checks possible hardware errors (RAM
265 errors in most cases). Benchmark uses these settings:
266 (-a1, -d21, -fb32, -mfbt4). You can change only -d. Also you
267 can change number of iterations. Example for 30 iterations:
269 Default number of iterations is 10.
274 -a{N}: set compression mode 0 = fast, 1 = normal
277 d{N}: Sets Dictionary size - [0, 30], default: 23 (8MB)
278 The maximum value for dictionary size is 1 GB = 2^30 bytes.
279 Dictionary size is calculated as DictionarySize = 2^N bytes.
280 For decompressing file compressed by LZMA method with dictionary
281 size D = 2^N you need about D bytes of memory (RAM).
283 -fb{N}: set number of fast bytes - [5, 273], default: 128
284 Usually big number gives a little bit better compression ratio
285 and slower compression process.
287 -lc{N}: set number of literal context bits - [0, 8], default: 3
288 Sometimes lc=4 gives gain for big files.
290 -lp{N}: set number of literal pos bits - [0, 4], default: 0
291 lp switch is intended for periodical data when period is
292 equal 2^N. For example, for 32-bit (4 bytes)
293 periodical data you can use lp=2. Often it's better to set lc0,
294 if you change lp switch.
296 -pb{N}: set number of pos bits - [0, 4], default: 2
297 pb switch is intended for periodical data
298 when period is equal 2^N.
300 -mf{MF_ID}: set Match Finder. Default: bt4.
301 Algorithms from hc* group doesn't provide good compression
302 ratio, but they often works pretty fast in combination with
305 Memory requirements depend from dictionary size
306 (parameter "d" in table below).
308 MF_ID Memory Description
310 bt2 d * 9.5 + 4MB Binary Tree with 2 bytes hashing.
311 bt3 d * 11.5 + 4MB Binary Tree with 3 bytes hashing.
312 bt4 d * 11.5 + 4MB Binary Tree with 4 bytes hashing.
313 hc4 d * 7.5 + 4MB Hash Chain with 4 bytes hashing.
315 -eos: write End Of Stream marker. By default LZMA doesn't write
316 eos marker, since LZMA decoder knows uncompressed size
317 stored in .lzma file header.
319 -si: Read data from stdin (it will write End Of Stream marker).
320 -so: Write data to stdout
325 1) LZMA e file.bin file.lzma -d16 -lc0
327 compresses file.bin to file.lzma with 64 KB dictionary (2^16=64K)
328 and 0 literal context bits. -lc0 allows to reduce memory requirements
332 2) LZMA e file.bin file.lzma -lc0 -lp2
334 compresses file.bin to file.lzma with settings suitable
335 for 32-bit periodical data (for example, ARM or MIPS code).
337 3) LZMA d file.lzma file.bin
339 decompresses file.lzma to file.bin.
342 Compression ratio hints
343 -----------------------
348 To increase compression ratio for LZMA compressing it's desirable
349 to have aligned data (if it's possible) and also it's desirable to locate
350 data in such order, where code is grouped in one place and data is
351 grouped in other place (it's better than such mixing: code, data, code,
357 You can increase compression ratio for some data types, using
358 special filters before compressing. For example, it's possible to
359 increase compression ratio on 5-10% for code for those CPU ISAs:
360 x86, IA-64, ARM, ARM-Thumb, PowerPC, SPARC.
362 You can find C/C++ source code of such filters in folder "7zip/Compress/Branch"
364 You can check compression ratio gain of these filters with such
365 7-Zip commands (example for ARM code):
367 7z a a1.7z a.bin -m0=lzma
369 With filter for little-endian ARM code:
370 7z a a2.7z a.bin -m0=bc_arm -m1=lzma
372 With filter for big-endian ARM code (using additional Swap4 filter):
373 7z a a3.7z a.bin -m0=swap4 -m1=bc_arm -m2=lzma
375 It works in such manner:
376 Compressing = Filter_encoding + LZMA_encoding
377 Decompressing = LZMA_decoding + Filter_decoding
379 Compressing and decompressing speed of such filters is very high,
380 so it will not increase decompressing time too much.
381 Moreover, it reduces decompression time for LZMA_decoding,
382 since compression ratio with filtering is higher.
384 These filters convert CALL (calling procedure) instructions
385 from relative offsets to absolute addresses, so such data becomes more
386 compressible. Source code of these CALL filters is pretty simple
387 (about 20 lines of C++), so you can convert it from C++ version yourself.
389 For some ISAs (for example, for MIPS) it's impossible to get gain from such filter.
392 LZMA compressed file format
393 ---------------------------
394 Offset Size Description
395 0 1 Special LZMA properties for compressed data
396 1 4 Dictionary size (little endian)
397 5 8 Uncompressed size (little endian). -1 means unknown size
404 To compile ANSI-C LZMA Decoder you can use one of the following files sets:
405 1) LzmaDecode.h + LzmaDecode.c + LzmaTest.c (fastest version)
406 2) LzmaDecode.h + LzmaDecodeSize.c + LzmaTest.c (old size-optimized version)
407 3) LzmaStateDecode.h + LzmaStateDecode.c + LzmaStateTest.c (zlib-like interface)
410 Memory requirements for LZMA decoding
411 -------------------------------------
413 LZMA decoder doesn't allocate memory itself, so you must
414 allocate memory and send it to LZMA.
416 Stack usage of LZMA decoding function for local variables is not
417 larger than 200 bytes.
419 How To decompress data
420 ----------------------
422 LZMA Decoder (ANSI-C version) now supports 5 interfaces:
423 1) Single-call Decompressing
424 2) Single-call Decompressing with input stream callback
425 3) Multi-call Decompressing with output buffer
426 4) Multi-call Decompressing with input callback and output buffer
427 5) Multi-call State Decompressing (zlib-like interface)
429 Variant-5 is similar to Variant-4, but Variant-5 doesn't use callback functions.
434 1) read LZMA properties (5 bytes):
435 unsigned char properties[LZMA_PROPERTIES_SIZE];
437 2) read uncompressed size (8 bytes, little-endian)
439 3) Decode properties:
441 CLzmaDecoderState state; /* it's 24-140 bytes structure, if int is 32-bit */
443 if (LzmaDecodeProperties(&state.Properties, properties, LZMA_PROPERTIES_SIZE) != LZMA_RESULT_OK)
444 return PrintError(rs, "Incorrect stream properties");
446 4) Allocate memory block for internal Structures:
448 state.Probs = (CProb *)malloc(LzmaGetNumProbs(&state.Properties) * sizeof(CProb));
449 if (state.Probs == 0)
450 return PrintError(rs, kCantAllocateMessage);
452 LZMA decoder uses array of CProb variables as internal structure.
453 By default, CProb is unsigned_short. But you can define _LZMA_PROB32 to make
454 it unsigned_int. It can increase speed on some 32-bit CPUs, but memory
455 usage will be doubled in that case.
458 5) Main Decompressing
460 You must use one of the following interfaces:
462 5.1 Single-call Decompressing
463 -----------------------------
464 When to use: RAM->RAM decompressing
465 Compile files: LzmaDecode.h, LzmaDecode.c
466 Compile defines: no defines
468 - Input buffer: compressed size
469 - Output buffer: uncompressed size
470 - LZMA Internal Structures (~16 KB for default settings)
473 int res = LzmaDecode(&state,
474 inStream, compressedSize, &inProcessed,
475 outStream, outSize, &outProcessed);
478 5.2 Single-call Decompressing with input stream callback
479 --------------------------------------------------------
480 When to use: File->RAM or Flash->RAM decompressing.
481 Compile files: LzmaDecode.h, LzmaDecode.c
482 Compile defines: _LZMA_IN_CB
484 - Buffer for input stream: any size (for example, 16 KB)
485 - Output buffer: uncompressed size
486 - LZMA Internal Structures (~16 KB for default settings)
489 typedef struct _CBuffer
491 ILzmaInCallback InCallback;
493 unsigned char Buffer[kInBufferSize];
496 int LzmaReadCompressed(void *object, const unsigned char **buffer, SizeT *size)
498 CBuffer *bo = (CBuffer *)object;
499 *buffer = bo->Buffer;
500 *size = MyReadFile(bo->File, bo->Buffer, kInBufferSize);
501 return LZMA_RESULT_OK;
506 g_InBuffer.File = inFile;
507 g_InBuffer.InCallback.Read = LzmaReadCompressed;
508 int res = LzmaDecode(&state,
509 &g_InBuffer.InCallback,
510 outStream, outSize, &outProcessed);
513 5.3 Multi-call decompressing with output buffer
514 -----------------------------------------------
515 When to use: RAM->File decompressing
516 Compile files: LzmaDecode.h, LzmaDecode.c
517 Compile defines: _LZMA_OUT_READ
519 - Input buffer: compressed size
520 - Buffer for output stream: any size (for example, 16 KB)
521 - LZMA Internal Structures (~16 KB for default settings)
522 - LZMA dictionary (dictionary size is encoded in stream properties)
526 state.Dictionary = (unsigned char *)malloc(state.Properties.DictionarySize);
528 LzmaDecoderInit(&state);
532 inBuffer, inAvail, &inProcessed,
533 g_OutBuffer, outAvail, &outProcessed);
534 inAvail -= inProcessed;
535 inBuffer += inProcessed;
537 while you need more bytes
539 see LzmaTest.c for more details.
542 5.4 Multi-call decompressing with input callback and output buffer
543 ------------------------------------------------------------------
544 When to use: File->File decompressing
545 Compile files: LzmaDecode.h, LzmaDecode.c
546 Compile defines: _LZMA_IN_CB, _LZMA_OUT_READ
548 - Buffer for input stream: any size (for example, 16 KB)
549 - Buffer for output stream: any size (for example, 16 KB)
550 - LZMA Internal Structures (~16 KB for default settings)
551 - LZMA dictionary (dictionary size is encoded in stream properties)
555 state.Dictionary = (unsigned char *)malloc(state.Properties.DictionarySize);
557 LzmaDecoderInit(&state);
562 g_OutBuffer, outAvail, &outProcessed);
564 while you need more bytes
566 see LzmaTest.c for more details:
569 5.5 Multi-call State Decompressing (zlib-like interface)
570 ------------------------------------------------------------------
571 When to use: file->file decompressing
572 Compile files: LzmaStateDecode.h, LzmaStateDecode.c
575 - Buffer for input stream: any size (for example, 16 KB)
576 - Buffer for output stream: any size (for example, 16 KB)
577 - LZMA Internal Structures (~16 KB for default settings)
578 - LZMA dictionary (dictionary size is encoded in stream properties)
582 state.Dictionary = (unsigned char *)malloc(state.Properties.DictionarySize);
585 LzmaDecoderInit(&state);
588 res = LzmaDecode(&state,
589 inBuffer, inAvail, &inProcessed,
590 g_OutBuffer, outAvail, &outProcessed,
592 inAvail -= inProcessed;
593 inBuffer += inProcessed;
595 while you need more bytes
597 see LzmaStateTest.c for more details:
600 6) Free all allocated blocks
605 LzmaDecodeSize.c is size-optimized version of LzmaDecode.c.
606 But compiled code of LzmaDecodeSize.c can be larger than
607 compiled code of LzmaDecode.c. So it's better to use
608 LzmaDecode.c in most cases.
614 LZMA decoder can return one of the following codes:
616 #define LZMA_RESULT_OK 0
617 #define LZMA_RESULT_DATA_ERROR 1
619 If you use callback function for input data and you return some
620 error code, LZMA Decoder also returns that code.
627 _LZMA_IN_CB - Use callback for input data
629 _LZMA_OUT_READ - Use read function for output data
631 _LZMA_LOC_OPT - Enable local speed optimizations inside code.
632 _LZMA_LOC_OPT is only for LzmaDecodeSize.c (size-optimized version).
633 _LZMA_LOC_OPT doesn't affect LzmaDecode.c (speed-optimized version)
634 and LzmaStateDecode.c
636 _LZMA_PROB32 - It can increase speed on some 32-bit CPUs,
637 but memory usage will be doubled in that case
639 _LZMA_UINT32_IS_ULONG - Define it if int is 16-bit on your compiler
642 _LZMA_SYSTEM_SIZE_T - Define it if you want to use system's size_t.
643 You can use it to enable 64-bit sizes supporting
647 C++ LZMA Encoder/Decoder
648 ~~~~~~~~~~~~~~~~~~~~~~~~
649 C++ LZMA code use COM-like interfaces. So if you want to use it,
650 you can study basics of COM/OLE.
652 By default, LZMA Encoder contains all Match Finders.
653 But for compressing it's enough to have just one of them.
654 So for reducing size of compressing code you can define:
655 #define COMPRESS_MF_BT
656 #define COMPRESS_MF_BT4
657 and it will use only bt4 match finder.
663 http://www.7-zip.org/support.html