221 lines
7.4 KiB
Groff
221 lines
7.4 KiB
Groff
.
|
|
.TH "LZ4" "1" "July 2017" "lz4 1.8.0" "User Commands"
|
|
.
|
|
.SH "NAME"
|
|
\fBlz4\fR \- lz4, unlz4, lz4cat \- Compress or decompress \.lz4 files
|
|
.
|
|
.SH "SYNOPSIS"
|
|
\fBlz4\fR [\fIOPTIONS\fR] [\-|INPUT\-FILE] \fIOUTPUT\-FILE\fR
|
|
.
|
|
.P
|
|
\fBunlz4\fR is equivalent to \fBlz4 \-d\fR
|
|
.
|
|
.P
|
|
\fBlz4cat\fR is equivalent to \fBlz4 \-dcfm\fR
|
|
.
|
|
.P
|
|
When writing scripts that need to decompress files, it is recommended to always use the name \fBlz4\fR with appropriate arguments (\fBlz4 \-d\fR or \fBlz4 \-dc\fR) instead of the names \fBunlz4\fR and \fBlz4cat\fR\.
|
|
.
|
|
.SH "DESCRIPTION"
|
|
\fBlz4\fR is an extremely fast lossless compression algorithm, based on \fBbyte\-aligned LZ77\fR family of compression scheme\. \fBlz4\fR offers compression speeds of 400 MB/s per core, linearly scalable with multi\-core CPUs\. It features an extremely fast decoder, with speed in multiple GB/s per core, typically reaching RAM speed limit on multi\-core systems\. The native file format is the \fB\.lz4\fR format\.
|
|
.
|
|
.SS "Difference between lz4 and gzip"
|
|
\fBlz4\fR supports a command line syntax similar \fIbut not identical\fR to \fBgzip(1)\fR\. Differences are :
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBlz4\fR preserves original files
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBlz4\fR compresses a single file by default (see \fB\-m\fR for multiple files)
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBlz4 file1 file2\fR means : compress file1 \fIinto\fR file2
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBlz4 file\.lz4\fR will default to decompression (use \fB\-z\fR to force compression)
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBlz4\fR shows real\-time notification statistics during compression or decompression of a single file (use \fB\-q\fR to silent them)
|
|
.
|
|
.IP "\(bu" 4
|
|
If no destination name is provided, result is sent to \fBstdout\fR \fIexcept if stdout is the console\fR\.
|
|
.
|
|
.IP "\(bu" 4
|
|
If no destination name is provided, \fBand\fR if \fBstdout\fR is the console, \fBfile\fR is compressed into \fBfile\.lz4\fR\.
|
|
.
|
|
.IP "\(bu" 4
|
|
As a consequence of previous rules, note the following example : \fBlz4 file | consumer\fR sends compressed data to \fBconsumer\fR through \fBstdout\fR, hence it does \fInot\fR create \fBfile\.lz4\fR\.
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
Default behaviors can be modified by opt\-in commands, detailed below\.
|
|
.
|
|
.IP "\(bu" 4
|
|
\fBlz4 \-m\fR makes it possible to provide multiple input filenames, which will be compressed into files using suffix \fB\.lz4\fR\. Progress notifications are also disabled by default (use \fB\-v\fR to enable them)\. This mode has a behavior which more closely mimics \fBgzip\fR command line, with the main remaining difference being that source files are preserved by default\.
|
|
.
|
|
.IP "\(bu" 4
|
|
Similarly, \fBlz4 \-m \-d\fR can decompress multiple \fB*\.lz4\fR files\.
|
|
.
|
|
.IP "\(bu" 4
|
|
It\'s possible to opt\-in to erase source files on successful compression or decompression, using \fB\-\-rm\fR command\.
|
|
.
|
|
.IP "\(bu" 4
|
|
Consequently, \fBlz4 \-m \-\-rm\fR behaves the same as \fBgzip\fR\.
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.SS "Concatenation of \.lz4 files"
|
|
It is possible to concatenate \fB\.lz4\fR files as is\. \fBlz4\fR will decompress such files as if they were a single \fB\.lz4\fR file\. For example:
|
|
.
|
|
.IP "" 4
|
|
.
|
|
.nf
|
|
|
|
lz4 file1 > foo\.lz4
|
|
lz4 file2 >> foo\.lz4
|
|
.
|
|
.fi
|
|
.
|
|
.IP "" 0
|
|
.
|
|
.P
|
|
Then \fBlz4cat foo\.lz4\fR is equivalent to \fBcat file1 file2\fR\.
|
|
.
|
|
.SH "OPTIONS"
|
|
.
|
|
.SS "Short commands concatenation"
|
|
In some cases, some options can be expressed using short command \fB\-x\fR or long command \fB\-\-long\-word\fR\. Short commands can be concatenated together\. For example, \fB\-d \-c\fR is equivalent to \fB\-dc\fR\. Long commands cannot be concatenated\. They must be clearly separated by a space\.
|
|
.
|
|
.SS "Multiple commands"
|
|
When multiple contradictory commands are issued on a same command line, only the latest one will be applied\.
|
|
.
|
|
.SS "Operation mode"
|
|
.
|
|
.TP
|
|
\fB\-z\fR \fB\-\-compress\fR
|
|
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, \fBunlz4\fR implies \fB\-\-decompress\fR), nor from the input file name (for example, a file extension \fB\.lz4\fR implies \fB\-\-decompress\fR by default)\. \fB\-z\fR can also be used to force compression of an already compressed \fB\.lz4\fR file\.
|
|
.
|
|
.TP
|
|
\fB\-d\fR \fB\-\-decompress\fR \fB\-\-uncompress\fR
|
|
Decompress\. \fB\-\-decompress\fR is also the default operation when the input filename has an \fB\.lz4\fR extension\.
|
|
.
|
|
.TP
|
|
\fB\-t\fR \fB\-\-test\fR
|
|
Test the integrity of compressed \fB\.lz4\fR files\. The decompressed data is discarded\. No files are created nor removed\.
|
|
.
|
|
.TP
|
|
\fB\-b#\fR
|
|
Benchmark mode, using \fB#\fR compression level\.
|
|
.
|
|
.SS "Operation modifiers"
|
|
.
|
|
.TP
|
|
\fB\-#\fR
|
|
Compression level, with # being any value from 1 to 16\. Higher values trade compression speed for compression ratio\. Values above 16 are considered the same as 16\. 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\.
|
|
.
|
|
.TP
|
|
\fB\-f\fR \fB\-\-[no\-]force\fR
|
|
This option has several effects:
|
|
.
|
|
.IP
|
|
If the target file already exists, overwrite it without prompting\.
|
|
.
|
|
.IP
|
|
When used with \fB\-\-decompress\fR and \fBlz4\fR cannot recognize the type of the source file, copy the source file as is to standard output\. This allows \fBlz4cat \-\-force\fR to be used like \fBcat (1)\fR for files that have not been compressed with \fBlz4\fR\.
|
|
.
|
|
.TP
|
|
\fB\-c\fR \fB\-\-stdout\fR \fB\-\-to\-stdout\fR
|
|
Force write to standard output, even if it is the console\.
|
|
.
|
|
.TP
|
|
\fB\-m\fR \fB\-\-multiple\fR
|
|
Multiple input files\. Compressed file names will be appended a \fB\.lz4\fR suffix\. This mode also reduces notification level\. \fBlz4 \-m\fR has a behavior equivalent to \fBgzip \-k\fR (it preserves source files by default)\.
|
|
.
|
|
.TP
|
|
\fB\-r\fR
|
|
operate recursively on directories\. This mode also sets \fB\-m\fR (multiple input files)\.
|
|
.
|
|
.TP
|
|
\fB\-B#\fR
|
|
Block size [4\-7](default : 7)
|
|
.
|
|
.br
|
|
\fB\-B4\fR= 64KB ; \fB\-B5\fR= 256KB ; \fB\-B6\fR= 1MB ; \fB\-B7\fR= 4MB
|
|
.
|
|
.TP
|
|
\fB\-BD\fR
|
|
Block Dependency (improves compression ratio on small blocks)
|
|
.
|
|
.TP
|
|
\fB\-\-[no\-]frame\-crc\fR
|
|
Select frame checksum (default:enabled)
|
|
.
|
|
.TP
|
|
\fB\-\-[no\-]content\-size\fR
|
|
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\.
|
|
.
|
|
.TP
|
|
\fB\-\-[no\-]sparse\fR
|
|
Sparse mode support (default:enabled on file, disabled on stdout)
|
|
.
|
|
.TP
|
|
\fB\-l\fR
|
|
Use Legacy format (typically for Linux Kernel compression)
|
|
.
|
|
.br
|
|
Note : \fB\-l\fR is not compatible with \fB\-m\fR (\fB\-\-multiple\fR) nor \fB\-r\fR
|
|
.
|
|
.SS "Other options"
|
|
.
|
|
.TP
|
|
\fB\-v\fR \fB\-\-verbose\fR
|
|
Verbose mode
|
|
.
|
|
.TP
|
|
\fB\-q\fR \fB\-\-quiet\fR
|
|
Suppress warnings and real\-time statistics; specify twice to suppress errors too
|
|
.
|
|
.TP
|
|
\fB\-h\fR \fB\-H\fR \fB\-\-help\fR
|
|
Display help/long help and exit
|
|
.
|
|
.TP
|
|
\fB\-V\fR \fB\-\-version\fR
|
|
Display Version number and exit
|
|
.
|
|
.TP
|
|
\fB\-k\fR \fB\-\-keep\fR
|
|
Preserve source files (default behavior)
|
|
.
|
|
.TP
|
|
\fB\-\-rm\fR
|
|
Delete source files on successful compression or decompression
|
|
.
|
|
.TP
|
|
\fB\-\-\fR
|
|
Treat all subsequent arguments as files
|
|
.
|
|
.SS "Benchmark mode"
|
|
.
|
|
.TP
|
|
\fB\-b#\fR
|
|
Benchmark file(s), using # compression level
|
|
.
|
|
.TP
|
|
\fB\-e#\fR
|
|
Benchmark multiple compression levels, from b# to e# (included)
|
|
.
|
|
.TP
|
|
\fB\-i#\fR
|
|
Minimum evaluation in seconds [1\-9] (default : 3)
|
|
.
|
|
.SH "BUGS"
|
|
Report bugs at: https://github\.com/lz4/lz4/issues
|
|
.
|
|
.SH "AUTHOR"
|
|
Yann Collet
|