3 .\" Author: Lasse Collin
5 .\" This file has been put into the public domain.
6 .\" You can do whatever you want with this file.
8 .TH XZ 1 "2010-07-28" "Tukaani" "XZ Utils"
10 xz, unxz, xzcat, lzma, unlzma, lzcat \- Compress or decompress .xz and .lzma files
18 .BR "xz \-\-decompress" .
22 .BR "xz \-\-decompress \-\-stdout" .
26 .BR "xz \-\-format=lzma" .
30 .BR "xz \-\-format=lzma \-\-decompress" .
34 .BR "xz \-\-format=lzma \-\-decompress \-\-stdout" .
36 When writing scripts that need to decompress files, it is recommended to
39 with appropriate arguments
49 is a general-purpose data compression tool with command line syntax similar to
53 The native file format is the
55 format, but also the legacy
57 format and raw compressed streams with no container format headers
61 compresses or decompresses each
63 according to the selected operation mode.
71 reads from standard input and writes the processed data to standard output.
73 will refuse (display an error and skip the
75 to write compressed data to standard output if it is a terminal. Similarly,
77 will refuse to read compressed data from standard input if it is a terminal.
85 are written to a new file whose name is derived from the source
89 When compressing, the suffix of the target file format
93 is appended to the source filename to get the target filename.
95 When decompressing, the
99 suffix is removed from the filename to get the target filename.
101 also recognizes the suffixes
105 and replaces them with the
109 If the target file already exists, an error is displayed and the
113 Unless writing to standard output,
115 will display a warning and skip the
117 if any of the following applies:
120 is not a regular file. Symbolic links are not followed, thus they
121 are not considered to be regular files.
124 has more than one hard link.
127 has setuid, setgid, or sticky bit set.
129 The operation mode is set to compress, and the
131 already has a suffix of the target file format
135 when compressing to the
141 when compressing to the
145 The operation mode is set to decompress, and the
147 doesn't have a suffix of any of the supported file formats
154 After successfully compressing or decompressing the
157 copies the owner, group, permissions, access time, and modification time
160 to the target file. If copying the group fails, the permissions are modified
161 so that the target file doesn't become accessible to users who didn't have
162 permission to access the source
165 doesn't support copying other metadata like access control lists
166 or extended attributes yet.
168 Once the target file has been successfully closed, the source
172 was specified. The source
174 is never removed if the output is written to standard output.
182 process makes it print progress information to standard error.
183 This has only limited use since when standard error is a terminal, using
185 will display an automatically updating progress indicator.
189 varies from a few hundred kilobytes to several gigabytes depending on
190 the compression settings. The settings used when compressing a file
191 affect also the memory usage of the decompressor. Typically the decompressor
192 needs only 5\ % to 20\ % of the amount of RAM that the compressor needed when
193 creating the file. Still, the worst-case memory usage of the decompressor
194 is several gigabytes.
196 To prevent uncomfortable surprises caused by huge memory usage,
198 has a built-in memory usage limiter. While some operating systems provide
199 ways to limit the memory usage of processes, relying on it wasn't deemed
200 to be flexible enough. The default limit depends on the total amount of
203 If 40\ % of RAM is at least 80 MiB, 40\ % of RAM is used as the limit.
205 If 80\ % of RAM is less than 80 MiB, 80\ % of RAM is used as the limit.
207 Otherwise 80 MiB is used as the limit.
209 When compressing, if the selected compression settings exceed the memory
210 usage limit, the settings are automatically adjusted downwards and a notice
211 about this is displayed. As an exception, if the memory usage limit is
212 exceeded when compressing with
216 an error is displayed and
218 will exit with exit status
223 cannot be decompressed without exceeding the memory usage limit, an error
224 message is displayed and the file is skipped. Note that compressed files
225 may contain many blocks, which may have been compressed with different
226 settings. Typically all blocks will have roughly the same memory requirements,
227 but it is possible that a block later in the file will exceed the memory usage
228 limit, and an error about too low memory usage limit gets displayed after some
229 data has already been decompressed.
231 The absolute value of the active memory usage limit can be seen with
233 or near the bottom of the output of
235 The default limit can be overridden with
236 \fB\-\-memory=\fIlimit\fR.
237 .SS Concatenation and padding with .xz files
238 It is possible to concatenate
242 will decompress such files as if they were a single
246 It is possible to insert padding between the concatenated parts
247 or after the last part. The padding must be null bytes and the size
248 of the padding must be a multiple of four bytes. This can be useful
249 if the .xz file is stored on a medium that stores file sizes
250 e.g. as 512-byte blocks.
252 Concatenation and padding are not allowed with
254 files or raw streams.
256 .SS "Integer suffixes and special values"
257 In most places where an integer argument is expected, an optional suffix
258 is supported to easily indicate large integers. There must be no space
259 between the integer and the suffix.
262 The integer is multiplied by 1,024 (2^10). Also
269 are accepted as synonyms for
273 The integer is multiplied by 1,048,576 (2^20). Also
279 are accepted as synonyms for
283 The integer is multiplied by 1,073,741,824 (2^30). Also
289 are accepted as synonyms for
294 can be used to indicate the maximum integer value supported by the option.
296 If multiple operation mode options are given, the last one takes effect.
298 .BR \-z ", " \-\-compress
299 Compress. This is the default operation mode when no operation mode option
300 is specified, and no other operation mode is implied from the command name
304 .BR \-\-decompress ).
306 .BR \-d ", " \-\-decompress ", " \-\-uncompress
309 .BR \-t ", " \-\-test
310 Test the integrity of compressed
312 No files are created or removed. This option is equivalent to
313 .B "\-\-decompress \-\-stdout"
314 except that the decompressed data is discarded instead of being
315 written to standard output.
317 .BR \-l ", " \-\-list
318 List information about compressed
320 No uncompressed output is produced, and no files are created or removed.
321 In list mode, the program cannot read the compressed data from standard
322 input or from other unseekable sources.
324 The default listing shows basic information about
326 one file per line. To get more detailed information, use also the
328 option. For even more information, use
330 twice, but note that it may be slow, because getting all the extra
331 information requires many seeks. The width of verbose output exceeds
332 80 characters, so piping the output to e.g.
334 may be convenient if the terminal isn't wide enough.
336 The exact output may vary between
338 versions and different locales. To get machine-readable output,
339 .B \-\-robot \-\-list
341 .SS "Operation modifiers"
343 .BR \-k ", " \-\-keep
344 Keep (don't delete) the input files.
346 .BR \-f ", " \-\-force
347 This option has several effects:
350 If the target file already exists, delete it before compressing or
353 Compress or decompress even if the input is a symbolic link to a regular file,
354 has more than one hard link, or has setuid, setgid, or sticky bit set.
355 The setuid, setgid, and sticky bits are not copied to the target file.
362 doesn't recognize the type of the source file,
364 will copy the source file as is to standard output. This allows using
369 for files that have not been compressed with
373 might support new compressed file formats, which may make
375 decompress more types of files instead of copying them as is to
377 .BI \-\-format= format
378 can be used to restrict
380 to decompress only a single file format.
383 .BR \-c ", " \-\-stdout ", " \-\-to-stdout
384 Write the compressed or decompressed data to standard output instead of
389 Disable creation of sparse files. By default, if decompressing into
392 tries to make the file sparse if the decompressed data contains long
393 sequences of binary zeros. It works also when writing to standard output
394 as long as standard output is connected to a regular file, and certain
395 additional conditions are met to make it safe. Creating sparse files may
396 save disk space and speed up the decompression by reducing the amount of
399 \fB\-S\fR \fI.suf\fR, \fB\-\-suffix=\fI.suf
400 When compressing, use
402 as the suffix for the target file instead of
406 If not writing to standard output and the source file already has the suffix
408 a warning is displayed and the file is skipped.
410 When decompressing, recognize also files with the suffix
412 in addition to files with the
418 suffix. If the source file has the suffix
420 the suffix is removed to get the target filename.
422 When compressing or decompressing raw streams
423 .RB ( \-\-format=raw ),
424 the suffix must always be specified unless writing to standard output,
425 because there is no default suffix for raw streams.
427 \fB\-\-files\fR[\fB=\fIfile\fR]
428 Read the filenames to process from
432 is omitted, filenames are read from standard input. Filenames must be
433 terminated with the newline character. A dash
435 is taken as a regular filename; it doesn't mean standard input.
436 If filenames are given also as command line arguments, they are
437 processed before the filenames read from
440 \fB\-\-files0\fR[\fB=\fIfile\fR]
441 This is identical to \fB\-\-files\fR[\fB=\fIfile\fR] except that the
442 filenames must be terminated with the null character.
443 .SS "Basic file format and compression options"
445 \fB\-F\fR \fIformat\fR, \fB\-\-format=\fIformat
446 Specify the file format to compress or decompress:
450 This is the default. When compressing,
454 When decompressing, the format of the input file is automatically detected.
455 Note that raw streams (created with
457 cannot be auto-detected.
462 file format, or accept only
464 files when decompressing.
469 Compress to the legacy
471 file format, or accept only
473 files when decompressing. The alternative name
475 is provided for backwards compatibility with LZMA Utils.
478 Compress or uncompress a raw stream (no headers). This is meant for advanced
479 users only. To decode raw streams, you need to set not only
481 but also specify the filter chain, which would normally be stored in the
482 container format headers.
485 \fB\-C\fR \fIcheck\fR, \fB\-\-check=\fIcheck
486 Specify the type of the integrity check, which is calculated from the
487 uncompressed data. This option has an effect only when compressing into the
491 format doesn't support integrity checks.
492 The integrity check (if any) is verified when the
494 file is decompressed.
502 Don't calculate an integrity check at all. This is usually a bad idea. This
503 can be useful when integrity of the data is verified by other means anyway.
506 Calculate CRC32 using the polynomial from IEEE-802.3 (Ethernet).
509 Calculate CRC64 using the polynomial from ECMA-182. This is the default, since
510 it is slightly better than CRC32 at detecting damaged files and the speed
511 difference is negligible.
514 Calculate SHA-256. This is somewhat slower than CRC32 and CRC64.
519 headers is always verified with CRC32. It is not possible to change or
523 Select compression preset. If a preset level is specified multiple times,
524 the last one takes effect.
526 The compression preset levels can be categorised roughly into three
529 .IP "\fB\-0\fR ... \fB\-2"
530 Fast presets with relatively low memory usage.
534 should give compression speed and ratios comparable to
541 is not very good (not much faster than
543 but much worse compression). In future,
545 may be indicate some fast algorithm instead of LZMA2.
546 .IP "\fB\-3\fR ... \fB\-5"
547 Good compression ratio with low to medium memory usage.
548 These are significantly slower than levels 0\-2.
549 .IP "\fB\-6\fR ... \fB\-9"
550 Excellent compression with medium to high memory usage. These are also
551 slower than the lower preset levels. The default is
553 Unless you want to maximize the compression ratio, you probably don't want
554 a higher preset level than
556 due to speed and memory usage.
559 The exact compression settings (filter chain) used by each preset may
562 versions. The settings may also vary between files being compressed, if
564 determines that modified settings will probably give better compression
565 ratio without significantly affecting compression time or memory usage.
567 Because the settings may vary, the memory usage may vary too. The following
568 table lists the maximum memory usage of each preset level, which won't be
569 exceeded even in future versions of
572 .B "FIXME: The table below is just a rough idea."
579 Preset;Compression;Decompression
596 automatically adjusts the compression settings downwards if
597 the memory usage limit would be exceeded, so it is safe to specify
598 a high preset level even on systems that don't have lots of RAM.
600 .BR \-\-fast " and " \-\-best
601 These are somewhat misleading aliases for
606 These are provided only for backwards compatibility with LZMA Utils.
607 Avoid using these options.
609 Especially the name of
611 is misleading, because the definition of best depends on the input data,
612 and that usually people don't want the very best compression ratio anyway,
613 because it would be very slow.
615 .BR \-e ", " \-\-extreme
616 Modify the compression preset (\fB\-0\fR ... \fB\-9\fR) so that a little bit
617 better compression ratio can be achieved without increasing memory usage
618 of the compressor or decompressor (exception: compressor memory usage may
619 increase a little with presets \fB\-0\fR ... \fB\-2\fR). The downside is that
620 the compression time will increase dramatically (it can easily double).
623 Display an error and exit if the compression settings exceed the
624 the memory usage limit. The default is to adjust the settings downwards so
625 that the memory usage limit is not exceeded. Automatic adjusting is
626 always disabled when creating raw streams
627 .RB ( \-\-format=raw ).
629 \fB\-M\fR \fIlimit\fR, \fB\-\-memory=\fIlimit
630 Set the memory usage limit. If this option is specified multiple times,
631 the last one takes effect. The
633 can be specified in multiple ways:
638 can be an absolute value in bytes. Using an integer suffix like
640 can be useful. Example:
641 .B "\-\-memory=80MiB"
645 can be specified as a percentage of physical RAM. Example:
650 can be reset back to its default value by setting it to
654 for how the default limit is defined.
656 The memory usage limiting can be effectively disabled by setting
660 This isn't recommended. It's usually better to use, for example,
666 can be seen near the bottom of the output of the
670 \fB\-T\fR \fIthreads\fR, \fB\-\-threads=\fIthreads
671 Specify the maximum number of worker threads to use. The default is
672 the number of available CPU cores. You can see the current value of
674 near the end of the output of the
678 The actual number of worker threads can be less than
680 if using more threads would exceed the memory usage limit.
681 In addition to CPU-intensive worker threads,
683 may use a few auxiliary threads, which don't use a lot of CPU time.
685 .B "Multithreaded compression and decompression are not implemented yet,"
686 .B "so this option has no effect for now."
687 .SS Custom compressor filter chains
688 A custom filter chain allows specifying the compression settings in detail
689 instead of relying on the settings associated to the preset levels.
690 When a custom filter chain is specified, the compression preset level options
691 (\fB\-0\fR ... \fB\-9\fR and \fB\-\-extreme\fR) are silently ignored.
693 A filter chain is comparable to piping on the UN*X command line.
694 When compressing, the uncompressed input goes to the first filter, whose
695 output goes to the next filter (if any). The output of the last filter
696 gets written to the compressed file. The maximum number of filters in
697 the chain is four, but typically a filter chain has only one or two filters.
699 Many filters have limitations where they can be in the filter chain:
700 some filters can work only as the last filter in the chain, some only
701 as a non-last filter, and some work in any position in the chain. Depending
702 on the filter, this limitation is either inherent to the filter design or
703 exists to prevent security issues.
705 A custom filter chain is specified by using one or more filter options in
706 the order they are wanted in the filter chain. That is, the order of filter
707 options is significant! When decoding raw streams
708 .RB ( \-\-format=raw ),
709 the filter chain is specified in the same order as it was specified when
712 Filters take filter-specific
714 as a comma-separated list. Extra commas in
716 are ignored. Every option has a default value, so you need to
717 specify only those you want to change.
719 \fB\-\-lzma1\fR[\fB=\fIoptions\fR], \fB\-\-lzma2\fR[\fB=\fIoptions\fR]
720 Add LZMA1 or LZMA2 filter to the filter chain. These filter can be used
721 only as the last filter in the chain.
723 LZMA1 is a legacy filter, which is supported almost solely due to the legacy
725 file format, which supports only LZMA1. LZMA2 is an updated
726 version of LZMA1 to fix some practical issues of LZMA1. The
728 format uses LZMA2, and doesn't support LZMA1 at all. Compression speed and
729 ratios of LZMA1 and LZMA2 are practically the same.
731 LZMA1 and LZMA2 share the same set of
736 Reset all LZMA1 or LZMA2
741 consist of an integer, which may be followed by single-letter preset
742 modifiers. The integer can be from
746 matching the command line options \fB\-0\fR ... \fB\-9\fR.
747 The only supported modifier is currently
756 from which the default values for the rest of the LZMA1 or LZMA2
761 Dictionary (history buffer) size indicates how many bytes of the recently
762 processed uncompressed data is kept in memory. One method to reduce size of
763 the uncompressed data is to store distance-length pairs, which
764 indicate what data to repeat from the dictionary buffer. The bigger
765 the dictionary, the better the compression ratio usually is,
766 but dictionaries bigger than the uncompressed data are waste of RAM.
768 Typical dictionary size is from 64 KiB to 64 MiB. The minimum is 4 KiB.
769 The maximum for compression is currently 1.5 GiB. The decompressor already
770 supports dictionaries up to one byte less than 4 GiB, which is the
771 maximum for LZMA1 and LZMA2 stream formats.
773 Dictionary size has the biggest effect on compression ratio.
774 Dictionary size and match finder together determine the memory usage of
775 the LZMA1 or LZMA2 encoder. The same dictionary size is required
776 for decompressing that was used when compressing, thus the memory usage of
777 the decoder is determined by the dictionary size used when compressing.
780 Specify the number of literal context bits. The minimum is
786 In addition, the sum of
794 Specify the number of literal position bits. The minimum is
802 Specify the number of position bits. The minimum is
812 specifies the function used to analyze the data produced by the match finder.
831 Match finder has a major effect on encoder speed, memory usage, and
832 compression ratio. Usually Hash Chain match finders are faster than
833 Binary Tree match finders. Hash Chains are usually used together with
835 and Binary Trees with
837 The memory usage formulas are only rough estimates,
838 which are closest to reality when
844 Hash Chain with 2- and 3-byte hashing
862 Hash Chain with 2-, 3-, and 4-byte hashing
873 Binary Tree with 2-byte hashing
884 Binary Tree with 2- and 3-byte hashing
902 Binary Tree with 2-, 3-, and 4-byte hashing
914 Specify what is considered to be a nice length for a match. Once a match
917 bytes is found, the algorithm stops looking for possibly better matches.
920 can be 2\-273 bytes. Higher values tend to give better compression ratio
921 at expense of speed. The default depends on the
926 Specify the maximum search depth in the match finder. The default is the
929 which makes the compressor determine a reasonable
936 Using very high values for
938 can make the encoder extremely slow with carefully crafted files.
941 over 1000 unless you are prepared to interrupt the compression in case it
945 When decoding raw streams
946 .RB ( \-\-format=raw ),
947 LZMA2 needs only the value of
955 \fB\-\-x86\fR[\fB=\fIoptions\fR]
957 \fB\-\-powerpc\fR[\fB=\fIoptions\fR]
959 \fB\-\-ia64\fR[\fB=\fIoptions\fR]
961 \fB\-\-arm\fR[\fB=\fIoptions\fR]
963 \fB\-\-armthumb\fR[\fB=\fIoptions\fR]
965 \fB\-\-sparc\fR[\fB=\fIoptions\fR]
966 Add a branch/call/jump (BCJ) filter to the filter chain. These filters
967 can be used only as non-last filter in the filter chain.
969 A BCJ filter converts relative addresses in the machine code to their
970 absolute counterparts. This doesn't change the size of the data, but
971 it increases redundancy, which allows e.g. LZMA2 to get better
974 The BCJ filters are always reversible, so using a BCJ filter for wrong
975 type of data doesn't cause any data loss. However, applying a BCJ filter
976 for wrong type of data is a bad idea, because it tends to make the
977 compression ratio worse.
979 Different instruction sets have have different alignment:
986 Filter;Alignment;Notes
987 x86;1;32-bit and 64-bit x86
988 PowerPC;4;Big endian only
989 ARM;4;Little endian only
990 ARM-Thumb;2;Little endian only
991 IA-64;16;Big or little endian
992 SPARC;4;Big or little endian
997 Since the BCJ-filtered data is usually compressed with LZMA2, the compression
998 ratio may be improved slightly if the LZMA2 options are set to match the
999 alignment of the selected BCJ filter. For example, with the IA-64 filter,
1002 with LZMA2 (2^4=16). The x86 filter is an exception; it's usually good to
1003 stick to LZMA2's default four-byte alignment when compressing x86 executables.
1005 All BCJ filters support the same
1012 that is used when converting between relative and absolute addresses.
1015 must be a multiple of the alignment of the filter (see the table above).
1016 The default is zero. In practice, the default is good; specifying
1019 is almost never useful.
1021 Specifying a non-zero start
1023 is probably useful only if the executable has multiple sections, and there
1024 are many cross-section jumps or calls. Applying a BCJ filter separately for
1025 each section with proper start offset and then compressing the result as
1026 a single chunk may give some improvement in compression ratio compared
1027 to applying the BCJ filter with the default
1029 for the whole executable.
1032 \fB\-\-delta\fR[\fB=\fIoptions\fR]
1033 Add Delta filter to the filter chain. The Delta filter
1034 can be used only as non-last filter in the filter chain.
1036 Currently only simple byte-wise delta calculation is supported. It can
1037 be useful when compressing e.g. uncompressed bitmap images or uncompressed
1038 PCM audio. However, special purpose algorithms may give significantly better
1039 results than Delta + LZMA2. This is true especially with audio, which
1040 compresses faster and better e.g. with FLAC.
1049 of the delta calculation as bytes.
1051 must be 1\-256. The default is 1.
1055 and eight-byte input A1 B1 A2 B3 A3 B5 A4 B7, the output will be
1056 A1 B1 01 02 01 02 01 02.
1060 .BR \-q ", " \-\-quiet
1061 Suppress warnings and notices. Specify this twice to suppress errors too.
1062 This option has no effect on the exit status. That is, even if a warning
1063 was suppressed, the exit status to indicate a warning is still used.
1065 .BR \-v ", " \-\-verbose
1066 Be verbose. If standard error is connected to a terminal,
1068 will display a progress indicator.
1071 twice will give even more verbose output (useful mostly for debugging).
1073 The progress indicator shows the following information:
1076 Completion percentage is shown if the size of the input file is known.
1077 That is, percentage cannot be shown in pipes.
1079 Amount of compressed data produced (compressing) or consumed (decompressing).
1081 Amount of uncompressed data consumed (compressing) or produced
1084 Compression ratio, which is calculated by dividing the amount of
1085 compressed data processed so far by the amount of uncompressed data
1088 Compression or decompression speed. This is measured as the amount of
1089 uncompressed data consumed (compression) or produced (decompression)
1090 per second. It is shown once a few seconds have passed since
1092 started processing the file.
1094 Elapsed time or estimated time remaining.
1095 Elapsed time is displayed in the format M:SS or H:MM:SS.
1096 The estimated remaining time is displayed in a less precise format
1097 which never has colons, for example, 2 min 30 s. The estimate can
1098 be shown only when the size of the input file is known and a couple of
1099 seconds have already passed since
1101 started processing the file.
1104 When standard error is not a terminal,
1108 print the filename, compressed size, uncompressed size, compression ratio,
1109 speed, and elapsed time on a single line to standard error after
1110 compressing or decompressing the file. If operating took at least a few
1111 seconds, also the speed and elapsed time are printed. If the operation
1112 didn't finish, for example due to user interruption, also the completion
1113 percentage is printed if the size of the input file is known.
1115 .BR \-Q ", " \-\-no\-warn
1116 Don't set the exit status to
1118 even if a condition worth a warning was detected. This option doesn't affect
1119 the verbosity level, thus both
1123 have to be used to not display warnings and to not alter the exit status.
1126 Print messages in a machine-parsable format. This is intended to ease
1127 writing frontends that want to use
1129 instead of liblzma, which may be the case with various scripts. The output
1130 with this option enabled is meant to be stable across
1132 releases. See the section
1137 Display the current memory usage limit in human-readable format on
1138 a single line, and exit successfully. To see how much RAM
1140 thinks your system has, use
1141 .BR "\-\-memory=100% \-\-info\-memory" .
1143 .BR \-h ", " \-\-help
1144 Display a help message describing the most commonly used options,
1145 and exit successfully.
1147 .BR \-H ", " \-\-long\-help
1148 Display a help message describing all features of
1150 and exit successfully
1152 .BR \-V ", " \-\-version
1153 Display the version number of
1155 and liblzma in human readable format. To get machine-parsable output, specify
1160 The robot mode is activated with the
1162 option. It makes the output of
1164 easier to parse by other programs. Currently
1166 is supported only together with
1168 .BR \-\-info-memory ,
1171 It will be supported for normal compression and decompression in the future.
1174 .B "xz \-\-robot \-\-version"
1175 will print the version number of
1177 and liblzma in the following format:
1179 .BI XZ_VERSION= XYYYZZZS
1181 .BI LIBLZMA_VERSION= XYYYZZZS
1187 Minor version. Even numbers are stable.
1188 Odd numbers are alpha or beta versions.
1191 Patch level for stable releases or just a counter for development releases.
1209 are the same on both lines if
1211 and liblzma are from the same XZ Utils release.
1213 Examples: 4.999.9beta is
1218 .SS Memory limit information
1219 .B "xz \-\-robot \-\-info-memory"
1220 prints the current memory usage limit as bytes on a single line.
1221 To get the total amount of installed RAM, use
1222 .BR "xz \-\-robot \-\-memory=100% \-\-info-memory" .
1224 .B "xz \-\-robot \-\-list"
1225 uses tab-separated output. The first column of every line has a string
1226 that indicates the type of the information found on that line:
1229 This is always the first line when starting to list a file. The second
1230 column on the line is the filename.
1233 This line contains overall information about the
1235 file. This line is always printed after the
1240 This line type is used only when
1242 was specified. There are as many
1244 lines as there are streams in the
1249 This line type is used only when
1251 was specified. There are as many
1253 lines as there are blocks in the
1257 lines are shown after all the
1259 lines; different line types are not interleaved.
1262 This line type is used only when
1264 was specified twice. This line is printed after all
1270 line contains overall information about the
1275 This line is always the very last line of the list output. It shows
1276 the total counts and sizes.
1283 Number of streams in the file
1285 Total number of blocks in the stream(s)
1287 Compressed size of the file
1289 Uncompressed size of the file
1291 Compression ratio, for example
1293 If ratio is over 9.999, three dashes
1295 are displayed instead of the ratio.
1297 Comma-separated list of integrity check names. The following strings are
1298 used for the known check types:
1304 For unknown check types,
1308 is the Check ID as a decimal number (one or two digits).
1310 Total size of stream padding in the file
1318 Stream number (the first stream is 1)
1320 Number of blocks in the stream
1322 Compressed start offset
1324 Uncompressed start offset
1326 Compressed size (does not include stream padding)
1332 Name of the integrity check
1334 Size of stream padding
1342 Number of the stream containing this block
1344 Block number relative to the beginning of the stream (the first block is 1)
1346 Block number relative to the beginning of the file
1348 Compressed start offset relative to the beginning of the file
1350 Uncompressed start offset relative to the beginning of the file
1352 Total compressed size of the block (includes headers)
1358 Name of the integrity check
1363 was specified twice, additional columns are included on the
1365 lines. These are not displayed with a single
1367 because getting this information requires many seeks and can thus be slow:
1370 Value of the integrity check in hexadecimal
1376 indicates that compressed size is present, and
1378 indicates that uncompressed size is present.
1379 If the flag is not set, a dash
1381 is shown instead to keep the string length fixed. New flags may be added
1382 to the end of the string in the future.
1384 Size of the actual compressed data in the block (this excludes
1385 the block header, block padding, and check fields)
1387 Amount of memory (as bytes) required to decompress this block with this
1391 Filter chain. Note that most of the options used at compression time cannot
1392 be known, because only the options that are needed for decompression are
1411 Average compression ratio
1413 Comma-separated list of integrity check names that were present in the files
1417 Number of files. This is here to keep the order of the earlier columns
1425 was specified twice, additional columns are included on the
1430 Maximum amount of memory (as bytes) required to decompress the files
1438 indicating if all block headers have both compressed size and
1439 uncompressed size stored in them
1442 Future versions may add new line types and new columns can be added to
1443 the existing line types, but the existing columns won't be changed.
1453 Something worth a warning occurred, but no actual errors occurred.
1455 Notices (not warnings or errors) printed on standard error don't affect
1460 A space-separated list of options is parsed from
1462 before parsing the options given on the command line. Note that only
1463 options are parsed from
1465 all non-options are silently ignored. Parsing is done with
1467 which is used also for the command line arguments.
1468 .SH "LZMA UTILS COMPATIBILITY"
1469 The command line syntax of
1471 is practically a superset of
1476 as found from LZMA Utils 4.32.x. In most cases, it is possible to replace
1477 LZMA Utils with XZ Utils without breaking existing scripts. There are some
1478 incompatibilities though, which may sometimes cause problems.
1479 .SS "Compression preset levels"
1480 The numbering of the compression level presets is not identical in
1483 The most important difference is how dictionary sizes are mapped to different
1484 presets. Dictionary size is roughly equal to the decompressor memory usage.
1503 The dictionary size differences affect the compressor memory usage too,
1504 but there are some other differences between LZMA Utils and XZ Utils, which
1505 make the difference even bigger:
1511 Level;xz;LZMA Utils 4.32.x
1524 The default preset level in LZMA Utils is
1526 while in XZ Utils it is
1528 so both use 8 MiB dictionary by default.
1529 .SS "Streamed vs. non-streamed .lzma files"
1530 Uncompressed size of the file can be stored in the
1532 header. LZMA Utils does that when compressing regular files.
1533 The alternative is to mark that uncompressed size is unknown and
1534 use end of payload marker to indicate where the decompressor should stop.
1535 LZMA Utils uses this method when uncompressed size isn't known, which is
1536 the case for example in pipes.
1539 supports decompressing
1541 files with or without end of payload marker, but all
1545 will use end of payload marker and have uncompressed size marked as unknown
1548 header. This may be a problem in some (uncommon) situations. For example, a
1550 decompressor in an embedded device might work only with files that have known
1551 uncompressed size. If you hit this problem, you need to use LZMA Utils or
1554 files with known uncompressed size.
1555 .SS "Unsupported .lzma files"
1562 values up to 4. LZMA Utils can decompress files with any
1566 but always creates files with
1570 Creating files with other
1578 The implementation of the LZMA1 filter in liblzma requires
1583 must not exceed 4. Thus,
1585 files which exceed this limitation, cannot be decompressed with
1588 LZMA Utils creates only
1590 files which have dictionary size of
1592 (a power of 2), but accepts files with any dictionary size.
1593 liblzma accepts only
1595 files which have dictionary size of
1598 .RI "2^" n " + 2^(" n "\-1)."
1599 This is to decrease false positives when detecting
1603 These limitations shouldn't be a problem in practice, since practically all
1605 files have been compressed with settings that liblzma will accept.
1606 .SS "Trailing garbage"
1607 When decompressing, LZMA Utils silently ignore everything after the first
1609 stream. In most situations, this is a bug. This also means that LZMA Utils
1610 don't support decompressing concatenated
1614 If there is data left after the first
1618 considers the file to be corrupt. This may break obscure scripts which have
1619 assumed that trailing garbage is ignored.
1621 .SS Compressed output may vary
1622 The exact compressed output produced from the same uncompressed input file
1623 may vary between XZ Utils versions even if compression options are identical.
1624 This is because the encoder can be improved (faster or better compression)
1625 without affecting the file format. The output can vary even between different
1626 builds of the same XZ Utils version, if different build options are used.
1628 The above means that implementing
1632 files is not going to happen without freezing a part of the encoder
1633 implementation, which can then be used with
1635 .SS Embedded .xz decompressors
1638 decompressor implementations like XZ Embedded don't necessarily support files
1645 Since the default is \fB\-\-check=\fIcrc64\fR, you must use
1649 when creating files for embedded systems.
1651 Outside embedded systems, all
1653 format decompressors support all the
1655 types, or at least are able to decompress the file without verifying the
1656 integrity check if the particular
1660 XZ Embedded supports BCJ filters, but only with the default start offset.
1663 A mix of compressed and uncompressed files can be decompressed
1664 to standard output with a single command:
1666 .B "xz -dcf a.txt b.txt.xz c.txt d.txt.xz > abcd.txt"
1667 .SS Parallel compression of many files
1672 can be used to parallelize compression of many files:
1675 .B "find . \-type f \e! \-name '*.xz' \-print0 | xargs \-0r \-P4 \-n16 xz"
1679 option sets the number of parallel
1681 processes. The best value for the
1683 option depends on how many files there are to be compressed.
1684 If there are only a couple of files, the value should probably be
1686 with tens of thousands of files,
1688 or even more may be appropriate to reduce the number of
1692 will eventually create.
1693 .SS Robot mode examples
1694 Calculating how many bytes have been saved in total after compressing
1697 .B "xz --robot --list *.xz | awk '/^totals/{print $5\-$4}'"
1703 XZ Utils: <http://tukaani.org/xz/>
1705 XZ Embedded: <http://tukaani.org/xz/embedded.html>
1707 LZMA SDK: <http://7-zip.org/sdk.html>