1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/other-licenses/7zstub/src/DOC/7zC.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,235 @@
1.4 +7z ANSI-C Decoder 4.23
1.5 +----------------------
1.6 +
1.7 +7z ANSI-C Decoder 4.23 Copyright (C) 1999-2005 Igor Pavlov
1.8 +
1.9 +7z ANSI-C provides 7z/LZMA decoding.
1.10 +7z ANSI-C version is simplified version ported from C++ code.
1.11 +
1.12 +LZMA is default and general compression method of 7z format
1.13 +in 7-Zip compression program (www.7-zip.org). LZMA provides high
1.14 +compression ratio and very fast decompression.
1.15 +
1.16 +
1.17 +LICENSE
1.18 +-------
1.19 +
1.20 +Read lzma.txt for information about license.
1.21 +
1.22 +
1.23 +Files
1.24 +---------------------
1.25 +
1.26 +7zAlloc.* - Allocate and Free
1.27 +7zBuffer.* - Buffer structure
1.28 +7zCrc.* - CRC32 code
1.29 +7zDecode.* - Low level memory->memory decoding
1.30 +7zExtract.* - High level stream->memory decoding
1.31 +7zHeader.* - .7z format constants
1.32 +7zIn.* - .7z archive opening
1.33 +7zItem.* - .7z structures
1.34 +7zMain.c - Test application
1.35 +7zMethodID.* - MethodID structure
1.36 +7zTypes.h - Base types and constants
1.37 +
1.38 +
1.39 +How To Use
1.40 +----------
1.41 +
1.42 +You must download 7-Zip program from www.7-zip.org.
1.43 +
1.44 +You can create .7z archive with 7z.exe or 7za.exe:
1.45 +
1.46 + 7za.exe a archive.7z *.htm -r -mx -m0fb=255 -mf=off
1.47 +
1.48 +If you have big number of files in archive, and you need fast extracting,
1.49 +you can use partly-solid archives:
1.50 +
1.51 + 7za.exe a archive.7z *.htm -ms=512K -r -mx -m0fb=255 -m0d=512K -mf=off
1.52 +
1.53 +In that example 7-Zip will use 512KB solid blocks. So it needs to decompress only
1.54 +512KB for extracting one file from such archive.
1.55 +
1.56 +
1.57 +Limitations of current version of 7z ANSI-C Decoder
1.58 +---------------------------------------------------
1.59 +
1.60 + - It reads only "FileName", "Size", and "CRC" information for each file in archive.
1.61 + - It supports only LZMA and Copy (no compression) methods.
1.62 + - It converts original UTF-16 Unicode file names to UTF-8 Unicode file names.
1.63 +
1.64 +These limitations will be fixed in future versions.
1.65 +
1.66 +
1.67 +Using 7z ANSI-C Decoder Test application:
1.68 +-----------------------------------------
1.69 +
1.70 +Usage: 7zDec <command> <archive_name>
1.71 +
1.72 +<Command>:
1.73 + e: Extract files from archive
1.74 + l: List contents of archive
1.75 + t: Test integrity of archive
1.76 +
1.77 +Example:
1.78 +
1.79 + 7zDec l archive.7z
1.80 +
1.81 +lists contents of archive.7z
1.82 +
1.83 + 7zDec e archive.7z
1.84 +
1.85 +extracts files from archive.7z to current folder.
1.86 +
1.87 +
1.88 +How to use .7z Decoder
1.89 +----------------------
1.90 +
1.91 +.7z Decoder can be compiled in one of two modes:
1.92 +
1.93 +1) Default mode. In that mode 7z Decoder will read full compressed
1.94 + block to RAM before decompressing.
1.95 +
1.96 +2) Mode with defined _LZMA_IN_CB. In that mode 7z Decoder can read
1.97 + compressed block by parts. And you can specify desired buffer size.
1.98 + So memory requirements can be reduced. But decompressing speed will
1.99 + be 5-10% lower and code size is slightly larger.
1.100 +
1.101 +
1.102 +Memory allocation
1.103 +~~~~~~~~~~~~~~~~~
1.104 +
1.105 +7z Decoder uses two memory pools:
1.106 +1) Temporary pool
1.107 +2) Main pool
1.108 +Such scheme can allow you to avoid fragmentation of allocated blocks.
1.109 +
1.110 +Steps for using 7z decoder
1.111 +--------------------------
1.112 +
1.113 +Use code at 7zMain.c as example.
1.114 +
1.115 +1) Declare variables:
1.116 + inStream /* implements ISzInStream interface */
1.117 + CArchiveDatabaseEx db; /* 7z archive database structure */
1.118 + ISzAlloc allocImp; /* memory functions for main pool */
1.119 + ISzAlloc allocTempImp; /* memory functions for temporary pool */
1.120 +
1.121 +2) call InitCrcTable(); function to initialize CRC structures.
1.122 +
1.123 +3) call SzArDbExInit(&db); function to initialize db structures.
1.124 +
1.125 +4) call SzArchiveOpen(inStream, &db, &allocMain, &allocTemp) to open archive
1.126 +
1.127 +This function opens archive "inStream" and reads headers to "db".
1.128 +All items in "db" will be allocated with "allocMain" functions.
1.129 +SzArchiveOpen function allocates and frees temporary structures by "allocTemp" functions.
1.130 +
1.131 +5) List items or Extract items
1.132 +
1.133 + Listing code:
1.134 + ~~~~~~~~~~~~~
1.135 + {
1.136 + UInt32 i;
1.137 + for (i = 0; i < db.Database.NumFiles; i++)
1.138 + {
1.139 + CFileItem *f = db.Database.Files + i;
1.140 + printf("%10d %s\n", (int)f->Size, f->Name);
1.141 + }
1.142 + }
1.143 +
1.144 + Extracting code:
1.145 + ~~~~~~~~~~~~~~~~
1.146 +
1.147 + SZ_RESULT SzExtract(
1.148 + ISzInStream *inStream,
1.149 + CArchiveDatabaseEx *db,
1.150 + UInt32 fileIndex, /* index of file */
1.151 + UInt32 *blockIndex, /* index of solid block */
1.152 + Byte **outBuffer, /* pointer to pointer to output buffer (allocated with allocMain) */
1.153 + size_t *outBufferSize, /* buffer size for output buffer */
1.154 + size_t *offset, /* offset of stream for required file in *outBuffer */
1.155 + size_t *outSizeProcessed, /* size of file in *outBuffer */
1.156 + ISzAlloc *allocMain,
1.157 + ISzAlloc *allocTemp);
1.158 +
1.159 + If you need to decompress more than one file, you can send these values from previous call:
1.160 + blockIndex,
1.161 + outBuffer,
1.162 + outBufferSize,
1.163 + You can consider "outBuffer" as cache of solid block. If your archive is solid,
1.164 + it will increase decompression speed.
1.165 +
1.166 + After decompressing you must free "outBuffer":
1.167 + allocImp.Free(outBuffer);
1.168 +
1.169 +6) call SzArDbExFree(&db, allocImp.Free) to free allocated items in "db".
1.170 +
1.171 +
1.172 +
1.173 +
1.174 +Memory requirements for .7z decoding
1.175 +------------------------------------
1.176 +
1.177 +Memory usage for Archive opening:
1.178 + - Temporary pool:
1.179 + - Memory for compressed .7z headers (if _LZMA_IN_CB is not defined)
1.180 + - Memory for uncompressed .7z headers
1.181 + - some other temporary blocks
1.182 + - Main pool:
1.183 + - Memory for database:
1.184 + Estimated size of one file structures in solid archive:
1.185 + - Size (4 or 8 Bytes)
1.186 + - CRC32 (4 bytes)
1.187 + - Some file information (4 bytes)
1.188 + - File Name (variable length) + pointer + allocation structures
1.189 +
1.190 +Memory usage for archive Decompressing:
1.191 + - Temporary pool:
1.192 + - Memory for compressed solid block (if _LZMA_IN_CB is not defined)
1.193 + - Memory for LZMA decompressing structures
1.194 + - Main pool:
1.195 + - Memory for decompressed solid block
1.196 +
1.197 +
1.198 +If _LZMA_IN_CB is defined, 7z Decoder will not allocate memory for
1.199 +compressed blocks. Instead of this, you must allocate buffer with desired
1.200 +size before calling 7z Decoder. Use 7zMain.c as example.
1.201 +
1.202 +
1.203 +
1.204 +EXIT codes
1.205 +-----------
1.206 +
1.207 +7z Decoder functions can return one of the following codes:
1.208 +
1.209 +#define SZ_OK (0)
1.210 +#define SZE_DATA_ERROR (1)
1.211 +#define SZE_OUTOFMEMORY (2)
1.212 +#define SZE_CRC_ERROR (3)
1.213 +
1.214 +#define SZE_NOTIMPL (4)
1.215 +#define SZE_FAIL (5)
1.216 +
1.217 +#define SZE_ARCHIVE_ERROR (6)
1.218 +
1.219 +
1.220 +
1.221 +LZMA Defines
1.222 +------------
1.223 +
1.224 +_LZMA_IN_CB - Use special callback mode for input stream to reduce memory requirements
1.225 +
1.226 +_SZ_FILE_SIZE_64 - define it if you need support for files larger than 4 GB
1.227 +_SZ_NO_INT_64 - define it if your compiler doesn't support long long int
1.228 +
1.229 +_LZMA_PROB32 - it can increase LZMA decompressing speed on some 32-bit CPUs.
1.230 +
1.231 +_SZ_ONE_DIRECTORY - define it if you want to locate all source files to one directory
1.232 +_SZ_ALLOC_DEBUG - define it if you want to debug alloc/free operations to stderr.
1.233 +
1.234 +
1.235 +---
1.236 +
1.237 +http://www.7-zip.org
1.238 +http://www.7-zip.org/support.html
