summaryrefslogtreecommitdiffstats
path: root/programs/lz4.1.md
diff options
context:
space:
mode:
Diffstat (limited to 'programs/lz4.1.md')
-rw-r--r--programs/lz4.1.md219
1 files changed, 219 insertions, 0 deletions
diff --git a/programs/lz4.1.md b/programs/lz4.1.md
new file mode 100644
index 0000000..48f3152
--- /dev/null
+++ b/programs/lz4.1.md
@@ -0,0 +1,219 @@
+lz4(1) -- lz4, unlz4, lz4cat - Compress or decompress .lz4 files
+================================================================
+
+SYNOPSIS
+--------
+
+`lz4` [*OPTIONS*] [-|INPUT-FILE] <OUTPUT-FILE>
+
+`unlz4` is equivalent to `lz4 -d`
+
+`lz4cat` is equivalent to `lz4 -dcfm`
+
+When writing scripts that need to decompress files,
+it is recommended to always use the name `lz4` with appropriate arguments
+(`lz4 -d` or `lz4 -dc`) instead of the names `unlz4` and `lz4cat`.
+
+
+DESCRIPTION
+-----------
+
+`lz4` is an extremely fast lossless compression algorithm,
+based on **byte-aligned LZ77** family of compression scheme.
+`lz4` 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 `.lz4` format.
+
+### Difference between lz4 and gzip
+
+`lz4` supports a command line syntax similar _but not identical_ to `gzip(1)`.
+Differences are :
+
+ * `lz4` preserves original files
+ * `lz4` compresses a single file by default (see `-m` for multiple files)
+ * `lz4 file1 file2` means : compress file1 _into_ file2
+ * `lz4 file.lz4` will default to decompression (use `-z` to force compression)
+ * `lz4` shows real-time notification statistics
+ during compression or decompression of a single file
+ (use `-q` to silent them)
+ * If no destination name is provided, result is sent to `stdout`
+ _except if stdout is the console_.
+ * If no destination name is provided, __and__ if `stdout` is the console,
+ `file` is compressed into `file.lz4`.
+ * As a consequence of previous rules, note the following example :
+ `lz4 file | consumer` sends compressed data to `consumer` through `stdout`,
+ hence it does _not_ create `file.lz4`.
+
+Default behaviors can be modified by opt-in commands, detailed below.
+
+ * `lz4 -m` makes it possible to provide multiple input filenames,
+ which will be compressed into files using suffix `.lz4`.
+ Progress notifications are also disabled by default (use `-v` to enable them).
+ This mode has a behavior which more closely mimics `gzip` command line,
+ with the main remaining difference being that source files are preserved by default.
+ * Similarly, `lz4 -m -d` can decompress multiple `*.lz4` files.
+ * It's possible to opt-in to erase source files
+ on successful compression or decompression, using `--rm` command.
+ * Consequently, `lz4 -m --rm` behaves the same as `gzip`.
+
+### Concatenation of .lz4 files
+
+It is possible to concatenate `.lz4` files as is.
+`lz4` will decompress such files as if they were a single `.lz4` file.
+For example:
+ lz4 file1 > foo.lz4
+ lz4 file2 >> foo.lz4
+
+then
+ lz4cat foo.lz4
+
+is equivalent to :
+ cat file1 file2
+
+
+OPTIONS
+-------
+
+### Short commands concatenation
+
+In some cases, some options can be expressed using short command `-x`
+or long command `--long-word`.
+Short commands can be concatenated together.
+For example, `-d -c` is equivalent to `-dc`.
+Long commands cannot be concatenated.
+They must be clearly separated by a space.
+
+### Multiple commands
+
+When multiple contradictory commands are issued on a same command line,
+only the latest one will be applied.
+
+### Operation mode
+
+* `-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, `unlz4` implies `--decompress`),
+ nor from the input file name
+ (for example, a file extension `.lz4` implies `--decompress` by default).
+ `-z` can also be used to force compression of an already compressed
+ `.lz4` file.
+
+* `-d` `--decompress` `--uncompress`:
+ Decompress.
+ `--decompress` is also the default operation when the input filename has an
+ `.lz4` extension.
+
+* `-t` `--test`:
+ Test the integrity of compressed `.lz4` files.
+ The decompressed data is discarded.
+ No files are created nor removed.
+
+* `-b#`:
+ Benchmark mode, using `#` compression level.
+
+### Operation modifiers
+
+* `-#`:
+ 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.
+
+* `-f` `--[no-]force`:
+ This option has several effects:
+
+ If the target file already exists, overwrite it without prompting.
+
+ When used with `--decompress` and `lz4` cannot recognize the type of
+ the source file, copy the source file as is to standard output.
+ This allows `lz4cat --force` to be used like `cat (1)` for files
+ that have not been compressed with `lz4`.
+
+* `-c` `--stdout` `--to-stdout`:
+ Force write to standard output, even if it is the console.
+
+* `-m` `--multiple`:
+ Multiple input files.
+ Compressed file names will be appended a `.lz4` suffix.
+ This mode also reduces notification level.
+ `lz4 -m` has a behavior equivalent to `gzip -k`
+ (it preserves source files by default).
+
+* `-r` :
+ operate recursively on directories.
+ This mode also sets `-m` (multiple input files).
+
+* `-B#`:
+ Block size \[4-7\](default : 7)<br/>
+ `-B4`= 64KB ; `-B5`= 256KB ; `-B6`= 1MB ; `-B7`= 4MB
+
+* `-BD`:
+ Block Dependency (improves compression ratio on small blocks)
+
+* `--[no-]frame-crc`:
+ Select frame checksum (default:enabled)
+
+* `--[no-]content-size`:
+ 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.
+
+* `--[no-]sparse`:
+ Sparse mode support (default:enabled on file, disabled on stdout)
+
+* `-l`:
+ Use Legacy format (typically for Linux Kernel compression)<br/>
+ Note : `-l` is not compatible with `-m` (`--multiple`) nor `-r`
+
+### Other options
+
+* `-v` `--verbose`:
+ Verbose mode
+
+* `-q` `--quiet`:
+ Suppress warnings and real-time statistics;
+ specify twice to suppress errors too
+
+* `-h` `-H` `--help`:
+ Display help/long help and exit
+
+* `-V` `--version`:
+ Display Version number and exit
+
+* `-k` `--keep`:
+ Preserve source files (default behavior)
+
+* `--rm` :
+ Delete source files on successful compression or decompression
+
+
+### Benchmark mode
+
+* `-b#`:
+ Benchmark file(s), using # compression level
+
+* `-e#`:
+ Benchmark multiple compression levels, from b# to e# (included)
+
+* `-i#`:
+ Minimum evaluation in seconds \[1-9\] (default : 3)
+
+
+BUGS
+----
+
+Report bugs at: https://github.com/lz4/lz4/issues
+
+
+AUTHOR
+------
+
+Yann Collet