227 lines
11 KiB
HTML
227 lines
11 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of LZ4</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>LZ4</H1>
|
|
Section: User Commands (1)<BR>Updated: July 2019<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
<B>lz4</B> - lz4, unlz4, lz4cat - Compress or decompress .lz4 files
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>lz4</B> [<I>OPTIONS</I>] [-|INPUT-FILE] <I>OUTPUT-FILE</I>
|
|
<P>
|
|
|
|
<B>unlz4</B> is equivalent to <B>lz4 -d</B>
|
|
<P>
|
|
|
|
<B>lz4cat</B> is equivalent to <B>lz4 -dcfm</B>
|
|
<P>
|
|
|
|
When writing scripts that need to decompress files, it is recommended to always use the name <B>lz4</B> with appropriate arguments (<B>lz4 -d</B> or <B>lz4 -dc</B>) instead of the names <B>unlz4</B> and <B>lz4cat</B>.
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>lz4</B> is an extremely fast lossless compression algorithm, based on <B>byte-aligned LZ77</B> family of compression scheme. <B>lz4</B> 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</B> format.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Difference between lz4 and gzip</H3>
|
|
|
|
<B>lz4</B> supports a command line syntax similar <I>but not identical</I> to <B><A HREF="/cgi-bin/man/man2html?1+gzip">gzip</A>(1)</B>. Differences are :
|
|
<DL COMPACT>
|
|
<DT id="1">•<DD>
|
|
<B>lz4</B> compresses a single file by default (see <B>-m</B> for multiple files)
|
|
<DT id="2">•<DD>
|
|
<B>lz4 file1 file2</B> means : compress file1 <I>into</I> file2
|
|
<DT id="3">•<DD>
|
|
<B>lz4 file.lz4</B> will default to decompression (use <B>-z</B> to force compression)
|
|
<DT id="4">•<DD>
|
|
<B>lz4</B> preserves original files
|
|
<DT id="5">•<DD>
|
|
<B>lz4</B> shows real-time notification statistics during compression or decompression of a single file (use <B>-q</B> to silence them)
|
|
<DT id="6">•<DD>
|
|
When no destination is specified, result is sent on implicit output, which depends on <B>stdout</B> status. When <B>stdout</B> <I>is Not the console</I>, it becomes the implicit output. Otherwise, if <B>stdout</B> is the console, the implicit output is <B>filename.lz4</B>.
|
|
<DT id="7">•<DD>
|
|
It is considered bad practice to rely on implicit output in scripts. because the script's environment may change. Always use explicit output in scripts. <B>-c</B> ensures that output will be <B>stdout</B>. Conversely, providing a destination name, or using <B>-m</B> ensures that the output will be either the specified name, or <B>filename.lz4</B> respectively.
|
|
<DT id="8"><DD>
|
|
</DL>
|
|
<P>
|
|
|
|
Default behaviors can be modified by opt-in commands, detailed below.
|
|
<DL COMPACT>
|
|
<DT id="9">•<DD>
|
|
<B>lz4 -m</B> makes it possible to provide multiple input filenames, which will be compressed into files using suffix <B>.lz4</B>. Progress notifications become disabled by default (use <B>-v</B> to enable them). This mode has a behavior which more closely mimics <B>gzip</B> command line, with the main remaining difference being that source files are preserved by default.
|
|
<DT id="10">•<DD>
|
|
Similarly, <B>lz4 -m -d</B> can decompress multiple <B>*.lz4</B> files.
|
|
<DT id="11">•<DD>
|
|
It's possible to opt-in to erase source files on successful compression or decompression, using <B>--rm</B> command.
|
|
<DT id="12">•<DD>
|
|
Consequently, <B>lz4 -m --rm</B> behaves the same as <B>gzip</B>.
|
|
<DT id="13"><DD>
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Concatenation of .lz4 files</H3>
|
|
|
|
It is possible to concatenate <B>.lz4</B> files as is. <B>lz4</B> will decompress such files as if they were a single <B>.lz4</B> file. For example:
|
|
<DL COMPACT>
|
|
<DT id="14"><DD>
|
|
<PRE>
|
|
|
|
lz4 file1 > foo.lz4
|
|
lz4 file2 >> foo.lz4
|
|
</PRE>
|
|
|
|
<DT id="15"><DD>
|
|
</DL>
|
|
<P>
|
|
|
|
Then <B>lz4cat foo.lz4</B> is equivalent to <B>cat file1 file2</B>.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Short commands concatenation</H3>
|
|
|
|
In some cases, some options can be expressed using short command <B>-x</B> or long command <B>--long-word</B>. Short commands can be concatenated together. For example, <B>-d -c</B> is equivalent to <B>-dc</B>. Long commands cannot be concatenated. They must be clearly separated by a space.
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Multiple commands</H3>
|
|
|
|
When multiple contradictory commands are issued on a same command line, only the latest one will be applied.
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Operation mode</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="16"><B>-z</B> <B>--compress</B><DD>
|
|
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</B> implies <B>--decompress</B>), nor from the input file name (for example, a file extension <B>.lz4</B> implies <B>--decompress</B> by default). <B>-z</B> can also be used to force compression of an already compressed <B>.lz4</B> file.
|
|
<DT id="17"><B>-d</B> <B>--decompress</B> <B>--uncompress</B><DD>
|
|
Decompress. <B>--decompress</B> is also the default operation when the input filename has an <B>.lz4</B> extension.
|
|
<DT id="18"><B>-t</B> <B>--test</B><DD>
|
|
Test the integrity of compressed <B>.lz4</B> files. The decompressed data is discarded. No files are created nor removed.
|
|
<DT id="19"><B>-b#</B><DD>
|
|
Benchmark mode, using <B>#</B> compression level.
|
|
<DT id="20"><B>--list</B><DD>
|
|
List information about .lz4 files. note : current implementation is limited to single-frame .lz4 files.
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Operation modifiers</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="21"><B>-#</B><DD>
|
|
Compression level, with # being any value from 1 to 12. Higher values trade compression speed for compression ratio. Values above 12 are considered the same as 12. 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.
|
|
<DT id="22"><B>--fast[=#]</B><DD>
|
|
Switch to ultra-fast compression levels. The higher the value, the faster the compression speed, at the cost of some compression ratio. If <B>=#</B> is not present, it defaults to <B>1</B>. This setting overrides compression level if one was set previously. Similarly, if a compression level is set after <B>--fast</B>, it overrides it.
|
|
<DT id="23"><B>--best</B><DD>
|
|
Set highest compression level. Same as -12.
|
|
<DT id="24"><B>--favor-decSpeed</B><DD>
|
|
Generate compressed data optimized for decompression speed. Compressed data will be larger as a consequence (typically by ~0.5%), while decompression speed will be improved by 5-20%, depending on use cases. This option only works in combination with very high compression levels (>=10).
|
|
<DT id="25"><B>-D dictionaryName</B><DD>
|
|
Compress, decompress or benchmark using dictionary <I>dictionaryName</I>. Compression and decompression must use the same dictionary to be compatible. Using a different dictionary during decompression will either abort due to decompression error, or generate a checksum error.
|
|
<DT id="26"><B>-f</B> <B>--[no-]force</B><DD>
|
|
This option has several effects:
|
|
<DT id="27"><DD>
|
|
If the target file already exists, overwrite it without prompting.
|
|
<DT id="28"><DD>
|
|
When used with <B>--decompress</B> and <B>lz4</B> cannot recognize the type of the source file, copy the source file as is to standard output. This allows <B>lz4cat --force</B> to be used like <B>cat (1)</B> for files that have not been compressed with <B>lz4</B>.
|
|
<DT id="29"><B>-c</B> <B>--stdout</B> <B>--to-stdout</B><DD>
|
|
Force write to standard output, even if it is the console.
|
|
<DT id="30"><B>-m</B> <B>--multiple</B><DD>
|
|
Multiple input files. Compressed file names will be appended a <B>.lz4</B> suffix. This mode also reduces notification level. Can also be used to list multiple files. <B>lz4 -m</B> has a behavior equivalent to <B>gzip -k</B> (it preserves source files by default).
|
|
<DT id="31"><B>-r</B><DD>
|
|
operate recursively on directories. This mode also sets <B>-m</B> (multiple input files).
|
|
<DT id="32"><B>-B#</B><DD>
|
|
Block size [4-7](default : 7)
|
|
<BR>
|
|
|
|
<B>-B4</B>= 64KB ; <B>-B5</B>= 256KB ; <B>-B6</B>= 1MB ; <B>-B7</B>= 4MB
|
|
<DT id="33"><B>-BI</B><DD>
|
|
Produce independent blocks (default)
|
|
<DT id="34"><B>-BD</B><DD>
|
|
Blocks depend on predecessors (improves compression ratio, more noticeable on small blocks)
|
|
<DT id="35"><B>--[no-]frame-crc</B><DD>
|
|
Select frame checksum (default:enabled)
|
|
<DT id="36"><B>--[no-]content-size</B><DD>
|
|
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.
|
|
<DT id="37"><B>--[no-]sparse</B><DD>
|
|
Sparse mode support (default:enabled on file, disabled on stdout)
|
|
<DT id="38"><B>-l</B><DD>
|
|
Use Legacy format (typically for Linux Kernel compression)
|
|
<BR>
|
|
|
|
Note : <B>-l</B> is not compatible with <B>-m</B> (<B>--multiple</B>) nor <B>-r</B>
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Other options</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="39"><B>-v</B> <B>--verbose</B><DD>
|
|
Verbose mode
|
|
<DT id="40"><B>-q</B> <B>--quiet</B><DD>
|
|
Suppress warnings and real-time statistics; specify twice to suppress errors too
|
|
<DT id="41"><B>-h</B> <B>-H</B> <B>--help</B><DD>
|
|
Display help/long help and exit
|
|
<DT id="42"><B>-V</B> <B>--version</B><DD>
|
|
Display Version number and exit
|
|
<DT id="43"><B>-k</B> <B>--keep</B><DD>
|
|
Preserve source files (default behavior)
|
|
<DT id="44"><B>--rm</B><DD>
|
|
Delete source files on successful compression or decompression
|
|
<DT id="45"><B>--</B><DD>
|
|
Treat all subsequent arguments as files
|
|
</DL>
|
|
<A NAME="lbAM"> </A>
|
|
<H3>Benchmark mode</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="46"><B>-b#</B><DD>
|
|
Benchmark file(s), using # compression level
|
|
<DT id="47"><B>-e#</B><DD>
|
|
Benchmark multiple compression levels, from b# to e# (included)
|
|
<DT id="48"><B>-i#</B><DD>
|
|
Minimum evaluation time in seconds [1-9] (default : 3)
|
|
</DL>
|
|
<A NAME="lbAN"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
Report bugs at: <A HREF="https://github.com/lz4/lz4/issues">https://github.com/lz4/lz4/issues</A>
|
|
<A NAME="lbAO"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
Yann Collet
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="49"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="50"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="51"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="52"><A HREF="#lbAE">Difference between lz4 and gzip</A><DD>
|
|
<DT id="53"><A HREF="#lbAF">Concatenation of .lz4 files</A><DD>
|
|
</DL>
|
|
<DT id="54"><A HREF="#lbAG">OPTIONS</A><DD>
|
|
<DL>
|
|
<DT id="55"><A HREF="#lbAH">Short commands concatenation</A><DD>
|
|
<DT id="56"><A HREF="#lbAI">Multiple commands</A><DD>
|
|
<DT id="57"><A HREF="#lbAJ">Operation mode</A><DD>
|
|
<DT id="58"><A HREF="#lbAK">Operation modifiers</A><DD>
|
|
<DT id="59"><A HREF="#lbAL">Other options</A><DD>
|
|
<DT id="60"><A HREF="#lbAM">Benchmark mode</A><DD>
|
|
</DL>
|
|
<DT id="61"><A HREF="#lbAN">BUGS</A><DD>
|
|
<DT id="62"><A HREF="#lbAO">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:29 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|