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