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