17z ANSI-C Decoder 9.35
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 can create .7z archive with 7z.exe, 7za.exe or 7zr.exe:
33
34  7z.exe a archive.7z *.htm -r -mx -m0fb=255
35
36If you have big number of files in archive, and you need fast extracting,
37you can use partly-solid archives:
38
39  7za.exe a archive.7z *.htm -ms=512K -r -mx -m0fb=255 -m0d=512K
40
41In that example 7-Zip will use 512KB solid blocks. So it needs to decompress only
42512KB for extracting one file from such archive.
43
44
45Limitations of current version of 7z ANSI-C Decoder
46---------------------------------------------------
47
48 - It reads only "FileName", "Size", "LastWriteTime" and "CRC" information for each file in archive.
49 - It supports only LZMA and Copy (no compression) methods with BCJ or BCJ2 filters.
50 - It converts original UTF-16 Unicode file names to UTF-8 Unicode file names.
51
52These limitations will be fixed in future versions.
53
54
55Using 7z ANSI-C Decoder Test application:
56-----------------------------------------
57
58Usage: 7zDec <command> <archive_name>
59
60<Command>:
61  e: Extract files from archive
62  l: List contents of archive
63  t: Test integrity of archive
64
65Example:
66
67  7zDec l archive.7z
68
69lists contents of archive.7z
70
71  7zDec e archive.7z
72
73extracts files from archive.7z to current folder.
74
75
76How to use .7z Decoder
77----------------------
78
79Memory allocation
80~~~~~~~~~~~~~~~~~
81
827z Decoder uses two memory pools:
831) Temporary pool
842) Main pool
85Such scheme can allow you to avoid fragmentation of allocated blocks.
86
87
88Steps for using 7z decoder
89--------------------------
90
91Use code at 7zMain.c as example.
92
931) Declare variables:
94  inStream                 /* implements ILookInStream interface */
95  CSzArEx db;              /* 7z archive database structure */
96  ISzAlloc allocImp;       /* memory functions for main pool */
97  ISzAlloc allocTempImp;   /* memory functions for temporary pool */
98
992) call CrcGenerateTable(); function to initialize CRC structures.
100
1013) call SzArEx_Init(&db); function to initialize db structures.
102
1034) call SzArEx_Open(&db, inStream, &allocMain, &allocTemp) to open archive
104
105This function opens archive "inStream" and reads headers to "db".
106All items in "db" will be allocated with "allocMain" functions.
107SzArEx_Open function allocates and frees temporary structures by "allocTemp" functions.
108
1095) List items or Extract items
110
111  Listing code:
112  ~~~~~~~~~~~~~
113
114    Use SzArEx_GetFileNameUtf16 function. Look example code in C\Util\7z\7zMain.c file.
115
116
117  Extracting code:
118  ~~~~~~~~~~~~~~~~
119
120  SZ_RESULT SzAr_Extract(
121    CArchiveDatabaseEx *db,
122    ILookInStream *inStream,
123    UInt32 fileIndex,         /* index of file */
124    UInt32 *blockIndex,       /* index of solid block */
125    Byte **outBuffer,         /* pointer to pointer to output buffer (allocated with allocMain) */
126    size_t *outBufferSize,    /* buffer size for output buffer */
127    size_t *offset,           /* offset of stream for required file in *outBuffer */
128    size_t *outSizeProcessed, /* size of file in *outBuffer */
129    ISzAlloc *allocMain,
130    ISzAlloc *allocTemp);
131
132  If you need to decompress more than one file, you can send these values from previous call:
133    blockIndex,
134    outBuffer,
135    outBufferSize,
136  You can consider "outBuffer" as cache of solid block. If your archive is solid,
137  it will increase decompression speed.
138
139  After decompressing you must free "outBuffer":
140  allocImp.Free(outBuffer);
141
1426) call SzArEx_Free(&db, allocImp.Free) to free allocated items in "db".
143
144
145
146
147Memory requirements for .7z decoding
148------------------------------------
149
150Memory usage for Archive opening:
151  - Temporary pool:
152     - Memory for uncompressed .7z headers
153     - some other temporary blocks
154  - Main pool:
155     - Memory for database:
156       Estimated size of one file structures in solid archive:
157         - Size (4 or 8 Bytes)
158         - CRC32 (4 bytes)
159         - LastWriteTime (8 bytes)
160         - Some file information (4 bytes)
161         - File Name (variable length) + pointer + allocation structures
162
163Memory usage for archive Decompressing:
164  - Temporary pool:
165     - Memory for LZMA decompressing structures
166  - Main pool:
167     - Memory for decompressed solid block
168     - Memory for temprorary buffers, if BCJ2 fileter is used. Usually these
169       temprorary buffers can be about 15% of solid block size.
170
171
1727z Decoder doesn't allocate memory for compressed blocks.
173Instead of this, you must allocate buffer with desired
174size before calling 7z Decoder. Use 7zMain.c as example.
175
176
177Defines
178-------
179
180_SZ_ALLOC_DEBUG   - define it if you want to debug alloc/free operations to stderr.
181
182
183---
184
185http://www.7-zip.org
186http://www.7-zip.org/sdk.html
187http://www.7-zip.org/support.html
188