| |
| 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. |
| |