doc/lzma-intro.txt

   1
   2 Introduction to the lzma command line tool
   3 ------------------------------------------
   4
   5 Overview
   6
   7     The lzma command line tool is similar to gzip and bzip2, but for
   8     compressing and uncompressing .lzma files.
   9
  10
  11 Supported file formats
  12
  13     By default, the tool creates files in the new .lzma format. This can
  14     be overriden with --format=FMT command line option. Use --format=alone
  15     to create files in the old LZMA_Alone format.
  16
  17     By default, the tool uncompresses both the new .lzma format and
  18     LZMA_Alone format. This is to make it transparent to switch from
  19     the old LZMA_Alone format to the new .lzma format. Since both
  20     formats use the same filename suffix, average user should never
  21     notice which format was used.
  22
  23
  24 Differences to gzip and bzip2
  25
  26   Standard input and output
  27
  28     Both gzip and bzip2 refuse to write compressed data to a terminal and
  29     read compressed data from a terminal. With gzip (but not with bzip2),
  30     this can be overriden with the `--force' option. lzma follows the
  31     behavior of gzip here.
  32
  33   Usage of LZMA_OPT environment variable
  34
  35     gzip and bzip2 read GZIP and BZIP2 environment variables at startup.
  36     These variables may contain extra command line options.
  37
  38     gzip and bzip2 allow passing not only options, but also end-of-options
  39     indicator (`--') and filenames via the environment variable. No quoting
  40     is supported with the filenames.
  41
  42     Here are examples with gzip. bzip2 behaves identically.
  43
  44         bash$ echo asdf > 'foo bar'
  45         bash$ GZIP='"foo bar"' gzip
  46         gzip: "foo: No such file or directory
  47         gzip: bar": No such file or directory
  48
  49         bash$ GZIP=-- gzip --help
  50         gzip: --help: No such file or directory
  51
  52     lzma silently ignores all non-option arguments given via the
  53     environment variable LZMA_OPT. Like on the command line, everything
  54     after `--' is taken as non-options, and thus ignored in LZMA_OPT.
  55
  56         bash$ LZMA_OPT='--help' lzma --version     # Displays help
  57         bash$ LZMA_OPT='-- --help' lzma --version  # Displays version
  58
  59
  60 Filter chain presets
  61
  62     Like in gzip and bzip2, lzma supports numbered presets from 1 to 9
  63     where 1 is the fastest and 9 the best compression. 1 and 2 are for
  64     fast compressing with small memory usage, 3 to 6 for good compression
  65     ratio with medium memory usage, and 7 to 9 for excellent compression
  66     ratio with higher memory requirements. The default is 7 if memory
  67     usage limit allows.
  68
  69     In future, there will probably be an option like --preset=NAME, which
  70     will contain more special presets for specific file types.
  71
  72     It's also possible that there will be some heuristics to select good
  73     filters. For example, the tool could detect when a .tar archive is
  74     being compressed, and enable x86 filter only for those files in the
  75     .tar archive that are ELF or PE executables for x86.
  76
  77
  78 Specifying custom filter chains
  79
  80     Custom filter chains are specified by using long options with the name
  81     of the filters in correct order. For example, to pass the input data to
  82     the x86 filter and the output of that to the LZMA filter, the following
  83     command will do:
  84
  85         lzma --x86 --lzma filename
  86
  87     Some filters accept options, which are specified as a comma-separated
  88     list of key=value pairs:
  89
  90         lzma --delta=distance=4 --lzma=dict=4Mi,lc=8,lp=2 filename
  91
  92
  93 Memory usage control
  94
  95     By default, the command line tool limits memory usage to 1/3 of the
  96     available physical RAM. If no preset or custom filter chain has been
  97     given, the default preset will be used. If the memory limit is too
  98     low for the default preset, the tool will silently switch to lower
  99     preset.
 100
 101     When a preset or a custom filter chain has been specified and the
 102     memory limit is too low, an error message is displayed and no files
 103     are processed.
 104
 105     If the decoder hits the memory usage limit, an error is displayed and
 106     no more files are processed.
 107