Introduction to the lzma command line tool
------------------------------------------
Overview
The lzma command line tool is similar to gzip and bzip2, but for
compressing and uncompressing .lzma files.
Supported file formats
By default, the tool creates files in the new .lzma format. This can
be overriden with --format=FMT command line option. Use --format=alone
to create files in the old LZMA_Alone format.
By default, the tool uncompresses both the new .lzma format and
LZMA_Alone format. This is to make it transparent to switch from
the old LZMA_Alone format to the new .lzma format. Since both
formats use the same filename suffix, average user should never
notice which format was used.
Differences to gzip and bzip2
Standard input and output
Both gzip and bzip2 refuse to write compressed data to a terminal and
read compressed data from a terminal. With gzip (but not with bzip2),
this can be overriden with the `--force' option. lzma follows the
behavior of gzip here.
Usage of LZMA_OPT environment variable
gzip and bzip2 read GZIP and BZIP2 environment variables at startup.
These variables may contain extra command line options.
gzip and bzip2 allow passing not only options, but also end-of-options
indicator (`--') and filenames via the environment variable. No quoting
is supported with the filenames.
Here are examples with gzip. bzip2 behaves identically.
bash$ echo asdf > 'foo bar'
bash$ GZIP='"foo bar"' gzip
gzip: "foo: No such file or directory
gzip: bar": No such file or directory
bash$ GZIP=-- gzip --help
gzip: --help: No such file or directory
lzma silently ignores all non-option arguments given via the
environment variable LZMA_OPT. Like on the command line, everything
after `--' is taken as non-options, and thus ignored in LZMA_OPT.
bash$ LZMA_OPT='--help' lzma --version # Displays help
bash$ LZMA_OPT='-- --help' lzma --version # Displays version
Filter chain presets
Like in gzip and bzip2, lzma supports numbered presets from 1 to 9
where 1 is the fastest and 9 the best compression. 1 and 2 are for
fast compressing with small memory usage, 3 to 6 for good compression
ratio with medium memory usage, and 7 to 9 for excellent compression
ratio with higher memory requirements. The default is 7 if memory
usage limit allows.
In future, there will probably be an option like --preset=NAME, which
will contain more special presets for specific file types.
It's also possible that there will be some heuristics to select good
filters. For example, the tool could detect when a .tar archive is
being compressed, and enable x86 filter only for those files in the
.tar archive that are ELF or PE executables for x86.
Specifying custom filter chains
Custom filter chains are specified by using long options with the name
of the filters in correct order. For example, to pass the input data to
the x86 filter and the output of that to the LZMA filter, the following
command will do:
lzma --x86 --lzma filename
Some filters accept options, which are specified as a comma-separated
list of key=value pairs:
lzma --delta=distance=4 --lzma=dict=4Mi,lc=8,lp=2 filename
Memory usage control
By default, the command line tool limits memory usage to 1/3 of the
available physical RAM. If no preset or custom filter chain has been
given, the default preset will be used. If the memory limit is too
low for the default preset, the tool will silently switch to lower
preset.
When a preset or a custom filter chain has been specified and the
memory limit is too low, an error message is displayed and no files
are processed.
If the decoder hits the memory usage limit, an error is displayed and
no more files are processed.
