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-08-07" "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 determine the memory requirements of the decompressor. Typically the
192 decompressor needs only 5\ % to 20\ % of the amount of memory that the
193 compressor needed when creating the file. For example, decompressing a
196 currently requires 65 MiB of memory. Still, it is possible to have
198 files that need several gigabytes of memory to decompress.
200 Especially users of older systems may find the possibility of very large
201 memory usage annoying. To prevent uncomfortable surprises,
203 has a built-in memory usage limiter, which is disabled by default.
204 While some operating systems provide ways to limit the memory usage of
205 processes, relying on it wasn't deemed to be flexible enough (e.g. using
207 to limit virtual memory tends to cripple
210 The memory usage limiter can be enabled with the command line option
211 \fB\-\-memlimit=\fIlimit\fR, but often it is more convenient to enable
212 the limiter by default by setting the environment variable
215 .BR XZ_DEFAULTS=\-\-memlimit=150MiB .
216 It is possible to set the limits separately for compression and decompression
217 by using \fB\-\-memlimit\-compress=\fIlimit\fR and
218 \fB\-\-memlimit\-decompress=\fIlimit\fR, respectively.
219 Using these two options outside
221 is rarely useful, because a single run of
223 cannot do both compression and decompression and
224 .BI \-\-memlimit= limit
225 (or \fB\-M\fR \fIlimit\fR)
226 is shorter to type on the command line.
228 If the specified memory usage limit is exceeded when decompressing,
230 will display an error and decompressing the file will fail.
231 If the limit is exceeded when compressing,
233 will try to scale the settings down so that the limit is no longer exceeded
234 (except when using \fB\-\-format=raw\fR or \fB\-\-no\-adjust\fR).
235 This way the operation won't fail unless the limit is very small. The scaling
236 of the settings is done in steps that don't match the compression level
237 presets, e.g. if the limit is only slightly less than the amount required for
239 the settings will be scaled down only a little, not all the way down to
241 .SS Concatenation and padding with .xz files
242 It is possible to concatenate
246 will decompress such files as if they were a single
250 It is possible to insert padding between the concatenated parts
251 or after the last part. The padding must be null bytes and the size
252 of the padding must be a multiple of four bytes. This can be useful
253 if the .xz file is stored on a medium that stores file sizes
254 e.g. as 512-byte blocks.
256 Concatenation and padding are not allowed with
258 files or raw streams.
260 .SS "Integer suffixes and special values"
261 In most places where an integer argument is expected, an optional suffix
262 is supported to easily indicate large integers. There must be no space
263 between the integer and the suffix.
266 The integer is multiplied by 1,024 (2^10). Also
273 are accepted as synonyms for
277 The integer is multiplied by 1,048,576 (2^20). Also
283 are accepted as synonyms for
287 The integer is multiplied by 1,073,741,824 (2^30). Also
293 are accepted as synonyms for
298 can be used to indicate the maximum integer value supported by the option.
300 If multiple operation mode options are given, the last one takes effect.
302 .BR \-z ", " \-\-compress
303 Compress. This is the default operation mode when no operation mode option
304 is specified, and no other operation mode is implied from the command name
308 .BR \-\-decompress ).
310 .BR \-d ", " \-\-decompress ", " \-\-uncompress
313 .BR \-t ", " \-\-test
314 Test the integrity of compressed
316 No files are created or removed. This option is equivalent to
317 .B "\-\-decompress \-\-stdout"
318 except that the decompressed data is discarded instead of being
319 written to standard output.
321 .BR \-l ", " \-\-list
322 List information about compressed
324 No uncompressed output is produced, and no files are created or removed.
325 In list mode, the program cannot read the compressed data from standard
326 input or from other unseekable sources.
328 The default listing shows basic information about
330 one file per line. To get more detailed information, use also the
332 option. For even more information, use
334 twice, but note that it may be slow, because getting all the extra
335 information requires many seeks. The width of verbose output exceeds
336 80 characters, so piping the output to e.g.
338 may be convenient if the terminal isn't wide enough.
340 The exact output may vary between
342 versions and different locales. To get machine-readable output,
343 .B \-\-robot \-\-list
345 .SS "Operation modifiers"
347 .BR \-k ", " \-\-keep
348 Keep (don't delete) the input files.
350 .BR \-f ", " \-\-force
351 This option has several effects:
354 If the target file already exists, delete it before compressing or
357 Compress or decompress even if the input is a symbolic link to a regular file,
358 has more than one hard link, or has setuid, setgid, or sticky bit set.
359 The setuid, setgid, and sticky bits are not copied to the target file.
366 doesn't recognize the type of the source file,
368 will copy the source file as is to standard output. This allows using
373 for files that have not been compressed with
377 might support new compressed file formats, which may make
379 decompress more types of files instead of copying them as is to
381 .BI \-\-format= format
382 can be used to restrict
384 to decompress only a single file format.
387 .BR \-c ", " \-\-stdout ", " \-\-to\-stdout
388 Write the compressed or decompressed data to standard output instead of
393 Disable creation of sparse files. By default, if decompressing into
396 tries to make the file sparse if the decompressed data contains long
397 sequences of binary zeros. It works also when writing to standard output
398 as long as standard output is connected to a regular file, and certain
399 additional conditions are met to make it safe. Creating sparse files may
400 save disk space and speed up the decompression by reducing the amount of
403 \fB\-S\fR \fI.suf\fR, \fB\-\-suffix=\fI.suf
404 When compressing, use
406 as the suffix for the target file instead of
410 If not writing to standard output and the source file already has the suffix
412 a warning is displayed and the file is skipped.
414 When decompressing, recognize also files with the suffix
416 in addition to files with the
422 suffix. If the source file has the suffix
424 the suffix is removed to get the target filename.
426 When compressing or decompressing raw streams
427 .RB ( \-\-format=raw ),
428 the suffix must always be specified unless writing to standard output,
429 because there is no default suffix for raw streams.
431 \fB\-\-files\fR[\fB=\fIfile\fR]
432 Read the filenames to process from
436 is omitted, filenames are read from standard input. Filenames must be
437 terminated with the newline character. A dash
439 is taken as a regular filename; it doesn't mean standard input.
440 If filenames are given also as command line arguments, they are
441 processed before the filenames read from
444 \fB\-\-files0\fR[\fB=\fIfile\fR]
445 This is identical to \fB\-\-files\fR[\fB=\fIfile\fR] except that the
446 filenames must be terminated with the null character.
447 .SS "Basic file format and compression options"
449 \fB\-F\fR \fIformat\fR, \fB\-\-format=\fIformat
450 Specify the file format to compress or decompress:
454 This is the default. When compressing,
458 When decompressing, the format of the input file is automatically detected.
459 Note that raw streams (created with
461 cannot be auto-detected.
466 file format, or accept only
468 files when decompressing.
473 Compress to the legacy
475 file format, or accept only
477 files when decompressing. The alternative name
479 is provided for backwards compatibility with LZMA Utils.
482 Compress or uncompress a raw stream (no headers). This is meant for advanced
483 users only. To decode raw streams, you need to set not only
485 but also specify the filter chain, which would normally be stored in the
486 container format headers.
489 \fB\-C\fR \fIcheck\fR, \fB\-\-check=\fIcheck
490 Specify the type of the integrity check, which is calculated from the
491 uncompressed data. This option has an effect only when compressing into the
495 format doesn't support integrity checks.
496 The integrity check (if any) is verified when the
498 file is decompressed.
506 Don't calculate an integrity check at all. This is usually a bad idea. This
507 can be useful when integrity of the data is verified by other means anyway.
510 Calculate CRC32 using the polynomial from IEEE-802.3 (Ethernet).
513 Calculate CRC64 using the polynomial from ECMA-182. This is the default, since
514 it is slightly better than CRC32 at detecting damaged files and the speed
515 difference is negligible.
518 Calculate SHA-256. This is somewhat slower than CRC32 and CRC64.
523 headers is always verified with CRC32. It is not possible to change or
527 Select compression preset. If a preset level is specified multiple times,
528 the last one takes effect.
530 The compression preset levels can be categorised roughly into three
533 .IP "\fB\-0\fR ... \fB\-2"
534 Fast presets with relatively low memory usage.
538 should give compression speed and ratios comparable to
545 is not very good (not much faster than
547 but much worse compression). In future,
549 may be indicate some fast algorithm instead of LZMA2.
550 .IP "\fB\-3\fR ... \fB\-5"
551 Good compression ratio with low to medium memory usage.
552 These are significantly slower than levels 0\-2.
553 .IP "\fB\-6\fR ... \fB\-9"
554 Excellent compression with medium to high memory usage. These are also
555 slower than the lower preset levels. The default is
557 Unless you want to maximize the compression ratio, you probably don't want
558 a higher preset level than
560 due to speed and memory usage.
563 The exact compression settings (filter chain) used by each preset may
566 versions. Because the settings may vary, the memory usage may vary
567 slightly too. FIXME 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
594 .BR \-\-fast " and " \-\-best
595 These are somewhat misleading aliases for
600 These are provided only for backwards compatibility with LZMA Utils.
601 Avoid using these options.
603 Especially the name of
605 is misleading, because the definition of best depends on the input data,
606 and that usually people don't want the very best compression ratio anyway,
607 because it would be very slow.
609 .BR \-e ", " \-\-extreme
610 Modify the compression preset (\fB\-0\fR ... \fB\-9\fR) so that a little bit
611 better compression ratio can be achieved without increasing memory usage
612 of the compressor or decompressor (exception: compressor memory usage may
613 increase a little with presets \fB\-0\fR ... \fB\-2\fR). The downside is that
614 the compression time will increase dramatically (it can easily double).
616 .BI \-\-memlimit\-compress= limit
617 Set a memory usage limit for compression. If this option is specified
618 multiple times, the last one takes effect.
620 If the compression settings exceed the
623 will adjust the settings downwards so that the limit is no longer exceeded
624 and display a notice that automatic adjustment was done. Adjustment is never
625 done when compressing with
629 has been specified. In those cases, an error is displayed and
631 will exit with exit status
636 can be specified in multiple ways:
641 can be an absolute value in bytes. Using an integer suffix like
643 can be useful. Example:
644 .B "\-\-memlimit\-compress=80MiB"
648 can be specified as a percentage of total physical memory (RAM).
649 This can be useful especially when setting the
651 environment variable in a shell initialization script that is shared
652 between different computers. That way the limit is automatically bigger
653 on systems with more memory. Example:
654 .B "\-\-memlimit\-compress=70%"
658 can be reset back to its default value by setting it to
660 This is currently equivalent to setting the
664 i.e. no memory usage limit. Once multithreading support has been implemented,
665 there may be a difference between
669 for the multithreaded case, so it is recommended to use
673 at least until the details have been decided.
679 .BI \-\-memlimit\-decompress= limit
680 Set a memory usage limit for decompression. This affects also the
682 mode. If the operation is not possible without exceeding the
685 will display an error and decompressing the file will fail. See
686 .BI \-\-memlimit\-compress= limit
687 for possible ways to specify the
690 \fB\-M\fR \fIlimit\fR, \fB\-\-memlimit=\fIlimit\fR, \fB\-\-memory=\fIlimit
691 This is equivalent to specifying \fB\-\-memlimit\-compress=\fIlimit
692 \fB\-\-memlimit\-decompress=\fIlimit\fR.
695 Display an error and exit if the compression settings exceed the
696 the memory usage limit. The default is to adjust the settings downwards so
697 that the memory usage limit is not exceeded. Automatic adjusting is
698 always disabled when creating raw streams
699 .RB ( \-\-format=raw ).
701 \fB\-T\fR \fIthreads\fR, \fB\-\-threads=\fIthreads
702 Specify the number of worker threads to use. The actual number of threads
705 if using more threads would exceed the memory usage limit.
707 .B "Multithreaded compression and decompression are not implemented yet,"
708 .B "so this option has no effect for now."
710 .B "As of writing (2010-08-07), it hasn't been decided if threads will be"
711 .B "used by default on multicore systems once support for threading has"
712 .B "been implemented. Comments are welcome."
713 The complicating factor is that using many threads will increase the memory
714 usage dramatically. Note that if multithreading will be the default,
715 it will be done so that single-threaded and multithreaded modes produce
716 the same output, so compression ratio won't be significantly affected if
717 threading will be enabled by default.
718 .SS Custom compressor filter chains
719 A custom filter chain allows specifying the compression settings in detail
720 instead of relying on the settings associated to the preset levels.
721 When a custom filter chain is specified, the compression preset level options
722 (\fB\-0\fR ... \fB\-9\fR and \fB\-\-extreme\fR) are silently ignored.
724 A filter chain is comparable to piping on the UN*X command line.
725 When compressing, the uncompressed input goes to the first filter, whose
726 output goes to the next filter (if any). The output of the last filter
727 gets written to the compressed file. The maximum number of filters in
728 the chain is four, but typically a filter chain has only one or two filters.
730 Many filters have limitations where they can be in the filter chain:
731 some filters can work only as the last filter in the chain, some only
732 as a non-last filter, and some work in any position in the chain. Depending
733 on the filter, this limitation is either inherent to the filter design or
734 exists to prevent security issues.
736 A custom filter chain is specified by using one or more filter options in
737 the order they are wanted in the filter chain. That is, the order of filter
738 options is significant! When decoding raw streams
739 .RB ( \-\-format=raw ),
740 the filter chain is specified in the same order as it was specified when
743 Filters take filter-specific
745 as a comma-separated list. Extra commas in
747 are ignored. Every option has a default value, so you need to
748 specify only those you want to change.
750 \fB\-\-lzma1\fR[\fB=\fIoptions\fR], \fB\-\-lzma2\fR[\fB=\fIoptions\fR]
751 Add LZMA1 or LZMA2 filter to the filter chain. These filter can be used
752 only as the last filter in the chain.
754 LZMA1 is a legacy filter, which is supported almost solely due to the legacy
756 file format, which supports only LZMA1. LZMA2 is an updated
757 version of LZMA1 to fix some practical issues of LZMA1. The
759 format uses LZMA2, and doesn't support LZMA1 at all. Compression speed and
760 ratios of LZMA1 and LZMA2 are practically the same.
762 LZMA1 and LZMA2 share the same set of
767 Reset all LZMA1 or LZMA2
772 consist of an integer, which may be followed by single-letter preset
773 modifiers. The integer can be from
777 matching the command line options \fB\-0\fR ... \fB\-9\fR.
778 The only supported modifier is currently
787 from which the default values for the rest of the LZMA1 or LZMA2
792 Dictionary (history buffer) size indicates how many bytes of the recently
793 processed uncompressed data is kept in memory. One method to reduce size of
794 the uncompressed data is to store distance-length pairs, which
795 indicate what data to repeat from the dictionary buffer. The bigger
796 the dictionary, the better the compression ratio usually is,
797 but dictionaries bigger than the uncompressed data are waste of RAM.
799 Typical dictionary size is from 64 KiB to 64 MiB. The minimum is 4 KiB.
800 The maximum for compression is currently 1.5 GiB. The decompressor already
801 supports dictionaries up to one byte less than 4 GiB, which is the
802 maximum for LZMA1 and LZMA2 stream formats.
804 Dictionary size has the biggest effect on compression ratio.
805 Dictionary size and match finder together determine the memory usage of
806 the LZMA1 or LZMA2 encoder. The same dictionary size is required
807 for decompressing that was used when compressing, thus the memory usage of
808 the decoder is determined by the dictionary size used when compressing.
811 Specify the number of literal context bits. The minimum is
817 In addition, the sum of
825 Specify the number of literal position bits. The minimum is
833 Specify the number of position bits. The minimum is
843 specifies the function used to analyze the data produced by the match finder.
862 Match finder has a major effect on encoder speed, memory usage, and
863 compression ratio. Usually Hash Chain match finders are faster than
864 Binary Tree match finders. Hash Chains are usually used together with
866 and Binary Trees with
868 The memory usage formulas are only rough estimates,
869 which are closest to reality when
875 Hash Chain with 2- and 3-byte hashing
893 Hash Chain with 2-, 3-, and 4-byte hashing
904 Binary Tree with 2-byte hashing
915 Binary Tree with 2- and 3-byte hashing
933 Binary Tree with 2-, 3-, and 4-byte hashing
945 Specify what is considered to be a nice length for a match. Once a match
948 bytes is found, the algorithm stops looking for possibly better matches.
951 can be 2\-273 bytes. Higher values tend to give better compression ratio
952 at expense of speed. The default depends on the
957 Specify the maximum search depth in the match finder. The default is the
960 which makes the compressor determine a reasonable
967 Using very high values for
969 can make the encoder extremely slow with carefully crafted files.
972 over 1000 unless you are prepared to interrupt the compression in case it
976 When decoding raw streams
977 .RB ( \-\-format=raw ),
978 LZMA2 needs only the value of
986 \fB\-\-x86\fR[\fB=\fIoptions\fR]
988 \fB\-\-powerpc\fR[\fB=\fIoptions\fR]
990 \fB\-\-ia64\fR[\fB=\fIoptions\fR]
992 \fB\-\-arm\fR[\fB=\fIoptions\fR]
994 \fB\-\-armthumb\fR[\fB=\fIoptions\fR]
996 \fB\-\-sparc\fR[\fB=\fIoptions\fR]
997 Add a branch/call/jump (BCJ) filter to the filter chain. These filters
998 can be used only as non-last filter in the filter chain.
1000 A BCJ filter converts relative addresses in the machine code to their
1001 absolute counterparts. This doesn't change the size of the data, but
1002 it increases redundancy, which allows e.g. LZMA2 to get better
1005 The BCJ filters are always reversible, so using a BCJ filter for wrong
1006 type of data doesn't cause any data loss. However, applying a BCJ filter
1007 for wrong type of data is a bad idea, because it tends to make the
1008 compression ratio worse.
1010 Different instruction sets have have different alignment:
1017 Filter;Alignment;Notes
1018 x86;1;32-bit and 64-bit x86
1019 PowerPC;4;Big endian only
1020 ARM;4;Little endian only
1021 ARM-Thumb;2;Little endian only
1022 IA-64;16;Big or little endian
1023 SPARC;4;Big or little endian
1028 Since the BCJ-filtered data is usually compressed with LZMA2, the compression
1029 ratio may be improved slightly if the LZMA2 options are set to match the
1030 alignment of the selected BCJ filter. For example, with the IA-64 filter,
1033 with LZMA2 (2^4=16). The x86 filter is an exception; it's usually good to
1034 stick to LZMA2's default four-byte alignment when compressing x86 executables.
1036 All BCJ filters support the same
1043 that is used when converting between relative and absolute addresses.
1046 must be a multiple of the alignment of the filter (see the table above).
1047 The default is zero. In practice, the default is good; specifying
1050 is almost never useful.
1052 Specifying a non-zero start
1054 is probably useful only if the executable has multiple sections, and there
1055 are many cross-section jumps or calls. Applying a BCJ filter separately for
1056 each section with proper start offset and then compressing the result as
1057 a single chunk may give some improvement in compression ratio compared
1058 to applying the BCJ filter with the default
1060 for the whole executable.
1063 \fB\-\-delta\fR[\fB=\fIoptions\fR]
1064 Add Delta filter to the filter chain. The Delta filter
1065 can be used only as non-last filter in the filter chain.
1067 Currently only simple byte-wise delta calculation is supported. It can
1068 be useful when compressing e.g. uncompressed bitmap images or uncompressed
1069 PCM audio. However, special purpose algorithms may give significantly better
1070 results than Delta + LZMA2. This is true especially with audio, which
1071 compresses faster and better e.g. with
1081 of the delta calculation as bytes.
1083 must be 1\-256. The default is 1.
1087 and eight-byte input A1 B1 A2 B3 A3 B5 A4 B7, the output will be
1088 A1 B1 01 02 01 02 01 02.
1092 .BR \-q ", " \-\-quiet
1093 Suppress warnings and notices. Specify this twice to suppress errors too.
1094 This option has no effect on the exit status. That is, even if a warning
1095 was suppressed, the exit status to indicate a warning is still used.
1097 .BR \-v ", " \-\-verbose
1098 Be verbose. If standard error is connected to a terminal,
1100 will display a progress indicator.
1103 twice will give even more verbose output (useful mostly for debugging).
1105 The progress indicator shows the following information:
1108 Completion percentage is shown if the size of the input file is known.
1109 That is, percentage cannot be shown in pipes.
1111 Amount of compressed data produced (compressing) or consumed (decompressing).
1113 Amount of uncompressed data consumed (compressing) or produced
1116 Compression ratio, which is calculated by dividing the amount of
1117 compressed data processed so far by the amount of uncompressed data
1120 Compression or decompression speed. This is measured as the amount of
1121 uncompressed data consumed (compression) or produced (decompression)
1122 per second. It is shown after a few seconds have passed since
1124 started processing the file.
1126 Elapsed time in the format M:SS or H:MM:SS.
1128 Estimated remaining time is shown only when the size of the input file is
1129 known and a couple of seconds have already passed since
1131 started processing the file. The time is shown in a less precise format which
1132 never has any colons, e.g. 2 min 30 s.
1135 When standard error is not a terminal,
1139 print the filename, compressed size, uncompressed size, compression ratio,
1140 and possibly also the speed and elapsed time on a single line to standard
1141 error after compressing or decompressing the file. The speed and elapsed
1142 time are included only when the operation took at least a few seconds.
1143 If the operation didn't finish, for example due to user interruption, also
1144 the completion percentage is printed if the size of the input file is known.
1146 .BR \-Q ", " \-\-no\-warn
1147 Don't set the exit status to
1149 even if a condition worth a warning was detected. This option doesn't affect
1150 the verbosity level, thus both
1154 have to be used to not display warnings and to not alter the exit status.
1157 Print messages in a machine-parsable format. This is intended to ease
1158 writing frontends that want to use
1160 instead of liblzma, which may be the case with various scripts. The output
1161 with this option enabled is meant to be stable across
1163 releases. See the section
1167 .BR \-\-info\-memory
1168 Display, in human-readable format, how much physical memory (RAM)
1170 thinks the system has and the memory usage limits for compression
1171 and decompression, and exit successfully.
1173 .BR \-h ", " \-\-help
1174 Display a help message describing the most commonly used options,
1175 and exit successfully.
1177 .BR \-H ", " \-\-long\-help
1178 Display a help message describing all features of
1180 and exit successfully
1182 .BR \-V ", " \-\-version
1183 Display the version number of
1185 and liblzma in human readable format. To get machine-parsable output, specify
1190 The robot mode is activated with the
1192 option. It makes the output of
1194 easier to parse by other programs. Currently
1196 is supported only together with
1198 .BR \-\-info\-memory ,
1201 It will be supported for normal compression and decompression in the future.
1204 .B "xz \-\-robot \-\-version"
1205 will print the version number of
1207 and liblzma in the following format:
1209 .BI XZ_VERSION= XYYYZZZS
1211 .BI LIBLZMA_VERSION= XYYYZZZS
1217 Minor version. Even numbers are stable.
1218 Odd numbers are alpha or beta versions.
1221 Patch level for stable releases or just a counter for development releases.
1239 are the same on both lines if
1241 and liblzma are from the same XZ Utils release.
1243 Examples: 4.999.9beta is
1248 .SS Memory limit information
1249 .B "xz \-\-robot \-\-info\-memory"
1250 prints a single line with three tab-separated columns:
1253 Total amount of physical memory (RAM) as bytes
1255 Memory usage limit for compression as bytes.
1256 A special value of zero indicates the default setting,
1257 which for single-threaded mode is the same as no limit.
1259 Memory usage limit for decompression as bytes.
1260 A special value of zero indicates the default setting,
1261 which for single-threaded mode is the same as no limit.
1264 In the future, the output of
1265 .B "xz \-\-robot \-\-info\-memory"
1266 may have more columns, but never more than a single line.
1268 .B "xz \-\-robot \-\-list"
1269 uses tab-separated output. The first column of every line has a string
1270 that indicates the type of the information found on that line:
1273 This is always the first line when starting to list a file. The second
1274 column on the line is the filename.
1277 This line contains overall information about the
1279 file. This line is always printed after the
1284 This line type is used only when
1286 was specified. There are as many
1288 lines as there are streams in the
1293 This line type is used only when
1295 was specified. There are as many
1297 lines as there are blocks in the
1301 lines are shown after all the
1303 lines; different line types are not interleaved.
1306 This line type is used only when
1308 was specified twice. This line is printed after all
1314 line contains overall information about the
1319 This line is always the very last line of the list output. It shows
1320 the total counts and sizes.
1327 Number of streams in the file
1329 Total number of blocks in the stream(s)
1331 Compressed size of the file
1333 Uncompressed size of the file
1335 Compression ratio, for example
1337 If ratio is over 9.999, three dashes
1339 are displayed instead of the ratio.
1341 Comma-separated list of integrity check names. The following strings are
1342 used for the known check types:
1348 For unknown check types,
1352 is the Check ID as a decimal number (one or two digits).
1354 Total size of stream padding in the file
1362 Stream number (the first stream is 1)
1364 Number of blocks in the stream
1366 Compressed start offset
1368 Uncompressed start offset
1370 Compressed size (does not include stream padding)
1376 Name of the integrity check
1378 Size of stream padding
1386 Number of the stream containing this block
1388 Block number relative to the beginning of the stream (the first block is 1)
1390 Block number relative to the beginning of the file
1392 Compressed start offset relative to the beginning of the file
1394 Uncompressed start offset relative to the beginning of the file
1396 Total compressed size of the block (includes headers)
1402 Name of the integrity check
1407 was specified twice, additional columns are included on the
1409 lines. These are not displayed with a single
1411 because getting this information requires many seeks and can thus be slow:
1414 Value of the integrity check in hexadecimal
1420 indicates that compressed size is present, and
1422 indicates that uncompressed size is present.
1423 If the flag is not set, a dash
1425 is shown instead to keep the string length fixed. New flags may be added
1426 to the end of the string in the future.
1428 Size of the actual compressed data in the block (this excludes
1429 the block header, block padding, and check fields)
1431 Amount of memory (as bytes) required to decompress this block with this
1435 Filter chain. Note that most of the options used at compression time cannot
1436 be known, because only the options that are needed for decompression are
1455 Average compression ratio
1457 Comma-separated list of integrity check names that were present in the files
1461 Number of files. This is here to keep the order of the earlier columns
1469 was specified twice, additional columns are included on the
1474 Maximum amount of memory (as bytes) required to decompress the files
1482 indicating if all block headers have both compressed size and
1483 uncompressed size stored in them
1486 Future versions may add new line types and new columns can be added to
1487 the existing line types, but the existing columns won't be changed.
1497 Something worth a warning occurred, but no actual errors occurred.
1499 Notices (not warnings or errors) printed on standard error don't affect
1503 parses space-separated lists of options from the environment variables
1507 in this order, before parsing the options from the command line. Note that
1508 only options are parsed from the environment variables; all non-options
1509 are silently ignored. Parsing is done with
1511 which is used also for the command line arguments.
1514 User-specific or system-wide default options.
1515 Typically this is set in a shell initialization script to enable
1517 memory usage limiter by default. Excluding shell initialization scripts
1518 and similar special cases, scripts must never set or unset
1522 This is for passing options to
1524 when it is not possible to set the options directly on the
1526 command line. This is the case e.g. when
1528 is run by a script or tool, e.g. GNU
1532 \fBXZ_OPT=\-2v tar caf foo.tar.xz foo
1537 e.g. to set script-specific default compression options.
1538 It is still recommended to allow users to override
1540 if that is reasonable, e.g. in
1542 scripts one may use something like this:
1545 \fBXZ_OPT=${XZ_OPT\-"\-7e"}; export XZ_OPT
1548 .SH "LZMA UTILS COMPATIBILITY"
1549 The command line syntax of
1551 is practically a superset of
1556 as found from LZMA Utils 4.32.x. In most cases, it is possible to replace
1557 LZMA Utils with XZ Utils without breaking existing scripts. There are some
1558 incompatibilities though, which may sometimes cause problems.
1559 .SS "Compression preset levels"
1560 The numbering of the compression level presets is not identical in
1563 The most important difference is how dictionary sizes are mapped to different
1564 presets. Dictionary size is roughly equal to the decompressor memory usage.
1583 The dictionary size differences affect the compressor memory usage too,
1584 but there are some other differences between LZMA Utils and XZ Utils, which
1585 make the difference even bigger:
1591 Level;xz;LZMA Utils 4.32.x
1604 The default preset level in LZMA Utils is
1606 while in XZ Utils it is
1608 so both use 8 MiB dictionary by default.
1609 .SS "Streamed vs. non-streamed .lzma files"
1610 Uncompressed size of the file can be stored in the
1612 header. LZMA Utils does that when compressing regular files.
1613 The alternative is to mark that uncompressed size is unknown and
1614 use end of payload marker to indicate where the decompressor should stop.
1615 LZMA Utils uses this method when uncompressed size isn't known, which is
1616 the case for example in pipes.
1619 supports decompressing
1621 files with or without end of payload marker, but all
1625 will use end of payload marker and have uncompressed size marked as unknown
1628 header. This may be a problem in some (uncommon) situations. For example, a
1630 decompressor in an embedded device might work only with files that have known
1631 uncompressed size. If you hit this problem, you need to use LZMA Utils or
1634 files with known uncompressed size.
1635 .SS "Unsupported .lzma files"
1642 values up to 4. LZMA Utils can decompress files with any
1646 but always creates files with
1650 Creating files with other
1658 The implementation of the LZMA1 filter in liblzma requires
1663 must not exceed 4. Thus,
1665 files which exceed this limitation, cannot be decompressed with
1668 LZMA Utils creates only
1670 files which have dictionary size of
1672 (a power of 2), but accepts files with any dictionary size.
1673 liblzma accepts only
1675 files which have dictionary size of
1678 .RI "2^" n " + 2^(" n "\-1)."
1679 This is to decrease false positives when detecting
1683 These limitations shouldn't be a problem in practice, since practically all
1685 files have been compressed with settings that liblzma will accept.
1686 .SS "Trailing garbage"
1687 When decompressing, LZMA Utils silently ignore everything after the first
1689 stream. In most situations, this is a bug. This also means that LZMA Utils
1690 don't support decompressing concatenated
1694 If there is data left after the first
1698 considers the file to be corrupt. This may break obscure scripts which have
1699 assumed that trailing garbage is ignored.
1701 .SS Compressed output may vary
1702 The exact compressed output produced from the same uncompressed input file
1703 may vary between XZ Utils versions even if compression options are identical.
1704 This is because the encoder can be improved (faster or better compression)
1705 without affecting the file format. The output can vary even between different
1706 builds of the same XZ Utils version, if different build options are used.
1708 The above means that implementing
1712 files is not going to happen without freezing a part of the encoder
1713 implementation, which can then be used with
1715 .SS Embedded .xz decompressors
1718 decompressor implementations like XZ Embedded don't necessarily support files
1725 Since the default is \fB\-\-check=\fIcrc64\fR, you must use
1729 when creating files for embedded systems.
1731 Outside embedded systems, all
1733 format decompressors support all the
1735 types, or at least are able to decompress the file without verifying the
1736 integrity check if the particular
1740 XZ Embedded supports BCJ filters, but only with the default start offset.
1743 A mix of compressed and uncompressed files can be decompressed
1744 to standard output with a single command:
1746 .B "xz \-dcf a.txt b.txt.xz c.txt d.txt.xz > abcd.txt"
1747 .SS Parallel compression of many files
1752 can be used to parallelize compression of many files:
1755 .B "find . \-type f \e! \-name '*.xz' \-print0 |"
1756 .B "xargs \-0r \-P4 \-n16 xz \-T1"
1760 option sets the number of parallel
1762 processes. The best value for the
1764 option depends on how many files there are to be compressed.
1765 If there are only a couple of files, the value should probably be
1767 with tens of thousands of files,
1769 or even more may be appropriate to reduce the number of
1773 will eventually create.
1779 is there to force it to single-threaded mode, because
1781 is used to control the amount of parallelization.
1782 .SS Robot mode examples
1783 Calculating how many bytes have been saved in total after compressing
1786 .B "xz \-\-robot \-\-list *.xz | awk '/^totals/{print $5\-$4}'"
1792 XZ Utils: <http://tukaani.org/xz/>
1794 XZ Embedded: <http://tukaani.org/xz/embedded.html>
1796 LZMA SDK: <http://7-zip.org/sdk.html>
projects / icculus / xz.git / blob