1 lz4(1) -- lz4, unlz4, lz4cat - Compress or decompress .lz4 files 2 ================================================================ 3 4 SYNOPSIS 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 13 When writing scripts that need to decompress files, 14 it 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 18 DESCRIPTION 19 ----------- 20 21 `lz4` is an extremely fast lossless compression algorithm, 22 based on **byte-aligned LZ77** family of compression scheme. 23 `lz4` offers compression speeds of 400 MB/s per core, linearly scalable with 24 multi-core CPUs. 25 It features an extremely fast decoder, with speed in multiple GB/s per core, 26 typically reaching RAM speed limit on multi-core systems. 27 The 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)`. 32 Differences 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 silent 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 49 Default behaviors can be modified by opt-in commands, detailed below. 50 51 * `lz4 -m` makes it possible to provide multiple input filenames, 52 which will be compressed into files using suffix `.lz4`. 53 Progress notifications are also disabled by default (use `-v` to enable them). 54 This mode has a behavior which more closely mimics `gzip` command line, 55 with the main remaining difference being that source files are preserved by default. 56 * Similarly, `lz4 -m -d` can decompress multiple `*.lz4` files. 57 * It's possible to opt-in to erase source files 58 on successful compression or decompression, using `--rm` command. 59 * Consequently, `lz4 -m --rm` behaves the same as `gzip`. 60 61 ### Concatenation of .lz4 files 62 63 It is possible to concatenate `.lz4` files as is. 64 `lz4` will decompress such files as if they were a single `.lz4` file. 65 For example: 66 lz4 file1 > foo.lz4 67 lz4 file2 >> foo.lz4 68 69 then 70 lz4cat foo.lz4 71 72 is equivalent to : 73 cat file1 file2 74 75 76 OPTIONS 77 ------- 78 79 ### Short commands concatenation 80 81 In some cases, some options can be expressed using short command `-x` 82 or long command `--long-word`. 83 Short commands can be concatenated together. 84 For example, `-d -c` is equivalent to `-dc`. 85 Long commands cannot be concatenated. 86 They must be clearly separated by a space. 87 88 ### Multiple commands 89 90 When multiple contradictory commands are issued on a same command line, 91 only the latest one will be applied. 92 93 ### Operation mode 94 95 * `-z` `--compress`: 96 Compress. 97 This is the default operation mode when no operation mode option is 98 specified, no other operation mode is implied from the command name 99 (for example, `unlz4` implies `--decompress`), 100 nor from the input file name 101 (for example, a file extension `.lz4` implies `--decompress` by default). 102 `-z` can also be used to force compression of an already compressed 103 `.lz4` file. 104 105 * `-d` `--decompress` `--uncompress`: 106 Decompress. 107 `--decompress` is also the default operation when the input filename has an 108 `.lz4` extension. 109 110 * `-t` `--test`: 111 Test the integrity of compressed `.lz4` files. 112 The decompressed data is discarded. 113 No files are created nor removed. 114 115 * `-b#`: 116 Benchmark mode, using `#` compression level. 117 118 ### Operation modifiers 119 120 * `-#`: 121 Compression level, with # being any value from 1 to 16. 122 Higher values trade compression speed for compression ratio. 123 Values above 16 are considered the same as 16. 124 Recommended values are 1 for fast compression (default), 125 and 9 for high compression. 126 Speed/compression trade-off will vary depending on data to compress. 127 Decompression speed remains fast at all settings. 128 129 * `-f` `--[no-]force`: 130 This option has several effects: 131 132 If the target file already exists, overwrite it without prompting. 133 134 When used with `--decompress` and `lz4` cannot recognize the type of 135 the source file, copy the source file as is to standard output. 136 This allows `lz4cat --force` to be used like `cat (1)` for files 137 that have not been compressed with `lz4`. 138 139 * `-c` `--stdout` `--to-stdout`: 140 Force write to standard output, even if it is the console. 141 142 * `-m` `--multiple`: 143 Multiple input files. 144 Compressed file names will be appended a `.lz4` suffix. 145 This mode also reduces notification level. 146 `lz4 -m` has a behavior equivalent to `gzip -k` 147 (it preserves source files by default). 148 149 * `-r` : 150 operate recursively on directories. 151 This mode also sets `-m` (multiple input files). 152 153 * `-B#`: 154 Block size \[4-7\](default : 7)<br/> 155 `-B4`= 64KB ; `-B5`= 256KB ; `-B6`= 1MB ; `-B7`= 4MB 156 157 * `-BD`: 158 Block Dependency (improves compression ratio on small blocks) 159 160 * `--[no-]frame-crc`: 161 Select frame checksum (default:enabled) 162 163 * `--[no-]content-size`: 164 Header includes original size (default:not present)<br/> 165 Note : this option can only be activated when the original size can be 166 determined, hence for a file. It won't work with unknown source size, 167 such as stdin or pipe. 168 169 * `--[no-]sparse`: 170 Sparse mode support (default:enabled on file, disabled on stdout) 171 172 * `-l`: 173 Use Legacy format (typically for Linux Kernel compression)<br/> 174 Note : `-l` is not compatible with `-m` (`--multiple`) nor `-r` 175 176 ### Other options 177 178 * `-v` `--verbose`: 179 Verbose mode 180 181 * `-q` `--quiet`: 182 Suppress warnings and real-time statistics; 183 specify twice to suppress errors too 184 185 * `-h` `-H` `--help`: 186 Display help/long help and exit 187 188 * `-V` `--version`: 189 Display Version number and exit 190 191 * `-k` `--keep`: 192 Preserve source files (default behavior) 193 194 * `--rm` : 195 Delete source files on successful compression or decompression 196 197 198 ### Benchmark mode 199 200 * `-b#`: 201 Benchmark file(s), using # compression level 202 203 * `-e#`: 204 Benchmark multiple compression levels, from b# to e# (included) 205 206 * `-i#`: 207 Minimum evaluation in seconds \[1-9\] (default : 3) 208 209 210 BUGS 211 ---- 212 213 Report bugs at: https://github.com/lz4/lz4/issues 214 215 216 AUTHOR 217 ------ 218 219 Yann Collet 220
