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-10" "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.
 708 .TP
 709 .BI lp= lp
 710 Specify the number of literal position bits.
 711 .TP
 712 .BI pb= pb
 713 Specify the number of position bits.
 714 .TP
 715 .BI mode= mode
 716 Compression
 717 .I mode
 718 specifies the function used to analyze the data produced by the match finder.
 719 Supported
 720 .I modes
 721 are
 722 .B fast
 723 and
 724 .BR normal .
 725 The default is
 726 .B fast
 727 for
 728 .I presets
 729 .BR 0 \- 2
 730 and
 731 .B normal
 732 for
 733 .I presets
 734 .BR 3 \- 9 .
 735 .TP
 736 .BI mf= mf
 737 Match finder has a major effect on encoder speed, memory usage, and
 738 compression ratio. Usually Hash Chain match finders are faster than
 739 Binary Tree match finders. The memory usage formulas are only rough
 740 estimates, which are closest to reality when
 741 .I dict
 742 is a power of two.
 743 .IP
 744 FIXME Defaults
 745 .RS
 746 .TP
 747 .B hc3
 748 Hash Chain with 2- and 3-byte hashing
 749 .br
 750 Minimum value for
 751 .IR nice :
 752 3
 753 .br
 754 Memory usage:
 755 .I dict
 756 * 7.5 (if
 757 .I dict
 758 <= 16 MiB);
 759 .br
 760 .I dict
 761 * 5.5 + 64 MiB (if
 762 .I dict
 763 > 16 MiB)
 764 .TP
 765 .B hc4
 766 Hash Chain with 2-, 3-, and 4-byte hashing
 767 .br
 768 Minimum value for
 769 .IR nice :
 770 4
 771 .br
 772 Memory usage:
 773 .I dict
 774 * 7.5
 775 .TP
 776 .B bt2
 777 Binary Tree with 2-byte hashing
 778 .br
 779 Minimum value for
 780 .IR nice :
 781 2
 782 .br
 783 Memory usage:
 784 .I dict
 785 * 9.5
 786 .TP
 787 .B bt3
 788 Binary Tree with 2- and 3-byte hashing
 789 .br
 790 Minimum value for
 791 .IR nice :
 792 3
 793 .br
 794 Memory usage:
 795 .I dict
 796 * 11.5 (if
 797 .I dict
 798 <= 16 MiB);
 799 .br
 800 .I dict
 801 * 9.5 + 64 MiB (if
 802 .I dict
 803 > 16 MiB)
 804 .TP
 805 .B bt4
 806 Binary Tree with 2-, 3-, and 4-byte hashing
 807 .br
 808 Minimum value for
 809 .IR nice :
 810 4
 811 .br
 812 Memory usage:
 813 .I dict
 814 * 11.5
 815 .RE
 816 .TP
 817 .BI nice= nice
 818 Specify what is considered to be a nice length for a match. Once a match
 819 of at least
 820 .I nice
 821 bytes is found, the algorithm stops looking for possibly better matches.
 822 .IP
 823 .I nice
 824 can be 2\-273 bytes. Higher values tend to give better compression ratio
 825 at expense of speed. The default depends on the
 826 .I preset
 827 level.
 828 .TP
 829 .BI depth= depth
 830 Specify the maximum search depth in the match finder. The default is the
 831 special value
 832 .BR 0 ,
 833 which makes the compressor determine a reasonable
 834 .I depth
 835 from
 836 .I mf
 837 and
 838 .IR nice .
 839 .IP
 840 Using very high values for
 841 .I depth
 842 can make the encoder extremely slow with carefully crafted files.
 843 Avoid setting the
 844 .I depth
 845 over 1000 unless you are prepared to interrupt the compression in case it
 846 is taking too long.
 847 .RE
 848 .IP
 849 When decoding raw streams
 850 .RB ( \-\-format=raw ),
 851 LZMA2 needs only the value of
 852 .BR dict .
 853 LZMA1 needs also
 854 .BR lc ,
 855 .BR lp ,
 856 and
 857 .BR pb.
 858 .TP
 859 \fB\-\-x86\fR[\fB=\fIoptions\fR]
 860 .TP
 861 \fB\-\-powerpc\fR[\fB=\fIoptions\fR]
 862 .TP
 863 \fB\-\-ia64\fR[\fB=\fIoptions\fR]
 864 .TP
 865 \fB\-\-arm\fR[\fB=\fIoptions\fR]
 866 .TP
 867 \fB\-\-armthumb\fR[\fB=\fIoptions\fR]
 868 .TP
 869 \fB\-\-sparc\fR[\fB=\fIoptions\fR]
 870 Add a branch/call/jump (BCJ) filter to the filter chain. These filters
 871 can be used only as non-last filter in the filter chain.
 872 .IP
 873 A BCJ filter converts relative addresses in the machine code to their
 874 absolute counterparts. This doesn't change the size of the data, but
 875 it increases redundancy, which allows e.g. LZMA2 to get better
 876 compression ratio.
 877 .IP
 878 The BCJ filters are always reversible, so using a BCJ filter for wrong
 879 type of data doesn't cause any data loss. However, applying a BCJ filter
 880 for wrong type of data is a bad idea, because it tends to make the
 881 compression ratio worse.
 882 .IP
 883 Different instruction sets have have different alignment:
 884 .RS
 885 .RS
 886 .TS
 887 tab(;);
 888 l n l
 889 l n l.
 890 Filter;Alignment;Notes
 891 x86;1;32-bit and 64-bit x86
 892 PowerPC;4;Big endian only
 893 ARM;4;Little endian only
 894 ARM-Thumb;2;Little endian only
 895 IA-64;16;Big or little endian
 896 SPARC;4;Big or little endian
 897 .TE
 898 .RE
 899 .RE
 900 .IP
 901 Since the BCJ-filtered data is usually compressed with LZMA2, the compression
 902 ratio may be improved slightly if the LZMA2 options are set to match the
 903 alignment of the selected BCJ filter. For example, with the IA-64 filter,
 904 it's good to set
 905 .B pb=4
 906 with LZMA2 (2^4=16). The x86 filter is an exception; it's usually good to
 907 stick to LZMA2's default four-byte alignment when compressing x86 executables.
 908 .IP
 909 All BCJ filters support the same
 910 .IR options :
 911 .RS
 912 .TP
 913 .BI start= offset
 914 Specify the start
 915 .I offset
 916 that is used when converting between relative and absolute addresses.
 917 The
 918 .I offset
 919 must be a multiple of the alignment of the filter (see the table above).
 920 The default is zero. In practice, the default is good; specifying
 921 a custom
 922 .I offset
 923 is almost never useful.
 924 .IP
 925 Specifying a non-zero start
 926 .I offset
 927 is probably useful only if the executable has multiple sections, and there
 928 are many cross-section jumps or calls. Applying a BCJ filter separately for
 929 each section with proper start offset and then compressing the result as
 930 a single chunk may give some improvement in compression ratio compared
 931 to applying the BCJ filter with the default
 932 .I offset
 933 for the whole executable.
 934 .RE
 935 .TP
 936 \fB\-\-delta\fR[\fB=\fIoptions\fR]
 937 Add Delta filter to the filter chain. The Delta filter
 938 can be used only as non-last filter in the filter chain.
 939 .IP
 940 Currently only simple byte-wise delta calculation is supported. It can
 941 be useful when compressing e.g. uncompressed bitmap images or uncompressed
 942 PCM audio. However, special purpose algorithms may give significantly better
 943 results than Delta + LZMA2. This is true especially with audio, which
 944 compresses faster and better e.g. with FLAC.
 945 .IP
 946 Supported
 947 .IR options :
 948 .RS
 949 .TP
 950 .BI dist= distance
 951 Specify the
 952 .I distance
 953 of the delta calculation as bytes.
 954 .I distance
 955 must be 1\-256. The default is 1.
 956 .IP
 957 For example, with
 958 .B dist=2
 959 and eight-byte input A1 B1 A2 B3 A3 B5 A4 B7, the output will be
 960 A1 B1 01 02 01 02 01 02.
 961 .RE
 962 .SS "Other options"
 963 .TP
 964 .BR \-q ", " \-\-quiet
 965 Suppress warnings and notices. Specify this twice to suppress errors too.
 966 This option has no effect on the exit status. That is, even if a warning
 967 was suppressed, the exit status to indicate a warning is still used.
 968 .TP
 969 .BR \-v ", " \-\-verbose
 970 Be verbose. If standard error is connected to a terminal,
 971 .B xz
 972 will display a progress indicator.
 973 Specifying
 974 .B \-\-verbose
 975 twice will give even more verbose output (useful mostly for debugging).
 976 .TP
 977 .BR \-Q ", " \-\-no\-warn
 978 Don't set the exit status to
 979 .B 2
 980 even if a condition worth a warning was detected. This option doesn't affect
 981 the verbosity level, thus both
 982 .B \-\-quiet
 983 and
 984 .B \-\-no\-warn
 985 have to be used to not display warnings and to not alter the exit status.
 986 .TP
 987 .BR \-h ", " \-\-help
 988 Display a help message describing the most commonly used options,
 989 and exit successfully.
 990 .TP
 991 .BR \-H ", " \-\-long\-help
 992 Display a help message describing all features of
 993 .BR xz ,
 994 and exit successfully
 995 .TP
 996 .BR \-V ", " \-\-version
 997 Display the version number of
 998 .B xz
 999 and liblzma.
1000 .SH "EXIT STATUS"
1001 .TP
1002 .B 0
1003 All is good.
1004 .TP
1005 .B 1
1006 An error occurred.
1007 .TP
1008 .B 2
1009 Something worth a warning occurred, but no actual errors occurred.
1010 .PP
1011 Notices (not warnings or errors) printed on standard error don't affect
1012 the exit status.
1013 .SH ENVIRONMENT
1014 .TP
1015 .B XZ_OPT
1016 A space-separated list of options is parsed from
1017 .B XZ_OPT
1018 before parsing the options given on the command line. Note that only
1019 options are parsed from
1020 .BR XZ_OPT ;
1021 all non-options are silently ignored. Parsing is done with
1022 .BR getopt_long (3)
1023 which is used also for the command line arguments.
1024 .SH "LZMA UTILS COMPATIBILITY"
1025 The command line syntax of
1026 .B xz
1027 is practically a superset of
1028 .BR lzma ,
1029 .BR unlzma ,
1030 and
1031 .BR lzcat
1032 as found from LZMA Utils 4.32.x. In most cases, it is possible to replace
1033 LZMA Utils with XZ Utils without breaking existing scripts. There are some
1034 incompatibilities though, which may sometimes cause problems.
1035 .SS "Compression preset levels"
1036 The numbering of the compression level presets is not identical in
1037 .B xz
1038 and LZMA Utils. Compressor memory usage:
1039 .PP
1040 .B FIXME
1041 .RS
1042 .TS
1043 tab(;);
1044 c c c
1045 c n n.
1046 Level;xz;LZMA Utils 4.32.x
1047 \-1;2 MiB;2 MiB
1048 \-2;5 MiB;12 MiB
1049 \-3;13 MiB;12 MiB
1050 \-4;25 MiB;16 MiB
1051 \-5;48 MiB;26 MiB
1052 \-6;94 MiB;45 MiB
1053 \-7;186 MiB;83 MiB
1054 \-8;370 MiB;159 MiB
1055 \-9;674 MiB;311 MiB
1056 .TE
1057 .RE
1058 .SS "Streamed vs. non-streamed .lzma files"
1059 Uncompressed size of the file can be stored in the
1060 .B .lzma
1061 header. LZMA Utils does that when compressing regular files.
1062 The alternative is to mark that uncompressed size is unknown and
1063 use end of payload marker to indicate where the decompressor should stop.
1064 LZMA Utils uses this method when uncompressed size isn't known, which is
1065 the case for example in pipes.
1066 .PP
1067 .B xz
1068 supports decompressing
1069 .B .lzma
1070 files with or without end of payload marker, but all
1071 .B .lzma
1072 files created by
1073 .B xz
1074 will use end of payload marker and have uncompressed size marked as unknown
1075 in the
1076 .B .lzma
1077 header. This may be a problem in some (uncommon) situations. For example, a
1078 .B .lzma
1079 decompressor in an embedded device might work only with files that have known
1080 uncompressed size. If you hit this problem, you need to use LZMA Utils or
1081 LZMA SDK to create
1082 .B .lzma
1083 files with known uncompressed size.
1084 .SS "Unsupported .lzma files"
1085 The
1086 .B .lzma
1087 format allows
1088 .I lc
1089 values up to 8, and
1090 .I lp
1091 values up to 4. LZMA Utils can decompress files with any
1092 .I lc
1093 and
1094 .IR lp ,
1095 but always creates files with
1096 .B lc=3
1097 and
1098 .BR lp=0 .
1099 Creating files with other
1100 .I lc
1101 and
1102 .I lp
1103 is possible with
1104 .B xz
1105 and with LZMA SDK.
1106 .PP
1107 The implementation of the LZMA1 filter in liblzma requires
1108 that the sum of
1109 .I lc
1110 and
1111 .I lp
1112 must not exceed 4. Thus,
1113 .B .lzma
1114 files which exceed this limitation, cannot be decompressed with
1115 .BR xz .
1116 .PP
1117 LZMA Utils creates only
1118 .B .lzma
1119 files which have dictionary size of
1120 .RI "2^" n
1121 (a power of 2), but accepts files with any dictionary size.
1122 liblzma accepts only
1123 .B .lzma
1124 files which have dictionary size of
1125 .RI "2^" n
1126 or
1127 .RI "2^" n " + 2^(" n "\-1)."
1128 This is to decrease false positives when autodetecting
1129 .B .lzma
1130 files.
1131 .PP
1132 These limitations shouldn't be a problem in practice, since practically all
1133 .B .lzma
1134 files have been compressed with settings that liblzma will accept.
1135 .SS "Trailing garbage"
1136 When decompressing, LZMA Utils silently ignore everything after the first
1137 .B .lzma
1138 stream. In most situations, this is a bug. This also means that LZMA Utils
1139 don't support decompressing concatenated
1140 .B .lzma
1141 files.
1142 .PP
1143 If there is data left after the first
1144 .B .lzma
1145 stream,
1146 .B xz
1147 considers the file to be corrupt. This may break obscure scripts which have
1148 assumed that trailing garbage is ignored.
1149 .SH NOTES
1150 .SS Builds with disabled features
1151 .B xz
1152 can be built with some features disabled, which can make some features
1153 unavailable. This is never the case with normal non-embedded builds.
1154 .SS FIXME
1155 The exact compressed output produced from the same uncompressed input file
1156 may vary between XZ Utils versions even if compression options are identical.
1157 This is because the encoder can be improved (faster or better compression)
1158 without affecting the file format. The output can vary even between different
1159 builds of XZ Utils, if different build options are used or if the endianness
1160 of the hardware is different for different builds.
1161 .PP
1162 The above means that implementing
1163 .B \-\-rsyncable
1164 to create rsyncable
1165 .B .xz
1166 files is not going to happen without freezing a part of the encoder
1167 implementation, which can then be used with
1168 .BR \-\-rsyncable .
1169 .SS Embedded .xz decompressors
1170 Embedded
1171 .B .xz
1172 decompressor implementations like XZ Embedded don't necessarily support files
1173 created with
1174 .I check
1175 types other than
1176 .B none
1177 and
1178 .BR crc32 .
1179 Since the default is \fB\-\-check=\fIcrc64\fR, you must use
1180 .B \-\-check=none
1181 or
1182 .B \-\-check=crc32
1183 when creating files for embedded systems.
1184 .PP
1185 Outside embedded systems, all
1186 .B .xz
1187 format decompressors support all the
1188 .I check
1189 types, or at least are able to decompress the file without verifying the
1190 integrity check if the particular
1191 .I check
1192 is not supported.
1193 .PP
1194 XZ Embedded supports BCJ filters, but only with the default start offset.
1195 .SH "SEE ALSO"
1196 .BR xzdec (1),
1197 .BR gzip (1),
1198 .BR bzip2 (1)
1199 .PP
1200 XZ Utils: <http://tukaani.org/xz/>
1201 .br
1202 XZ Embedded: <http://tukaani.org/xz/embedded.html>
1203 .br
1204 LZMA SDK: <http://7-zip.org/sdk.html>