\."
\." lz4.1: This is a manual page for 'lz4' program. This file is part of the
\." lz4 project.
\." Author: Yann Collet
\."
.
\." No hyphenation
.hy 0
.nr HY 0
.
.TH lz4 "1" "2015-03-21" "lz4" "User Commands"
.SH NAME
\fBlz4, unlz4, lz4cat\fR \- Compress or decompress .lz4 files
.SH SYNOPSIS
.TP 5
\fBlz4\fR [\fBOPTIONS\fR] [-|INPUT-FILE]
.PP
.B unlz4
is equivalent to
.BR "lz4 \-d"
.br
.B lz4cat
is equivalent to
.BR "lz4 \-dcfm"
.br
.PP
When writing scripts that need to decompress files,
it is recommended to always use the name
.B lz4
with appropriate arguments
.RB ( "lz4 \-d"
or
.BR "lz4 \-dc" )
instead of the names
.B unlz4
and
.BR lz4cat .
.SH DESCRIPTION
.PP
\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
.B .lz4
format.
.B lz4
supports a command line syntax similar \fIbut not identical\fR to
.BR gzip (1).
Differences are :
\fBlz4\fR preserves original files
\fBlz4\fR compresses a single file by default (use \fB-m\fR for multiple files)
\fBlz4 file1 file2\fR means : compress file1 \fIinto\fR file2
When no destination name is provided, compressed file name receives a \fB.lz4\fR suffix
When no destination name is provided, if \fBstdout\fR is \fInot\fR the console, it becomes the output (like a silent \fB-c\fR)
Therefore \fBlz4 file > /dev/null\fR will not create \fBfile.lz4\fR
\fBlz4 file\fR shows real-time statistics during compression (use \fB-q\fR to silent them)
Default behaviors can be modified by opt-in commands, described below.
\fBlz4 --quiet --multiple\fR more closely mimics \fBgzip\fR behavior.
.SS "Concatenation of .lz4 files"
It is possible to concatenate
.B .lz4
files as is.
.B lz4
will decompress such files as if they were a single
.B .lz4
file. For example:
lz4 file1 > foo.lz4
lz4 file2 >> foo.lz4
then
lz4cat foo.lz4
is equivalent to :
cat file1 file2
.PP
.SH OPTIONS
.
.SS "Short commands concatenation"
In some cases, some options can be expressed using short command
.B "-x"
or long command
.B "--long-word" .
Short commands can be concatenated together. For example,
.B "-d -c"
is equivalent to
.B "-dc" .
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
.BR \-z ", " \-\-compress
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,
.B unlz4
implies
.B \-\-decompress ),
nor from the input file name
(for example, a file extension
.B .lz4
implies
.B \-\-decompress
by default).
.B -z
can also be used to force compression of an already compressed
.B .lz4
file.
.TP
.BR \-d ", " \-\-decompress ", " \-\-uncompress
Decompress.
.B --decompress
is also the default operation when the input filename has an
.B .lz4
extension.
.TP
.BR \-t ", " \-\-test
Test the integrity of compressed
.B .lz4
files.
The decompressed data is discarded.
No files are created nor removed.
.TP
.BR \-b#
Benchmark mode, using # compression level.
.
.SS "Operation modifiers"
.TP
.B \-#
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
.BR \-f ", " --[no-]force
This option has several effects:
.RS
.IP \(bu 3
If the target file already exists,
overwrite it without prompting.
.IP \(bu 3
When used with
.B \-\-decompress
and
.B lz4
cannot recognize the type of the source file,
copy the source file as is to standard output.
This allows
.B lz4cat
.B \-\-force
to be used like
.BR cat (1)
for files that have not been compressed with
.BR lz4 .
.RE
.TP
.BR \-c ", " \--stdout ", " \--to-stdout
force write to standard output, even if it is the console
.TP
.BR \-m ", " \--multiple
Multiple file names.
By default, the second filename is used as the destination filename for the compressed file.
With
.B -m
, it is possible to specify any number of input filenames. Each of them will be compressed
independently, and the resulting name of each compressed file will be
.B filename.lz4
.
.TP
.B \-B#
block size [4-7](default : 7)
B4= 64KB ; B5= 256KB ; B6= 1MB ; B7= 4MB
.TP
.B \-BD
block dependency (improves compression ratio on small blocks)
.TP
.B \--[no-]frame-crc
select frame checksum (default:enabled)
.TP
.B \--[no-]content-size
header includes original size (default:not present)
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
.B \--[no-]sparse
sparse mode support (default:enabled on file, disabled on stdout)
.TP
.B \-l
use Legacy format (useful for Linux Kernel compression)
.
.SS "Other options"
.TP
.BR \-v ", " --verbose
verbose mode
.TP
.BR \-q ", " --quiet
suppress warnings and real-time statistics; specify twice to suppress errors too
.TP
.B \-h/\-H ", " --help
display help/long help and exit
.TP
.BR \-V ", " \--version
display Version number and exit
.TP
.BR \-k ", " \--keep
Don't delete source file.
This is default behavior anyway, so this option is just for compatibility with gzip/xz.
.
.SS "Benchmark mode"
.TP
.B \-b#
benchmark file(s), using # compression level
.TP
.B \-e#
benchmark multiple compression levels, from b# to e# (included)
.TP
.B \-i#
minimum evaluation in seconds [1-9] (default : 3)
.TP
.B \-r
operate recursively on directories
.SH BUGS
Report bugs at: https://github.com/Cyan4973/lz4/issues
.SH AUTHOR
Yann Collet