The Tor Browser / file comparison
comparison: other-licenses/7zstub/src/DOC/7zC.txt
other-licenses/7zstub/src/DOC/7zC.txt
- branch
- TOR_BUG_9701
- changeset 14
- 925c144e1f1f
equal
deleted
inserted
replaced
| -1:000000000000 | 0:28ab9ec088fd |
|---|---|
| 1 7z ANSI-C Decoder 4.23 | |
| 2 ---------------------- | |
| 3 | |
| 4 7z ANSI-C Decoder 4.23 Copyright (C) 1999-2005 Igor Pavlov | |
| 5 | |
| 6 7z ANSI-C provides 7z/LZMA decoding. | |
| 7 7z ANSI-C version is simplified version ported from C++ code. | |
| 8 | |
| 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. | |
| 12 | |
| 13 | |
| 14 LICENSE | |
| 15 ------- | |
| 16 | |
| 17 Read lzma.txt for information about license. | |
| 18 | |
| 19 | |
| 20 Files | |
| 21 --------------------- | |
| 22 | |
| 23 7zAlloc.* - Allocate and Free | |
| 24 7zBuffer.* - Buffer structure | |
| 25 7zCrc.* - CRC32 code | |
| 26 7zDecode.* - Low level memory->memory decoding | |
| 27 7zExtract.* - High level stream->memory decoding | |
| 28 7zHeader.* - .7z format constants | |
| 29 7zIn.* - .7z archive opening | |
| 30 7zItem.* - .7z structures | |
| 31 7zMain.c - Test application | |
| 32 7zMethodID.* - MethodID structure | |
| 33 7zTypes.h - Base types and constants | |
| 34 | |
| 35 | |
| 36 How To Use | |
| 37 ---------- | |
| 38 | |
| 39 You must download 7-Zip program from www.7-zip.org. | |
| 40 | |
| 41 You can create .7z archive with 7z.exe or 7za.exe: | |
| 42 | |
| 43 7za.exe a archive.7z *.htm -r -mx -m0fb=255 -mf=off | |
| 44 | |
| 45 If you have big number of files in archive, and you need fast extracting, | |
| 46 you can use partly-solid archives: | |
| 47 | |
| 48 7za.exe a archive.7z *.htm -ms=512K -r -mx -m0fb=255 -m0d=512K -mf=off | |
| 49 | |
| 50 In that example 7-Zip will use 512KB solid blocks. So it needs to decompress only | |
| 51 512KB for extracting one file from such archive. | |
| 52 | |
| 53 | |
| 54 Limitations of current version of 7z ANSI-C Decoder | |
| 55 --------------------------------------------------- | |
| 56 | |
| 57 - It reads only "FileName", "Size", and "CRC" information for each file in archive. | |
| 58 - It supports only LZMA and Copy (no compression) methods. | |
| 59 - It converts original UTF-16 Unicode file names to UTF-8 Unicode file names. | |
| 60 | |
| 61 These limitations will be fixed in future versions. | |
| 62 | |
| 63 | |
| 64 Using 7z ANSI-C Decoder Test application: | |
| 65 ----------------------------------------- | |
| 66 | |
| 67 Usage: 7zDec <command> <archive_name> | |
| 68 | |
| 69 <Command>: | |
| 70 e: Extract files from archive | |
| 71 l: List contents of archive | |
| 72 t: Test integrity of archive | |
| 73 | |
| 74 Example: | |
| 75 | |
| 76 7zDec l archive.7z | |
| 77 | |
| 78 lists contents of archive.7z | |
| 79 | |
| 80 7zDec e archive.7z | |
| 81 | |
| 82 extracts files from archive.7z to current folder. | |
| 83 | |
| 84 | |
| 85 How to use .7z Decoder | |
| 86 ---------------------- | |
| 87 | |
| 88 .7z Decoder can be compiled in one of two modes: | |
| 89 | |
| 90 1) Default mode. In that mode 7z Decoder will read full compressed | |
| 91 block to RAM before decompressing. | |
| 92 | |
| 93 2) Mode with defined _LZMA_IN_CB. In that mode 7z Decoder can read | |
| 94 compressed block by parts. And you can specify desired buffer size. | |
| 95 So memory requirements can be reduced. But decompressing speed will | |
| 96 be 5-10% lower and code size is slightly larger. | |
| 97 | |
| 98 | |
| 99 Memory allocation | |
| 100 ~~~~~~~~~~~~~~~~~ | |
| 101 | |
| 102 7z Decoder uses two memory pools: | |
| 103 1) Temporary pool | |
| 104 2) Main pool | |
| 105 Such scheme can allow you to avoid fragmentation of allocated blocks. | |
| 106 | |
| 107 Steps for using 7z decoder | |
| 108 -------------------------- | |
| 109 | |
| 110 Use code at 7zMain.c as example. | |
| 111 | |
| 112 1) Declare variables: | |
| 113 inStream /* implements ISzInStream interface */ | |
| 114 CArchiveDatabaseEx db; /* 7z archive database structure */ | |
| 115 ISzAlloc allocImp; /* memory functions for main pool */ | |
| 116 ISzAlloc allocTempImp; /* memory functions for temporary pool */ | |
| 117 | |
| 118 2) call InitCrcTable(); function to initialize CRC structures. | |
| 119 | |
| 120 3) call SzArDbExInit(&db); function to initialize db structures. | |
| 121 | |
| 122 4) call SzArchiveOpen(inStream, &db, &allocMain, &allocTemp) to open archive | |
| 123 | |
| 124 This function opens archive "inStream" and reads headers to "db". | |
| 125 All items in "db" will be allocated with "allocMain" functions. | |
| 126 SzArchiveOpen function allocates and frees temporary structures by "allocTemp" functions. | |
| 127 | |
| 128 5) List items or Extract items | |
| 129 | |
| 130 Listing code: | |
| 131 ~~~~~~~~~~~~~ | |
| 132 { | |
| 133 UInt32 i; | |
| 134 for (i = 0; i < db.Database.NumFiles; i++) | |
| 135 { | |
| 136 CFileItem *f = db.Database.Files + i; | |
| 137 printf("%10d %s\n", (int)f->Size, f->Name); | |
| 138 } | |
| 139 } | |
| 140 | |
| 141 Extracting code: | |
| 142 ~~~~~~~~~~~~~~~~ | |
| 143 | |
| 144 SZ_RESULT SzExtract( | |
| 145 ISzInStream *inStream, | |
| 146 CArchiveDatabaseEx *db, | |
| 147 UInt32 fileIndex, /* index of file */ | |
| 148 UInt32 *blockIndex, /* index of solid block */ | |
| 149 Byte **outBuffer, /* pointer to pointer to output buffer (allocated with allocMain) */ | |
| 150 size_t *outBufferSize, /* buffer size for output buffer */ | |
| 151 size_t *offset, /* offset of stream for required file in *outBuffer */ | |
| 152 size_t *outSizeProcessed, /* size of file in *outBuffer */ | |
| 153 ISzAlloc *allocMain, | |
| 154 ISzAlloc *allocTemp); | |
| 155 | |
| 156 If you need to decompress more than one file, you can send these values from previous call: | |
| 157 blockIndex, | |
| 158 outBuffer, | |
| 159 outBufferSize, | |
| 160 You can consider "outBuffer" as cache of solid block. If your archive is solid, | |
| 161 it will increase decompression speed. | |
| 162 | |
| 163 After decompressing you must free "outBuffer": | |
| 164 allocImp.Free(outBuffer); | |
| 165 | |
| 166 6) call SzArDbExFree(&db, allocImp.Free) to free allocated items in "db". | |
| 167 | |
| 168 | |
| 169 | |
| 170 | |
| 171 Memory requirements for .7z decoding | |
| 172 ------------------------------------ | |
| 173 | |
| 174 Memory usage for Archive opening: | |
| 175 - Temporary pool: | |
| 176 - Memory for compressed .7z headers (if _LZMA_IN_CB is not defined) | |
| 177 - Memory for uncompressed .7z headers | |
| 178 - some other temporary blocks | |
| 179 - Main pool: | |
| 180 - Memory for database: | |
| 181 Estimated size of one file structures in solid archive: | |
| 182 - Size (4 or 8 Bytes) | |
| 183 - CRC32 (4 bytes) | |
| 184 - Some file information (4 bytes) | |
| 185 - File Name (variable length) + pointer + allocation structures | |
| 186 | |
| 187 Memory usage for archive Decompressing: | |
| 188 - Temporary pool: | |
| 189 - Memory for compressed solid block (if _LZMA_IN_CB is not defined) | |
| 190 - Memory for LZMA decompressing structures | |
| 191 - Main pool: | |
| 192 - Memory for decompressed solid block | |
| 193 | |
| 194 | |
| 195 If _LZMA_IN_CB is defined, 7z Decoder will not allocate memory for | |
| 196 compressed blocks. Instead of this, you must allocate buffer with desired | |
| 197 size before calling 7z Decoder. Use 7zMain.c as example. | |
| 198 | |
| 199 | |
| 200 | |
| 201 EXIT codes | |
| 202 ----------- | |
| 203 | |
| 204 7z Decoder functions can return one of the following codes: | |
| 205 | |
| 206 #define SZ_OK (0) | |
| 207 #define SZE_DATA_ERROR (1) | |
| 208 #define SZE_OUTOFMEMORY (2) | |
| 209 #define SZE_CRC_ERROR (3) | |
| 210 | |
| 211 #define SZE_NOTIMPL (4) | |
| 212 #define SZE_FAIL (5) | |
| 213 | |
| 214 #define SZE_ARCHIVE_ERROR (6) | |
| 215 | |
| 216 | |
| 217 | |
| 218 LZMA Defines | |
| 219 ------------ | |
| 220 | |
| 221 _LZMA_IN_CB - Use special callback mode for input stream to reduce memory requirements | |
| 222 | |
| 223 _SZ_FILE_SIZE_64 - define it if you need support for files larger than 4 GB | |
| 224 _SZ_NO_INT_64 - define it if your compiler doesn't support long long int | |
| 225 | |
| 226 _LZMA_PROB32 - it can increase LZMA decompressing speed on some 32-bit CPUs. | |
| 227 | |
| 228 _SZ_ONE_DIRECTORY - define it if you want to locate all source files to one directory | |
| 229 _SZ_ALLOC_DEBUG - define it if you want to debug alloc/free operations to stderr. | |
| 230 | |
| 231 | |
| 232 --- | |
| 233 | |
| 234 http://www.7-zip.org | |
| 235 http://www.7-zip.org/support.html |
