contrib/xz/src/xz/xz.1

   1 '\" t
   2 .\"
   3 .\" Author: Lasse Collin
   4 .\"
   5 .\" This file has been put into the public domain.
   6 .\" You can do whatever you want with this file.
   7 .\"
   8 .TH XZ 1 "2010-03-07" "Tukaani" "XZ Utils"
   9 .SH NAME
  10 xz, unxz, xzcat, lzma, unlzma, lzcat \- Compress or decompress .xz and .lzma files
  11 .SH SYNOPSIS
  12 .B xz
  13 .RI [ option ]...
  14 .RI [ file ]...
  15 .PP
  16 .B unxz
  17 is equivalent to
  18 .BR "xz \-\-decompress" .
  19 .br
  20 .B xzcat
  21 is equivalent to
  22 .BR "xz \-\-decompress \-\-stdout" .
  23 .br
  24 .B lzma
  25 is equivalent to
  26 .BR "xz \-\-format=lzma" .
  27 .br
  28 .B unlzma
  29 is equivalent to
  30 .BR "xz \-\-format=lzma \-\-decompress" .
  31 .br
  32 .B lzcat
  33 is equivalent to
  34 .BR "xz \-\-format=lzma \-\-decompress \-\-stdout" .
  35 .PP
  36 When writing scripts that need to decompress files, it is recommended to
  37 always use the name
  38 .B xz
  39 with appropriate arguments
  40 .RB ( "xz \-d"
  41 or
  42 .BR "xz \-dc" )
  43 instead of the names
  44 .B unxz
  45 and
  46 .BR xzcat.
  47 .SH DESCRIPTION
  48 .B xz
  49 is a general-purpose data compression tool with command line syntax similar to
  50 .BR gzip (1)
  51 and
  52 .BR bzip2 (1).
  53 The native file format is the
  54 .B .xz
  55 format, but also the legacy
  56 .B .lzma
  57 format and raw compressed streams with no container format headers
  58 are supported.
  59 .PP
  60 .B xz
  61 compresses or decompresses each
  62 .I file
  63 according to the selected operation mode.
  64 If no
  65 .I files
  66 are given or
  67 .I file
  68 is
  69 .BR \- ,
  70 .B xz
  71 reads from standard input and writes the processed data to standard output.
  72 .B xz
  73 will refuse (display an error and skip the
  74 .IR file )
  75 to write compressed data to standard output if it is a terminal. Similarly,
  76 .B xz
  77 will refuse to read compressed data from standard input if it is a terminal.
  78 .PP
  79 Unless
  80 .B \-\-stdout
  81 is specified,
  82 .I files
  83 other than
  84 .B \-
  85 are written to a new file whose name is derived from the source
  86 .I file
  87 name:
  88 .IP \(bu 3
  89 When compressing, the suffix of the target file format
  90 .RB ( .xz
  91 or
  92 .BR .lzma )
  93 is appended to the source filename to get the target filename.
  94 .IP \(bu 3
  95 When decompressing, the
  96 .B .xz
  97 or
  98 .B .lzma
  99 suffix is removed from the filename to get the target filename.
 100 .B xz
 101 also recognizes the suffixes
 102 .B .txz
 103 and
 104 .BR .tlz ,
 105 and replaces them with the
 106 .B .tar
 107 suffix.
 108 .PP
 109 If the target file already exists, an error is displayed and the
 110 .I file
 111 is skipped.
 112 .PP
 113 Unless writing to standard output,
 114 .B xz
 115 will display a warning and skip the
 116 .I file
 117 if any of the following applies:
 118 .IP \(bu 3
 119 .I File
 120 is not a regular file. Symbolic links are not followed, thus they
 121 are not considered to be regular files.
 122 .IP \(bu 3
 123 .I File
 124 has more than one hard link.
 125 .IP \(bu 3
 126 .I File
 127 has setuid, setgid, or sticky bit set.
 128 .IP \(bu 3
 129 The operation mode is set to compress, and the
 130 .I file
 131 already has a suffix of the target file format
 132 .RB ( .xz
 133 or
 134 .B .txz
 135 when compressing to the
 136 .B .xz
 137 format, and
 138 .B .lzma
 139 or
 140 .B .tlz
 141 when compressing to the
 142 .B .lzma
 143 format).
 144 .IP \(bu 3
 145 The operation mode is set to decompress, and the
 146 .I file
 147 doesn't have a suffix of any of the supported file formats
 148 .RB ( .xz ,
 149 .BR .txz ,
 150 .BR .lzma ,
 151 or
 152 .BR .tlz ).
 153 .PP
 154 After successfully compressing or decompressing the
 155 .IR file ,
 156 .B xz
 157 copies the owner, group, permissions, access time, and modification time
 158 from the source
 159 .I file
 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
 163 .IR file .
 164 .B xz
 165 doesn't support copying other metadata like access control lists
 166 or extended attributes yet.
 167 .PP
 168 Once the target file has been successfully closed, the source
 169 .I file
 170 is removed unless
 171 .B \-\-keep
 172 was specified. The source
 173 .I file
 174 is never removed if the output is written to standard output.
 175 .PP
 176 Sending
 177 .B SIGINFO
 178 or
 179 .B SIGUSR1
 180 to the
 181 .B xz
 182 process makes it print progress information to standard error.
 183 This has only limited use since when standard error is a terminal, using
 184 .B \-\-verbose
 185 will display an automatically updating progress indicator.
 186 .SS "Memory usage"
 187 The memory usage of
 188 .B xz
 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.
 195 .PP
 196 To prevent uncomfortable surprises caused by huge memory usage,
 197 .B xz
 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
 201 physical RAM:
 202 .IP \(bu 3
 203 If 40\ % of RAM is at least 80 MiB, 40\ % of RAM is used as the limit.
 204 .IP \(bu 3
 205 If 80\ % of RAM is over 80 MiB, 80 MiB is used as the limit.
 206 .IP \(bu 3
 207 Otherwise 80\ % of RAM is used as the limit.
 208 .PP
 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
 213 .BR \-\-format=raw ,
 214 an error is displayed and
 215 .B xz
 216 will exit with exit status
 217 .BR 1 .
 218 .PP
 219 If source
 220 .I file
 221 cannot be decompressed without exceeding the memory usage limit, an error
 222 message is displayed and the file is skipped. Note that compressed files
 223 may contain many blocks, which may have been compressed with different
 224 settings. Typically all blocks will have roughly the same memory requirements,
 225 but it is possible that a block later in the file will exceed the memory usage
 226 limit, and an error about too low memory usage limit gets displayed after some
 227 data has already been decompressed.
 228 .PP
 229 The absolute value of the active memory usage limit can be seen with
 230 .B \-\-info-memory
 231 or near the bottom of the output of
 232 .BR \-\-long\-help .
 233 The default limit can be overridden with
 234 \fB\-\-memory=\fIlimit\fR.
 235 .SH OPTIONS
 236 .SS "Integer suffixes and special values"
 237 In most places where an integer argument is expected, an optional suffix
 238 is supported to easily indicate large integers. There must be no space
 239 between the integer and the suffix.
 240 .TP
 241 .B KiB
 242 The integer is multiplied by 1,024 (2^10). Also
 243 .BR Ki ,
 244 .BR k ,
 245 .BR kB ,
 246 .BR K ,
 247 and
 248 .B KB
 249 are accepted as synonyms for
 250 .BR KiB .
 251 .TP
 252 .B MiB
 253 The integer is multiplied by 1,048,576 (2^20). Also
 254 .BR Mi ,
 255 .BR m ,
 256 .BR M ,
 257 and
 258 .B MB
 259 are accepted as synonyms for
 260 .BR MiB .
 261 .TP
 262 .B GiB
 263 The integer is multiplied by 1,073,741,824 (2^30). Also
 264 .BR Gi ,
 265 .BR g ,
 266 .BR G ,
 267 and
 268 .B GB
 269 are accepted as synonyms for
 270 .BR GiB .
 271 .PP
 272 A special value
 273 .B max
 274 can be used to indicate the maximum integer value supported by the option.
 275 .SS "Operation mode"
 276 If multiple operation mode options are given, the last one takes effect.
 277 .TP
 278 .BR \-z ", " \-\-compress
 279 Compress. This is the default operation mode when no operation mode option
 280 is specified, and no other operation mode is implied from the command name
 281 (for example,
 282 .B unxz
 283 implies
 284 .BR \-\-decompress ).
 285 .TP
 286 .BR \-d ", " \-\-decompress ", " \-\-uncompress
 287 Decompress.
 288 .TP
 289 .BR \-t ", " \-\-test
 290 Test the integrity of compressed
 291 .IR files .
 292 No files are created or removed. This option is equivalent to
 293 .B "\-\-decompress \-\-stdout"
 294 except that the decompressed data is discarded instead of being
 295 written to standard output.
 296 .TP
 297 .BR \-l ", " \-\-list
 298 View information about the compressed files. No uncompressed output is
 299 produced, and no files are created or removed. In list mode, the program
 300 cannot read the compressed data from standard input or from other
 301 unseekable sources.
 302 .IP
 303 .B "This feature has not been implemented yet."
 304 .SS "Operation modifiers"
 305 .TP
 306 .BR \-k ", " \-\-keep
 307 Keep (don't delete) the input files.
 308 .TP
 309 .BR \-f ", " \-\-force
 310 This option has several effects:
 311 .RS
 312 .IP \(bu 3
 313 If the target file already exists, delete it before compressing or
 314 decompressing.
 315 .IP \(bu 3
 316 Compress or decompress even if the input is a symbolic link to a regular file,
 317 has more than one hard link, or has setuid, setgid, or sticky bit set.
 318 The setuid, setgid, and sticky bits are not copied to the target file.
 319 .IP \(bu 3
 320 If combined with
 321 .B \-\-decompress
 322 .BR \-\-stdout
 323 and
 324 .B xz
 325 doesn't recognize the type of the source file,
 326 .B xz
 327 will copy the source file as is to standard output. This allows using
 328 .B xzcat
 329 .B \--force
 330 like
 331 .BR cat (1)
 332 for files that have not been compressed with
 333 .BR xz .
 334 Note that in future,
 335 .B xz
 336 might support new compressed file formats, which may make
 337 .B xz
 338 decompress more types of files instead of copying them as is to
 339 standard output.
 340 .BI \-\-format= format
 341 can be used to restrict
 342 .B xz
 343 to decompress only a single file format.
 344 .RE
 345 .TP
 346 .BR \-c ", " \-\-stdout ", " \-\-to-stdout
 347 Write the compressed or decompressed data to standard output instead of
 348 a file. This implies
 349 .BR \-\-keep .
 350 .TP
 351 .B \-\-no\-sparse
 352 Disable creation of sparse files. By default, if decompressing into
 353 a regular file,
 354 .B xz
 355 tries to make the file sparse if the decompressed data contains long
 356 sequences of binary zeros. It works also when writing to standard output
 357 as long as standard output is connected to a regular file, and certain
 358 additional conditions are met to make it safe. Creating sparse files may
 359 save disk space and speed up the decompression by reducing the amount of
 360 disk I/O.
 361 .TP
 362 \fB\-S\fR \fI.suf\fR, \fB\-\-suffix=\fI.suf
 363 When compressing, use
 364 .I .suf
 365 as the suffix for the target file instead of
 366 .B .xz
 367 or
 368 .BR .lzma .
 369 If not writing to standard output and the source file already has the suffix
 370 .IR .suf ,
 371 a warning is displayed and the file is skipped.
 372 .IP
 373 When decompressing, recognize also files with the suffix
 374 .I .suf
 375 in addition to files with the
 376 .BR .xz ,
 377 .BR .txz ,
 378 .BR .lzma ,
 379 or
 380 .B .tlz
 381 suffix. If the source file has the suffix
 382 .IR .suf ,
 383 the suffix is removed to get the target filename.
 384 .IP
 385 When compressing or decompressing raw streams
 386 .RB ( \-\-format=raw ),
 387 the suffix must always be specified unless writing to standard output,
 388 because there is no default suffix for raw streams.
 389 .TP
 390 \fB\-\-files\fR[\fB=\fIfile\fR]
 391 Read the filenames to process from
 392 .IR file ;
 393 if
 394 .I file
 395 is omitted, filenames are read from standard input. Filenames must be
 396 terminated with the newline character. A dash
 397 .RB ( \- )
 398 is taken as a regular filename; it doesn't mean standard input.
 399 If filenames are given also as command line arguments, they are
 400 processed before the filenames read from
 401 .IR file .
 402 .TP
 403 \fB\-\-files0\fR[\fB=\fIfile\fR]
 404 This is identical to \fB\-\-files\fR[\fB=\fIfile\fR] except that the
 405 filenames must be terminated with the null character.
 406 .SS "Basic file format and compression options"
 407 .TP
 408 \fB\-F\fR \fIformat\fR, \fB\-\-format=\fIformat
 409 Specify the file format to compress or decompress:
 410 .RS
 411 .IP \(bu 3
 412 .BR auto :
 413 This is the default. When compressing,
 414 .B auto
 415 is equivalent to
 416 .BR xz .
 417 When decompressing, the format of the input file is automatically detected.
 418 Note that raw streams (created with
 419 .BR \-\-format=raw )
 420 cannot be auto-detected.
 421 .IP \(bu 3
 422 .BR xz :
 423 Compress to the
 424 .B .xz
 425 file format, or accept only
 426 .B .xz
 427 files when decompressing.
 428 .IP \(bu 3
 429 .B lzma
 430 or
 431 .BR alone :
 432 Compress to the legacy
 433 .B .lzma
 434 file format, or accept only
 435 .B .lzma
 436 files when decompressing. The alternative name
 437 .B alone
 438 is provided for backwards compatibility with LZMA Utils.
 439 .IP \(bu 3
 440 .BR raw :
 441 Compress or uncompress a raw stream (no headers). This is meant for advanced
 442 users only. To decode raw streams, you need to set not only
 443 .B \-\-format=raw
 444 but also specify the filter chain, which would normally be stored in the
 445 container format headers.
 446 .RE
 447 .TP
 448 \fB\-C\fR \fIcheck\fR, \fB\-\-check=\fIcheck
 449 Specify the type of the integrity check, which is calculated from the
 450 uncompressed data. This option has an effect only when compressing into the
 451 .B .xz
 452 format; the
 453 .B .lzma
 454 format doesn't support integrity checks.
 455 The integrity check (if any) is verified when the
 456 .B .xz
 457 file is decompressed.
 458 .IP
 459 Supported
 460 .I check
 461 types:
 462 .RS
 463 .IP \(bu 3
 464 .BR none :
 465 Don't calculate an integrity check at all. This is usually a bad idea. This
 466 can be useful when integrity of the data is verified by other means anyway.
 467 .IP \(bu 3
 468 .BR crc32 :
 469 Calculate CRC32 using the polynomial from IEEE-802.3 (Ethernet).
 470 .IP \(bu 3
 471 .BR crc64 :
 472 Calculate CRC64 using the polynomial from ECMA-182. This is the default, since
 473 it is slightly better than CRC32 at detecting damaged files and the speed
 474 difference is negligible.
 475 .IP \(bu 3
 476 .BR sha256 :
 477 Calculate SHA-256. This is somewhat slower than CRC32 and CRC64.
 478 .RE
 479 .IP
 480 Integrity of the
 481 .B .xz
 482 headers is always verified with CRC32. It is not possible to change or
 483 disable it.
 484 .TP
 485 .BR \-0 " ... " \-9
 486 Select compression preset. If a preset level is specified multiple times,
 487 the last one takes effect.
 488 .IP
 489 The compression preset levels can be categorised roughly into three
 490 categories:
 491 .RS
 492 .IP "\fB\-0\fR ... \fB\-2"
 493 Fast presets with relatively low memory usage.
 494 .B \-1
 495 and
 496 .B \-2
 497 should give compression speed and ratios comparable to
 498 .B "bzip2 \-1"
 499 and
 500 .BR "bzip2 \-9" ,
 501 respectively.
 502 Currently
 503 .B \-0
 504 is not very good (not much faster than
 505 .B \-1
 506 but much worse compression). In future,
 507 .B \-0
 508 may be indicate some fast algorithm instead of LZMA2.
 509 .IP "\fB\-3\fR ... \fB\-5"
 510 Good compression ratio with low to medium memory usage.
 511 These are significantly slower than levels 0\-2.
 512 .IP "\fB\-6\fR ... \fB\-9"
 513 Excellent compression with medium to high memory usage. These are also
 514 slower than the lower preset levels. The default is
 515 .BR \-6 .
 516 Unless you want to maximize the compression ratio, you probably don't want
 517 a higher preset level than
 518 .B \-7
 519 due to speed and memory usage.
 520 .RE
 521 .IP
 522 The exact compression settings (filter chain) used by each preset may
 523 vary between
 524 .B xz
 525 versions. The settings may also vary between files being compressed, if
 526 .B xz
 527 determines that modified settings will probably give better compression
 528 ratio without significantly affecting compression time or memory usage.
 529 .IP
 530 Because the settings may vary, the memory usage may vary too. The following
 531 table lists the maximum memory usage of each preset level, which won't be
 532 exceeded even in future versions of
 533 .BR xz .
 534 .IP
 535 .B "FIXME: The table below is just a rough idea."
 536 .RS
 537 .RS
 538 .TS
 539 tab(;);
 540 c c c
 541 n n n.
 542 Preset;Compression;Decompression
 543 \-0;6 MiB;1 MiB
 544 \-1;6 MiB;1 MiB
 545 \-2;10 MiB;1 MiB
 546 \-3;20 MiB;2 MiB
 547 \-4;30 MiB;3 MiB
 548 \-5;60 MiB;6 MiB
 549 \-6;100 MiB;10 MiB
 550 \-7;200 MiB;20 MiB
 551 \-8;400 MiB;40 MiB
 552 \-9;800 MiB;80 MiB
 553 .TE
 554 .RE
 555 .RE
 556 .IP
 557 When compressing,
 558 .B xz
 559 automatically adjusts the compression settings downwards if
 560 the memory usage limit would be exceeded, so it is safe to specify
 561 a high preset level even on systems that don't have lots of RAM.
 562 .TP
 563 .BR \-\-fast " and " \-\-best
 564 These are somewhat misleading aliases for
 565 .B \-0
 566 and
 567 .BR \-9 ,
 568 respectively.
 569 These are provided only for backwards compatibility with LZMA Utils.
 570 Avoid using these options.
 571 .IP
 572 Especially the name of
 573 .B \-\-best
 574 is misleading, because the definition of best depends on the input data,
 575 and that usually people don't want the very best compression ratio anyway,
 576 because it would be very slow.
 577 .TP
 578 .BR \-e ", " \-\-extreme
 579 Modify the compression preset (\fB\-0\fR ... \fB\-9\fR) so that a little bit
 580 better compression ratio can be achieved without increasing memory usage
 581 of the compressor or decompressor (exception: compressor memory usage may
 582 increase a little with presets \fB\-0\fR ... \fB\-2\fR). The downside is that
 583 the compression time will increase dramatically (it can easily double).
 584 .TP
 585 \fB\-M\fR \fIlimit\fR, \fB\-\-memory=\fIlimit
 586 Set the memory usage limit. If this option is specified multiple times,
 587 the last one takes effect. The
 588 .I limit
 589 can be specified in multiple ways:
 590 .RS
 591 .IP \(bu 3
 592 The
 593 .I limit
 594 can be an absolute value in bytes. Using an integer suffix like
 595 .B MiB
 596 can be useful. Example:
 597 .B "\-\-memory=80MiB"
 598 .IP \(bu 3
 599 The
 600 .I limit
 601 can be specified as a percentage of physical RAM. Example:
 602 .B "\-\-memory=70%"
 603 .IP \(bu 3
 604 The
 605 .I limit
 606 can be reset back to its default value by setting it to
 607 .BR 0 .
 608 See the section
 609 .B "Memory usage"
 610 for how the default limit is defined.
 611 .IP \(bu 3
 612 The memory usage limiting can be effectively disabled by setting
 613 .I limit
 614 to
 615 .BR max .
 616 This isn't recommended. It's usually better to use, for example,
 617 .BR \-\-memory=90% .
 618 .RE
 619 .IP
 620 The current
 621 .I limit
 622 can be seen near the bottom of the output of the
 623 .B \-\-long-help
 624 option.
 625 .TP
 626 \fB\-T\fR \fIthreads\fR, \fB\-\-threads=\fIthreads
 627 Specify the maximum number of worker threads to use. The default is
 628 the number of available CPU cores. You can see the current value of
 629 .I threads
 630 near the end of the output of the
 631 .B \-\-long\-help
 632 option.
 633 .IP
 634 The actual number of worker threads can be less than
 635 .I threads
 636 if using more threads would exceed the memory usage limit.
 637 In addition to CPU-intensive worker threads,
 638 .B xz
 639 may use a few auxiliary threads, which don't use a lot of CPU time.
 640 .IP
 641 .B "Multithreaded compression and decompression are not implemented yet,"
 642 .B "so this option has no effect for now."
 643 .SS Custom compressor filter chains
 644 A custom filter chain allows specifying the compression settings in detail
 645 instead of relying on the settings associated to the preset levels.
 646 When a custom filter chain is specified, the compression preset level options
 647 (\fB\-0\fR ... \fB\-9\fR and \fB\-\-extreme\fR) are silently ignored.
 648 .PP
 649 A filter chain is comparable to piping on the UN*X command line.
 650 When compressing, the uncompressed input goes to the first filter, whose
 651 output goes to the next filter (if any). The output of the last filter
 652 gets written to the compressed file. The maximum number of filters in
 653 the chain is four, but typically a filter chain has only one or two filters.
 654 .PP
 655 Many filters have limitations where they can be in the filter chain:
 656 some filters can work only as the last filter in the chain, some only
 657 as a non-last filter, and some work in any position in the chain. Depending
 658 on the filter, this limitation is either inherent to the filter design or
 659 exists to prevent security issues.
 660 .PP
 661 A custom filter chain is specified by using one or more filter options in
 662 the order they are wanted in the filter chain. That is, the order of filter
 663 options is significant! When decoding raw streams
 664 .RB ( \-\-format=raw ),
 665 the filter chain is specified in the same order as it was specified when
 666 compressing.
 667 .PP
 668 Filters take filter-specific
 669 .I options
 670 as a comma-separated list. Extra commas in
 671 .I options
 672 are ignored. Every option has a default value, so you need to
 673 specify only those you want to change.
 674 .TP
 675 \fB\-\-lzma1\fR[\fB=\fIoptions\fR], \fB\-\-lzma2\fR[\fB=\fIoptions\fR]
 676 Add LZMA1 or LZMA2 filter to the filter chain. These filter can be used
 677 only as the last filter in the chain.
 678 .IP
 679 LZMA1 is a legacy filter, which is supported almost solely due to the legacy
 680 .B .lzma
 681 file format, which supports only LZMA1. LZMA2 is an updated
 682 version of LZMA1 to fix some practical issues of LZMA1. The
 683 .B .xz
 684 format uses LZMA2, and doesn't support LZMA1 at all. Compression speed and
 685 ratios of LZMA1 and LZMA2 are practically the same.
 686 .IP
 687 LZMA1 and LZMA2 share the same set of
 688 .IR options :
 689 .RS
 690 .TP
 691 .BI preset= preset
 692 Reset all LZMA1 or LZMA2
 693 .I options
 694 to
 695 .IR preset .
 696 .I Preset
 697 consist of an integer, which may be followed by single-letter preset
 698 modifiers. The integer can be from
 699 .B 0
 700 to
 701 .BR 9 ,
 702 matching the command line options \fB\-0\fR ... \fB\-9\fR.
 703 The only supported modifier is currently
 704 .BR e ,
 705 which matches
 706 .BR \-\-extreme .
 707 .IP
 708 The default
 709 .I preset
 710 is
 711 .BR 6 ,
 712 from which the default values for the rest of the LZMA1 or LZMA2
 713 .I options
 714 are taken.
 715 .TP
 716 .BI dict= size
 717 Dictionary (history buffer) size indicates how many bytes of the recently
 718 processed uncompressed data is kept in memory. One method to reduce size of
 719 the uncompressed data is to store distance-length pairs, which
 720 indicate what data to repeat from the dictionary buffer. The bigger
 721 the dictionary, the better the compression ratio usually is,
 722 but dictionaries bigger than the uncompressed data are waste of RAM.
 723 .IP
 724 Typical dictionary size is from 64 KiB to 64 MiB. The minimum is 4 KiB.
 725 The maximum for compression is currently 1.5 GiB. The decompressor already
 726 supports dictionaries up to one byte less than 4 GiB, which is the
 727 maximum for LZMA1 and LZMA2 stream formats.
 728 .IP
 729 Dictionary size has the biggest effect on compression ratio.
 730 Dictionary size and match finder together determine the memory usage of
 731 the LZMA1 or LZMA2 encoder. The same dictionary size is required
 732 for decompressing that was used when compressing, thus the memory usage of
 733 the decoder is determined by the dictionary size used when compressing.
 734 .TP
 735 .BI lc= lc
 736 Specify the number of literal context bits. The minimum is
 737 .B 0
 738 and the maximum is
 739 .BR 4 ;
 740 the default is
 741 .BR 3 .
 742 In addition, the sum of
 743 .I lc
 744 and
 745 .I lp
 746 must not exceed
 747 .BR 4 .
 748 .TP
 749 .BI lp= lp
 750 Specify the number of literal position bits. The minimum is
 751 .B 0
 752 and the maximum is
 753 .BR 4 ;
 754 the default is
 755 .BR 0 .
 756 .TP
 757 .BI pb= pb
 758 Specify the number of position bits. The minimum is
 759 .B 0
 760 and the maximum is
 761 .BR 4 ;
 762 the default is
 763 .BR 2 .
 764 .TP
 765 .BI mode= mode
 766 Compression
 767 .I mode
 768 specifies the function used to analyze the data produced by the match finder.
 769 Supported
 770 .I modes
 771 are
 772 .B fast
 773 and
 774 .BR normal .
 775 The default is
 776 .B fast
 777 for
 778 .I presets
 779 .BR 0 \- 2
 780 and
 781 .B normal
 782 for
 783 .I presets
 784 .BR 3 \- 9 .
 785 .TP
 786 .BI mf= mf
 787 Match finder has a major effect on encoder speed, memory usage, and
 788 compression ratio. Usually Hash Chain match finders are faster than
 789 Binary Tree match finders. Hash Chains are usually used together with
 790 .B mode=fast
 791 and Binary Trees with
 792 .BR mode=normal .
 793 The memory usage formulas are only rough estimates,
 794 which are closest to reality when
 795 .I dict
 796 is a power of two.
 797 .RS
 798 .TP
 799 .B hc3
 800 Hash Chain with 2- and 3-byte hashing
 801 .br
 802 Minimum value for
 803 .IR nice :
 804 3
 805 .br
 806 Memory usage:
 807 .I dict
 808 * 7.5 (if
 809 .I dict
 810 <= 16 MiB);
 811 .br
 812 .I dict
 813 * 5.5 + 64 MiB (if
 814 .I dict
 815 > 16 MiB)
 816 .TP
 817 .B hc4
 818 Hash Chain with 2-, 3-, and 4-byte hashing
 819 .br
 820 Minimum value for
 821 .IR nice :
 822 4
 823 .br
 824 Memory usage:
 825 .I dict
 826 * 7.5
 827 .TP
 828 .B bt2
 829 Binary Tree with 2-byte hashing
 830 .br
 831 Minimum value for
 832 .IR nice :
 833 2
 834 .br
 835 Memory usage:
 836 .I dict
 837 * 9.5
 838 .TP
 839 .B bt3
 840 Binary Tree with 2- and 3-byte hashing
 841 .br
 842 Minimum value for
 843 .IR nice :
 844 3
 845 .br
 846 Memory usage:
 847 .I dict
 848 * 11.5 (if
 849 .I dict
 850 <= 16 MiB);
 851 .br
 852 .I dict
 853 * 9.5 + 64 MiB (if
 854 .I dict
 855 > 16 MiB)
 856 .TP
 857 .B bt4
 858 Binary Tree with 2-, 3-, and 4-byte hashing
 859 .br
 860 Minimum value for
 861 .IR nice :
 862 4
 863 .br
 864 Memory usage:
 865 .I dict
 866 * 11.5
 867 .RE
 868 .TP
 869 .BI nice= nice
 870 Specify what is considered to be a nice length for a match. Once a match
 871 of at least
 872 .I nice
 873 bytes is found, the algorithm stops looking for possibly better matches.
 874 .IP
 875 .I nice
 876 can be 2\-273 bytes. Higher values tend to give better compression ratio
 877 at expense of speed. The default depends on the
 878 .I preset
 879 level.
 880 .TP
 881 .BI depth= depth
 882 Specify the maximum search depth in the match finder. The default is the
 883 special value
 884 .BR 0 ,
 885 which makes the compressor determine a reasonable
 886 .I depth
 887 from
 888 .I mf
 889 and
 890 .IR nice .
 891 .IP
 892 Using very high values for
 893 .I depth
 894 can make the encoder extremely slow with carefully crafted files.
 895 Avoid setting the
 896 .I depth
 897 over 1000 unless you are prepared to interrupt the compression in case it
 898 is taking too long.
 899 .RE
 900 .IP
 901 When decoding raw streams
 902 .RB ( \-\-format=raw ),
 903 LZMA2 needs only the value of
 904 .BR dict .
 905 LZMA1 needs also
 906 .BR lc ,
 907 .BR lp ,
 908 and
 909 .BR pb.
 910 .TP
 911 \fB\-\-x86\fR[\fB=\fIoptions\fR]
 912 .TP
 913 \fB\-\-powerpc\fR[\fB=\fIoptions\fR]
 914 .TP
 915 \fB\-\-ia64\fR[\fB=\fIoptions\fR]
 916 .TP
 917 \fB\-\-arm\fR[\fB=\fIoptions\fR]
 918 .TP
 919 \fB\-\-armthumb\fR[\fB=\fIoptions\fR]
 920 .TP
 921 \fB\-\-sparc\fR[\fB=\fIoptions\fR]
 922 Add a branch/call/jump (BCJ) filter to the filter chain. These filters
 923 can be used only as non-last filter in the filter chain.
 924 .IP
 925 A BCJ filter converts relative addresses in the machine code to their
 926 absolute counterparts. This doesn't change the size of the data, but
 927 it increases redundancy, which allows e.g. LZMA2 to get better
 928 compression ratio.
 929 .IP
 930 The BCJ filters are always reversible, so using a BCJ filter for wrong
 931 type of data doesn't cause any data loss. However, applying a BCJ filter
 932 for wrong type of data is a bad idea, because it tends to make the
 933 compression ratio worse.
 934 .IP
 935 Different instruction sets have have different alignment:
 936 .RS
 937 .RS
 938 .TS
 939 tab(;);
 940 l n l
 941 l n l.
 942 Filter;Alignment;Notes
 943 x86;1;32-bit and 64-bit x86
 944 PowerPC;4;Big endian only
 945 ARM;4;Little endian only
 946 ARM-Thumb;2;Little endian only
 947 IA-64;16;Big or little endian
 948 SPARC;4;Big or little endian
 949 .TE
 950 .RE
 951 .RE
 952 .IP
 953 Since the BCJ-filtered data is usually compressed with LZMA2, the compression
 954 ratio may be improved slightly if the LZMA2 options are set to match the
 955 alignment of the selected BCJ filter. For example, with the IA-64 filter,
 956 it's good to set
 957 .B pb=4
 958 with LZMA2 (2^4=16). The x86 filter is an exception; it's usually good to
 959 stick to LZMA2's default four-byte alignment when compressing x86 executables.
 960 .IP
 961 All BCJ filters support the same
 962 .IR options :
 963 .RS
 964 .TP
 965 .BI start= offset
 966 Specify the start
 967 .I offset
 968 that is used when converting between relative and absolute addresses.
 969 The
 970 .I offset
 971 must be a multiple of the alignment of the filter (see the table above).
 972 The default is zero. In practice, the default is good; specifying
 973 a custom
 974 .I offset
 975 is almost never useful.
 976 .IP
 977 Specifying a non-zero start
 978 .I offset
 979 is probably useful only if the executable has multiple sections, and there
 980 are many cross-section jumps or calls. Applying a BCJ filter separately for
 981 each section with proper start offset and then compressing the result as
 982 a single chunk may give some improvement in compression ratio compared
 983 to applying the BCJ filter with the default
 984 .I offset
 985 for the whole executable.
 986 .RE
 987 .TP
 988 \fB\-\-delta\fR[\fB=\fIoptions\fR]
 989 Add Delta filter to the filter chain. The Delta filter
 990 can be used only as non-last filter in the filter chain.
 991 .IP
 992 Currently only simple byte-wise delta calculation is supported. It can
 993 be useful when compressing e.g. uncompressed bitmap images or uncompressed
 994 PCM audio. However, special purpose algorithms may give significantly better
 995 results than Delta + LZMA2. This is true especially with audio, which
 996 compresses faster and better e.g. with FLAC.
 997 .IP
 998 Supported
 999 .IR options :
1000 .RS
1001 .TP
1002 .BI dist= distance
1003 Specify the
1004 .I distance
1005 of the delta calculation as bytes.
1006 .I distance
1007 must be 1\-256. The default is 1.
1008 .IP
1009 For example, with
1010 .B dist=2
1011 and eight-byte input A1 B1 A2 B3 A3 B5 A4 B7, the output will be
1012 A1 B1 01 02 01 02 01 02.
1013 .RE
1014 .SS "Other options"
1015 .TP
1016 .BR \-q ", " \-\-quiet
1017 Suppress warnings and notices. Specify this twice to suppress errors too.
1018 This option has no effect on the exit status. That is, even if a warning
1019 was suppressed, the exit status to indicate a warning is still used.
1020 .TP
1021 .BR \-v ", " \-\-verbose
1022 Be verbose. If standard error is connected to a terminal,
1023 .B xz
1024 will display a progress indicator.
1025 Specifying
1026 .B \-\-verbose
1027 twice will give even more verbose output (useful mostly for debugging).
1028 .IP
1029 The progress indicator shows the following information:
1030 .RS
1031 .IP \(bu 3
1032 Completion percentage is shown if the size of the input file is known.
1033 That is, percentage cannot be shown in pipes.
1034 .IP \(bu 3
1035 Amount of compressed data produced (compressing) or consumed (decompressing).
1036 .IP \(bu 3
1037 Amount of uncompressed data consumed (compressing) or produced
1038 (decompressing).
1039 .IP \(bu 3
1040 Compression ratio, which is calculated by dividing the amount of
1041 compressed data processed so far by the amount of uncompressed data
1042 processed so far.
1043 .IP \(bu 3
1044 Compression or decompression speed. This is measured as the amount of
1045 uncompressed data consumed (compression) or produced (decompression)
1046 per second. It is shown once a few seconds have passed since
1047 .B xz
1048 started processing the file.
1049 .IP \(bu 3
1050 Elapsed time or estimated time remaining.
1051 Elapsed time is displayed in the format M:SS or H:MM:SS.
1052 The estimated remaining time is displayed in a less precise format
1053 which never has colons, for example, 2 min 30 s. The estimate can
1054 be shown only when the size of the input file is known and a couple of
1055 seconds have already passed since
1056 .B xz
1057 started processing the file.
1058 .RE
1059 .IP
1060 When standard error is not a terminal,
1061 .B \-\-verbose
1062 will make
1063 .B xz
1064 print the filename, compressed size, uncompressed size, compression ratio,
1065 speed, and elapsed time on a single line to standard error after
1066 compressing or decompressing the file. If operating took at least a few
1067 seconds, also the speed and elapsed time are printed. If the operation
1068 didn't finish, for example due to user interruption, also the completion
1069 percentage is printed if the size of the input file is known.
1070 .TP
1071 .BR \-Q ", " \-\-no\-warn
1072 Don't set the exit status to
1073 .B 2
1074 even if a condition worth a warning was detected. This option doesn't affect
1075 the verbosity level, thus both
1076 .B \-\-quiet
1077 and
1078 .B \-\-no\-warn
1079 have to be used to not display warnings and to not alter the exit status.
1080 .TP
1081 .B \-\-robot
1082 Print messages in a machine-parsable format. This is intended to ease
1083 writing frontends that want to use
1084 .B xz
1085 instead of liblzma, which may be the case with various scripts. The output
1086 with this option enabled is meant to be stable across
1087 .B xz
1088 releases. Currently
1089 .B \-\-robot
1090 is implemented only for
1091 .B \-\-info\-memory
1092 and
1093 .BR \-\-version ,
1094 but the idea is to make it usable for actual compression
1095 and decompression too.
1096 .TP
1097 .BR \-\-info-memory
1098 Display the current memory usage limit in human-readable format on
1099 a single line, and exit successfully. To see how much RAM
1100 .B xz
1101 thinks your system has, use
1102 .BR "\-\-memory=100% \-\-info\-memory" .
1103 To get machine-parsable output
1104 (memory usage limit as bytes without thousand separators), specify
1105 .B \-\-robot
1106 before
1107 .BR \-\-info-memory .
1108 .TP
1109 .BR \-h ", " \-\-help
1110 Display a help message describing the most commonly used options,
1111 and exit successfully.
1112 .TP
1113 .BR \-H ", " \-\-long\-help
1114 Display a help message describing all features of
1115 .BR xz ,
1116 and exit successfully
1117 .TP
1118 .BR \-V ", " \-\-version
1119 Display the version number of
1120 .B xz
1121 and liblzma in human readable format. To get machine-parsable output, specify
1122 .B \-\-robot
1123 before
1124 .BR \-\-version .
1125 .SH "EXIT STATUS"
1126 .TP
1127 .B 0
1128 All is good.
1129 .TP
1130 .B 1
1131 An error occurred.
1132 .TP
1133 .B 2
1134 Something worth a warning occurred, but no actual errors occurred.
1135 .PP
1136 Notices (not warnings or errors) printed on standard error don't affect
1137 the exit status.
1138 .SH ENVIRONMENT
1139 .TP
1140 .B XZ_OPT
1141 A space-separated list of options is parsed from
1142 .B XZ_OPT
1143 before parsing the options given on the command line. Note that only
1144 options are parsed from
1145 .BR XZ_OPT ;
1146 all non-options are silently ignored. Parsing is done with
1147 .BR getopt_long (3)
1148 which is used also for the command line arguments.
1149 .SH "LZMA UTILS COMPATIBILITY"
1150 The command line syntax of
1151 .B xz
1152 is practically a superset of
1153 .BR lzma ,
1154 .BR unlzma ,
1155 and
1156 .BR lzcat
1157 as found from LZMA Utils 4.32.x. In most cases, it is possible to replace
1158 LZMA Utils with XZ Utils without breaking existing scripts. There are some
1159 incompatibilities though, which may sometimes cause problems.
1160 .SS "Compression preset levels"
1161 The numbering of the compression level presets is not identical in
1162 .B xz
1163 and LZMA Utils.
1164 The most important difference is how dictionary sizes are mapped to different
1165 presets. Dictionary size is roughly equal to the decompressor memory usage.
1166 .RS
1167 .TS
1168 tab(;);
1169 c c c
1170 c n n.
1171 Level;xz;LZMA Utils
1172 \-1;64 KiB;64 KiB
1173 \-2;512 KiB;1 MiB
1174 \-3;1 MiB;512 KiB
1175 \-4;2 MiB;1 MiB
1176 \-5;4 MiB;2 MiB
1177 \-6;8 MiB;4 MiB
1178 \-7;16 MiB;8 MiB
1179 \-8;32 MiB;16 MiB
1180 \-9;64 MiB;32 MiB
1181 .TE
1182 .RE
1183 .PP
1184 The dictionary size differences affect the compressor memory usage too,
1185 but there are some other differences between LZMA Utils and XZ Utils, which
1186 make the difference even bigger:
1187 .RS
1188 .TS
1189 tab(;);
1190 c c c
1191 c n n.
1192 Level;xz;LZMA Utils 4.32.x
1193 \-1;2 MiB;2 MiB
1194 \-2;5 MiB;12 MiB
1195 \-3;13 MiB;12 MiB
1196 \-4;25 MiB;16 MiB
1197 \-5;48 MiB;26 MiB
1198 \-6;94 MiB;45 MiB
1199 \-7;186 MiB;83 MiB
1200 \-8;370 MiB;159 MiB
1201 \-9;674 MiB;311 MiB
1202 .TE
1203 .RE
1204 .PP
1205 The default preset level in LZMA Utils is
1206 .B \-7
1207 while in XZ Utils it is
1208 .BR \-6 ,
1209 so both use 8 MiB dictionary by default.
1210 .SS "Streamed vs. non-streamed .lzma files"
1211 Uncompressed size of the file can be stored in the
1212 .B .lzma
1213 header. LZMA Utils does that when compressing regular files.
1214 The alternative is to mark that uncompressed size is unknown and
1215 use end of payload marker to indicate where the decompressor should stop.
1216 LZMA Utils uses this method when uncompressed size isn't known, which is
1217 the case for example in pipes.
1218 .PP
1219 .B xz
1220 supports decompressing
1221 .B .lzma
1222 files with or without end of payload marker, but all
1223 .B .lzma
1224 files created by
1225 .B xz
1226 will use end of payload marker and have uncompressed size marked as unknown
1227 in the
1228 .B .lzma
1229 header. This may be a problem in some (uncommon) situations. For example, a
1230 .B .lzma
1231 decompressor in an embedded device might work only with files that have known
1232 uncompressed size. If you hit this problem, you need to use LZMA Utils or
1233 LZMA SDK to create
1234 .B .lzma
1235 files with known uncompressed size.
1236 .SS "Unsupported .lzma files"
1237 The
1238 .B .lzma
1239 format allows
1240 .I lc
1241 values up to 8, and
1242 .I lp
1243 values up to 4. LZMA Utils can decompress files with any
1244 .I lc
1245 and
1246 .IR lp ,
1247 but always creates files with
1248 .B lc=3
1249 and
1250 .BR lp=0 .
1251 Creating files with other
1252 .I lc
1253 and
1254 .I lp
1255 is possible with
1256 .B xz
1257 and with LZMA SDK.
1258 .PP
1259 The implementation of the LZMA1 filter in liblzma requires
1260 that the sum of
1261 .I lc
1262 and
1263 .I lp
1264 must not exceed 4. Thus,
1265 .B .lzma
1266 files which exceed this limitation, cannot be decompressed with
1267 .BR xz .
1268 .PP
1269 LZMA Utils creates only
1270 .B .lzma
1271 files which have dictionary size of
1272 .RI "2^" n
1273 (a power of 2), but accepts files with any dictionary size.
1274 liblzma accepts only
1275 .B .lzma
1276 files which have dictionary size of
1277 .RI "2^" n
1278 or
1279 .RI "2^" n " + 2^(" n "\-1)."
1280 This is to decrease false positives when detecting
1281 .B .lzma
1282 files.
1283 .PP
1284 These limitations shouldn't be a problem in practice, since practically all
1285 .B .lzma
1286 files have been compressed with settings that liblzma will accept.
1287 .SS "Trailing garbage"
1288 When decompressing, LZMA Utils silently ignore everything after the first
1289 .B .lzma
1290 stream. In most situations, this is a bug. This also means that LZMA Utils
1291 don't support decompressing concatenated
1292 .B .lzma
1293 files.
1294 .PP
1295 If there is data left after the first
1296 .B .lzma
1297 stream,
1298 .B xz
1299 considers the file to be corrupt. This may break obscure scripts which have
1300 assumed that trailing garbage is ignored.
1301 .SH NOTES
1302 .SS Compressed output may vary
1303 The exact compressed output produced from the same uncompressed input file
1304 may vary between XZ Utils versions even if compression options are identical.
1305 This is because the encoder can be improved (faster or better compression)
1306 without affecting the file format. The output can vary even between different
1307 builds of the same XZ Utils version, if different build options are used.
1308 .PP
1309 The above means that implementing
1310 .B \-\-rsyncable
1311 to create rsyncable
1312 .B .xz
1313 files is not going to happen without freezing a part of the encoder
1314 implementation, which can then be used with
1315 .BR \-\-rsyncable .
1316 .SS Embedded .xz decompressors
1317 Embedded
1318 .B .xz
1319 decompressor implementations like XZ Embedded don't necessarily support files
1320 created with
1321 .I check
1322 types other than
1323 .B none
1324 and
1325 .BR crc32 .
1326 Since the default is \fB\-\-check=\fIcrc64\fR, you must use
1327 .B \-\-check=none
1328 or
1329 .B \-\-check=crc32
1330 when creating files for embedded systems.
1331 .PP
1332 Outside embedded systems, all
1333 .B .xz
1334 format decompressors support all the
1335 .I check
1336 types, or at least are able to decompress the file without verifying the
1337 integrity check if the particular
1338 .I check
1339 is not supported.
1340 .PP
1341 XZ Embedded supports BCJ filters, but only with the default start offset.
1342 .SH "SEE ALSO"
1343 .BR xzdec (1),
1344 .BR gzip (1),
1345 .BR bzip2 (1)
1346 .PP
1347 XZ Utils: <http://tukaani.org/xz/>
1348 .br
1349 XZ Embedded: <http://tukaani.org/xz/embedded.html>
1350 .br
1351 LZMA SDK: <http://7-zip.org/sdk.html>