17z ANSI-C Decoder 4.62
2----------------------
3
47z ANSI-C provides 7z/LZMA decoding.
57z ANSI-C version is simplified version ported from C++ code.
6
7LZMA is default and general compression method of 7z format
8in 7-Zip compression program (www.7-zip.org). LZMA provides high
9compression ratio and very fast decompression.
10
11
12LICENSE
13-------
14
157z ANSI-C Decoder is part of the LZMA SDK.
16LZMA SDK is written and placed in the public domain by Igor Pavlov.
17
18Files
19---------------------
20
217zDecode.*   - Low level 7z decoding
227zExtract.*  - High level 7z decoding
237zHeader.*   - .7z format constants
247zIn.*       - .7z archive opening
257zItem.*     - .7z structures
267zMain.c     - Test application
27
28
29How To Use
30----------
31
32You must download 7-Zip program from www.7-zip.org.
33
34You can create .7z archive with 7z.exe or 7za.exe:
35
36  7za.exe a archive.7z *.htm -r -mx -m0fb=255
37
38If you have big number of files in archive, and you need fast extracting,
39you can use partly-solid archives:
40
41  7za.exe a archive.7z *.htm -ms=512K -r -mx -m0fb=255 -m0d=512K
42
43In that example 7-Zip will use 512KB solid blocks. So it needs to decompress only
44512KB for extracting one file from such archive.
45
46
47Limitations of current version of 7z ANSI-C Decoder
48---------------------------------------------------
49
50 - It reads only "FileName", "Size", "LastWriteTime" and "CRC" information for each file in archive.
51 - It supports only LZMA and Copy (no compression) methods with BCJ or BCJ2 filters.
52 - It converts original UTF-16 Unicode file names to UTF-8 Unicode file names.
53
54These limitations will be fixed in future versions.
55
56
57Using 7z ANSI-C Decoder Test application:
58-----------------------------------------
59
60Usage: 7zDec <command> <archive_name>
61
62<Command>:
63  e: Extract files from archive
64  l: List contents of archive
65  t: Test integrity of archive
66
67Example:
68
69  7zDec l archive.7z
70
71lists contents of archive.7z
72
73  7zDec e archive.7z
74
75extracts files from archive.7z to current folder.
76
77
78How to use .7z Decoder
79----------------------
80
81Memory allocation
82~~~~~~~~~~~~~~~~~
83
847z Decoder uses two memory pools:
851) Temporary pool
862) Main pool
87Such scheme can allow you to avoid fragmentation of allocated blocks.
88
89
90Steps for using 7z decoder
91--------------------------
92
93Use code at 7zMain.c as example.
94
951) Declare variables:
96  inStream                 /* implements ILookInStream interface */
97  CSzArEx db;              /* 7z archive database structure */
98  ISzAlloc allocImp;       /* memory functions for main pool */
99  ISzAlloc allocTempImp;   /* memory functions for temporary pool */
100
1012) call CrcGenerateTable(); function to initialize CRC structures.
102
1033) call SzArEx_Init(&db); function to initialize db structures.
104
1054) call SzArEx_Open(&db, inStream, &allocMain, &allocTemp) to open archive
106
107This function opens archive "inStream" and reads headers to "db".
108All items in "db" will be allocated with "allocMain" functions.
109SzArEx_Open function allocates and frees temporary structures by "allocTemp" functions.
110
1115) List items or Extract items
112
113  Listing code:
114  ~~~~~~~~~~~~~
115    {
116      UInt32 i;
117      for (i = 0; i < db.db.NumFiles; i++)
118      {
119        CFileItem *f = db.db.Files + i;
120        printf("%10d  %s\n", (int)f->Size, f->Name);
121      }
122    }
123
124  Extracting code:
125  ~~~~~~~~~~~~~~~~
126
127  SZ_RESULT SzAr_Extract(
128    CArchiveDatabaseEx *db,
129    ILookInStream *inStream,
130    UInt32 fileIndex,         /* index of file */
131    UInt32 *blockIndex,       /* index of solid block */
132    Byte **outBuffer,         /* pointer to pointer to output buffer (allocated with allocMain) */
133    size_t *outBufferSize,    /* buffer size for output buffer */
134    size_t *offset,           /* offset of stream for required file in *outBuffer */
135    size_t *outSizeProcessed, /* size of file in *outBuffer */
136    ISzAlloc *allocMain,
137    ISzAlloc *allocTemp);
138
139  If you need to decompress more than one file, you can send these values from previous call:
140    blockIndex,
141    outBuffer,
142    outBufferSize,
143  You can consider "outBuffer" as cache of solid block. If your archive is solid,
144  it will increase decompression speed.
145
146  After decompressing you must free "outBuffer":
147  allocImp.Free(outBuffer);
148
1496) call SzArEx_Free(&db, allocImp.Free) to free allocated items in "db".
150
151
152
153
154Memory requirements for .7z decoding
155------------------------------------
156
157Memory usage for Archive opening:
158  - Temporary pool:
159     - Memory for uncompressed .7z headers
160     - some other temporary blocks
161  - Main pool:
162     - Memory for database:
163       Estimated size of one file structures in solid archive:
164         - Size (4 or 8 Bytes)
165         - CRC32 (4 bytes)
166         - LastWriteTime (8 bytes)
167         - Some file information (4 bytes)
168         - File Name (variable length) + pointer + allocation structures
169
170Memory usage for archive Decompressing:
171  - Temporary pool:
172     - Memory for LZMA decompressing structures
173  - Main pool:
174     - Memory for decompressed solid block
175     - Memory for temprorary buffers, if BCJ2 fileter is used. Usually these
176       temprorary buffers can be about 15% of solid block size.
177
178
1797z Decoder doesn't allocate memory for compressed blocks.
180Instead of this, you must allocate buffer with desired
181size before calling 7z Decoder. Use 7zMain.c as example.
182
183
184Defines
185-------
186
187_SZ_ALLOC_DEBUG   - define it if you want to debug alloc/free operations to stderr.
188
189
190---
191
192http://www.7-zip.org
193http://www.7-zip.org/sdk.html
194http://www.7-zip.org/support.html
195