xref: /third_party/lz4/programs/lz4.1.md (revision 27b27ec6)

lz4(1) -- lz4, unlz4, lz4cat - Compress or decompress .lz4 files
================================================================

SYNOPSIS
--------

`lz4` [*OPTIONS*] [-|INPUT-FILE] <OUTPUT-FILE>

`unlz4` is equivalent to `lz4 -d`

`lz4cat` is equivalent to `lz4 -dcfm`

When writing scripts that need to decompress files,
it is recommended to always use the name `lz4` with appropriate arguments
(`lz4 -d` or `lz4 -dc`) instead of the names `unlz4` and `lz4cat`.


DESCRIPTION
-----------

`lz4` is an extremely fast lossless compression algorithm,
based on **byte-aligned LZ77** family of compression scheme.
`lz4` offers compression speeds > 500 MB/s per core,
linearly scalable with multi-core CPUs.
It features an extremely fast decoder, offering speed in multiple GB/s per core,
typically reaching RAM speed limit on multi-core systems.
The native file format is the `.lz4` format.

### Difference between lz4 and gzip

`lz4` supports a command line syntax similar _but not identical_ to `gzip(1)`.
Differences are :

  * `lz4` compresses a single file by default (see `-m` for multiple files)
  * `lz4 file1 file2` means : compress file1 _into_ file2
  * `lz4 file.lz4` will default to decompression (use `-z` to force compression)
  * `lz4` preserves original files (see `--rm` to erase source file on completion)
  * `lz4` shows real-time notification statistics
     during compression or decompression of a single file
     (use `-q` to silence them)
  * When no destination is specified, result is sent on implicit output,
    which depends on `stdout` status.
    When `stdout` _is Not the console_, it becomes the implicit output.
    Otherwise, if `stdout` is the console, the implicit output is `filename.lz4`.
  * It is considered bad practice to rely on implicit output in scripts.
    because the script's environment may change.
    Always use explicit output in scripts.
    `-c` ensures that output will be `stdout`.
    Conversely, providing a destination name, or using `-m`
    ensures that the output will be either the specified name, or `filename.lz4` respectively.

Default behaviors can be modified by opt-in commands, detailed below.

  * `lz4 -m` makes it possible to provide multiple input filenames,
    which will be compressed into files using suffix `.lz4`.
    Progress notifications become disabled by default (use `-v` to enable them).
    This mode has a behavior which more closely mimics `gzip` command line,
    with the main remaining difference being that source files are preserved by default.
  * Similarly, `lz4 -m -d` can decompress multiple `*.lz4` files.
  * It's possible to opt-in to erase source files
    on successful compression or decompression, using `--rm` command.
  * Consequently, `lz4 -m --rm` behaves the same as `gzip`.

### Concatenation of .lz4 files

It is possible to concatenate `.lz4` files as is.
`lz4` will decompress such files as if they were a single `.lz4` file.
For example:

    lz4 file1  > foo.lz4
    lz4 file2 >> foo.lz4

Then `lz4cat foo.lz4` is equivalent to `cat file1 file2`.

OPTIONS
-------

### Short commands concatenation

In some cases, some options can be expressed using short command `-x`
or long command `--long-word`.
Short commands can be concatenated together.
For example, `-d -c` is equivalent to `-dc`.
Long commands cannot be concatenated. They must be clearly separated by a space.

### Multiple commands

When multiple contradictory commands are issued on a same command line,
only the latest one will be applied.

### Operation mode

* `-z` `--compress`:
  Compress.
  This is the default operation mode when no operation mode option is
  specified, no other operation mode is implied from the command name
  (for example, `unlz4` implies `--decompress`),
  nor from the input file name
  (for example, a file extension `.lz4` implies  `--decompress` by default).
  `-z` can also be used to force compression of an already compressed
  `.lz4` file.

* `-d` `--decompress` `--uncompress`:
  Decompress.
  `--decompress` is also the default operation when the input filename has an
  `.lz4` extension.

* `-t` `--test`:
  Test the integrity of compressed `.lz4` files.
  The decompressed data is discarded.
  No files are created nor removed.

* `-b#`:
  Benchmark mode, using `#` compression level.

* `--list`:
  List information about .lz4 files.
  note : current implementation is limited to single-frame .lz4 files.

### Operation modifiers

* `-#`:
  Compression level, with # being any value from 1 to 12.
  Higher values trade compression speed for compression ratio.
  Values above 12 are considered the same as 12.
  Recommended values are 1 for fast compression (default),
  and 9 for high compression.
  Speed/compression trade-off will vary depending on data to compress.
  Decompression speed remains fast at all settings.

* `--fast[=#]`:
  Switch to ultra-fast compression levels.
  The higher the value, the faster the compression speed, at the cost of some compression ratio.
  If `=#` is not present, it defaults to `1`.
  This setting overrides compression level if one was set previously.
  Similarly, if a compression level is set after `--fast`, it overrides it.

* `--best`:
  Set highest compression level. Same as -12.

* `--favor-decSpeed`:
  Generate compressed data optimized for decompression speed.
  Compressed data will be larger as a consequence (typically by ~0.5%),
  while decompression speed will be improved by 5-20%, depending on use cases.
  This option only works in combination with very high compression levels (>=10).

* `-D dictionaryName`:
  Compress, decompress or benchmark using dictionary _dictionaryName_.
  Compression and decompression must use the same dictionary to be compatible.
  Using a different dictionary during decompression will either
  abort due to decompression error, or generate a checksum error.

* `-f` `--[no-]force`:
  This option has several effects:

  If the target file already exists, overwrite it without prompting.

  When used with `--decompress` and `lz4` cannot recognize the type of
  the source file, copy the source file as is to standard output.
  This allows `lz4cat --force` to be used like `cat (1)` for files
  that have not been compressed with `lz4`.

* `-c` `--stdout` `--to-stdout`:
  Force write to standard output, even if it is the console.

* `-m` `--multiple`:
  Multiple input files.
  Compressed file names will be appended a `.lz4` suffix.
  This mode also reduces notification level.
  Can also be used to list multiple files.
  `lz4 -m` has a behavior equivalent to `gzip -k`
  (it preserves source files by default).

* `-r` :
  operate recursively on directories.
  This mode also sets `-m` (multiple input files).

* `-B#`:
  Block size \[4-7\](default : 7)<br/>
  `-B4`= 64KB ; `-B5`= 256KB ; `-B6`= 1MB ; `-B7`= 4MB

* `-BI`:
  Produce independent blocks (default)

* `-BD`:
  Blocks depend on predecessors (improves compression ratio, more noticeable on small blocks)

* `-BX`:
  Generate block checksums (default:disabled)

* `--[no-]frame-crc`:
  Select frame checksum (default:enabled)

* `--no-crc`:
  Disable both frame and block checksums

* `--[no-]content-size`:
  Header includes original size (default:not present)<br/>
  Note : this option can only be activated when the original size can be
  determined, hence for a file. It won't work with unknown source size,
  such as stdin or pipe.

* `--[no-]sparse`:
  Sparse mode support (default:enabled on file, disabled on stdout)

* `-l`:
  Use Legacy format (typically for Linux Kernel compression)<br/>
  Note : `-l` is not compatible with `-m` (`--multiple`) nor `-r`

### Other options

* `-v` `--verbose`:
  Verbose mode

* `-q` `--quiet`:
  Suppress warnings and real-time statistics;
  specify twice to suppress errors too

* `-h` `-H` `--help`:
  Display help/long help and exit

* `-V` `--version`:
  Display Version number and exit

* `-k` `--keep`:
  Preserve source files (default behavior)

* `--rm` :
  Delete source files on successful compression or decompression

* `--` :
  Treat all subsequent arguments as files


### Benchmark mode

* `-b#`:
  Benchmark file(s), using # compression level

* `-e#`:
  Benchmark multiple compression levels, from b# to e# (included)

* `-i#`:
  Minimum evaluation time in seconds \[1-9\] (default : 3)


BUGS
----

Report bugs at: https://github.com/lz4/lz4/issues


AUTHOR
------

Yann Collet