1lz4(1) -- lz4, unlz4, lz4cat - Compress or decompress .lz4 files
2================================================================
3
4SYNOPSIS
5--------
6
7`lz4` [*OPTIONS*] [-|INPUT-FILE] <OUTPUT-FILE>
8
9`unlz4` is equivalent to `lz4 -d`
10
11`lz4cat` is equivalent to `lz4 -dcfm`
12
13When writing scripts that need to decompress files,
14it is recommended to always use the name `lz4` with appropriate arguments
15(`lz4 -d` or `lz4 -dc`) instead of the names `unlz4` and `lz4cat`.
16
17
18DESCRIPTION
19-----------
20
21`lz4` is an extremely fast lossless compression algorithm,
22based on **byte-aligned LZ77** family of compression scheme.
23`lz4` offers compression speeds of 400 MB/s per core, linearly scalable with
24multi-core CPUs.
25It features an extremely fast decoder, with speed in multiple GB/s per core,
26typically reaching RAM speed limit on multi-core systems.
27The native file format is the `.lz4` format.
28
29### Difference between lz4 and gzip
30
31`lz4` supports a command line syntax similar _but not identical_ to `gzip(1)`.
32Differences are :
33
34  * `lz4` compresses a single file by default (see `-m` for multiple files)
35  * `lz4 file1 file2` means : compress file1 _into_ file2
36  * `lz4 file.lz4` will default to decompression (use `-z` to force compression)
37  * `lz4` preserves original files
38  * `lz4` shows real-time notification statistics
39     during compression or decompression of a single file
40     (use `-q` to silence them)
41  * When no destination is specified, result is sent on implicit output,
42    which depends on `stdout` status.
43    When `stdout` _is Not the console_, it becomes the implicit output.
44    Otherwise, if `stdout` is the console, the implicit output is `filename.lz4`.
45  * It is considered bad practice to rely on implicit output in scripts.
46    because the script's environment may change.
47    Always use explicit output in scripts.
48    `-c` ensures that output will be `stdout`.
49    Conversely, providing a destination name, or using `-m`
50    ensures that the output will be either the specified name, or `filename.lz4` respectively.
51
52Default behaviors can be modified by opt-in commands, detailed below.
53
54  * `lz4 -m` makes it possible to provide multiple input filenames,
55    which will be compressed into files using suffix `.lz4`.
56    Progress notifications become disabled by default (use `-v` to enable them).
57    This mode has a behavior which more closely mimics `gzip` command line,
58    with the main remaining difference being that source files are preserved by default.
59  * Similarly, `lz4 -m -d` can decompress multiple `*.lz4` files.
60  * It's possible to opt-in to erase source files
61    on successful compression or decompression, using `--rm` command.
62  * Consequently, `lz4 -m --rm` behaves the same as `gzip`.
63
64### Concatenation of .lz4 files
65
66It is possible to concatenate `.lz4` files as is.
67`lz4` will decompress such files as if they were a single `.lz4` file.
68For example:
69
70    lz4 file1  > foo.lz4
71    lz4 file2 >> foo.lz4
72
73Then `lz4cat foo.lz4` is equivalent to `cat file1 file2`.
74
75OPTIONS
76-------
77
78### Short commands concatenation
79
80In some cases, some options can be expressed using short command `-x`
81or long command `--long-word`.
82Short commands can be concatenated together.
83For example, `-d -c` is equivalent to `-dc`.
84Long commands cannot be concatenated. They must be clearly separated by a space.
85
86### Multiple commands
87
88When multiple contradictory commands are issued on a same command line,
89only the latest one will be applied.
90
91### Operation mode
92
93* `-z` `--compress`:
94  Compress.
95  This is the default operation mode when no operation mode option is
96  specified, no other operation mode is implied from the command name
97  (for example, `unlz4` implies `--decompress`),
98  nor from the input file name
99  (for example, a file extension `.lz4` implies  `--decompress` by default).
100  `-z` can also be used to force compression of an already compressed
101  `.lz4` file.
102
103* `-d` `--decompress` `--uncompress`:
104  Decompress.
105  `--decompress` is also the default operation when the input filename has an
106  `.lz4` extension.
107
108* `-t` `--test`:
109  Test the integrity of compressed `.lz4` files.
110  The decompressed data is discarded.
111  No files are created nor removed.
112
113* `-b#`:
114  Benchmark mode, using `#` compression level.
115
116* `--list`:
117  List information about .lz4 files.
118  note : current implementation is limited to single-frame .lz4 files.
119
120### Operation modifiers
121
122* `-#`:
123  Compression level, with # being any value from 1 to 12.
124  Higher values trade compression speed for compression ratio.
125  Values above 12 are considered the same as 12.
126  Recommended values are 1 for fast compression (default),
127  and 9 for high compression.
128  Speed/compression trade-off will vary depending on data to compress.
129  Decompression speed remains fast at all settings.
130
131* `--fast[=#]`:
132  Switch to ultra-fast compression levels.
133  The higher the value, the faster the compression speed, at the cost of some compression ratio.
134  If `=#` is not present, it defaults to `1`.
135  This setting overrides compression level if one was set previously.
136  Similarly, if a compression level is set after `--fast`, it overrides it.
137
138* `--best`:
139  Set highest compression level. Same as -12.
140
141* `--favor-decSpeed`:
142  Generate compressed data optimized for decompression speed.
143  Compressed data will be larger as a consequence (typically by ~0.5%),
144  while decompression speed will be improved by 5-20%, depending on use cases.
145  This option only works in combination with very high compression levels (>=10).
146
147* `-D dictionaryName`:
148  Compress, decompress or benchmark using dictionary _dictionaryName_.
149  Compression and decompression must use the same dictionary to be compatible.
150  Using a different dictionary during decompression will either
151  abort due to decompression error, or generate a checksum error.
152
153* `-f` `--[no-]force`:
154  This option has several effects:
155
156  If the target file already exists, overwrite it without prompting.
157
158  When used with `--decompress` and `lz4` cannot recognize the type of
159  the source file, copy the source file as is to standard output.
160  This allows `lz4cat --force` to be used like `cat (1)` for files
161  that have not been compressed with `lz4`.
162
163* `-c` `--stdout` `--to-stdout`:
164  Force write to standard output, even if it is the console.
165
166* `-m` `--multiple`:
167  Multiple input files.
168  Compressed file names will be appended a `.lz4` suffix.
169  This mode also reduces notification level.
170  Can also be used to list multiple files.
171  `lz4 -m` has a behavior equivalent to `gzip -k`
172  (it preserves source files by default).
173
174* `-r` :
175  operate recursively on directories.
176  This mode also sets `-m` (multiple input files).
177
178* `-B#`:
179  Block size \[4-7\](default : 7)<br/>
180  `-B4`= 64KB ; `-B5`= 256KB ; `-B6`= 1MB ; `-B7`= 4MB
181
182* `-BI`:
183  Produce independent blocks (default)
184
185* `-BD`:
186  Blocks depend on predecessors (improves compression ratio, more noticeable on small blocks)
187
188* `--[no-]frame-crc`:
189  Select frame checksum (default:enabled)
190
191* `--[no-]content-size`:
192  Header includes original size (default:not present)<br/>
193  Note : this option can only be activated when the original size can be
194  determined, hence for a file. It won't work with unknown source size,
195  such as stdin or pipe.
196
197* `--[no-]sparse`:
198  Sparse mode support (default:enabled on file, disabled on stdout)
199
200* `-l`:
201  Use Legacy format (typically for Linux Kernel compression)<br/>
202  Note : `-l` is not compatible with `-m` (`--multiple`) nor `-r`
203
204### Other options
205
206* `-v` `--verbose`:
207  Verbose mode
208
209* `-q` `--quiet`:
210  Suppress warnings and real-time statistics;
211  specify twice to suppress errors too
212
213* `-h` `-H` `--help`:
214  Display help/long help and exit
215
216* `-V` `--version`:
217  Display Version number and exit
218
219* `-k` `--keep`:
220  Preserve source files (default behavior)
221
222* `--rm` :
223  Delete source files on successful compression or decompression
224
225* `--` :
226  Treat all subsequent arguments as files
227
228
229### Benchmark mode
230
231* `-b#`:
232  Benchmark file(s), using # compression level
233
234* `-e#`:
235  Benchmark multiple compression levels, from b# to e# (included)
236
237* `-i#`:
238  Minimum evaluation time in seconds \[1-9\] (default : 3)
239
240
241BUGS
242----
243
244Report bugs at: https://github.com/lz4/lz4/issues
245
246
247AUTHOR
248------
249
250Yann Collet
251