.\" This file has been put into the public domain.
.\" You can do whatever you want with this file.
.\"
-.TH XZ 1 "2020-03-23" "Tukaani" "XZ Utils"
+.TH XZ 1 "2020-11-01" "Tukaani" "XZ Utils"
.
.SH NAME
xz, unxz, xzcat, lzma, unlzma, lzcat \- Compress or decompress .xz and .lzma files
has a built-in memory usage limiter, which is disabled by default.
While some operating systems provide ways to limit
the memory usage of processes, relying on it
-wasn't deemed to be flexible enough (e.g. using
+wasn't deemed to be flexible enough (for example, using
.BR ulimit (1)
to limit virtual memory tends to cripple
.BR mmap (2)).
Often it is more convenient to enable the limiter
by default by setting the environment variable
.BR XZ_DEFAULTS ,
-e.g.\&
+for example,
.BR XZ_DEFAULTS=\-\-memlimit=150MiB .
It is possible to set the limits separately
for compression and decompression
or \fB\-\-no\-adjust\fR).
This way the operation won't fail unless the limit is very small.
The scaling of the settings is done in steps that don't
-match the compression level presets, e.g. if the limit is
+match the compression level presets, for example, if the limit is
only slightly less than the amount required for
.BR "xz \-9" ,
the settings will be scaled down only a little,
or after the last part.
The padding must consist of null bytes and the size
of the padding must be a multiple of four bytes.
-This can be useful e.g. if the
+This can be useful, for example, if the
.B .xz
file is stored on a medium that measures file sizes
in 512-byte blocks.
twice, but note that this may be slow, because getting all the extra
information requires many seeks.
The width of verbose output exceeds
-80 characters, so piping the output to e.g.\&
+80 characters, so piping the output to, for example,
.B "less\ \-S"
may be convenient if the terminal isn't wide enough.
.IP ""
decompressor memory usage reasonable even for old systems.
.B \-6
is the default, which is usually a good choice
-e.g. for distributing files that need to be decompressible
+for distributing files that need to be decompressible
even on systems with only 16\ MiB RAM.
.RB ( \-5e
or
.I lc
bits of the previous uncompressed byte correlate
with the next byte.
-E.g. in typical English text, an upper-case letter is
+For example, in typical English text, an upper-case letter is
often followed by a lower-case letter, and a lower-case
letter is usually followed by another lower-case letter.
In the US-ASCII character set, the highest three bits are 010
.BR lc=4 .
Sometimes it helps a little, and
sometimes it makes compression worse.
-If it makes it worse, test e.g.\&
+If it makes it worse, test
.B lc=2
too.
.TP
When the alignment is known, setting
.I pb
accordingly may reduce the file size a little.
-E.g. with text files having one-byte
+For example, with text files having one-byte
alignment (US-ASCII, ISO-8859-*, UTF-8), setting
.B pb=0
can improve compression slightly.
.RS
.IP \(bu 3
Some types of files containing executable code
-(e.g. object files, static libraries, and Linux kernel modules)
+(for example, object files, static libraries, and Linux kernel modules)
have the addresses in the instructions filled with filler values.
These BCJ filters will still do the address conversion,
which will make the compression worse with these files.
in the filter chain.
.IP ""
Currently only simple byte-wise delta calculation is supported.
-It can be useful when compressing e.g. uncompressed bitmap images
+It can be useful when compressing, for example, uncompressed bitmap images
or uncompressed PCM audio.
However, special purpose algorithms may give significantly better
results than Delta + LZMA2.
This is true especially with audio,
-which compresses faster and better e.g. with
+which compresses faster and better, for example, with
.BR flac (1).
.IP ""
Supported
.B xz
started processing the file.
The time is shown in a less precise format which
-never has any colons, e.g. 2 min 30 s.
+never has any colons, for example, 2 min 30 s.
.RE
.IP ""
When standard error is not a terminal,
decompressing the file.
The speed and elapsed time are included only when
the operation took at least a few seconds.
-If the operation didn't finish, e.g. due to user interruption,
+If the operation didn't finish, for example, due to user interruption,
also the completion percentage is printed
if the size of the input file is known.
.TP
.IP 5. 4
Uncompressed size of the file
.IP 6. 4
-Compression ratio, for example
+Compression ratio, for example,
.BR 0.123 .
If ratio is over 9.999, three dashes
.RB ( \-\-\- )
when it is not possible to set the options directly on the
.B xz
command line.
-This is the case e.g. when
+This is the case when
.B xz
-is run by a script or tool, e.g. GNU
+is run by a script or tool, for example, GNU
.BR tar (1):
.RS
.RS
.RE
.IP ""
Scripts may use
-.B XZ_OPT
-e.g. to set script-specific default compression options.
+.BR XZ_OPT ,
+for example, to set script-specific default compression options.
It is still recommended to allow users to override
.B XZ_OPT
-if that is reasonable, e.g. in
+if that is reasonable.
+For example, in
.BR sh (1)
scripts one may use something like this:
.RS
and use end-of-payload marker to indicate
where the decompressor should stop.
LZMA Utils uses this method when uncompressed size isn't known,
-which is the case for example in pipes.
+which is the case, for example, in pipes.
.PP
.B xz
supports decompressing
with the preset
.B \-4e
.RB ( "\-4 \-\-extreme" ),
-which is slower than e.g. the default
+which is slower than the default
.BR \-6 ,
but needs less memory for compression and decompression (48\ MiB
and 5\ MiB, respectively):
.RE
.PP
If you know that a file requires
-somewhat big dictionary (e.g. 32 MiB) to compress well,
+somewhat big dictionary (for example, 32\ MiB) to compress well,
but you want to compress it quicker than
.B "xz \-8"
-would do, a preset with a low CompCPU value (e.g. 1)
+would do, a preset with a low CompCPU value (for example, 1)
can be modified to use a bigger dictionary:
.RS
.PP
so the above command isn't useful for small files.
.PP
Sometimes the compression time doesn't matter,
-but the decompressor memory usage has to be kept low
-e.g. to make it possible to decompress the file on
-an embedded system.
+but the decompressor memory usage has to be kept low, for example,
+to make it possible to decompress the file on an embedded system.
The following command uses
.B \-6e
.RB ( "\-6 \-\-extreme" )
and
.I pb
are more important.
-E.g. a source code archive contains mostly US-ASCII text,
+For example, a source code archive contains mostly US-ASCII text,
so something like the following might give
slightly (like 0.1\ %) smaller file than
.B "xz \-6e"
.PP
Using another filter together with LZMA2 can improve
compression with certain file types.
-E.g. to compress a x86-32 or x86-64 shared library
+For example, to compress a x86-32 or x86-64 shared library
using the x86 BCJ filter:
.RS
.PP
delta but uses Deflate for the actual compression.
.PP
The image has to be saved in uncompressed format,
-e.g. as uncompressed TIFF.
+for example, as uncompressed TIFF.
The distance parameter of the Delta filter is set
to match the number of bytes per pixel in the image.
-E.g. 24-bit RGB bitmap needs
+For example, 24-bit RGB bitmap needs
.BR dist=3 ,
and it is also good to pass
.B pb=0
.fi
.RE
.PP
-If multiple images have been put into a single archive (e.g.\&
+If multiple images have been put into a single archive (for example,
.BR .tar ),
the Delta filter will work on that too as long as all images
have the same number of bytes per pixel.
projects / thirdparty / xz.git / commitdiff
