• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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` preserves original files
35  * `lz4` compresses a single file by default (see `-m` for multiple files)
36  * `lz4 file1 file2` means : compress file1 _into_ file2
37  * `lz4 file.lz4` will default to decompression (use `-z` to force compression)
38  * `lz4` shows real-time notification statistics
39     during compression or decompression of a single file
40     (use `-q` to silence them)
41  * If no destination name is provided, result is sent to `stdout`
42    _except if stdout is the console_.
43  * If no destination name is provided, __and__ if `stdout` is the console,
44    `file` is compressed into `file.lz4`.
45  * As a consequence of previous rules, note the following example :
46    `lz4 file | consumer` sends compressed data to `consumer` through `stdout`,
47    hence it does _not_ create `file.lz4`.
48  * Another consequence of those rules is that to run `lz4` under `nohup`,
49    you should provide a destination file: `nohup lz4 file file.lz4`,
50    because `nohup` writes the specified command's output to a file.
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 are also 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.
85They must be clearly separated by a space.
86
87### Multiple commands
88
89When multiple contradictory commands are issued on a same command line,
90only the latest one will be applied.
91
92### Operation mode
93
94* `-z` `--compress`:
95  Compress.
96  This is the default operation mode when no operation mode option is
97  specified, no other operation mode is implied from the command name
98  (for example, `unlz4` implies `--decompress`),
99  nor from the input file name
100  (for example, a file extension `.lz4` implies  `--decompress` by default).
101  `-z` can also be used to force compression of an already compressed
102  `.lz4` file.
103
104* `-d` `--decompress` `--uncompress`:
105  Decompress.
106  `--decompress` is also the default operation when the input filename has an
107  `.lz4` extension.
108
109* `-t` `--test`:
110  Test the integrity of compressed `.lz4` files.
111  The decompressed data is discarded.
112  No files are created nor removed.
113
114* `-b#`:
115  Benchmark mode, using `#` compression level.
116
117### Operation modifiers
118
119* `-#`:
120  Compression level, with # being any value from 1 to 12.
121  Higher values trade compression speed for compression ratio.
122  Values above 12 are considered the same as 12.
123  Recommended values are 1 for fast compression (default),
124  and 9 for high compression.
125  Speed/compression trade-off will vary depending on data to compress.
126  Decompression speed remains fast at all settings.
127
128* `--fast[=#]`:
129  switch to ultra-fast compression levels.
130  The higher the value, the faster the compression speed, at the cost of some compression ratio.
131  If `=#` is not present, it defaults to `1`.
132  This setting overrides compression level if one was set previously.
133  Similarly, if a compression level is set after `--fast`, it overrides it.
134
135* `-D dictionaryName`:
136  Compress, decompress or benchmark using dictionary _dictionaryName_.
137  Compression and decompression must use the same dictionary to be compatible.
138  Using a different dictionary during decompression will either
139  abort due to decompression error, or generate a checksum error.
140
141* `-f` `--[no-]force`:
142  This option has several effects:
143
144  If the target file already exists, overwrite it without prompting.
145
146  When used with `--decompress` and `lz4` cannot recognize the type of
147  the source file, copy the source file as is to standard output.
148  This allows `lz4cat --force` to be used like `cat (1)` for files
149  that have not been compressed with `lz4`.
150
151* `-c` `--stdout` `--to-stdout`:
152  Force write to standard output, even if it is the console.
153
154* `-m` `--multiple`:
155  Multiple input files.
156  Compressed file names will be appended a `.lz4` suffix.
157  This mode also reduces notification level.
158  `lz4 -m` has a behavior equivalent to `gzip -k`
159  (it preserves source files by default).
160
161* `-r` :
162  operate recursively on directories.
163  This mode also sets `-m` (multiple input files).
164
165* `-B#`:
166  Block size \[4-7\](default : 7)<br/>
167  `-B4`= 64KB ; `-B5`= 256KB ; `-B6`= 1MB ; `-B7`= 4MB
168
169* `-BD`:
170  Block Dependency (improves compression ratio on small blocks)
171
172* `--[no-]frame-crc`:
173  Select frame checksum (default:enabled)
174
175* `--[no-]content-size`:
176  Header includes original size (default:not present)<br/>
177  Note : this option can only be activated when the original size can be
178  determined, hence for a file. It won't work with unknown source size,
179  such as stdin or pipe.
180
181* `--[no-]sparse`:
182  Sparse mode support (default:enabled on file, disabled on stdout)
183
184* `-l`:
185  Use Legacy format (typically for Linux Kernel compression)<br/>
186  Note : `-l` is not compatible with `-m` (`--multiple`) nor `-r`
187
188### Other options
189
190* `-v` `--verbose`:
191  Verbose mode
192
193* `-q` `--quiet`:
194  Suppress warnings and real-time statistics;
195  specify twice to suppress errors too
196
197* `-h` `-H` `--help`:
198  Display help/long help and exit
199
200* `-V` `--version`:
201  Display Version number and exit
202
203* `-k` `--keep`:
204  Preserve source files (default behavior)
205
206* `--rm` :
207  Delete source files on successful compression or decompression
208
209* `--` :
210  Treat all subsequent arguments as files
211
212
213### Benchmark mode
214
215* `-b#`:
216  Benchmark file(s), using # compression level
217
218* `-e#`:
219  Benchmark multiple compression levels, from b# to e# (included)
220
221* `-i#`:
222  Minimum evaluation time in seconds \[1-9\] (default : 3)
223
224
225BUGS
226----
227
228Report bugs at: https://github.com/lz4/lz4/issues
229
230
231AUTHOR
232------
233
234Yann Collet
235