The Tor Browser: other-licenses/7zstub/src/DOC/7zC.txt@925c144e1f1f (annotated)

other-licenses/7zstub/src/DOC/7zC.txt@925c144e1f1f (annotated)

other-licenses/7zstub/src/DOC/7zC.txt

Fri, 16 Jan 2015 18:13:44 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Fri, 16 Jan 2015 18:13:44 +0100
branch: TOR_BUG_9701
changeset 14: 925c144e1f1f
permissions: -rw-r--r--

Integrate suggestion from review to improve consistency with existing code.

 z ANSI-C Decoder 4.23
 ----------------------
 z ANSI-C Decoder 4.23 Copyright (C) 1999-2005 Igor Pavlov
 z ANSI-C provides 7z/LZMA decoding.
 z ANSI-C version is simplified version ported from C++ code.
 LZMA is default and general compression method of 7z format
 in 7-Zip compression program (www.7-zip.org). LZMA provides high
 compression ratio and very fast decompression.
 LICENSE
 -------
 Read lzma.txt for information about license.
 Files
 ---------------------
 zAlloc.*    - Allocate and Free
 zBuffer.*   - Buffer structure
 zCrc.*      - CRC32 code
 zDecode.*   - Low level memory->memory decoding
 zExtract.*  - High level stream->memory decoding
 zHeader.*   - .7z format constants
 zIn.*       - .7z archive opening
 zItem.*     - .7z structures
 zMain.c     - Test application
 zMethodID.* - MethodID structure
 zTypes.h    - Base types and constants
 How To Use
 ----------
 You must download 7-Zip program from www.7-zip.org.
 You can create .7z archive with 7z.exe or 7za.exe:
 za.exe a archive.7z *.htm -r -mx -m0fb=255 -mf=off
 If you have big number of files in archive, and you need fast extracting,
 you can use partly-solid archives:
 za.exe a archive.7z *.htm -ms=512K -r -mx -m0fb=255 -m0d=512K -mf=off
 In that example 7-Zip will use 512KB solid blocks. So it needs to decompress only
 KB for extracting one file from such archive.
 Limitations of current version of 7z ANSI-C Decoder
 ---------------------------------------------------
  - It reads only "FileName", "Size", and "CRC" information for each file in archive.
  - It supports only LZMA and Copy (no compression) methods.
  - It converts original UTF-16 Unicode file names to UTF-8 Unicode file names.
 These limitations will be fixed in future versions.
 Using 7z ANSI-C Decoder Test application:
 -----------------------------------------
 Usage: 7zDec <command> <archive_name>
 <Command>:
   e: Extract files from archive
   l: List contents of archive
   t: Test integrity of archive
 Example:
 zDec l archive.7z
 lists contents of archive.7z
 zDec e archive.7z
 extracts files from archive.7z to current folder.
 How to use .7z Decoder
 ----------------------
 .7z Decoder can be compiled in one of two modes:
 ) Default mode. In that mode 7z Decoder will read full compressed
    block to RAM before decompressing.
 ) Mode with defined _LZMA_IN_CB. In that mode 7z Decoder can read
    compressed block by parts. And you can specify desired buffer size.
    So memory requirements can be reduced. But decompressing speed will
    be 5-10% lower and code size is slightly larger.
 Memory allocation
 ~~~~~~~~~~~~~~~~~
 z Decoder uses two memory pools:
 ) Temporary pool
 ) Main pool
 Such scheme can allow you to avoid fragmentation of allocated blocks.
 Steps for using 7z decoder
 --------------------------
 Use code at 7zMain.c as example.
 ) Declare variables:
   inStream                     /* implements ISzInStream interface */
   CArchiveDatabaseEx db;       /* 7z archive database structure */
   ISzAlloc allocImp;           /* memory functions for main pool */
   ISzAlloc allocTempImp;       /* memory functions for temporary pool */
 ) call InitCrcTable(); function to initialize CRC structures.
 ) call SzArDbExInit(&db); function to initialize db structures.
 ) call SzArchiveOpen(inStream, &db, &allocMain, &allocTemp) to open archive
 This function opens archive "inStream" and reads headers to "db".
 All items in "db" will be allocated with "allocMain" functions.
 SzArchiveOpen function allocates and frees temporary structures by "allocTemp" functions.
 ) List items or Extract items
   Listing code:
   ~~~~~~~~~~~~~
     {
       UInt32 i;
       for (i = 0; i < db.Database.NumFiles; i++)
       {
         CFileItem *f = db.Database.Files + i;
         printf("%10d  %s\n", (int)f->Size, f->Name);
       }
     }
   Extracting code:
   ~~~~~~~~~~~~~~~~
   SZ_RESULT SzExtract(
     ISzInStream *inStream,
     CArchiveDatabaseEx *db,
     UInt32 fileIndex,         /* index of file */
     UInt32 *blockIndex,       /* index of solid block */
     Byte **outBuffer,         /* pointer to pointer to output buffer (allocated with allocMain) */
     size_t *outBufferSize,    /* buffer size for output buffer */
     size_t *offset,           /* offset of stream for required file in *outBuffer */
     size_t *outSizeProcessed, /* size of file in *outBuffer */
     ISzAlloc *allocMain,
     ISzAlloc *allocTemp);
   If you need to decompress more than one file, you can send these values from previous call:
     blockIndex,
     outBuffer,
     outBufferSize,
   You can consider "outBuffer" as cache of solid block. If your archive is solid,
   it will increase decompression speed.
   After decompressing you must free "outBuffer":
   allocImp.Free(outBuffer);
 ) call SzArDbExFree(&db, allocImp.Free) to free allocated items in "db".
 Memory requirements for .7z decoding
 ------------------------------------
 Memory usage for Archive opening:
   - Temporary pool:
      - Memory for compressed .7z headers (if _LZMA_IN_CB is not defined)
      - Memory for uncompressed .7z headers
      - some other temporary blocks
   - Main pool:
      - Memory for database:
        Estimated size of one file structures in solid archive:
          - Size (4 or 8 Bytes)
          - CRC32 (4 bytes)
          - Some file information (4 bytes)
          - File Name (variable length) + pointer + allocation structures
 Memory usage for archive Decompressing:
   - Temporary pool:
      - Memory for compressed solid block (if _LZMA_IN_CB is not defined)
      - Memory for LZMA decompressing structures
   - Main pool:
      - Memory for decompressed solid block
 If _LZMA_IN_CB is defined, 7z Decoder will not allocate memory for
 compressed blocks. Instead of this, you must allocate buffer with desired
 size before calling 7z Decoder. Use 7zMain.c as example.
 EXIT codes
 -----------
 z Decoder functions can return one of the following codes:
 #define SZ_OK (0)
 #define SZE_DATA_ERROR (1)
 #define SZE_OUTOFMEMORY (2)
 #define SZE_CRC_ERROR (3)
 #define SZE_NOTIMPL (4)
 #define SZE_FAIL (5)
 #define SZE_ARCHIVE_ERROR (6)
 LZMA Defines
 ------------
 _LZMA_IN_CB       - Use special callback mode for input stream to reduce memory requirements
 _SZ_FILE_SIZE_64  - define it if you need support for files larger than 4 GB
 _SZ_NO_INT_64     - define it if your compiler doesn't support long long int
 _LZMA_PROB32      - it can increase LZMA decompressing speed on some 32-bit CPUs.
 _SZ_ONE_DIRECTORY - define it if you want to locate all source files to one directory
 _SZ_ALLOC_DEBUG   - define it if you want to debug alloc/free operations to stderr.
 ---
 http://www.7-zip.org
 http://www.7-zip.org/support.html

The Tor Browser / annotate

other-licenses/7zstub/src/DOC/7zC.txt@925c144e1f1f (annotated)

other-licenses/7zstub/src/DOC/7zC.txt