vcs.maemo.org Git - physicsfs/blob - lzma/7zC.txt

   1 7z ANSI-C Decoder 4.48
   2 ----------------------
   3
   4 7z ANSI-C Decoder 4.48 Copyright (C) 1999-2006 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
  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
  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", "LastWriteTime" and "CRC" information for each file in archive.
  58  - It supports only LZMA and Copy (no compression) methods with BCJ or BCJ2 filters.
  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          - LastWriteTime (8 bytes)
 185          - Some file information (4 bytes)
 186          - File Name (variable length) + pointer + allocation structures
 187
 188 Memory usage for archive Decompressing:
 189   - Temporary pool:
 190      - Memory for compressed solid block (if _LZMA_IN_CB is not defined)
 191      - Memory for LZMA decompressing structures
 192   - Main pool:
 193      - Memory for decompressed solid block
 194      - Memory for temprorary buffers, if BCJ2 fileter is used. Usually these
 195        temprorary buffers can be about 15% of solid block size.
 196
 197
 198 If _LZMA_IN_CB is defined, 7z Decoder will not allocate memory for
 199 compressed blocks. Instead of this, you must allocate buffer with desired
 200 size before calling 7z Decoder. Use 7zMain.c as example.
 201
 202
 203
 204 EXIT codes
 205 -----------
 206
 207 7z Decoder functions can return one of the following codes:
 208
 209 #define SZ_OK (0)
 210 #define SZE_DATA_ERROR (1)
 211 #define SZE_OUTOFMEMORY (2)
 212 #define SZE_CRC_ERROR (3)
 213
 214 #define SZE_NOTIMPL (4)
 215 #define SZE_FAIL (5)
 216
 217 #define SZE_ARCHIVE_ERROR (6)
 218
 219
 220
 221 LZMA Defines
 222 ------------
 223
 224 _LZMA_IN_CB       - Use special callback mode for input stream to reduce memory requirements
 225
 226 _SZ_FILE_SIZE_32  - define it if you need only support for files smaller than 4 GB
 227 _SZ_NO_INT_64     - define it if your compiler doesn't support long long int or __int64.
 228
 229 _LZMA_PROB32      - it can increase LZMA decompressing speed on some 32-bit CPUs.
 230
 231 _SZ_ALLOC_DEBUG   - define it if you want to debug alloc/free operations to stderr.
 232
 233
 234 ---
 235
 236 http://www.7-zip.org
 237 http://www.7-zip.org/support.html