Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man1/xzcat.1 @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
rev   line source
jpayne@68 1 '\" t
jpayne@68 2 .\" SPDX-License-Identifier: 0BSD
jpayne@68 3 .\"
jpayne@68 4 .\" Authors: Lasse Collin
jpayne@68 5 .\" Jia Tan
jpayne@68 6 .\"
jpayne@68 7 .TH XZ 1 "2024-12-30" "Tukaani" "XZ Utils"
jpayne@68 8 .
jpayne@68 9 .SH NAME
jpayne@68 10 xz, unxz, xzcat, lzma, unlzma, lzcat \- Compress or decompress .xz and .lzma files
jpayne@68 11 .
jpayne@68 12 .SH SYNOPSIS
jpayne@68 13 .B xz
jpayne@68 14 .RI [ option... ]
jpayne@68 15 .RI [ file... ]
jpayne@68 16 .
jpayne@68 17 .SH COMMAND ALIASES
jpayne@68 18 .B unxz
jpayne@68 19 is equivalent to
jpayne@68 20 .BR "xz \-\-decompress" .
jpayne@68 21 .br
jpayne@68 22 .B xzcat
jpayne@68 23 is equivalent to
jpayne@68 24 .BR "xz \-\-decompress \-\-stdout" .
jpayne@68 25 .br
jpayne@68 26 .B lzma
jpayne@68 27 is equivalent to
jpayne@68 28 .BR "xz \-\-format=lzma" .
jpayne@68 29 .br
jpayne@68 30 .B unlzma
jpayne@68 31 is equivalent to
jpayne@68 32 .BR "xz \-\-format=lzma \-\-decompress" .
jpayne@68 33 .br
jpayne@68 34 .B lzcat
jpayne@68 35 is equivalent to
jpayne@68 36 .BR "xz \-\-format=lzma \-\-decompress \-\-stdout" .
jpayne@68 37 .PP
jpayne@68 38 When writing scripts that need to decompress files,
jpayne@68 39 it is recommended to always use the name
jpayne@68 40 .B xz
jpayne@68 41 with appropriate arguments
jpayne@68 42 .RB ( "xz \-d"
jpayne@68 43 or
jpayne@68 44 .BR "xz \-dc" )
jpayne@68 45 instead of the names
jpayne@68 46 .B unxz
jpayne@68 47 and
jpayne@68 48 .BR xzcat .
jpayne@68 49 .
jpayne@68 50 .SH DESCRIPTION
jpayne@68 51 .B xz
jpayne@68 52 is a general-purpose data compression tool with
jpayne@68 53 command line syntax similar to
jpayne@68 54 .BR gzip (1)
jpayne@68 55 and
jpayne@68 56 .BR bzip2 (1).
jpayne@68 57 The native file format is the
jpayne@68 58 .B .xz
jpayne@68 59 format, but the legacy
jpayne@68 60 .B .lzma
jpayne@68 61 format used by LZMA Utils and
jpayne@68 62 raw compressed streams with no container format headers
jpayne@68 63 are also supported.
jpayne@68 64 In addition, decompression of the
jpayne@68 65 .B .lz
jpayne@68 66 format used by
jpayne@68 67 .B lzip
jpayne@68 68 is supported.
jpayne@68 69 .PP
jpayne@68 70 .B xz
jpayne@68 71 compresses or decompresses each
jpayne@68 72 .I file
jpayne@68 73 according to the selected operation mode.
jpayne@68 74 If no
jpayne@68 75 .I files
jpayne@68 76 are given or
jpayne@68 77 .I file
jpayne@68 78 is
jpayne@68 79 .BR \- ,
jpayne@68 80 .B xz
jpayne@68 81 reads from standard input and writes the processed data
jpayne@68 82 to standard output.
jpayne@68 83 .B xz
jpayne@68 84 will refuse (display an error and skip the
jpayne@68 85 .IR file )
jpayne@68 86 to write compressed data to standard output if it is a terminal.
jpayne@68 87 Similarly,
jpayne@68 88 .B xz
jpayne@68 89 will refuse to read compressed data
jpayne@68 90 from standard input if it is a terminal.
jpayne@68 91 .PP
jpayne@68 92 Unless
jpayne@68 93 .B \-\-stdout
jpayne@68 94 is specified,
jpayne@68 95 .I files
jpayne@68 96 other than
jpayne@68 97 .B \-
jpayne@68 98 are written to a new file whose name is derived from the source
jpayne@68 99 .I file
jpayne@68 100 name:
jpayne@68 101 .IP \(bu 3
jpayne@68 102 When compressing, the suffix of the target file format
jpayne@68 103 .RB ( .xz
jpayne@68 104 or
jpayne@68 105 .BR .lzma )
jpayne@68 106 is appended to the source filename to get the target filename.
jpayne@68 107 .IP \(bu 3
jpayne@68 108 When decompressing, the
jpayne@68 109 .BR .xz ,
jpayne@68 110 .BR .lzma ,
jpayne@68 111 or
jpayne@68 112 .B .lz
jpayne@68 113 suffix is removed from the filename to get the target filename.
jpayne@68 114 .B xz
jpayne@68 115 also recognizes the suffixes
jpayne@68 116 .B .txz
jpayne@68 117 and
jpayne@68 118 .BR .tlz ,
jpayne@68 119 and replaces them with the
jpayne@68 120 .B .tar
jpayne@68 121 suffix.
jpayne@68 122 .PP
jpayne@68 123 If the target file already exists, an error is displayed and the
jpayne@68 124 .I file
jpayne@68 125 is skipped.
jpayne@68 126 .PP
jpayne@68 127 Unless writing to standard output,
jpayne@68 128 .B xz
jpayne@68 129 will display a warning and skip the
jpayne@68 130 .I file
jpayne@68 131 if any of the following applies:
jpayne@68 132 .IP \(bu 3
jpayne@68 133 .I File
jpayne@68 134 is not a regular file.
jpayne@68 135 Symbolic links are not followed,
jpayne@68 136 and thus they are not considered to be regular files.
jpayne@68 137 .IP \(bu 3
jpayne@68 138 .I File
jpayne@68 139 has more than one hard link.
jpayne@68 140 .IP \(bu 3
jpayne@68 141 .I File
jpayne@68 142 has setuid, setgid, or sticky bit set.
jpayne@68 143 .IP \(bu 3
jpayne@68 144 The operation mode is set to compress and the
jpayne@68 145 .I file
jpayne@68 146 already has a suffix of the target file format
jpayne@68 147 .RB ( .xz
jpayne@68 148 or
jpayne@68 149 .B .txz
jpayne@68 150 when compressing to the
jpayne@68 151 .B .xz
jpayne@68 152 format, and
jpayne@68 153 .B .lzma
jpayne@68 154 or
jpayne@68 155 .B .tlz
jpayne@68 156 when compressing to the
jpayne@68 157 .B .lzma
jpayne@68 158 format).
jpayne@68 159 .IP \(bu 3
jpayne@68 160 The operation mode is set to decompress and the
jpayne@68 161 .I file
jpayne@68 162 doesn't have a suffix of any of the supported file formats
jpayne@68 163 .RB ( .xz ,
jpayne@68 164 .BR .txz ,
jpayne@68 165 .BR .lzma ,
jpayne@68 166 .BR .tlz ,
jpayne@68 167 or
jpayne@68 168 .BR .lz ).
jpayne@68 169 .PP
jpayne@68 170 After successfully compressing or decompressing the
jpayne@68 171 .IR file ,
jpayne@68 172 .B xz
jpayne@68 173 copies the owner, group, permissions, access time,
jpayne@68 174 and modification time from the source
jpayne@68 175 .I file
jpayne@68 176 to the target file.
jpayne@68 177 If copying the group fails, the permissions are modified
jpayne@68 178 so that the target file doesn't become accessible to users
jpayne@68 179 who didn't have permission to access the source
jpayne@68 180 .IR file .
jpayne@68 181 .B xz
jpayne@68 182 doesn't support copying other metadata like access control lists
jpayne@68 183 or extended attributes yet.
jpayne@68 184 .PP
jpayne@68 185 Once the target file has been successfully closed, the source
jpayne@68 186 .I file
jpayne@68 187 is removed unless
jpayne@68 188 .B \-\-keep
jpayne@68 189 was specified.
jpayne@68 190 The source
jpayne@68 191 .I file
jpayne@68 192 is never removed if the output is written to standard output
jpayne@68 193 or if an error occurs.
jpayne@68 194 .PP
jpayne@68 195 Sending
jpayne@68 196 .B SIGINFO
jpayne@68 197 or
jpayne@68 198 .B SIGUSR1
jpayne@68 199 to the
jpayne@68 200 .B xz
jpayne@68 201 process makes it print progress information to standard error.
jpayne@68 202 This has only limited use since when standard error
jpayne@68 203 is a terminal, using
jpayne@68 204 .B \-\-verbose
jpayne@68 205 will display an automatically updating progress indicator.
jpayne@68 206 .
jpayne@68 207 .SS "Memory usage"
jpayne@68 208 The memory usage of
jpayne@68 209 .B xz
jpayne@68 210 varies from a few hundred kilobytes to several gigabytes
jpayne@68 211 depending on the compression settings.
jpayne@68 212 The settings used when compressing a file determine
jpayne@68 213 the memory requirements of the decompressor.
jpayne@68 214 Typically the decompressor needs 5\ % to 20\ % of
jpayne@68 215 the amount of memory that the compressor needed when
jpayne@68 216 creating the file.
jpayne@68 217 For example, decompressing a file created with
jpayne@68 218 .B xz \-9
jpayne@68 219 currently requires 65\ MiB of memory.
jpayne@68 220 Still, it is possible to have
jpayne@68 221 .B .xz
jpayne@68 222 files that require several gigabytes of memory to decompress.
jpayne@68 223 .PP
jpayne@68 224 Especially users of older systems may find
jpayne@68 225 the possibility of very large memory usage annoying.
jpayne@68 226 To prevent uncomfortable surprises,
jpayne@68 227 .B xz
jpayne@68 228 has a built-in memory usage limiter, which is disabled by default.
jpayne@68 229 While some operating systems provide ways to limit
jpayne@68 230 the memory usage of processes, relying on it
jpayne@68 231 wasn't deemed to be flexible enough (for example, using
jpayne@68 232 .BR ulimit (1)
jpayne@68 233 to limit virtual memory tends to cripple
jpayne@68 234 .BR mmap (2)).
jpayne@68 235 .PP
jpayne@68 236 The memory usage limiter can be enabled with
jpayne@68 237 the command line option \fB\-\-memlimit=\fIlimit\fR.
jpayne@68 238 Often it is more convenient to enable the limiter
jpayne@68 239 by default by setting the environment variable
jpayne@68 240 .BR XZ_DEFAULTS ,
jpayne@68 241 for example,
jpayne@68 242 .BR XZ_DEFAULTS=\-\-memlimit=150MiB .
jpayne@68 243 It is possible to set the limits separately
jpayne@68 244 for compression and decompression by using
jpayne@68 245 .BI \-\-memlimit\-compress= limit
jpayne@68 246 and \fB\-\-memlimit\-decompress=\fIlimit\fR.
jpayne@68 247 Using these two options outside
jpayne@68 248 .B XZ_DEFAULTS
jpayne@68 249 is rarely useful because a single run of
jpayne@68 250 .B xz
jpayne@68 251 cannot do both compression and decompression and
jpayne@68 252 .BI \-\-memlimit= limit
jpayne@68 253 (or
jpayne@68 254 .B \-M
jpayne@68 255 .IR limit )
jpayne@68 256 is shorter to type on the command line.
jpayne@68 257 .PP
jpayne@68 258 If the specified memory usage limit is exceeded when decompressing,
jpayne@68 259 .B xz
jpayne@68 260 will display an error and decompressing the file will fail.
jpayne@68 261 If the limit is exceeded when compressing,
jpayne@68 262 .B xz
jpayne@68 263 will try to scale the settings down so that the limit
jpayne@68 264 is no longer exceeded (except when using
jpayne@68 265 .B \-\-format=raw
jpayne@68 266 or
jpayne@68 267 .BR \-\-no\-adjust ).
jpayne@68 268 This way the operation won't fail unless the limit is very small.
jpayne@68 269 The scaling of the settings is done in steps that don't
jpayne@68 270 match the compression level presets, for example, if the limit is
jpayne@68 271 only slightly less than the amount required for
jpayne@68 272 .BR "xz \-9" ,
jpayne@68 273 the settings will be scaled down only a little,
jpayne@68 274 not all the way down to
jpayne@68 275 .BR "xz \-8" .
jpayne@68 276 .
jpayne@68 277 .SS "Concatenation and padding with .xz files"
jpayne@68 278 It is possible to concatenate
jpayne@68 279 .B .xz
jpayne@68 280 files as is.
jpayne@68 281 .B xz
jpayne@68 282 will decompress such files as if they were a single
jpayne@68 283 .B .xz
jpayne@68 284 file.
jpayne@68 285 .PP
jpayne@68 286 It is possible to insert padding between the concatenated parts
jpayne@68 287 or after the last part.
jpayne@68 288 The padding must consist of null bytes and the size
jpayne@68 289 of the padding must be a multiple of four bytes.
jpayne@68 290 This can be useful, for example, if the
jpayne@68 291 .B .xz
jpayne@68 292 file is stored on a medium that measures file sizes
jpayne@68 293 in 512-byte blocks.
jpayne@68 294 .PP
jpayne@68 295 Concatenation and padding are not allowed with
jpayne@68 296 .B .lzma
jpayne@68 297 files or raw streams.
jpayne@68 298 .
jpayne@68 299 .SH OPTIONS
jpayne@68 300 .
jpayne@68 301 .SS "Integer suffixes and special values"
jpayne@68 302 In most places where an integer argument is expected,
jpayne@68 303 an optional suffix is supported to easily indicate large integers.
jpayne@68 304 There must be no space between the integer and the suffix.
jpayne@68 305 .TP
jpayne@68 306 .B KiB
jpayne@68 307 Multiply the integer by 1,024 (2^10).
jpayne@68 308 .BR Ki ,
jpayne@68 309 .BR k ,
jpayne@68 310 .BR kB ,
jpayne@68 311 .BR K ,
jpayne@68 312 and
jpayne@68 313 .B KB
jpayne@68 314 are accepted as synonyms for
jpayne@68 315 .BR KiB .
jpayne@68 316 .TP
jpayne@68 317 .B MiB
jpayne@68 318 Multiply the integer by 1,048,576 (2^20).
jpayne@68 319 .BR Mi ,
jpayne@68 320 .BR m ,
jpayne@68 321 .BR M ,
jpayne@68 322 and
jpayne@68 323 .B MB
jpayne@68 324 are accepted as synonyms for
jpayne@68 325 .BR MiB .
jpayne@68 326 .TP
jpayne@68 327 .B GiB
jpayne@68 328 Multiply the integer by 1,073,741,824 (2^30).
jpayne@68 329 .BR Gi ,
jpayne@68 330 .BR g ,
jpayne@68 331 .BR G ,
jpayne@68 332 and
jpayne@68 333 .B GB
jpayne@68 334 are accepted as synonyms for
jpayne@68 335 .BR GiB .
jpayne@68 336 .PP
jpayne@68 337 The special value
jpayne@68 338 .B max
jpayne@68 339 can be used to indicate the maximum integer value
jpayne@68 340 supported by the option.
jpayne@68 341 .
jpayne@68 342 .SS "Operation mode"
jpayne@68 343 If multiple operation mode options are given,
jpayne@68 344 the last one takes effect.
jpayne@68 345 .TP
jpayne@68 346 .BR \-z ", " \-\-compress
jpayne@68 347 Compress.
jpayne@68 348 This is the default operation mode when no operation mode option
jpayne@68 349 is specified and no other operation mode is implied from
jpayne@68 350 the command name (for example,
jpayne@68 351 .B unxz
jpayne@68 352 implies
jpayne@68 353 .BR \-\-decompress ).
jpayne@68 354 .IP ""
jpayne@68 355 .\" The DESCRIPTION section already says this but it's good to repeat it
jpayne@68 356 .\" here because the default behavior is a bit dangerous and new users
jpayne@68 357 .\" in a hurry may skip reading the DESCRIPTION section.
jpayne@68 358 After successful compression, the source file is removed
jpayne@68 359 unless writing to standard output or
jpayne@68 360 .B \-\-keep
jpayne@68 361 was specified.
jpayne@68 362 .TP
jpayne@68 363 .BR \-d ", " \-\-decompress ", " \-\-uncompress
jpayne@68 364 Decompress.
jpayne@68 365 .\" The DESCRIPTION section already says this but it's good to repeat it
jpayne@68 366 .\" here because the default behavior is a bit dangerous and new users
jpayne@68 367 .\" in a hurry may skip reading the DESCRIPTION section.
jpayne@68 368 After successful decompression, the source file is removed
jpayne@68 369 unless writing to standard output or
jpayne@68 370 .B \-\-keep
jpayne@68 371 was specified.
jpayne@68 372 .TP
jpayne@68 373 .BR \-t ", " \-\-test
jpayne@68 374 Test the integrity of compressed
jpayne@68 375 .IR files .
jpayne@68 376 This option is equivalent to
jpayne@68 377 .B "\-\-decompress \-\-stdout"
jpayne@68 378 except that the decompressed data is discarded instead of being
jpayne@68 379 written to standard output.
jpayne@68 380 No files are created or removed.
jpayne@68 381 .TP
jpayne@68 382 .BR \-l ", " \-\-list
jpayne@68 383 Print information about compressed
jpayne@68 384 .IR files .
jpayne@68 385 No uncompressed output is produced,
jpayne@68 386 and no files are created or removed.
jpayne@68 387 In list mode, the program cannot read
jpayne@68 388 the compressed data from standard
jpayne@68 389 input or from other unseekable sources.
jpayne@68 390 .IP ""
jpayne@68 391 The default listing shows basic information about
jpayne@68 392 .IR files ,
jpayne@68 393 one file per line.
jpayne@68 394 To get more detailed information, use also the
jpayne@68 395 .B \-\-verbose
jpayne@68 396 option.
jpayne@68 397 For even more information, use
jpayne@68 398 .B \-\-verbose
jpayne@68 399 twice, but note that this may be slow, because getting all the extra
jpayne@68 400 information requires many seeks.
jpayne@68 401 The width of verbose output exceeds
jpayne@68 402 80 characters, so piping the output to, for example,
jpayne@68 403 .B "less\ \-S"
jpayne@68 404 may be convenient if the terminal isn't wide enough.
jpayne@68 405 .IP ""
jpayne@68 406 The exact output may vary between
jpayne@68 407 .B xz
jpayne@68 408 versions and different locales.
jpayne@68 409 For machine-readable output,
jpayne@68 410 .B \-\-robot \-\-list
jpayne@68 411 should be used.
jpayne@68 412 .
jpayne@68 413 .SS "Operation modifiers"
jpayne@68 414 .TP
jpayne@68 415 .BR \-k ", " \-\-keep
jpayne@68 416 Don't delete the input files.
jpayne@68 417 .IP ""
jpayne@68 418 Since
jpayne@68 419 .B xz
jpayne@68 420 5.2.6,
jpayne@68 421 this option also makes
jpayne@68 422 .B xz
jpayne@68 423 compress or decompress even if the input is
jpayne@68 424 a symbolic link to a regular file,
jpayne@68 425 has more than one hard link,
jpayne@68 426 or has the setuid, setgid, or sticky bit set.
jpayne@68 427 The setuid, setgid, and sticky bits are not copied
jpayne@68 428 to the target file.
jpayne@68 429 In earlier versions this was only done with
jpayne@68 430 .BR \-\-force .
jpayne@68 431 .TP
jpayne@68 432 .BR \-f ", " \-\-force
jpayne@68 433 This option has several effects:
jpayne@68 434 .RS
jpayne@68 435 .IP \(bu 3
jpayne@68 436 If the target file already exists,
jpayne@68 437 delete it before compressing or decompressing.
jpayne@68 438 .IP \(bu 3
jpayne@68 439 Compress or decompress even if the input is
jpayne@68 440 a symbolic link to a regular file,
jpayne@68 441 has more than one hard link,
jpayne@68 442 or has the setuid, setgid, or sticky bit set.
jpayne@68 443 The setuid, setgid, and sticky bits are not copied
jpayne@68 444 to the target file.
jpayne@68 445 .IP \(bu 3
jpayne@68 446 When used with
jpayne@68 447 .B \-\-decompress
jpayne@68 448 .B \-\-stdout
jpayne@68 449 and
jpayne@68 450 .B xz
jpayne@68 451 cannot recognize the type of the source file,
jpayne@68 452 copy the source file as is to standard output.
jpayne@68 453 This allows
jpayne@68 454 .B xzcat
jpayne@68 455 .B \-\-force
jpayne@68 456 to be used like
jpayne@68 457 .BR cat (1)
jpayne@68 458 for files that have not been compressed with
jpayne@68 459 .BR xz .
jpayne@68 460 Note that in future,
jpayne@68 461 .B xz
jpayne@68 462 might support new compressed file formats, which may make
jpayne@68 463 .B xz
jpayne@68 464 decompress more types of files instead of copying them as is to
jpayne@68 465 standard output.
jpayne@68 466 .BI \-\-format= format
jpayne@68 467 can be used to restrict
jpayne@68 468 .B xz
jpayne@68 469 to decompress only a single file format.
jpayne@68 470 .RE
jpayne@68 471 .TP
jpayne@68 472 .BR \-c ", " \-\-stdout ", " \-\-to\-stdout
jpayne@68 473 Write the compressed or decompressed data to
jpayne@68 474 standard output instead of a file.
jpayne@68 475 This implies
jpayne@68 476 .BR \-\-keep .
jpayne@68 477 .TP
jpayne@68 478 .B \-\-single\-stream
jpayne@68 479 Decompress only the first
jpayne@68 480 .B .xz
jpayne@68 481 stream, and
jpayne@68 482 silently ignore possible remaining input data following the stream.
jpayne@68 483 Normally such trailing garbage makes
jpayne@68 484 .B xz
jpayne@68 485 display an error.
jpayne@68 486 .IP ""
jpayne@68 487 .B xz
jpayne@68 488 never decompresses more than one stream from
jpayne@68 489 .B .lzma
jpayne@68 490 files or raw streams, but this option still makes
jpayne@68 491 .B xz
jpayne@68 492 ignore the possible trailing data after the
jpayne@68 493 .B .lzma
jpayne@68 494 file or raw stream.
jpayne@68 495 .IP ""
jpayne@68 496 This option has no effect if the operation mode is not
jpayne@68 497 .B \-\-decompress
jpayne@68 498 or
jpayne@68 499 .BR \-\-test .
jpayne@68 500 .TP
jpayne@68 501 .B \-\-no\-sparse
jpayne@68 502 Disable creation of sparse files.
jpayne@68 503 By default, if decompressing into a regular file,
jpayne@68 504 .B xz
jpayne@68 505 tries to make the file sparse if the decompressed data contains
jpayne@68 506 long sequences of binary zeros.
jpayne@68 507 It also works when writing to standard output
jpayne@68 508 as long as standard output is connected to a regular file
jpayne@68 509 and certain additional conditions are met to make it safe.
jpayne@68 510 Creating sparse files may save disk space and speed up
jpayne@68 511 the decompression by reducing the amount of disk I/O.
jpayne@68 512 .TP
jpayne@68 513 \fB\-S\fR \fI.suf\fR, \fB\-\-suffix=\fI.suf
jpayne@68 514 When compressing, use
jpayne@68 515 .I .suf
jpayne@68 516 as the suffix for the target file instead of
jpayne@68 517 .B .xz
jpayne@68 518 or
jpayne@68 519 .BR .lzma .
jpayne@68 520 If not writing to standard output and
jpayne@68 521 the source file already has the suffix
jpayne@68 522 .IR .suf ,
jpayne@68 523 a warning is displayed and the file is skipped.
jpayne@68 524 .IP ""
jpayne@68 525 When decompressing, recognize files with the suffix
jpayne@68 526 .I .suf
jpayne@68 527 in addition to files with the
jpayne@68 528 .BR .xz ,
jpayne@68 529 .BR .txz ,
jpayne@68 530 .BR .lzma ,
jpayne@68 531 .BR .tlz ,
jpayne@68 532 or
jpayne@68 533 .B .lz
jpayne@68 534 suffix.
jpayne@68 535 If the source file has the suffix
jpayne@68 536 .IR .suf ,
jpayne@68 537 the suffix is removed to get the target filename.
jpayne@68 538 .IP ""
jpayne@68 539 When compressing or decompressing raw streams
jpayne@68 540 .RB ( \-\-format=raw ),
jpayne@68 541 the suffix must always be specified unless
jpayne@68 542 writing to standard output,
jpayne@68 543 because there is no default suffix for raw streams.
jpayne@68 544 .TP
jpayne@68 545 \fB\-\-files\fR[\fB=\fIfile\fR]
jpayne@68 546 Read the filenames to process from
jpayne@68 547 .IR file ;
jpayne@68 548 if
jpayne@68 549 .I file
jpayne@68 550 is omitted, filenames are read from standard input.
jpayne@68 551 Filenames must be terminated with the newline character.
jpayne@68 552 A dash
jpayne@68 553 .RB ( \- )
jpayne@68 554 is taken as a regular filename; it doesn't mean standard input.
jpayne@68 555 If filenames are given also as command line arguments, they are
jpayne@68 556 processed before the filenames read from
jpayne@68 557 .IR file .
jpayne@68 558 .TP
jpayne@68 559 \fB\-\-files0\fR[\fB=\fIfile\fR]
jpayne@68 560 This is identical to \fB\-\-files\fR[\fB=\fIfile\fR] except
jpayne@68 561 that each filename must be terminated with the null character.
jpayne@68 562 .
jpayne@68 563 .SS "Basic file format and compression options"
jpayne@68 564 .TP
jpayne@68 565 \fB\-F\fR \fIformat\fR, \fB\-\-format=\fIformat
jpayne@68 566 Specify the file
jpayne@68 567 .I format
jpayne@68 568 to compress or decompress:
jpayne@68 569 .RS
jpayne@68 570 .TP
jpayne@68 571 .B auto
jpayne@68 572 This is the default.
jpayne@68 573 When compressing,
jpayne@68 574 .B auto
jpayne@68 575 is equivalent to
jpayne@68 576 .BR xz .
jpayne@68 577 When decompressing,
jpayne@68 578 the format of the input file is automatically detected.
jpayne@68 579 Note that raw streams (created with
jpayne@68 580 .BR \-\-format=raw )
jpayne@68 581 cannot be auto-detected.
jpayne@68 582 .TP
jpayne@68 583 .B xz
jpayne@68 584 Compress to the
jpayne@68 585 .B .xz
jpayne@68 586 file format, or accept only
jpayne@68 587 .B .xz
jpayne@68 588 files when decompressing.
jpayne@68 589 .TP
jpayne@68 590 .BR lzma ", " alone
jpayne@68 591 Compress to the legacy
jpayne@68 592 .B .lzma
jpayne@68 593 file format, or accept only
jpayne@68 594 .B .lzma
jpayne@68 595 files when decompressing.
jpayne@68 596 The alternative name
jpayne@68 597 .B alone
jpayne@68 598 is provided for backwards compatibility with LZMA Utils.
jpayne@68 599 .TP
jpayne@68 600 .B lzip
jpayne@68 601 Accept only
jpayne@68 602 .B .lz
jpayne@68 603 files when decompressing.
jpayne@68 604 Compression is not supported.
jpayne@68 605 .IP ""
jpayne@68 606 The
jpayne@68 607 .B .lz
jpayne@68 608 format version 0 and the unextended version 1 are supported.
jpayne@68 609 Version 0 files were produced by
jpayne@68 610 .B lzip
jpayne@68 611 1.3 and older.
jpayne@68 612 Such files aren't common but may be found from file archives
jpayne@68 613 as a few source packages were released in this format.
jpayne@68 614 People might have old personal files in this format too.
jpayne@68 615 Decompression support for the format version 0 was removed in
jpayne@68 616 .B lzip
jpayne@68 617 1.18.
jpayne@68 618 .IP ""
jpayne@68 619 .B lzip
jpayne@68 620 1.4 and later create files in the format version 1.
jpayne@68 621 The sync flush marker extension to the format version 1 was added in
jpayne@68 622 .B lzip
jpayne@68 623 1.6.
jpayne@68 624 This extension is rarely used and isn't supported by
jpayne@68 625 .B xz
jpayne@68 626 (diagnosed as corrupt input).
jpayne@68 627 .TP
jpayne@68 628 .B raw
jpayne@68 629 Compress or uncompress a raw stream (no headers).
jpayne@68 630 This is meant for advanced users only.
jpayne@68 631 To decode raw streams, you need use
jpayne@68 632 .B \-\-format=raw
jpayne@68 633 and explicitly specify the filter chain,
jpayne@68 634 which normally would have been stored in the container headers.
jpayne@68 635 .RE
jpayne@68 636 .TP
jpayne@68 637 \fB\-C\fR \fIcheck\fR, \fB\-\-check=\fIcheck
jpayne@68 638 Specify the type of the integrity check.
jpayne@68 639 The check is calculated from the uncompressed data and
jpayne@68 640 stored in the
jpayne@68 641 .B .xz
jpayne@68 642 file.
jpayne@68 643 This option has an effect only when compressing into the
jpayne@68 644 .B .xz
jpayne@68 645 format; the
jpayne@68 646 .B .lzma
jpayne@68 647 format doesn't support integrity checks.
jpayne@68 648 The integrity check (if any) is verified when the
jpayne@68 649 .B .xz
jpayne@68 650 file is decompressed.
jpayne@68 651 .IP ""
jpayne@68 652 Supported
jpayne@68 653 .I check
jpayne@68 654 types:
jpayne@68 655 .RS
jpayne@68 656 .TP
jpayne@68 657 .B none
jpayne@68 658 Don't calculate an integrity check at all.
jpayne@68 659 This is usually a bad idea.
jpayne@68 660 This can be useful when integrity of the data is verified
jpayne@68 661 by other means anyway.
jpayne@68 662 .TP
jpayne@68 663 .B crc32
jpayne@68 664 Calculate CRC32 using the polynomial from IEEE-802.3 (Ethernet).
jpayne@68 665 .TP
jpayne@68 666 .B crc64
jpayne@68 667 Calculate CRC64 using the polynomial from ECMA-182.
jpayne@68 668 This is the default, since it is slightly better than CRC32
jpayne@68 669 at detecting damaged files and the speed difference is negligible.
jpayne@68 670 .TP
jpayne@68 671 .B sha256
jpayne@68 672 Calculate SHA-256.
jpayne@68 673 This is somewhat slower than CRC32 and CRC64.
jpayne@68 674 .RE
jpayne@68 675 .IP ""
jpayne@68 676 Integrity of the
jpayne@68 677 .B .xz
jpayne@68 678 headers is always verified with CRC32.
jpayne@68 679 It is not possible to change or disable it.
jpayne@68 680 .TP
jpayne@68 681 .B \-\-ignore\-check
jpayne@68 682 Don't verify the integrity check of the compressed data when decompressing.
jpayne@68 683 The CRC32 values in the
jpayne@68 684 .B .xz
jpayne@68 685 headers will still be verified normally.
jpayne@68 686 .IP ""
jpayne@68 687 .B "Do not use this option unless you know what you are doing."
jpayne@68 688 Possible reasons to use this option:
jpayne@68 689 .RS
jpayne@68 690 .IP \(bu 3
jpayne@68 691 Trying to recover data from a corrupt .xz file.
jpayne@68 692 .IP \(bu 3
jpayne@68 693 Speeding up decompression.
jpayne@68 694 This matters mostly with SHA-256 or
jpayne@68 695 with files that have compressed extremely well.
jpayne@68 696 It's recommended to not use this option for this purpose
jpayne@68 697 unless the file integrity is verified externally in some other way.
jpayne@68 698 .RE
jpayne@68 699 .TP
jpayne@68 700 .BR \-0 " ... " \-9
jpayne@68 701 Select a compression preset level.
jpayne@68 702 The default is
jpayne@68 703 .BR \-6 .
jpayne@68 704 If multiple preset levels are specified,
jpayne@68 705 the last one takes effect.
jpayne@68 706 If a custom filter chain was already specified, setting
jpayne@68 707 a compression preset level clears the custom filter chain.
jpayne@68 708 .IP ""
jpayne@68 709 The differences between the presets are more significant than with
jpayne@68 710 .BR gzip (1)
jpayne@68 711 and
jpayne@68 712 .BR bzip2 (1).
jpayne@68 713 The selected compression settings determine
jpayne@68 714 the memory requirements of the decompressor,
jpayne@68 715 thus using a too high preset level might make it painful
jpayne@68 716 to decompress the file on an old system with little RAM.
jpayne@68 717 Specifically,
jpayne@68 718 .B "it's not a good idea to blindly use \-9 for everything"
jpayne@68 719 like it often is with
jpayne@68 720 .BR gzip (1)
jpayne@68 721 and
jpayne@68 722 .BR bzip2 (1).
jpayne@68 723 .RS
jpayne@68 724 .TP
jpayne@68 725 .BR "\-0" " ... " "\-3"
jpayne@68 726 These are somewhat fast presets.
jpayne@68 727 .B \-0
jpayne@68 728 is sometimes faster than
jpayne@68 729 .B "gzip \-9"
jpayne@68 730 while compressing much better.
jpayne@68 731 The higher ones often have speed comparable to
jpayne@68 732 .BR bzip2 (1)
jpayne@68 733 with comparable or better compression ratio,
jpayne@68 734 although the results
jpayne@68 735 depend a lot on the type of data being compressed.
jpayne@68 736 .TP
jpayne@68 737 .BR "\-4" " ... " "\-6"
jpayne@68 738 Good to very good compression while keeping
jpayne@68 739 decompressor memory usage reasonable even for old systems.
jpayne@68 740 .B \-6
jpayne@68 741 is the default, which is usually a good choice
jpayne@68 742 for distributing files that need to be decompressible
jpayne@68 743 even on systems with only 16\ MiB RAM.
jpayne@68 744 .RB ( \-5e
jpayne@68 745 or
jpayne@68 746 .B \-6e
jpayne@68 747 may be worth considering too.
jpayne@68 748 See
jpayne@68 749 .BR \-\-extreme .)
jpayne@68 750 .TP
jpayne@68 751 .B "\-7 ... \-9"
jpayne@68 752 These are like
jpayne@68 753 .B \-6
jpayne@68 754 but with higher compressor and decompressor memory requirements.
jpayne@68 755 These are useful only when compressing files bigger than
jpayne@68 756 8\ MiB, 16\ MiB, and 32\ MiB, respectively.
jpayne@68 757 .RE
jpayne@68 758 .IP ""
jpayne@68 759 On the same hardware, the decompression speed is approximately
jpayne@68 760 a constant number of bytes of compressed data per second.
jpayne@68 761 In other words, the better the compression,
jpayne@68 762 the faster the decompression will usually be.
jpayne@68 763 This also means that the amount of uncompressed output
jpayne@68 764 produced per second can vary a lot.
jpayne@68 765 .IP ""
jpayne@68 766 The following table summarises the features of the presets:
jpayne@68 767 .RS
jpayne@68 768 .RS
jpayne@68 769 .PP
jpayne@68 770 .TS
jpayne@68 771 tab(;);
jpayne@68 772 c c c c c
jpayne@68 773 n n n n n.
jpayne@68 774 Preset;DictSize;CompCPU;CompMem;DecMem
jpayne@68 775 \-0;256 KiB;0;3 MiB;1 MiB
jpayne@68 776 \-1;1 MiB;1;9 MiB;2 MiB
jpayne@68 777 \-2;2 MiB;2;17 MiB;3 MiB
jpayne@68 778 \-3;4 MiB;3;32 MiB;5 MiB
jpayne@68 779 \-4;4 MiB;4;48 MiB;5 MiB
jpayne@68 780 \-5;8 MiB;5;94 MiB;9 MiB
jpayne@68 781 \-6;8 MiB;6;94 MiB;9 MiB
jpayne@68 782 \-7;16 MiB;6;186 MiB;17 MiB
jpayne@68 783 \-8;32 MiB;6;370 MiB;33 MiB
jpayne@68 784 \-9;64 MiB;6;674 MiB;65 MiB
jpayne@68 785 .TE
jpayne@68 786 .RE
jpayne@68 787 .RE
jpayne@68 788 .IP ""
jpayne@68 789 Column descriptions:
jpayne@68 790 .RS
jpayne@68 791 .IP \(bu 3
jpayne@68 792 DictSize is the LZMA2 dictionary size.
jpayne@68 793 It is waste of memory to use a dictionary bigger than
jpayne@68 794 the size of the uncompressed file.
jpayne@68 795 This is why it is good to avoid using the presets
jpayne@68 796 .BR \-7 " ... " \-9
jpayne@68 797 when there's no real need for them.
jpayne@68 798 At
jpayne@68 799 .B \-6
jpayne@68 800 and lower, the amount of memory wasted is
jpayne@68 801 usually low enough to not matter.
jpayne@68 802 .IP \(bu 3
jpayne@68 803 CompCPU is a simplified representation of the LZMA2 settings
jpayne@68 804 that affect compression speed.
jpayne@68 805 The dictionary size affects speed too,
jpayne@68 806 so while CompCPU is the same for levels
jpayne@68 807 .BR \-6 " ... " \-9 ,
jpayne@68 808 higher levels still tend to be a little slower.
jpayne@68 809 To get even slower and thus possibly better compression, see
jpayne@68 810 .BR \-\-extreme .
jpayne@68 811 .IP \(bu 3
jpayne@68 812 CompMem contains the compressor memory requirements
jpayne@68 813 in the single-threaded mode.
jpayne@68 814 It may vary slightly between
jpayne@68 815 .B xz
jpayne@68 816 versions.
jpayne@68 817 .IP \(bu 3
jpayne@68 818 DecMem contains the decompressor memory requirements.
jpayne@68 819 That is, the compression settings determine
jpayne@68 820 the memory requirements of the decompressor.
jpayne@68 821 The exact decompressor memory usage is slightly more than
jpayne@68 822 the LZMA2 dictionary size, but the values in the table
jpayne@68 823 have been rounded up to the next full MiB.
jpayne@68 824 .RE
jpayne@68 825 .IP ""
jpayne@68 826 Memory requirements of the multi-threaded mode are
jpayne@68 827 significantly higher than that of the single-threaded mode.
jpayne@68 828 With the default value of
jpayne@68 829 .BR \-\-block\-size ,
jpayne@68 830 each thread needs 3*3*DictSize plus CompMem or DecMem.
jpayne@68 831 For example, four threads with preset
jpayne@68 832 .B \-6
jpayne@68 833 needs 660\(en670\ MiB of memory.
jpayne@68 834 .TP
jpayne@68 835 .BR \-e ", " \-\-extreme
jpayne@68 836 Use a slower variant of the selected compression preset level
jpayne@68 837 .RB ( \-0 " ... " \-9 )
jpayne@68 838 to hopefully get a little bit better compression ratio,
jpayne@68 839 but with bad luck this can also make it worse.
jpayne@68 840 Decompressor memory usage is not affected,
jpayne@68 841 but compressor memory usage increases a little at preset levels
jpayne@68 842 .BR \-0 " ... " \-3 .
jpayne@68 843 .IP ""
jpayne@68 844 Since there are two presets with dictionary sizes
jpayne@68 845 4\ MiB and 8\ MiB, the presets
jpayne@68 846 .B \-3e
jpayne@68 847 and
jpayne@68 848 .B \-5e
jpayne@68 849 use slightly faster settings (lower CompCPU) than
jpayne@68 850 .B \-4e
jpayne@68 851 and
jpayne@68 852 .BR \-6e ,
jpayne@68 853 respectively.
jpayne@68 854 That way no two presets are identical.
jpayne@68 855 .RS
jpayne@68 856 .RS
jpayne@68 857 .PP
jpayne@68 858 .TS
jpayne@68 859 tab(;);
jpayne@68 860 c c c c c
jpayne@68 861 n n n n n.
jpayne@68 862 Preset;DictSize;CompCPU;CompMem;DecMem
jpayne@68 863 \-0e;256 KiB;8;4 MiB;1 MiB
jpayne@68 864 \-1e;1 MiB;8;13 MiB;2 MiB
jpayne@68 865 \-2e;2 MiB;8;25 MiB;3 MiB
jpayne@68 866 \-3e;4 MiB;7;48 MiB;5 MiB
jpayne@68 867 \-4e;4 MiB;8;48 MiB;5 MiB
jpayne@68 868 \-5e;8 MiB;7;94 MiB;9 MiB
jpayne@68 869 \-6e;8 MiB;8;94 MiB;9 MiB
jpayne@68 870 \-7e;16 MiB;8;186 MiB;17 MiB
jpayne@68 871 \-8e;32 MiB;8;370 MiB;33 MiB
jpayne@68 872 \-9e;64 MiB;8;674 MiB;65 MiB
jpayne@68 873 .TE
jpayne@68 874 .RE
jpayne@68 875 .RE
jpayne@68 876 .IP ""
jpayne@68 877 For example, there are a total of four presets that use
jpayne@68 878 8\ MiB dictionary, whose order from the fastest to the slowest is
jpayne@68 879 .BR \-5 ,
jpayne@68 880 .BR \-6 ,
jpayne@68 881 .BR \-5e ,
jpayne@68 882 and
jpayne@68 883 .BR \-6e .
jpayne@68 884 .TP
jpayne@68 885 .B \-\-fast
jpayne@68 886 .PD 0
jpayne@68 887 .TP
jpayne@68 888 .B \-\-best
jpayne@68 889 .PD
jpayne@68 890 These are somewhat misleading aliases for
jpayne@68 891 .B \-0
jpayne@68 892 and
jpayne@68 893 .BR \-9 ,
jpayne@68 894 respectively.
jpayne@68 895 These are provided only for backwards compatibility
jpayne@68 896 with LZMA Utils.
jpayne@68 897 Avoid using these options.
jpayne@68 898 .TP
jpayne@68 899 .BI \-\-block\-size= size
jpayne@68 900 When compressing to the
jpayne@68 901 .B .xz
jpayne@68 902 format, split the input data into blocks of
jpayne@68 903 .I size
jpayne@68 904 bytes.
jpayne@68 905 The blocks are compressed independently from each other,
jpayne@68 906 which helps with multi-threading and
jpayne@68 907 makes limited random-access decompression possible.
jpayne@68 908 This option is typically used to override the default
jpayne@68 909 block size in multi-threaded mode,
jpayne@68 910 but this option can be used in single-threaded mode too.
jpayne@68 911 .IP ""
jpayne@68 912 In multi-threaded mode about three times
jpayne@68 913 .I size
jpayne@68 914 bytes will be allocated in each thread for buffering input and output.
jpayne@68 915 The default
jpayne@68 916 .I size
jpayne@68 917 is three times the LZMA2 dictionary size or 1 MiB,
jpayne@68 918 whichever is more.
jpayne@68 919 Typically a good value is 2\(en4 times
jpayne@68 920 the size of the LZMA2 dictionary or at least 1 MiB.
jpayne@68 921 Using
jpayne@68 922 .I size
jpayne@68 923 less than the LZMA2 dictionary size is waste of RAM
jpayne@68 924 because then the LZMA2 dictionary buffer will never get fully used.
jpayne@68 925 In multi-threaded mode,
jpayne@68 926 the sizes of the blocks are stored in the block headers.
jpayne@68 927 This size information is required for multi-threaded decompression.
jpayne@68 928 .IP ""
jpayne@68 929 In single-threaded mode no block splitting is done by default.
jpayne@68 930 Setting this option doesn't affect memory usage.
jpayne@68 931 No size information is stored in block headers,
jpayne@68 932 thus files created in single-threaded mode
jpayne@68 933 won't be identical to files created in multi-threaded mode.
jpayne@68 934 The lack of size information also means that
jpayne@68 935 .B xz
jpayne@68 936 won't be able decompress the files in multi-threaded mode.
jpayne@68 937 .TP
jpayne@68 938 .BI \-\-block\-list= items
jpayne@68 939 When compressing to the
jpayne@68 940 .B .xz
jpayne@68 941 format, start a new block with an optional custom filter chain after
jpayne@68 942 the given intervals of uncompressed data.
jpayne@68 943 .IP ""
jpayne@68 944 The
jpayne@68 945 .I items
jpayne@68 946 are a comma-separated list.
jpayne@68 947 Each item consists of an optional filter chain number
jpayne@68 948 between 0 and 9 followed by a colon
jpayne@68 949 .RB ( : )
jpayne@68 950 and a required size of uncompressed data.
jpayne@68 951 Omitting an item (two or more consecutive commas) is a
jpayne@68 952 shorthand to use the size and filters of the previous item.
jpayne@68 953 .IP ""
jpayne@68 954 If the input file is bigger than the sum of
jpayne@68 955 the sizes in
jpayne@68 956 .IR items ,
jpayne@68 957 the last item is repeated until the end of the file.
jpayne@68 958 A special value of
jpayne@68 959 .B 0
jpayne@68 960 may be used as the last size to indicate that
jpayne@68 961 the rest of the file should be encoded as a single block.
jpayne@68 962 .IP ""
jpayne@68 963 An alternative filter chain for each block can be
jpayne@68 964 specified in combination with the
jpayne@68 965 .BI \-\-filters1= filters
jpayne@68 966 \&...\&
jpayne@68 967 .BI \-\-filters9= filters
jpayne@68 968 options.
jpayne@68 969 These options define filter chains with an identifier
jpayne@68 970 between 1\(en9.
jpayne@68 971 Filter chain 0 can be used to refer to the default filter chain,
jpayne@68 972 which is the same as not specifying a filter chain.
jpayne@68 973 The filter chain identifier can be used before the uncompressed
jpayne@68 974 size, followed by a colon
jpayne@68 975 .RB ( : ).
jpayne@68 976 For example, if one specifies
jpayne@68 977 .B \-\-block\-list=1:2MiB,3:2MiB,2:4MiB,,2MiB,0:4MiB
jpayne@68 978 then blocks will be created using:
jpayne@68 979 .RS
jpayne@68 980 .IP \(bu 3
jpayne@68 981 The filter chain specified by
jpayne@68 982 .B \-\-filters1
jpayne@68 983 and 2 MiB input
jpayne@68 984 .IP \(bu 3
jpayne@68 985 The filter chain specified by
jpayne@68 986 .B \-\-filters3
jpayne@68 987 and 2 MiB input
jpayne@68 988 .IP \(bu 3
jpayne@68 989 The filter chain specified by
jpayne@68 990 .B \-\-filters2
jpayne@68 991 and 4 MiB input
jpayne@68 992 .IP \(bu 3
jpayne@68 993 The filter chain specified by
jpayne@68 994 .B \-\-filters2
jpayne@68 995 and 4 MiB input
jpayne@68 996 .IP \(bu 3
jpayne@68 997 The default filter chain and 2 MiB input
jpayne@68 998 .IP \(bu 3
jpayne@68 999 The default filter chain and 4 MiB input for every block until
jpayne@68 1000 end of input.
jpayne@68 1001 .RE
jpayne@68 1002 .IP ""
jpayne@68 1003 If one specifies a size that exceeds the encoder's block size
jpayne@68 1004 (either the default value in threaded mode or
jpayne@68 1005 the value specified with \fB\-\-block\-size=\fIsize\fR),
jpayne@68 1006 the encoder will create additional blocks while
jpayne@68 1007 keeping the boundaries specified in
jpayne@68 1008 .IR items .
jpayne@68 1009 For example, if one specifies
jpayne@68 1010 .B \-\-block\-size=10MiB
jpayne@68 1011 .B \-\-block\-list=5MiB,10MiB,8MiB,12MiB,24MiB
jpayne@68 1012 and the input file is 80 MiB,
jpayne@68 1013 one will get 11 blocks:
jpayne@68 1014 5, 10, 8, 10, 2, 10, 10, 4, 10, 10, and 1 MiB.
jpayne@68 1015 .IP ""
jpayne@68 1016 In multi-threaded mode the sizes of the blocks
jpayne@68 1017 are stored in the block headers.
jpayne@68 1018 This isn't done in single-threaded mode,
jpayne@68 1019 so the encoded output won't be
jpayne@68 1020 identical to that of the multi-threaded mode.
jpayne@68 1021 .TP
jpayne@68 1022 .BI \-\-flush\-timeout= timeout
jpayne@68 1023 When compressing, if more than
jpayne@68 1024 .I timeout
jpayne@68 1025 milliseconds (a positive integer) has passed since the previous flush and
jpayne@68 1026 reading more input would block,
jpayne@68 1027 all the pending input data is flushed from the encoder and
jpayne@68 1028 made available in the output stream.
jpayne@68 1029 This can be useful if
jpayne@68 1030 .B xz
jpayne@68 1031 is used to compress data that is streamed over a network.
jpayne@68 1032 Small
jpayne@68 1033 .I timeout
jpayne@68 1034 values make the data available at the receiving end
jpayne@68 1035 with a small delay, but large
jpayne@68 1036 .I timeout
jpayne@68 1037 values give better compression ratio.
jpayne@68 1038 .IP ""
jpayne@68 1039 This feature is disabled by default.
jpayne@68 1040 If this option is specified more than once, the last one takes effect.
jpayne@68 1041 The special
jpayne@68 1042 .I timeout
jpayne@68 1043 value of
jpayne@68 1044 .B 0
jpayne@68 1045 can be used to explicitly disable this feature.
jpayne@68 1046 .IP ""
jpayne@68 1047 This feature is not available on non-POSIX systems.
jpayne@68 1048 .IP ""
jpayne@68 1049 .\" FIXME
jpayne@68 1050 .B "This feature is still experimental."
jpayne@68 1051 Currently
jpayne@68 1052 .B xz
jpayne@68 1053 is unsuitable for decompressing the stream in real time due to how
jpayne@68 1054 .B xz
jpayne@68 1055 does buffering.
jpayne@68 1056 .TP
jpayne@68 1057 .BI \-\-memlimit\-compress= limit
jpayne@68 1058 Set a memory usage limit for compression.
jpayne@68 1059 If this option is specified multiple times,
jpayne@68 1060 the last one takes effect.
jpayne@68 1061 .IP ""
jpayne@68 1062 If the compression settings exceed the
jpayne@68 1063 .IR limit ,
jpayne@68 1064 .B xz
jpayne@68 1065 will attempt to adjust the settings downwards so that
jpayne@68 1066 the limit is no longer exceeded and display a notice that
jpayne@68 1067 automatic adjustment was done.
jpayne@68 1068 The adjustments are done in this order:
jpayne@68 1069 reducing the number of threads,
jpayne@68 1070 switching to single-threaded mode
jpayne@68 1071 if even one thread in multi-threaded mode exceeds the
jpayne@68 1072 .IR limit ,
jpayne@68 1073 and finally reducing the LZMA2 dictionary size.
jpayne@68 1074 .IP ""
jpayne@68 1075 When compressing with
jpayne@68 1076 .B \-\-format=raw
jpayne@68 1077 or if
jpayne@68 1078 .B \-\-no\-adjust
jpayne@68 1079 has been specified,
jpayne@68 1080 only the number of threads may be reduced
jpayne@68 1081 since it can be done without affecting the compressed output.
jpayne@68 1082 .IP ""
jpayne@68 1083 If the
jpayne@68 1084 .I limit
jpayne@68 1085 cannot be met even with the adjustments described above,
jpayne@68 1086 an error is displayed and
jpayne@68 1087 .B xz
jpayne@68 1088 will exit with exit status 1.
jpayne@68 1089 .IP ""
jpayne@68 1090 The
jpayne@68 1091 .I limit
jpayne@68 1092 can be specified in multiple ways:
jpayne@68 1093 .RS
jpayne@68 1094 .IP \(bu 3
jpayne@68 1095 The
jpayne@68 1096 .I limit
jpayne@68 1097 can be an absolute value in bytes.
jpayne@68 1098 Using an integer suffix like
jpayne@68 1099 .B MiB
jpayne@68 1100 can be useful.
jpayne@68 1101 Example:
jpayne@68 1102 .B "\-\-memlimit\-compress=80MiB"
jpayne@68 1103 .IP \(bu 3
jpayne@68 1104 The
jpayne@68 1105 .I limit
jpayne@68 1106 can be specified as a percentage of total physical memory (RAM).
jpayne@68 1107 This can be useful especially when setting the
jpayne@68 1108 .B XZ_DEFAULTS
jpayne@68 1109 environment variable in a shell initialization script
jpayne@68 1110 that is shared between different computers.
jpayne@68 1111 That way the limit is automatically bigger
jpayne@68 1112 on systems with more memory.
jpayne@68 1113 Example:
jpayne@68 1114 .B "\-\-memlimit\-compress=70%"
jpayne@68 1115 .IP \(bu 3
jpayne@68 1116 The
jpayne@68 1117 .I limit
jpayne@68 1118 can be reset back to its default value by setting it to
jpayne@68 1119 .BR 0 .
jpayne@68 1120 This is currently equivalent to setting the
jpayne@68 1121 .I limit
jpayne@68 1122 to
jpayne@68 1123 .B max
jpayne@68 1124 (no memory usage limit).
jpayne@68 1125 .RE
jpayne@68 1126 .IP ""
jpayne@68 1127 For 32-bit
jpayne@68 1128 .B xz
jpayne@68 1129 there is a special case: if the
jpayne@68 1130 .I limit
jpayne@68 1131 would be over
jpayne@68 1132 .BR "4020\ MiB" ,
jpayne@68 1133 the
jpayne@68 1134 .I limit
jpayne@68 1135 is set to
jpayne@68 1136 .BR "4020\ MiB" .
jpayne@68 1137 On MIPS32
jpayne@68 1138 .B "2000\ MiB"
jpayne@68 1139 is used instead.
jpayne@68 1140 (The values
jpayne@68 1141 .B 0
jpayne@68 1142 and
jpayne@68 1143 .B max
jpayne@68 1144 aren't affected by this.
jpayne@68 1145 A similar feature doesn't exist for decompression.)
jpayne@68 1146 This can be helpful when a 32-bit executable has access
jpayne@68 1147 to 4\ GiB address space (2 GiB on MIPS32)
jpayne@68 1148 while hopefully doing no harm in other situations.
jpayne@68 1149 .IP ""
jpayne@68 1150 See also the section
jpayne@68 1151 .BR "Memory usage" .
jpayne@68 1152 .TP
jpayne@68 1153 .BI \-\-memlimit\-decompress= limit
jpayne@68 1154 Set a memory usage limit for decompression.
jpayne@68 1155 This also affects the
jpayne@68 1156 .B \-\-list
jpayne@68 1157 mode.
jpayne@68 1158 If the operation is not possible without exceeding the
jpayne@68 1159 .IR limit ,
jpayne@68 1160 .B xz
jpayne@68 1161 will display an error and decompressing the file will fail.
jpayne@68 1162 See
jpayne@68 1163 .BI \-\-memlimit\-compress= limit
jpayne@68 1164 for possible ways to specify the
jpayne@68 1165 .IR limit .
jpayne@68 1166 .TP
jpayne@68 1167 .BI \-\-memlimit\-mt\-decompress= limit
jpayne@68 1168 Set a memory usage limit for multi-threaded decompression.
jpayne@68 1169 This can only affect the number of threads;
jpayne@68 1170 this will never make
jpayne@68 1171 .B xz
jpayne@68 1172 refuse to decompress a file.
jpayne@68 1173 If
jpayne@68 1174 .I limit
jpayne@68 1175 is too low to allow any multi-threading, the
jpayne@68 1176 .I limit
jpayne@68 1177 is ignored and
jpayne@68 1178 .B xz
jpayne@68 1179 will continue in single-threaded mode.
jpayne@68 1180 Note that if also
jpayne@68 1181 .B \-\-memlimit\-decompress
jpayne@68 1182 is used,
jpayne@68 1183 it will always apply to both single-threaded and multi-threaded modes,
jpayne@68 1184 and so the effective
jpayne@68 1185 .I limit
jpayne@68 1186 for multi-threading will never be higher than the limit set with
jpayne@68 1187 .BR \-\-memlimit\-decompress .
jpayne@68 1188 .IP ""
jpayne@68 1189 In contrast to the other memory usage limit options,
jpayne@68 1190 .BI \-\-memlimit\-mt\-decompress= limit
jpayne@68 1191 has a system-specific default
jpayne@68 1192 .IR limit .
jpayne@68 1193 .B "xz \-\-info\-memory"
jpayne@68 1194 can be used to see the current value.
jpayne@68 1195 .IP ""
jpayne@68 1196 This option and its default value exist
jpayne@68 1197 because without any limit the threaded decompressor
jpayne@68 1198 could end up allocating an insane amount of memory with some input files.
jpayne@68 1199 If the default
jpayne@68 1200 .I limit
jpayne@68 1201 is too low on your system,
jpayne@68 1202 feel free to increase the
jpayne@68 1203 .I limit
jpayne@68 1204 but never set it to a value larger than the amount of usable RAM
jpayne@68 1205 as with appropriate input files
jpayne@68 1206 .B xz
jpayne@68 1207 will attempt to use that amount of memory
jpayne@68 1208 even with a low number of threads.
jpayne@68 1209 Running out of memory or swapping
jpayne@68 1210 will not improve decompression performance.
jpayne@68 1211 .IP ""
jpayne@68 1212 See
jpayne@68 1213 .BI \-\-memlimit\-compress= limit
jpayne@68 1214 for possible ways to specify the
jpayne@68 1215 .IR limit .
jpayne@68 1216 Setting
jpayne@68 1217 .I limit
jpayne@68 1218 to
jpayne@68 1219 .B 0
jpayne@68 1220 resets the
jpayne@68 1221 .I limit
jpayne@68 1222 to the default system-specific value.
jpayne@68 1223 .TP
jpayne@68 1224 \fB\-M\fR \fIlimit\fR, \fB\-\-memlimit=\fIlimit\fR, \fB\-\-memory=\fIlimit
jpayne@68 1225 This is equivalent to specifying
jpayne@68 1226 .BI \-\-memlimit\-compress= limit
jpayne@68 1227 .BI \-\-memlimit-decompress= limit
jpayne@68 1228 \fB\-\-memlimit\-mt\-decompress=\fIlimit\fR.
jpayne@68 1229 .TP
jpayne@68 1230 .B \-\-no\-adjust
jpayne@68 1231 Display an error and exit if the memory usage limit cannot be
jpayne@68 1232 met without adjusting settings that affect the compressed output.
jpayne@68 1233 That is, this prevents
jpayne@68 1234 .B xz
jpayne@68 1235 from switching the encoder from multi-threaded mode to single-threaded mode
jpayne@68 1236 and from reducing the LZMA2 dictionary size.
jpayne@68 1237 Even when this option is used the number of threads may be reduced
jpayne@68 1238 to meet the memory usage limit as that won't affect the compressed output.
jpayne@68 1239 .IP ""
jpayne@68 1240 Automatic adjusting is always disabled when creating raw streams
jpayne@68 1241 .RB ( \-\-format=raw ).
jpayne@68 1242 .TP
jpayne@68 1243 \fB\-T\fR \fIthreads\fR, \fB\-\-threads=\fIthreads
jpayne@68 1244 Specify the number of worker threads to use.
jpayne@68 1245 Setting
jpayne@68 1246 .I threads
jpayne@68 1247 to a special value
jpayne@68 1248 .B 0
jpayne@68 1249 makes
jpayne@68 1250 .B xz
jpayne@68 1251 use up to as many threads as the processor(s) on the system support.
jpayne@68 1252 The actual number of threads can be fewer than
jpayne@68 1253 .I threads
jpayne@68 1254 if the input file is not big enough
jpayne@68 1255 for threading with the given settings or
jpayne@68 1256 if using more threads would exceed the memory usage limit.
jpayne@68 1257 .IP ""
jpayne@68 1258 The single-threaded and multi-threaded compressors produce different output.
jpayne@68 1259 Single-threaded compressor will give the smallest file size but
jpayne@68 1260 only the output from the multi-threaded compressor can be decompressed
jpayne@68 1261 using multiple threads.
jpayne@68 1262 Setting
jpayne@68 1263 .I threads
jpayne@68 1264 to
jpayne@68 1265 .B 1
jpayne@68 1266 will use the single-threaded mode.
jpayne@68 1267 Setting
jpayne@68 1268 .I threads
jpayne@68 1269 to any other value, including
jpayne@68 1270 .BR 0 ,
jpayne@68 1271 will use the multi-threaded compressor
jpayne@68 1272 even if the system supports only one hardware thread.
jpayne@68 1273 .RB ( xz
jpayne@68 1274 5.2.x
jpayne@68 1275 used single-threaded mode in this situation.)
jpayne@68 1276 .IP ""
jpayne@68 1277 To use multi-threaded mode with only one thread, set
jpayne@68 1278 .I threads
jpayne@68 1279 to
jpayne@68 1280 .BR +1 .
jpayne@68 1281 The
jpayne@68 1282 .B +
jpayne@68 1283 prefix has no effect with values other than
jpayne@68 1284 .BR 1 .
jpayne@68 1285 A memory usage limit can still make
jpayne@68 1286 .B xz
jpayne@68 1287 switch to single-threaded mode unless
jpayne@68 1288 .B \-\-no\-adjust
jpayne@68 1289 is used.
jpayne@68 1290 Support for the
jpayne@68 1291 .B +
jpayne@68 1292 prefix was added in
jpayne@68 1293 .B xz
jpayne@68 1294 5.4.0.
jpayne@68 1295 .IP ""
jpayne@68 1296 If an automatic number of threads has been requested and
jpayne@68 1297 no memory usage limit has been specified,
jpayne@68 1298 then a system-specific default soft limit will be used to possibly
jpayne@68 1299 limit the number of threads.
jpayne@68 1300 It is a soft limit in sense that it is ignored
jpayne@68 1301 if the number of threads becomes one,
jpayne@68 1302 thus a soft limit will never stop
jpayne@68 1303 .B xz
jpayne@68 1304 from compressing or decompressing.
jpayne@68 1305 This default soft limit will not make
jpayne@68 1306 .B xz
jpayne@68 1307 switch from multi-threaded mode to single-threaded mode.
jpayne@68 1308 The active limits can be seen with
jpayne@68 1309 .BR "xz \-\-info\-memory" .
jpayne@68 1310 .IP ""
jpayne@68 1311 Currently the only threading method is to split the input into
jpayne@68 1312 blocks and compress them independently from each other.
jpayne@68 1313 The default block size depends on the compression level and
jpayne@68 1314 can be overridden with the
jpayne@68 1315 .BI \-\-block\-size= size
jpayne@68 1316 option.
jpayne@68 1317 .IP ""
jpayne@68 1318 Threaded decompression only works on files that contain
jpayne@68 1319 multiple blocks with size information in block headers.
jpayne@68 1320 All large enough files compressed in multi-threaded mode
jpayne@68 1321 meet this condition,
jpayne@68 1322 but files compressed in single-threaded mode don't even if
jpayne@68 1323 .BI \-\-block\-size= size
jpayne@68 1324 has been used.
jpayne@68 1325 .IP ""
jpayne@68 1326 The default value for
jpayne@68 1327 .I threads
jpayne@68 1328 is
jpayne@68 1329 .BR 0 .
jpayne@68 1330 In
jpayne@68 1331 .B xz
jpayne@68 1332 5.4.x and older the default is
jpayne@68 1333 .BR 1 .
jpayne@68 1334 .
jpayne@68 1335 .SS "Custom compressor filter chains"
jpayne@68 1336 A custom filter chain allows specifying
jpayne@68 1337 the compression settings in detail instead of relying on
jpayne@68 1338 the settings associated to the presets.
jpayne@68 1339 When a custom filter chain is specified,
jpayne@68 1340 preset options
jpayne@68 1341 .RB ( \-0
jpayne@68 1342 \&...\&
jpayne@68 1343 .B \-9
jpayne@68 1344 and
jpayne@68 1345 .BR \-\-extreme )
jpayne@68 1346 earlier on the command line are forgotten.
jpayne@68 1347 If a preset option is specified
jpayne@68 1348 after one or more custom filter chain options,
jpayne@68 1349 the new preset takes effect and
jpayne@68 1350 the custom filter chain options specified earlier are forgotten.
jpayne@68 1351 .PP
jpayne@68 1352 A filter chain is comparable to piping on the command line.
jpayne@68 1353 When compressing, the uncompressed input goes to the first filter,
jpayne@68 1354 whose output goes to the next filter (if any).
jpayne@68 1355 The output of the last filter gets written to the compressed file.
jpayne@68 1356 The maximum number of filters in the chain is four,
jpayne@68 1357 but typically a filter chain has only one or two filters.
jpayne@68 1358 .PP
jpayne@68 1359 Many filters have limitations on where they can be
jpayne@68 1360 in the filter chain:
jpayne@68 1361 some filters can work only as the last filter in the chain,
jpayne@68 1362 some only as a non-last filter, and some work in any position
jpayne@68 1363 in the chain.
jpayne@68 1364 Depending on the filter, this limitation is either inherent to
jpayne@68 1365 the filter design or exists to prevent security issues.
jpayne@68 1366 .PP
jpayne@68 1367 A custom filter chain can be specified in two different ways.
jpayne@68 1368 The options
jpayne@68 1369 .BI \-\-filters= filters
jpayne@68 1370 and
jpayne@68 1371 .BI \-\-filters1= filters
jpayne@68 1372 \&...\&
jpayne@68 1373 .BI \-\-filters9= filters
jpayne@68 1374 allow specifying an entire filter chain in one option using the
jpayne@68 1375 liblzma filter string syntax.
jpayne@68 1376 Alternatively, a filter chain can be specified by using one or more
jpayne@68 1377 individual filter options in the order they are wanted in the filter chain.
jpayne@68 1378 That is, the order of the individual filter options is significant!
jpayne@68 1379 When decoding raw streams
jpayne@68 1380 .RB ( \-\-format=raw ),
jpayne@68 1381 the filter chain must be specified in the same order as
jpayne@68 1382 it was specified when compressing.
jpayne@68 1383 Any individual filter or preset options specified before the full
jpayne@68 1384 chain option
jpayne@68 1385 (\fB\-\-filters=\fIfilters\fR)
jpayne@68 1386 will be forgotten.
jpayne@68 1387 Individual filters specified after the full chain option will reset the
jpayne@68 1388 filter chain.
jpayne@68 1389 .PP
jpayne@68 1390 Both the full and individual filter options take filter-specific
jpayne@68 1391 .I options
jpayne@68 1392 as a comma-separated list.
jpayne@68 1393 Extra commas in
jpayne@68 1394 .I options
jpayne@68 1395 are ignored.
jpayne@68 1396 Every option has a default value, so
jpayne@68 1397 specify those you want to change.
jpayne@68 1398 .PP
jpayne@68 1399 To see the whole filter chain and
jpayne@68 1400 .IR options ,
jpayne@68 1401 use
jpayne@68 1402 .B "xz \-vv"
jpayne@68 1403 (that is, use
jpayne@68 1404 .B \-\-verbose
jpayne@68 1405 twice).
jpayne@68 1406 This works also for viewing the filter chain options used by presets.
jpayne@68 1407 .TP
jpayne@68 1408 .BI \-\-filters= filters
jpayne@68 1409 Specify the full filter chain or a preset in a single option.
jpayne@68 1410 Each filter can be separated by spaces or two dashes
jpayne@68 1411 .RB ( \-\- ).
jpayne@68 1412 .I filters
jpayne@68 1413 may need to be quoted on the shell command line so it is
jpayne@68 1414 parsed as a single option.
jpayne@68 1415 To denote
jpayne@68 1416 .IR options ,
jpayne@68 1417 use
jpayne@68 1418 .B :
jpayne@68 1419 or
jpayne@68 1420 .BR = .
jpayne@68 1421 A preset can be prefixed with a
jpayne@68 1422 .B \-
jpayne@68 1423 and followed with zero or more flags.
jpayne@68 1424 The only supported flag is
jpayne@68 1425 .B e
jpayne@68 1426 to apply the same options as
jpayne@68 1427 .BR \-\-extreme .
jpayne@68 1428 .TP
jpayne@68 1429 \fB\-\-filters1\fR=\fIfilters\fR ... \fB\-\-filters9\fR=\fIfilters
jpayne@68 1430 Specify up to nine additional filter chains that can be used with
jpayne@68 1431 .BR \-\-block\-list .
jpayne@68 1432 .IP ""
jpayne@68 1433 For example, when compressing an archive with executable files
jpayne@68 1434 followed by text files, the executable part could use a filter
jpayne@68 1435 chain with a BCJ filter and the text part only the LZMA2 filter.
jpayne@68 1436 .TP
jpayne@68 1437 .B \-\-filters-help
jpayne@68 1438 Display a help message describing how to specify presets and
jpayne@68 1439 custom filter chains in the
jpayne@68 1440 .B \-\-filters
jpayne@68 1441 and
jpayne@68 1442 .BI \-\-filters1= filters
jpayne@68 1443 \&...\&
jpayne@68 1444 .BI \-\-filters9= filters
jpayne@68 1445 options, and exit successfully.
jpayne@68 1446 .TP
jpayne@68 1447 \fB\-\-lzma1\fR[\fB=\fIoptions\fR]
jpayne@68 1448 .PD 0
jpayne@68 1449 .TP
jpayne@68 1450 \fB\-\-lzma2\fR[\fB=\fIoptions\fR]
jpayne@68 1451 .PD
jpayne@68 1452 Add LZMA1 or LZMA2 filter to the filter chain.
jpayne@68 1453 These filters can be used only as the last filter in the chain.
jpayne@68 1454 .IP ""
jpayne@68 1455 LZMA1 is a legacy filter,
jpayne@68 1456 which is supported almost solely due to the legacy
jpayne@68 1457 .B .lzma
jpayne@68 1458 file format, which supports only LZMA1.
jpayne@68 1459 LZMA2 is an updated
jpayne@68 1460 version of LZMA1 to fix some practical issues of LZMA1.
jpayne@68 1461 The
jpayne@68 1462 .B .xz
jpayne@68 1463 format uses LZMA2 and doesn't support LZMA1 at all.
jpayne@68 1464 Compression speed and ratios of LZMA1 and LZMA2
jpayne@68 1465 are practically the same.
jpayne@68 1466 .IP ""
jpayne@68 1467 LZMA1 and LZMA2 share the same set of
jpayne@68 1468 .IR options :
jpayne@68 1469 .RS
jpayne@68 1470 .TP
jpayne@68 1471 .BI preset= preset
jpayne@68 1472 Reset all LZMA1 or LZMA2
jpayne@68 1473 .I options
jpayne@68 1474 to
jpayne@68 1475 .IR preset .
jpayne@68 1476 .I Preset
jpayne@68 1477 consist of an integer, which may be followed by single-letter
jpayne@68 1478 preset modifiers.
jpayne@68 1479 The integer can be from
jpayne@68 1480 .B 0
jpayne@68 1481 to
jpayne@68 1482 .BR 9 ,
jpayne@68 1483 matching the command line options
jpayne@68 1484 .B \-0
jpayne@68 1485 \&...\&
jpayne@68 1486 .BR \-9 .
jpayne@68 1487 The only supported modifier is currently
jpayne@68 1488 .BR e ,
jpayne@68 1489 which matches
jpayne@68 1490 .BR \-\-extreme .
jpayne@68 1491 If no
jpayne@68 1492 .B preset
jpayne@68 1493 is specified, the default values of LZMA1 or LZMA2
jpayne@68 1494 .I options
jpayne@68 1495 are taken from the preset
jpayne@68 1496 .BR 6 .
jpayne@68 1497 .TP
jpayne@68 1498 .BI dict= size
jpayne@68 1499 Dictionary (history buffer)
jpayne@68 1500 .I size
jpayne@68 1501 indicates how many bytes of the recently processed
jpayne@68 1502 uncompressed data is kept in memory.
jpayne@68 1503 The algorithm tries to find repeating byte sequences (matches) in
jpayne@68 1504 the uncompressed data, and replace them with references
jpayne@68 1505 to the data currently in the dictionary.
jpayne@68 1506 The bigger the dictionary, the higher is the chance
jpayne@68 1507 to find a match.
jpayne@68 1508 Thus, increasing dictionary
jpayne@68 1509 .I size
jpayne@68 1510 usually improves compression ratio, but
jpayne@68 1511 a dictionary bigger than the uncompressed file is waste of memory.
jpayne@68 1512 .IP ""
jpayne@68 1513 Typical dictionary
jpayne@68 1514 .I size
jpayne@68 1515 is from 64\ KiB to 64\ MiB.
jpayne@68 1516 The minimum is 4\ KiB.
jpayne@68 1517 The maximum for compression is currently 1.5\ GiB (1536\ MiB).
jpayne@68 1518 The decompressor already supports dictionaries up to
jpayne@68 1519 one byte less than 4\ GiB, which is the maximum for
jpayne@68 1520 the LZMA1 and LZMA2 stream formats.
jpayne@68 1521 .IP ""
jpayne@68 1522 Dictionary
jpayne@68 1523 .I size
jpayne@68 1524 and match finder
jpayne@68 1525 .RI ( mf )
jpayne@68 1526 together determine the memory usage of the LZMA1 or LZMA2 encoder.
jpayne@68 1527 The same (or bigger) dictionary
jpayne@68 1528 .I size
jpayne@68 1529 is required for decompressing that was used when compressing,
jpayne@68 1530 thus the memory usage of the decoder is determined
jpayne@68 1531 by the dictionary size used when compressing.
jpayne@68 1532 The
jpayne@68 1533 .B .xz
jpayne@68 1534 headers store the dictionary
jpayne@68 1535 .I size
jpayne@68 1536 either as
jpayne@68 1537 .RI "2^" n
jpayne@68 1538 or
jpayne@68 1539 .RI "2^" n " + 2^(" n "\-1),"
jpayne@68 1540 so these
jpayne@68 1541 .I sizes
jpayne@68 1542 are somewhat preferred for compression.
jpayne@68 1543 Other
jpayne@68 1544 .I sizes
jpayne@68 1545 will get rounded up when stored in the
jpayne@68 1546 .B .xz
jpayne@68 1547 headers.
jpayne@68 1548 .TP
jpayne@68 1549 .BI lc= lc
jpayne@68 1550 Specify the number of literal context bits.
jpayne@68 1551 The minimum is 0 and the maximum is 4; the default is 3.
jpayne@68 1552 In addition, the sum of
jpayne@68 1553 .I lc
jpayne@68 1554 and
jpayne@68 1555 .I lp
jpayne@68 1556 must not exceed 4.
jpayne@68 1557 .IP ""
jpayne@68 1558 All bytes that cannot be encoded as matches
jpayne@68 1559 are encoded as literals.
jpayne@68 1560 That is, literals are simply 8-bit bytes
jpayne@68 1561 that are encoded one at a time.
jpayne@68 1562 .IP ""
jpayne@68 1563 The literal coding makes an assumption that the highest
jpayne@68 1564 .I lc
jpayne@68 1565 bits of the previous uncompressed byte correlate
jpayne@68 1566 with the next byte.
jpayne@68 1567 For example, in typical English text, an upper-case letter is
jpayne@68 1568 often followed by a lower-case letter, and a lower-case
jpayne@68 1569 letter is usually followed by another lower-case letter.
jpayne@68 1570 In the US-ASCII character set, the highest three bits are 010
jpayne@68 1571 for upper-case letters and 011 for lower-case letters.
jpayne@68 1572 When
jpayne@68 1573 .I lc
jpayne@68 1574 is at least 3, the literal coding can take advantage of
jpayne@68 1575 this property in the uncompressed data.
jpayne@68 1576 .IP ""
jpayne@68 1577 The default value (3) is usually good.
jpayne@68 1578 If you want maximum compression, test
jpayne@68 1579 .BR lc=4 .
jpayne@68 1580 Sometimes it helps a little, and
jpayne@68 1581 sometimes it makes compression worse.
jpayne@68 1582 If it makes it worse, test
jpayne@68 1583 .B lc=2
jpayne@68 1584 too.
jpayne@68 1585 .TP
jpayne@68 1586 .BI lp= lp
jpayne@68 1587 Specify the number of literal position bits.
jpayne@68 1588 The minimum is 0 and the maximum is 4; the default is 0.
jpayne@68 1589 .IP ""
jpayne@68 1590 .I Lp
jpayne@68 1591 affects what kind of alignment in the uncompressed data is
jpayne@68 1592 assumed when encoding literals.
jpayne@68 1593 See
jpayne@68 1594 .I pb
jpayne@68 1595 below for more information about alignment.
jpayne@68 1596 .TP
jpayne@68 1597 .BI pb= pb
jpayne@68 1598 Specify the number of position bits.
jpayne@68 1599 The minimum is 0 and the maximum is 4; the default is 2.
jpayne@68 1600 .IP ""
jpayne@68 1601 .I Pb
jpayne@68 1602 affects what kind of alignment in the uncompressed data is
jpayne@68 1603 assumed in general.
jpayne@68 1604 The default means four-byte alignment
jpayne@68 1605 .RI (2^ pb =2^2=4),
jpayne@68 1606 which is often a good choice when there's no better guess.
jpayne@68 1607 .IP ""
jpayne@68 1608 When the alignment is known, setting
jpayne@68 1609 .I pb
jpayne@68 1610 accordingly may reduce the file size a little.
jpayne@68 1611 For example, with text files having one-byte
jpayne@68 1612 alignment (US-ASCII, ISO-8859-*, UTF-8), setting
jpayne@68 1613 .B pb=0
jpayne@68 1614 can improve compression slightly.
jpayne@68 1615 For UTF-16 text,
jpayne@68 1616 .B pb=1
jpayne@68 1617 is a good choice.
jpayne@68 1618 If the alignment is an odd number like 3 bytes,
jpayne@68 1619 .B pb=0
jpayne@68 1620 might be the best choice.
jpayne@68 1621 .IP ""
jpayne@68 1622 Even though the assumed alignment can be adjusted with
jpayne@68 1623 .I pb
jpayne@68 1624 and
jpayne@68 1625 .IR lp ,
jpayne@68 1626 LZMA1 and LZMA2 still slightly favor 16-byte alignment.
jpayne@68 1627 It might be worth taking into account when designing file formats
jpayne@68 1628 that are likely to be often compressed with LZMA1 or LZMA2.
jpayne@68 1629 .TP
jpayne@68 1630 .BI mf= mf
jpayne@68 1631 Match finder has a major effect on encoder speed,
jpayne@68 1632 memory usage, and compression ratio.
jpayne@68 1633 Usually Hash Chain match finders are faster than Binary Tree
jpayne@68 1634 match finders.
jpayne@68 1635 The default depends on the
jpayne@68 1636 .IR preset :
jpayne@68 1637 0 uses
jpayne@68 1638 .BR hc3 ,
jpayne@68 1639 1\(en3
jpayne@68 1640 use
jpayne@68 1641 .BR hc4 ,
jpayne@68 1642 and the rest use
jpayne@68 1643 .BR bt4 .
jpayne@68 1644 .IP ""
jpayne@68 1645 The following match finders are supported.
jpayne@68 1646 The memory usage formulas below are rough approximations,
jpayne@68 1647 which are closest to the reality when
jpayne@68 1648 .I dict
jpayne@68 1649 is a power of two.
jpayne@68 1650 .RS
jpayne@68 1651 .TP
jpayne@68 1652 .B hc3
jpayne@68 1653 Hash Chain with 2- and 3-byte hashing
jpayne@68 1654 .br
jpayne@68 1655 Minimum value for
jpayne@68 1656 .IR nice :
jpayne@68 1657 3
jpayne@68 1658 .br
jpayne@68 1659 Memory usage:
jpayne@68 1660 .br
jpayne@68 1661 .I dict
jpayne@68 1662 * 7.5 (if
jpayne@68 1663 .I dict
jpayne@68 1664 <= 16 MiB);
jpayne@68 1665 .br
jpayne@68 1666 .I dict
jpayne@68 1667 * 5.5 + 64 MiB (if
jpayne@68 1668 .I dict
jpayne@68 1669 > 16 MiB)
jpayne@68 1670 .TP
jpayne@68 1671 .B hc4
jpayne@68 1672 Hash Chain with 2-, 3-, and 4-byte hashing
jpayne@68 1673 .br
jpayne@68 1674 Minimum value for
jpayne@68 1675 .IR nice :
jpayne@68 1676 4
jpayne@68 1677 .br
jpayne@68 1678 Memory usage:
jpayne@68 1679 .br
jpayne@68 1680 .I dict
jpayne@68 1681 * 7.5 (if
jpayne@68 1682 .I dict
jpayne@68 1683 <= 32 MiB);
jpayne@68 1684 .br
jpayne@68 1685 .I dict
jpayne@68 1686 * 6.5 (if
jpayne@68 1687 .I dict
jpayne@68 1688 > 32 MiB)
jpayne@68 1689 .TP
jpayne@68 1690 .B bt2
jpayne@68 1691 Binary Tree with 2-byte hashing
jpayne@68 1692 .br
jpayne@68 1693 Minimum value for
jpayne@68 1694 .IR nice :
jpayne@68 1695 2
jpayne@68 1696 .br
jpayne@68 1697 Memory usage:
jpayne@68 1698 .I dict
jpayne@68 1699 * 9.5
jpayne@68 1700 .TP
jpayne@68 1701 .B bt3
jpayne@68 1702 Binary Tree with 2- and 3-byte hashing
jpayne@68 1703 .br
jpayne@68 1704 Minimum value for
jpayne@68 1705 .IR nice :
jpayne@68 1706 3
jpayne@68 1707 .br
jpayne@68 1708 Memory usage:
jpayne@68 1709 .br
jpayne@68 1710 .I dict
jpayne@68 1711 * 11.5 (if
jpayne@68 1712 .I dict
jpayne@68 1713 <= 16 MiB);
jpayne@68 1714 .br
jpayne@68 1715 .I dict
jpayne@68 1716 * 9.5 + 64 MiB (if
jpayne@68 1717 .I dict
jpayne@68 1718 > 16 MiB)
jpayne@68 1719 .TP
jpayne@68 1720 .B bt4
jpayne@68 1721 Binary Tree with 2-, 3-, and 4-byte hashing
jpayne@68 1722 .br
jpayne@68 1723 Minimum value for
jpayne@68 1724 .IR nice :
jpayne@68 1725 4
jpayne@68 1726 .br
jpayne@68 1727 Memory usage:
jpayne@68 1728 .br
jpayne@68 1729 .I dict
jpayne@68 1730 * 11.5 (if
jpayne@68 1731 .I dict
jpayne@68 1732 <= 32 MiB);
jpayne@68 1733 .br
jpayne@68 1734 .I dict
jpayne@68 1735 * 10.5 (if
jpayne@68 1736 .I dict
jpayne@68 1737 > 32 MiB)
jpayne@68 1738 .RE
jpayne@68 1739 .TP
jpayne@68 1740 .BI mode= mode
jpayne@68 1741 Compression
jpayne@68 1742 .I mode
jpayne@68 1743 specifies the method to analyze
jpayne@68 1744 the data produced by the match finder.
jpayne@68 1745 Supported
jpayne@68 1746 .I modes
jpayne@68 1747 are
jpayne@68 1748 .B fast
jpayne@68 1749 and
jpayne@68 1750 .BR normal .
jpayne@68 1751 The default is
jpayne@68 1752 .B fast
jpayne@68 1753 for
jpayne@68 1754 .I presets
jpayne@68 1755 0\(en3 and
jpayne@68 1756 .B normal
jpayne@68 1757 for
jpayne@68 1758 .I presets
jpayne@68 1759 4\(en9.
jpayne@68 1760 .IP ""
jpayne@68 1761 Usually
jpayne@68 1762 .B fast
jpayne@68 1763 is used with Hash Chain match finders and
jpayne@68 1764 .B normal
jpayne@68 1765 with Binary Tree match finders.
jpayne@68 1766 This is also what the
jpayne@68 1767 .I presets
jpayne@68 1768 do.
jpayne@68 1769 .TP
jpayne@68 1770 .BI nice= nice
jpayne@68 1771 Specify what is considered to be a nice length for a match.
jpayne@68 1772 Once a match of at least
jpayne@68 1773 .I nice
jpayne@68 1774 bytes is found, the algorithm stops
jpayne@68 1775 looking for possibly better matches.
jpayne@68 1776 .IP ""
jpayne@68 1777 .I Nice
jpayne@68 1778 can be 2\(en273 bytes.
jpayne@68 1779 Higher values tend to give better compression ratio
jpayne@68 1780 at the expense of speed.
jpayne@68 1781 The default depends on the
jpayne@68 1782 .IR preset .
jpayne@68 1783 .TP
jpayne@68 1784 .BI depth= depth
jpayne@68 1785 Specify the maximum search depth in the match finder.
jpayne@68 1786 The default is the special value of 0,
jpayne@68 1787 which makes the compressor determine a reasonable
jpayne@68 1788 .I depth
jpayne@68 1789 from
jpayne@68 1790 .I mf
jpayne@68 1791 and
jpayne@68 1792 .IR nice .
jpayne@68 1793 .IP ""
jpayne@68 1794 Reasonable
jpayne@68 1795 .I depth
jpayne@68 1796 for Hash Chains is 4\(en100 and 16\(en1000 for Binary Trees.
jpayne@68 1797 Using very high values for
jpayne@68 1798 .I depth
jpayne@68 1799 can make the encoder extremely slow with some files.
jpayne@68 1800 Avoid setting the
jpayne@68 1801 .I depth
jpayne@68 1802 over 1000 unless you are prepared to interrupt
jpayne@68 1803 the compression in case it is taking far too long.
jpayne@68 1804 .RE
jpayne@68 1805 .IP ""
jpayne@68 1806 When decoding raw streams
jpayne@68 1807 .RB ( \-\-format=raw ),
jpayne@68 1808 LZMA2 needs only the dictionary
jpayne@68 1809 .IR size .
jpayne@68 1810 LZMA1 needs also
jpayne@68 1811 .IR lc ,
jpayne@68 1812 .IR lp ,
jpayne@68 1813 and
jpayne@68 1814 .IR pb .
jpayne@68 1815 .TP
jpayne@68 1816 \fB\-\-x86\fR[\fB=\fIoptions\fR]
jpayne@68 1817 .PD 0
jpayne@68 1818 .TP
jpayne@68 1819 \fB\-\-arm\fR[\fB=\fIoptions\fR]
jpayne@68 1820 .TP
jpayne@68 1821 \fB\-\-armthumb\fR[\fB=\fIoptions\fR]
jpayne@68 1822 .TP
jpayne@68 1823 \fB\-\-arm64\fR[\fB=\fIoptions\fR]
jpayne@68 1824 .TP
jpayne@68 1825 \fB\-\-powerpc\fR[\fB=\fIoptions\fR]
jpayne@68 1826 .TP
jpayne@68 1827 \fB\-\-ia64\fR[\fB=\fIoptions\fR]
jpayne@68 1828 .TP
jpayne@68 1829 \fB\-\-sparc\fR[\fB=\fIoptions\fR]
jpayne@68 1830 .TP
jpayne@68 1831 \fB\-\-riscv\fR[\fB=\fIoptions\fR]
jpayne@68 1832 .PD
jpayne@68 1833 Add a branch/call/jump (BCJ) filter to the filter chain.
jpayne@68 1834 These filters can be used only as a non-last filter
jpayne@68 1835 in the filter chain.
jpayne@68 1836 .IP ""
jpayne@68 1837 A BCJ filter converts relative addresses in
jpayne@68 1838 the machine code to their absolute counterparts.
jpayne@68 1839 This doesn't change the size of the data
jpayne@68 1840 but it increases redundancy,
jpayne@68 1841 which can help LZMA2 to produce 0\(en15\ % smaller
jpayne@68 1842 .B .xz
jpayne@68 1843 file.
jpayne@68 1844 The BCJ filters are always reversible,
jpayne@68 1845 so using a BCJ filter for wrong type of data
jpayne@68 1846 doesn't cause any data loss, although it may make
jpayne@68 1847 the compression ratio slightly worse.
jpayne@68 1848 The BCJ filters are very fast and
jpayne@68 1849 use an insignificant amount of memory.
jpayne@68 1850 .IP ""
jpayne@68 1851 These BCJ filters have known problems related to
jpayne@68 1852 the compression ratio:
jpayne@68 1853 .RS
jpayne@68 1854 .IP \(bu 3
jpayne@68 1855 Some types of files containing executable code
jpayne@68 1856 (for example, object files, static libraries, and Linux kernel modules)
jpayne@68 1857 have the addresses in the instructions filled with filler values.
jpayne@68 1858 These BCJ filters will still do the address conversion,
jpayne@68 1859 which will make the compression worse with these files.
jpayne@68 1860 .IP \(bu 3
jpayne@68 1861 If a BCJ filter is applied on an archive,
jpayne@68 1862 it is possible that it makes the compression ratio
jpayne@68 1863 worse than not using a BCJ filter.
jpayne@68 1864 For example, if there are similar or even identical executables
jpayne@68 1865 then filtering will likely make the files less similar
jpayne@68 1866 and thus compression is worse.
jpayne@68 1867 The contents of non-executable files in the same archive can matter too.
jpayne@68 1868 In practice one has to try with and without a BCJ filter to see
jpayne@68 1869 which is better in each situation.
jpayne@68 1870 .RE
jpayne@68 1871 .IP ""
jpayne@68 1872 Different instruction sets have different alignment:
jpayne@68 1873 the executable file must be aligned to a multiple of
jpayne@68 1874 this value in the input data to make the filter work.
jpayne@68 1875 .RS
jpayne@68 1876 .RS
jpayne@68 1877 .PP
jpayne@68 1878 .TS
jpayne@68 1879 tab(;);
jpayne@68 1880 l n l
jpayne@68 1881 l n l.
jpayne@68 1882 Filter;Alignment;Notes
jpayne@68 1883 x86;1;32-bit or 64-bit x86
jpayne@68 1884 ARM;4;
jpayne@68 1885 ARM-Thumb;2;
jpayne@68 1886 ARM64;4;4096-byte alignment is best
jpayne@68 1887 PowerPC;4;Big endian only
jpayne@68 1888 IA-64;16;Itanium
jpayne@68 1889 SPARC;4;
jpayne@68 1890 RISC-V;2;
jpayne@68 1891 .TE
jpayne@68 1892 .RE
jpayne@68 1893 .RE
jpayne@68 1894 .IP ""
jpayne@68 1895 Since the BCJ-filtered data is usually compressed with LZMA2,
jpayne@68 1896 the compression ratio may be improved slightly if
jpayne@68 1897 the LZMA2 options are set to match the
jpayne@68 1898 alignment of the selected BCJ filter.
jpayne@68 1899 Examples:
jpayne@68 1900 .RS
jpayne@68 1901 .IP \(bu 3
jpayne@68 1902 IA-64 filter has 16-byte alignment so
jpayne@68 1903 .B pb=4,lp=4,lc=0
jpayne@68 1904 is good
jpayne@68 1905 with LZMA2 (2^4=16).
jpayne@68 1906 .IP \(bu 3
jpayne@68 1907 RISC-V code has 2-byte or 4-byte alignment
jpayne@68 1908 depending on whether the file contains
jpayne@68 1909 16-bit compressed instructions (the C extension).
jpayne@68 1910 When 16-bit instructions are used,
jpayne@68 1911 .B pb=2,lp=1,lc=3
jpayne@68 1912 or
jpayne@68 1913 .B pb=1,lp=1,lc=3
jpayne@68 1914 is good.
jpayne@68 1915 When 16-bit instructions aren't present,
jpayne@68 1916 .B pb=2,lp=2,lc=2
jpayne@68 1917 is the best.
jpayne@68 1918 .B readelf \-h
jpayne@68 1919 can be used to check if "RVC"
jpayne@68 1920 appears on the "Flags" line.
jpayne@68 1921 .IP \(bu 3
jpayne@68 1922 ARM64 is always 4-byte aligned so
jpayne@68 1923 .B pb=2,lp=2,lc=2
jpayne@68 1924 is the best.
jpayne@68 1925 .IP \(bu 3
jpayne@68 1926 The x86 filter is an exception.
jpayne@68 1927 It's usually good to stick to LZMA2's defaults
jpayne@68 1928 .RB ( pb=2,lp=0,lc=3 )
jpayne@68 1929 when compressing x86 executables.
jpayne@68 1930 .RE
jpayne@68 1931 .IP ""
jpayne@68 1932 All BCJ filters support the same
jpayne@68 1933 .IR options :
jpayne@68 1934 .RS
jpayne@68 1935 .TP
jpayne@68 1936 .BI start= offset
jpayne@68 1937 Specify the start
jpayne@68 1938 .I offset
jpayne@68 1939 that is used when converting between relative
jpayne@68 1940 and absolute addresses.
jpayne@68 1941 The
jpayne@68 1942 .I offset
jpayne@68 1943 must be a multiple of the alignment of the filter
jpayne@68 1944 (see the table above).
jpayne@68 1945 The default is zero.
jpayne@68 1946 In practice, the default is good; specifying a custom
jpayne@68 1947 .I offset
jpayne@68 1948 is almost never useful.
jpayne@68 1949 .RE
jpayne@68 1950 .TP
jpayne@68 1951 \fB\-\-delta\fR[\fB=\fIoptions\fR]
jpayne@68 1952 Add the Delta filter to the filter chain.
jpayne@68 1953 The Delta filter can be only used as a non-last filter
jpayne@68 1954 in the filter chain.
jpayne@68 1955 .IP ""
jpayne@68 1956 Currently only simple byte-wise delta calculation is supported.
jpayne@68 1957 It can be useful when compressing, for example, uncompressed bitmap images
jpayne@68 1958 or uncompressed PCM audio.
jpayne@68 1959 However, special purpose algorithms may give significantly better
jpayne@68 1960 results than Delta + LZMA2.
jpayne@68 1961 This is true especially with audio,
jpayne@68 1962 which compresses faster and better, for example, with
jpayne@68 1963 .BR flac (1).
jpayne@68 1964 .IP ""
jpayne@68 1965 Supported
jpayne@68 1966 .IR options :
jpayne@68 1967 .RS
jpayne@68 1968 .TP
jpayne@68 1969 .BI dist= distance
jpayne@68 1970 Specify the
jpayne@68 1971 .I distance
jpayne@68 1972 of the delta calculation in bytes.
jpayne@68 1973 .I distance
jpayne@68 1974 must be 1\(en256.
jpayne@68 1975 The default is 1.
jpayne@68 1976 .IP ""
jpayne@68 1977 For example, with
jpayne@68 1978 .B dist=2
jpayne@68 1979 and eight-byte input A1 B1 A2 B3 A3 B5 A4 B7, the output will be
jpayne@68 1980 A1 B1 01 02 01 02 01 02.
jpayne@68 1981 .RE
jpayne@68 1982 .
jpayne@68 1983 .SS "Other options"
jpayne@68 1984 .TP
jpayne@68 1985 .BR \-q ", " \-\-quiet
jpayne@68 1986 Suppress warnings and notices.
jpayne@68 1987 Specify this twice to suppress errors too.
jpayne@68 1988 This option has no effect on the exit status.
jpayne@68 1989 That is, even if a warning was suppressed,
jpayne@68 1990 the exit status to indicate a warning is still used.
jpayne@68 1991 .TP
jpayne@68 1992 .BR \-v ", " \-\-verbose
jpayne@68 1993 Be verbose.
jpayne@68 1994 If standard error is connected to a terminal,
jpayne@68 1995 .B xz
jpayne@68 1996 will display a progress indicator.
jpayne@68 1997 Specifying
jpayne@68 1998 .B \-\-verbose
jpayne@68 1999 twice will give even more verbose output.
jpayne@68 2000 .IP ""
jpayne@68 2001 The progress indicator shows the following information:
jpayne@68 2002 .RS
jpayne@68 2003 .IP \(bu 3
jpayne@68 2004 Completion percentage is shown
jpayne@68 2005 if the size of the input file is known.
jpayne@68 2006 That is, the percentage cannot be shown in pipes.
jpayne@68 2007 .IP \(bu 3
jpayne@68 2008 Amount of compressed data produced (compressing)
jpayne@68 2009 or consumed (decompressing).
jpayne@68 2010 .IP \(bu 3
jpayne@68 2011 Amount of uncompressed data consumed (compressing)
jpayne@68 2012 or produced (decompressing).
jpayne@68 2013 .IP \(bu 3
jpayne@68 2014 Compression ratio, which is calculated by dividing
jpayne@68 2015 the amount of compressed data processed so far by
jpayne@68 2016 the amount of uncompressed data processed so far.
jpayne@68 2017 .IP \(bu 3
jpayne@68 2018 Compression or decompression speed.
jpayne@68 2019 This is measured as the amount of uncompressed data consumed
jpayne@68 2020 (compression) or produced (decompression) per second.
jpayne@68 2021 It is shown after a few seconds have passed since
jpayne@68 2022 .B xz
jpayne@68 2023 started processing the file.
jpayne@68 2024 .IP \(bu 3
jpayne@68 2025 Elapsed time in the format M:SS or H:MM:SS.
jpayne@68 2026 .IP \(bu 3
jpayne@68 2027 Estimated remaining time is shown
jpayne@68 2028 only when the size of the input file is
jpayne@68 2029 known and a couple of seconds have already passed since
jpayne@68 2030 .B xz
jpayne@68 2031 started processing the file.
jpayne@68 2032 The time is shown in a less precise format which
jpayne@68 2033 never has any colons, for example, 2 min 30 s.
jpayne@68 2034 .RE
jpayne@68 2035 .IP ""
jpayne@68 2036 When standard error is not a terminal,
jpayne@68 2037 .B \-\-verbose
jpayne@68 2038 will make
jpayne@68 2039 .B xz
jpayne@68 2040 print the filename, compressed size, uncompressed size,
jpayne@68 2041 compression ratio, and possibly also the speed and elapsed time
jpayne@68 2042 on a single line to standard error after compressing or
jpayne@68 2043 decompressing the file.
jpayne@68 2044 The speed and elapsed time are included only when
jpayne@68 2045 the operation took at least a few seconds.
jpayne@68 2046 If the operation didn't finish, for example, due to user interruption,
jpayne@68 2047 also the completion percentage is printed
jpayne@68 2048 if the size of the input file is known.
jpayne@68 2049 .TP
jpayne@68 2050 .BR \-Q ", " \-\-no\-warn
jpayne@68 2051 Don't set the exit status to 2
jpayne@68 2052 even if a condition worth a warning was detected.
jpayne@68 2053 This option doesn't affect the verbosity level, thus both
jpayne@68 2054 .B \-\-quiet
jpayne@68 2055 and
jpayne@68 2056 .B \-\-no\-warn
jpayne@68 2057 have to be used to not display warnings and
jpayne@68 2058 to not alter the exit status.
jpayne@68 2059 .TP
jpayne@68 2060 .B \-\-robot
jpayne@68 2061 Print messages in a machine-parsable format.
jpayne@68 2062 This is intended to ease writing frontends that want to use
jpayne@68 2063 .B xz
jpayne@68 2064 instead of liblzma, which may be the case with various scripts.
jpayne@68 2065 The output with this option enabled is meant to be stable across
jpayne@68 2066 .B xz
jpayne@68 2067 releases.
jpayne@68 2068 See the section
jpayne@68 2069 .B "ROBOT MODE"
jpayne@68 2070 for details.
jpayne@68 2071 .TP
jpayne@68 2072 .B \-\-info\-memory
jpayne@68 2073 Display, in human-readable format, how much physical memory (RAM)
jpayne@68 2074 and how many processor threads
jpayne@68 2075 .B xz
jpayne@68 2076 thinks the system has and the memory usage limits for compression
jpayne@68 2077 and decompression, and exit successfully.
jpayne@68 2078 .TP
jpayne@68 2079 .BR \-h ", " \-\-help
jpayne@68 2080 Display a help message describing the most commonly used options,
jpayne@68 2081 and exit successfully.
jpayne@68 2082 .TP
jpayne@68 2083 .BR \-H ", " \-\-long\-help
jpayne@68 2084 Display a help message describing all features of
jpayne@68 2085 .BR xz ,
jpayne@68 2086 and exit successfully
jpayne@68 2087 .TP
jpayne@68 2088 .BR \-V ", " \-\-version
jpayne@68 2089 Display the version number of
jpayne@68 2090 .B xz
jpayne@68 2091 and liblzma in human readable format.
jpayne@68 2092 To get machine-parsable output, specify
jpayne@68 2093 .B \-\-robot
jpayne@68 2094 before
jpayne@68 2095 .BR \-\-version .
jpayne@68 2096 .
jpayne@68 2097 .SH "ROBOT MODE"
jpayne@68 2098 The robot mode is activated with the
jpayne@68 2099 .B \-\-robot
jpayne@68 2100 option.
jpayne@68 2101 It makes the output of
jpayne@68 2102 .B xz
jpayne@68 2103 easier to parse by other programs.
jpayne@68 2104 Currently
jpayne@68 2105 .B \-\-robot
jpayne@68 2106 is supported only together with
jpayne@68 2107 .BR \-\-list ,
jpayne@68 2108 .BR \-\-filters\-help ,
jpayne@68 2109 .BR \-\-info\-memory ,
jpayne@68 2110 and
jpayne@68 2111 .BR \-\-version .
jpayne@68 2112 It will be supported for compression and
jpayne@68 2113 decompression in the future.
jpayne@68 2114 .
jpayne@68 2115 .SS "List mode"
jpayne@68 2116 .B "xz \-\-robot \-\-list"
jpayne@68 2117 uses tab-separated output.
jpayne@68 2118 The first column of every line has a string
jpayne@68 2119 that indicates the type of the information found on that line:
jpayne@68 2120 .TP
jpayne@68 2121 .B name
jpayne@68 2122 This is always the first line when starting to list a file.
jpayne@68 2123 The second column on the line is the filename.
jpayne@68 2124 .TP
jpayne@68 2125 .B file
jpayne@68 2126 This line contains overall information about the
jpayne@68 2127 .B .xz
jpayne@68 2128 file.
jpayne@68 2129 This line is always printed after the
jpayne@68 2130 .B name
jpayne@68 2131 line.
jpayne@68 2132 .TP
jpayne@68 2133 .B stream
jpayne@68 2134 This line type is used only when
jpayne@68 2135 .B \-\-verbose
jpayne@68 2136 was specified.
jpayne@68 2137 There are as many
jpayne@68 2138 .B stream
jpayne@68 2139 lines as there are streams in the
jpayne@68 2140 .B .xz
jpayne@68 2141 file.
jpayne@68 2142 .TP
jpayne@68 2143 .B block
jpayne@68 2144 This line type is used only when
jpayne@68 2145 .B \-\-verbose
jpayne@68 2146 was specified.
jpayne@68 2147 There are as many
jpayne@68 2148 .B block
jpayne@68 2149 lines as there are blocks in the
jpayne@68 2150 .B .xz
jpayne@68 2151 file.
jpayne@68 2152 The
jpayne@68 2153 .B block
jpayne@68 2154 lines are shown after all the
jpayne@68 2155 .B stream
jpayne@68 2156 lines; different line types are not interleaved.
jpayne@68 2157 .TP
jpayne@68 2158 .B summary
jpayne@68 2159 This line type is used only when
jpayne@68 2160 .B \-\-verbose
jpayne@68 2161 was specified twice.
jpayne@68 2162 This line is printed after all
jpayne@68 2163 .B block
jpayne@68 2164 lines.
jpayne@68 2165 Like the
jpayne@68 2166 .B file
jpayne@68 2167 line, the
jpayne@68 2168 .B summary
jpayne@68 2169 line contains overall information about the
jpayne@68 2170 .B .xz
jpayne@68 2171 file.
jpayne@68 2172 .TP
jpayne@68 2173 .B totals
jpayne@68 2174 This line is always the very last line of the list output.
jpayne@68 2175 It shows the total counts and sizes.
jpayne@68 2176 .PP
jpayne@68 2177 The columns of the
jpayne@68 2178 .B file
jpayne@68 2179 lines:
jpayne@68 2180 .PD 0
jpayne@68 2181 .RS
jpayne@68 2182 .IP 2. 4
jpayne@68 2183 Number of streams in the file
jpayne@68 2184 .IP 3. 4
jpayne@68 2185 Total number of blocks in the stream(s)
jpayne@68 2186 .IP 4. 4
jpayne@68 2187 Compressed size of the file
jpayne@68 2188 .IP 5. 4
jpayne@68 2189 Uncompressed size of the file
jpayne@68 2190 .IP 6. 4
jpayne@68 2191 Compression ratio, for example,
jpayne@68 2192 .BR 0.123 .
jpayne@68 2193 If ratio is over 9.999, three dashes
jpayne@68 2194 .RB ( \-\-\- )
jpayne@68 2195 are displayed instead of the ratio.
jpayne@68 2196 .IP 7. 4
jpayne@68 2197 Comma-separated list of integrity check names.
jpayne@68 2198 The following strings are used for the known check types:
jpayne@68 2199 .BR None ,
jpayne@68 2200 .BR CRC32 ,
jpayne@68 2201 .BR CRC64 ,
jpayne@68 2202 and
jpayne@68 2203 .BR SHA\-256 .
jpayne@68 2204 For unknown check types,
jpayne@68 2205 .BI Unknown\- N
jpayne@68 2206 is used, where
jpayne@68 2207 .I N
jpayne@68 2208 is the Check ID as a decimal number (one or two digits).
jpayne@68 2209 .IP 8. 4
jpayne@68 2210 Total size of stream padding in the file
jpayne@68 2211 .RE
jpayne@68 2212 .PD
jpayne@68 2213 .PP
jpayne@68 2214 The columns of the
jpayne@68 2215 .B stream
jpayne@68 2216 lines:
jpayne@68 2217 .PD 0
jpayne@68 2218 .RS
jpayne@68 2219 .IP 2. 4
jpayne@68 2220 Stream number (the first stream is 1)
jpayne@68 2221 .IP 3. 4
jpayne@68 2222 Number of blocks in the stream
jpayne@68 2223 .IP 4. 4
jpayne@68 2224 Compressed start offset
jpayne@68 2225 .IP 5. 4
jpayne@68 2226 Uncompressed start offset
jpayne@68 2227 .IP 6. 4
jpayne@68 2228 Compressed size (does not include stream padding)
jpayne@68 2229 .IP 7. 4
jpayne@68 2230 Uncompressed size
jpayne@68 2231 .IP 8. 4
jpayne@68 2232 Compression ratio
jpayne@68 2233 .IP 9. 4
jpayne@68 2234 Name of the integrity check
jpayne@68 2235 .IP 10. 4
jpayne@68 2236 Size of stream padding
jpayne@68 2237 .RE
jpayne@68 2238 .PD
jpayne@68 2239 .PP
jpayne@68 2240 The columns of the
jpayne@68 2241 .B block
jpayne@68 2242 lines:
jpayne@68 2243 .PD 0
jpayne@68 2244 .RS
jpayne@68 2245 .IP 2. 4
jpayne@68 2246 Number of the stream containing this block
jpayne@68 2247 .IP 3. 4
jpayne@68 2248 Block number relative to the beginning of the stream
jpayne@68 2249 (the first block is 1)
jpayne@68 2250 .IP 4. 4
jpayne@68 2251 Block number relative to the beginning of the file
jpayne@68 2252 .IP 5. 4
jpayne@68 2253 Compressed start offset relative to the beginning of the file
jpayne@68 2254 .IP 6. 4
jpayne@68 2255 Uncompressed start offset relative to the beginning of the file
jpayne@68 2256 .IP 7. 4
jpayne@68 2257 Total compressed size of the block (includes headers)
jpayne@68 2258 .IP 8. 4
jpayne@68 2259 Uncompressed size
jpayne@68 2260 .IP 9. 4
jpayne@68 2261 Compression ratio
jpayne@68 2262 .IP 10. 4
jpayne@68 2263 Name of the integrity check
jpayne@68 2264 .RE
jpayne@68 2265 .PD
jpayne@68 2266 .PP
jpayne@68 2267 If
jpayne@68 2268 .B \-\-verbose
jpayne@68 2269 was specified twice, additional columns are included on the
jpayne@68 2270 .B block
jpayne@68 2271 lines.
jpayne@68 2272 These are not displayed with a single
jpayne@68 2273 .BR \-\-verbose ,
jpayne@68 2274 because getting this information requires many seeks
jpayne@68 2275 and can thus be slow:
jpayne@68 2276 .PD 0
jpayne@68 2277 .RS
jpayne@68 2278 .IP 11. 4
jpayne@68 2279 Value of the integrity check in hexadecimal
jpayne@68 2280 .IP 12. 4
jpayne@68 2281 Block header size
jpayne@68 2282 .IP 13. 4
jpayne@68 2283 Block flags:
jpayne@68 2284 .B c
jpayne@68 2285 indicates that compressed size is present, and
jpayne@68 2286 .B u
jpayne@68 2287 indicates that uncompressed size is present.
jpayne@68 2288 If the flag is not set, a dash
jpayne@68 2289 .RB ( \- )
jpayne@68 2290 is shown instead to keep the string length fixed.
jpayne@68 2291 New flags may be added to the end of the string in the future.
jpayne@68 2292 .IP 14. 4
jpayne@68 2293 Size of the actual compressed data in the block (this excludes
jpayne@68 2294 the block header, block padding, and check fields)
jpayne@68 2295 .IP 15. 4
jpayne@68 2296 Amount of memory (in bytes) required to decompress
jpayne@68 2297 this block with this
jpayne@68 2298 .B xz
jpayne@68 2299 version
jpayne@68 2300 .IP 16. 4
jpayne@68 2301 Filter chain.
jpayne@68 2302 Note that most of the options used at compression time
jpayne@68 2303 cannot be known, because only the options
jpayne@68 2304 that are needed for decompression are stored in the
jpayne@68 2305 .B .xz
jpayne@68 2306 headers.
jpayne@68 2307 .RE
jpayne@68 2308 .PD
jpayne@68 2309 .PP
jpayne@68 2310 The columns of the
jpayne@68 2311 .B summary
jpayne@68 2312 lines:
jpayne@68 2313 .PD 0
jpayne@68 2314 .RS
jpayne@68 2315 .IP 2. 4
jpayne@68 2316 Amount of memory (in bytes) required to decompress
jpayne@68 2317 this file with this
jpayne@68 2318 .B xz
jpayne@68 2319 version
jpayne@68 2320 .IP 3. 4
jpayne@68 2321 .B yes
jpayne@68 2322 or
jpayne@68 2323 .B no
jpayne@68 2324 indicating if all block headers have both compressed size and
jpayne@68 2325 uncompressed size stored in them
jpayne@68 2326 .PP
jpayne@68 2327 .I Since
jpayne@68 2328 .B xz
jpayne@68 2329 .I 5.1.2alpha:
jpayne@68 2330 .IP 4. 4
jpayne@68 2331 Minimum
jpayne@68 2332 .B xz
jpayne@68 2333 version required to decompress the file
jpayne@68 2334 .RE
jpayne@68 2335 .PD
jpayne@68 2336 .PP
jpayne@68 2337 The columns of the
jpayne@68 2338 .B totals
jpayne@68 2339 line:
jpayne@68 2340 .PD 0
jpayne@68 2341 .RS
jpayne@68 2342 .IP 2. 4
jpayne@68 2343 Number of streams
jpayne@68 2344 .IP 3. 4
jpayne@68 2345 Number of blocks
jpayne@68 2346 .IP 4. 4
jpayne@68 2347 Compressed size
jpayne@68 2348 .IP 5. 4
jpayne@68 2349 Uncompressed size
jpayne@68 2350 .IP 6. 4
jpayne@68 2351 Average compression ratio
jpayne@68 2352 .IP 7. 4
jpayne@68 2353 Comma-separated list of integrity check names
jpayne@68 2354 that were present in the files
jpayne@68 2355 .IP 8. 4
jpayne@68 2356 Stream padding size
jpayne@68 2357 .IP 9. 4
jpayne@68 2358 Number of files.
jpayne@68 2359 This is here to
jpayne@68 2360 keep the order of the earlier columns the same as on
jpayne@68 2361 .B file
jpayne@68 2362 lines.
jpayne@68 2363 .PD
jpayne@68 2364 .RE
jpayne@68 2365 .PP
jpayne@68 2366 If
jpayne@68 2367 .B \-\-verbose
jpayne@68 2368 was specified twice, additional columns are included on the
jpayne@68 2369 .B totals
jpayne@68 2370 line:
jpayne@68 2371 .PD 0
jpayne@68 2372 .RS
jpayne@68 2373 .IP 10. 4
jpayne@68 2374 Maximum amount of memory (in bytes) required to decompress
jpayne@68 2375 the files with this
jpayne@68 2376 .B xz
jpayne@68 2377 version
jpayne@68 2378 .IP 11. 4
jpayne@68 2379 .B yes
jpayne@68 2380 or
jpayne@68 2381 .B no
jpayne@68 2382 indicating if all block headers have both compressed size and
jpayne@68 2383 uncompressed size stored in them
jpayne@68 2384 .PP
jpayne@68 2385 .I Since
jpayne@68 2386 .B xz
jpayne@68 2387 .I 5.1.2alpha:
jpayne@68 2388 .IP 12. 4
jpayne@68 2389 Minimum
jpayne@68 2390 .B xz
jpayne@68 2391 version required to decompress the file
jpayne@68 2392 .RE
jpayne@68 2393 .PD
jpayne@68 2394 .PP
jpayne@68 2395 Future versions may add new line types and
jpayne@68 2396 new columns can be added to the existing line types,
jpayne@68 2397 but the existing columns won't be changed.
jpayne@68 2398 .
jpayne@68 2399 .SS "Filters help"
jpayne@68 2400 .B "xz \-\-robot \-\-filters-help"
jpayne@68 2401 prints the supported filters in the following format:
jpayne@68 2402 .PP
jpayne@68 2403 \fIfilter\fB:\fIoption\fB=<\fIvalue\fB>,\fIoption\fB=<\fIvalue\fB>\fR...
jpayne@68 2404 .TP
jpayne@68 2405 .I filter
jpayne@68 2406 Name of the filter
jpayne@68 2407 .TP
jpayne@68 2408 .I option
jpayne@68 2409 Name of a filter specific option
jpayne@68 2410 .TP
jpayne@68 2411 .I value
jpayne@68 2412 Numeric
jpayne@68 2413 .I value
jpayne@68 2414 ranges appear as
jpayne@68 2415 \fB<\fImin\fB\-\fImax\fB>\fR.
jpayne@68 2416 String
jpayne@68 2417 .I value
jpayne@68 2418 choices are shown within
jpayne@68 2419 .B "< >"
jpayne@68 2420 and separated by a
jpayne@68 2421 .B |
jpayne@68 2422 character.
jpayne@68 2423 .PP
jpayne@68 2424 Each filter is printed on its own line.
jpayne@68 2425 .
jpayne@68 2426 .SS "Memory limit information"
jpayne@68 2427 .B "xz \-\-robot \-\-info\-memory"
jpayne@68 2428 prints a single line with multiple tab-separated columns:
jpayne@68 2429 .IP 1. 4
jpayne@68 2430 Total amount of physical memory (RAM) in bytes.
jpayne@68 2431 .IP 2. 4
jpayne@68 2432 Memory usage limit for compression in bytes
jpayne@68 2433 .RB ( \-\-memlimit\-compress ).
jpayne@68 2434 A special value of
jpayne@68 2435 .B 0
jpayne@68 2436 indicates the default setting
jpayne@68 2437 which for single-threaded mode is the same as no limit.
jpayne@68 2438 .IP 3. 4
jpayne@68 2439 Memory usage limit for decompression in bytes
jpayne@68 2440 .RB ( \-\-memlimit\-decompress ).
jpayne@68 2441 A special value of
jpayne@68 2442 .B 0
jpayne@68 2443 indicates the default setting
jpayne@68 2444 which for single-threaded mode is the same as no limit.
jpayne@68 2445 .IP 4. 4
jpayne@68 2446 Since
jpayne@68 2447 .B xz
jpayne@68 2448 5.3.4alpha:
jpayne@68 2449 Memory usage for multi-threaded decompression in bytes
jpayne@68 2450 .RB ( \-\-memlimit\-mt\-decompress ).
jpayne@68 2451 This is never zero because a system-specific default value
jpayne@68 2452 shown in the column 5
jpayne@68 2453 is used if no limit has been specified explicitly.
jpayne@68 2454 This is also never greater than the value in the column 3
jpayne@68 2455 even if a larger value has been specified with
jpayne@68 2456 .BR \-\-memlimit\-mt\-decompress .
jpayne@68 2457 .IP 5. 4
jpayne@68 2458 Since
jpayne@68 2459 .B xz
jpayne@68 2460 5.3.4alpha:
jpayne@68 2461 A system-specific default memory usage limit
jpayne@68 2462 that is used to limit the number of threads
jpayne@68 2463 when compressing with an automatic number of threads
jpayne@68 2464 .RB ( \-\-threads=0 )
jpayne@68 2465 and no memory usage limit has been specified
jpayne@68 2466 .RB ( \-\-memlimit\-compress ).
jpayne@68 2467 This is also used as the default value for
jpayne@68 2468 .BR \-\-memlimit\-mt\-decompress .
jpayne@68 2469 .IP 6. 4
jpayne@68 2470 Since
jpayne@68 2471 .B xz
jpayne@68 2472 5.3.4alpha:
jpayne@68 2473 Number of available processor threads.
jpayne@68 2474 .PP
jpayne@68 2475 In the future, the output of
jpayne@68 2476 .B "xz \-\-robot \-\-info\-memory"
jpayne@68 2477 may have more columns, but never more than a single line.
jpayne@68 2478 .
jpayne@68 2479 .SS Version
jpayne@68 2480 .B "xz \-\-robot \-\-version"
jpayne@68 2481 prints the version number of
jpayne@68 2482 .B xz
jpayne@68 2483 and liblzma in the following format:
jpayne@68 2484 .PP
jpayne@68 2485 .BI XZ_VERSION= XYYYZZZS
jpayne@68 2486 .br
jpayne@68 2487 .BI LIBLZMA_VERSION= XYYYZZZS
jpayne@68 2488 .TP
jpayne@68 2489 .I X
jpayne@68 2490 Major version.
jpayne@68 2491 .TP
jpayne@68 2492 .I YYY
jpayne@68 2493 Minor version.
jpayne@68 2494 Even numbers are stable.
jpayne@68 2495 Odd numbers are alpha or beta versions.
jpayne@68 2496 .TP
jpayne@68 2497 .I ZZZ
jpayne@68 2498 Patch level for stable releases or
jpayne@68 2499 just a counter for development releases.
jpayne@68 2500 .TP
jpayne@68 2501 .I S
jpayne@68 2502 Stability.
jpayne@68 2503 0 is alpha, 1 is beta, and 2 is stable.
jpayne@68 2504 .I S
jpayne@68 2505 should be always 2 when
jpayne@68 2506 .I YYY
jpayne@68 2507 is even.
jpayne@68 2508 .PP
jpayne@68 2509 .I XYYYZZZS
jpayne@68 2510 are the same on both lines if
jpayne@68 2511 .B xz
jpayne@68 2512 and liblzma are from the same XZ Utils release.
jpayne@68 2513 .PP
jpayne@68 2514 Examples: 4.999.9beta is
jpayne@68 2515 .B 49990091
jpayne@68 2516 and
jpayne@68 2517 5.0.0 is
jpayne@68 2518 .BR 50000002 .
jpayne@68 2519 .
jpayne@68 2520 .SH "EXIT STATUS"
jpayne@68 2521 .TP
jpayne@68 2522 .B 0
jpayne@68 2523 All is good.
jpayne@68 2524 .TP
jpayne@68 2525 .B 1
jpayne@68 2526 An error occurred.
jpayne@68 2527 .TP
jpayne@68 2528 .B 2
jpayne@68 2529 Something worth a warning occurred,
jpayne@68 2530 but no actual errors occurred.
jpayne@68 2531 .PP
jpayne@68 2532 Notices (not warnings or errors) printed on standard error
jpayne@68 2533 don't affect the exit status.
jpayne@68 2534 .
jpayne@68 2535 .SH ENVIRONMENT
jpayne@68 2536 .B xz
jpayne@68 2537 parses space-separated lists of options
jpayne@68 2538 from the environment variables
jpayne@68 2539 .B XZ_DEFAULTS
jpayne@68 2540 and
jpayne@68 2541 .BR XZ_OPT ,
jpayne@68 2542 in this order, before parsing the options from the command line.
jpayne@68 2543 Note that only options are parsed from the environment variables;
jpayne@68 2544 all non-options are silently ignored.
jpayne@68 2545 Parsing is done with
jpayne@68 2546 .BR getopt_long (3)
jpayne@68 2547 which is used also for the command line arguments.
jpayne@68 2548 .TP
jpayne@68 2549 .B XZ_DEFAULTS
jpayne@68 2550 User-specific or system-wide default options.
jpayne@68 2551 Typically this is set in a shell initialization script to enable
jpayne@68 2552 .BR xz 's
jpayne@68 2553 memory usage limiter by default.
jpayne@68 2554 Excluding shell initialization scripts
jpayne@68 2555 and similar special cases, scripts must never set or unset
jpayne@68 2556 .BR XZ_DEFAULTS .
jpayne@68 2557 .TP
jpayne@68 2558 .B XZ_OPT
jpayne@68 2559 This is for passing options to
jpayne@68 2560 .B xz
jpayne@68 2561 when it is not possible to set the options directly on the
jpayne@68 2562 .B xz
jpayne@68 2563 command line.
jpayne@68 2564 This is the case when
jpayne@68 2565 .B xz
jpayne@68 2566 is run by a script or tool, for example, GNU
jpayne@68 2567 .BR tar (1):
jpayne@68 2568 .RS
jpayne@68 2569 .RS
jpayne@68 2570 .PP
jpayne@68 2571 .nf
jpayne@68 2572 .ft CR
jpayne@68 2573 XZ_OPT=\-2v tar caf foo.tar.xz foo
jpayne@68 2574 .ft R
jpayne@68 2575 .fi
jpayne@68 2576 .RE
jpayne@68 2577 .RE
jpayne@68 2578 .IP ""
jpayne@68 2579 Scripts may use
jpayne@68 2580 .BR XZ_OPT ,
jpayne@68 2581 for example, to set script-specific default compression options.
jpayne@68 2582 It is still recommended to allow users to override
jpayne@68 2583 .B XZ_OPT
jpayne@68 2584 if that is reasonable.
jpayne@68 2585 For example, in
jpayne@68 2586 .BR sh (1)
jpayne@68 2587 scripts one may use something like this:
jpayne@68 2588 .RS
jpayne@68 2589 .RS
jpayne@68 2590 .PP
jpayne@68 2591 .nf
jpayne@68 2592 .ft CR
jpayne@68 2593 XZ_OPT=${XZ_OPT\-"\-7e"}
jpayne@68 2594 export XZ_OPT
jpayne@68 2595 .ft R
jpayne@68 2596 .fi
jpayne@68 2597 .RE
jpayne@68 2598 .RE
jpayne@68 2599 .
jpayne@68 2600 .SH "LZMA UTILS COMPATIBILITY"
jpayne@68 2601 The command line syntax of
jpayne@68 2602 .B xz
jpayne@68 2603 is practically a superset of
jpayne@68 2604 .BR lzma ,
jpayne@68 2605 .BR unlzma ,
jpayne@68 2606 and
jpayne@68 2607 .B lzcat
jpayne@68 2608 as found from LZMA Utils 4.32.x.
jpayne@68 2609 In most cases, it is possible to replace
jpayne@68 2610 LZMA Utils with XZ Utils without breaking existing scripts.
jpayne@68 2611 There are some incompatibilities though,
jpayne@68 2612 which may sometimes cause problems.
jpayne@68 2613 .
jpayne@68 2614 .SS "Compression preset levels"
jpayne@68 2615 The numbering of the compression level presets is not identical in
jpayne@68 2616 .B xz
jpayne@68 2617 and LZMA Utils.
jpayne@68 2618 The most important difference is how dictionary sizes
jpayne@68 2619 are mapped to different presets.
jpayne@68 2620 Dictionary size is roughly equal to the decompressor memory usage.
jpayne@68 2621 .RS
jpayne@68 2622 .PP
jpayne@68 2623 .TS
jpayne@68 2624 tab(;);
jpayne@68 2625 c c c
jpayne@68 2626 c n n.
jpayne@68 2627 Level;xz;LZMA Utils
jpayne@68 2628 \-0;256 KiB;N/A
jpayne@68 2629 \-1;1 MiB;64 KiB
jpayne@68 2630 \-2;2 MiB;1 MiB
jpayne@68 2631 \-3;4 MiB;512 KiB
jpayne@68 2632 \-4;4 MiB;1 MiB
jpayne@68 2633 \-5;8 MiB;2 MiB
jpayne@68 2634 \-6;8 MiB;4 MiB
jpayne@68 2635 \-7;16 MiB;8 MiB
jpayne@68 2636 \-8;32 MiB;16 MiB
jpayne@68 2637 \-9;64 MiB;32 MiB
jpayne@68 2638 .TE
jpayne@68 2639 .RE
jpayne@68 2640 .PP
jpayne@68 2641 The dictionary size differences affect
jpayne@68 2642 the compressor memory usage too,
jpayne@68 2643 but there are some other differences between
jpayne@68 2644 LZMA Utils and XZ Utils, which
jpayne@68 2645 make the difference even bigger:
jpayne@68 2646 .RS
jpayne@68 2647 .PP
jpayne@68 2648 .TS
jpayne@68 2649 tab(;);
jpayne@68 2650 c c c
jpayne@68 2651 c n n.
jpayne@68 2652 Level;xz;LZMA Utils 4.32.x
jpayne@68 2653 \-0;3 MiB;N/A
jpayne@68 2654 \-1;9 MiB;2 MiB
jpayne@68 2655 \-2;17 MiB;12 MiB
jpayne@68 2656 \-3;32 MiB;12 MiB
jpayne@68 2657 \-4;48 MiB;16 MiB
jpayne@68 2658 \-5;94 MiB;26 MiB
jpayne@68 2659 \-6;94 MiB;45 MiB
jpayne@68 2660 \-7;186 MiB;83 MiB
jpayne@68 2661 \-8;370 MiB;159 MiB
jpayne@68 2662 \-9;674 MiB;311 MiB
jpayne@68 2663 .TE
jpayne@68 2664 .RE
jpayne@68 2665 .PP
jpayne@68 2666 The default preset level in LZMA Utils is
jpayne@68 2667 .B \-7
jpayne@68 2668 while in XZ Utils it is
jpayne@68 2669 .BR \-6 ,
jpayne@68 2670 so both use an 8 MiB dictionary by default.
jpayne@68 2671 .
jpayne@68 2672 .SS "Streamed vs. non-streamed .lzma files"
jpayne@68 2673 The uncompressed size of the file can be stored in the
jpayne@68 2674 .B .lzma
jpayne@68 2675 header.
jpayne@68 2676 LZMA Utils does that when compressing regular files.
jpayne@68 2677 The alternative is to mark that uncompressed size is unknown
jpayne@68 2678 and use end-of-payload marker to indicate
jpayne@68 2679 where the decompressor should stop.
jpayne@68 2680 LZMA Utils uses this method when uncompressed size isn't known,
jpayne@68 2681 which is the case, for example, in pipes.
jpayne@68 2682 .PP
jpayne@68 2683 .B xz
jpayne@68 2684 supports decompressing
jpayne@68 2685 .B .lzma
jpayne@68 2686 files with or without end-of-payload marker, but all
jpayne@68 2687 .B .lzma
jpayne@68 2688 files created by
jpayne@68 2689 .B xz
jpayne@68 2690 will use end-of-payload marker and have uncompressed size
jpayne@68 2691 marked as unknown in the
jpayne@68 2692 .B .lzma
jpayne@68 2693 header.
jpayne@68 2694 This may be a problem in some uncommon situations.
jpayne@68 2695 For example, a
jpayne@68 2696 .B .lzma
jpayne@68 2697 decompressor in an embedded device might work
jpayne@68 2698 only with files that have known uncompressed size.
jpayne@68 2699 If you hit this problem, you need to use LZMA Utils
jpayne@68 2700 or LZMA SDK to create
jpayne@68 2701 .B .lzma
jpayne@68 2702 files with known uncompressed size.
jpayne@68 2703 .
jpayne@68 2704 .SS "Unsupported .lzma files"
jpayne@68 2705 The
jpayne@68 2706 .B .lzma
jpayne@68 2707 format allows
jpayne@68 2708 .I lc
jpayne@68 2709 values up to 8, and
jpayne@68 2710 .I lp
jpayne@68 2711 values up to 4.
jpayne@68 2712 LZMA Utils can decompress files with any
jpayne@68 2713 .I lc
jpayne@68 2714 and
jpayne@68 2715 .IR lp ,
jpayne@68 2716 but always creates files with
jpayne@68 2717 .B lc=3
jpayne@68 2718 and
jpayne@68 2719 .BR lp=0 .
jpayne@68 2720 Creating files with other
jpayne@68 2721 .I lc
jpayne@68 2722 and
jpayne@68 2723 .I lp
jpayne@68 2724 is possible with
jpayne@68 2725 .B xz
jpayne@68 2726 and with LZMA SDK.
jpayne@68 2727 .PP
jpayne@68 2728 The implementation of the LZMA1 filter in liblzma
jpayne@68 2729 requires that the sum of
jpayne@68 2730 .I lc
jpayne@68 2731 and
jpayne@68 2732 .I lp
jpayne@68 2733 must not exceed 4.
jpayne@68 2734 Thus,
jpayne@68 2735 .B .lzma
jpayne@68 2736 files, which exceed this limitation, cannot be decompressed with
jpayne@68 2737 .BR xz .
jpayne@68 2738 .PP
jpayne@68 2739 LZMA Utils creates only
jpayne@68 2740 .B .lzma
jpayne@68 2741 files which have a dictionary size of
jpayne@68 2742 .RI "2^" n
jpayne@68 2743 (a power of 2) but accepts files with any dictionary size.
jpayne@68 2744 liblzma accepts only
jpayne@68 2745 .B .lzma
jpayne@68 2746 files which have a dictionary size of
jpayne@68 2747 .RI "2^" n
jpayne@68 2748 or
jpayne@68 2749 .RI "2^" n " + 2^(" n "\-1)."
jpayne@68 2750 This is to decrease false positives when detecting
jpayne@68 2751 .B .lzma
jpayne@68 2752 files.
jpayne@68 2753 .PP
jpayne@68 2754 These limitations shouldn't be a problem in practice,
jpayne@68 2755 since practically all
jpayne@68 2756 .B .lzma
jpayne@68 2757 files have been compressed with settings that liblzma will accept.
jpayne@68 2758 .
jpayne@68 2759 .SS "Trailing garbage"
jpayne@68 2760 When decompressing,
jpayne@68 2761 LZMA Utils silently ignore everything after the first
jpayne@68 2762 .B .lzma
jpayne@68 2763 stream.
jpayne@68 2764 In most situations, this is a bug.
jpayne@68 2765 This also means that LZMA Utils
jpayne@68 2766 don't support decompressing concatenated
jpayne@68 2767 .B .lzma
jpayne@68 2768 files.
jpayne@68 2769 .PP
jpayne@68 2770 If there is data left after the first
jpayne@68 2771 .B .lzma
jpayne@68 2772 stream,
jpayne@68 2773 .B xz
jpayne@68 2774 considers the file to be corrupt unless
jpayne@68 2775 .B \-\-single\-stream
jpayne@68 2776 was used.
jpayne@68 2777 This may break obscure scripts which have
jpayne@68 2778 assumed that trailing garbage is ignored.
jpayne@68 2779 .
jpayne@68 2780 .SH NOTES
jpayne@68 2781 .
jpayne@68 2782 .SS "Compressed output may vary"
jpayne@68 2783 The exact compressed output produced from
jpayne@68 2784 the same uncompressed input file
jpayne@68 2785 may vary between XZ Utils versions even if
jpayne@68 2786 compression options are identical.
jpayne@68 2787 This is because the encoder can be improved
jpayne@68 2788 (faster or better compression)
jpayne@68 2789 without affecting the file format.
jpayne@68 2790 The output can vary even between different
jpayne@68 2791 builds of the same XZ Utils version,
jpayne@68 2792 if different build options are used.
jpayne@68 2793 .PP
jpayne@68 2794 The above means that once
jpayne@68 2795 .B \-\-rsyncable
jpayne@68 2796 has been implemented,
jpayne@68 2797 the resulting files won't necessarily be rsyncable
jpayne@68 2798 unless both old and new files have been compressed
jpayne@68 2799 with the same xz version.
jpayne@68 2800 This problem can be fixed if a part of the encoder
jpayne@68 2801 implementation is frozen to keep rsyncable output
jpayne@68 2802 stable across xz versions.
jpayne@68 2803 .
jpayne@68 2804 .SS "Embedded .xz decompressors"
jpayne@68 2805 Embedded
jpayne@68 2806 .B .xz
jpayne@68 2807 decompressor implementations like XZ Embedded don't necessarily
jpayne@68 2808 support files created with integrity
jpayne@68 2809 .I check
jpayne@68 2810 types other than
jpayne@68 2811 .B none
jpayne@68 2812 and
jpayne@68 2813 .BR crc32 .
jpayne@68 2814 Since the default is
jpayne@68 2815 .BR \-\-check=crc64 ,
jpayne@68 2816 you must use
jpayne@68 2817 .B \-\-check=none
jpayne@68 2818 or
jpayne@68 2819 .B \-\-check=crc32
jpayne@68 2820 when creating files for embedded systems.
jpayne@68 2821 .PP
jpayne@68 2822 Outside embedded systems, all
jpayne@68 2823 .B .xz
jpayne@68 2824 format decompressors support all the
jpayne@68 2825 .I check
jpayne@68 2826 types, or at least are able to decompress
jpayne@68 2827 the file without verifying the
jpayne@68 2828 integrity check if the particular
jpayne@68 2829 .I check
jpayne@68 2830 is not supported.
jpayne@68 2831 .PP
jpayne@68 2832 XZ Embedded supports BCJ filters,
jpayne@68 2833 but only with the default start offset.
jpayne@68 2834 .
jpayne@68 2835 .SH EXAMPLES
jpayne@68 2836 .
jpayne@68 2837 .SS Basics
jpayne@68 2838 Compress the file
jpayne@68 2839 .I foo
jpayne@68 2840 into
jpayne@68 2841 .I foo.xz
jpayne@68 2842 using the default compression level
jpayne@68 2843 .RB ( \-6 ),
jpayne@68 2844 and remove
jpayne@68 2845 .I foo
jpayne@68 2846 if compression is successful:
jpayne@68 2847 .RS
jpayne@68 2848 .PP
jpayne@68 2849 .nf
jpayne@68 2850 .ft CR
jpayne@68 2851 xz foo
jpayne@68 2852 .ft R
jpayne@68 2853 .fi
jpayne@68 2854 .RE
jpayne@68 2855 .PP
jpayne@68 2856 Decompress
jpayne@68 2857 .I bar.xz
jpayne@68 2858 into
jpayne@68 2859 .I bar
jpayne@68 2860 and don't remove
jpayne@68 2861 .I bar.xz
jpayne@68 2862 even if decompression is successful:
jpayne@68 2863 .RS
jpayne@68 2864 .PP
jpayne@68 2865 .nf
jpayne@68 2866 .ft CR
jpayne@68 2867 xz \-dk bar.xz
jpayne@68 2868 .ft R
jpayne@68 2869 .fi
jpayne@68 2870 .RE
jpayne@68 2871 .PP
jpayne@68 2872 Create
jpayne@68 2873 .I baz.tar.xz
jpayne@68 2874 with the preset
jpayne@68 2875 .B \-4e
jpayne@68 2876 .RB ( "\-4 \-\-extreme" ),
jpayne@68 2877 which is slower than the default
jpayne@68 2878 .BR \-6 ,
jpayne@68 2879 but needs less memory for compression and decompression (48\ MiB
jpayne@68 2880 and 5\ MiB, respectively):
jpayne@68 2881 .RS
jpayne@68 2882 .PP
jpayne@68 2883 .nf
jpayne@68 2884 .ft CR
jpayne@68 2885 tar cf \- baz | xz \-4e > baz.tar.xz
jpayne@68 2886 .ft R
jpayne@68 2887 .fi
jpayne@68 2888 .RE
jpayne@68 2889 .PP
jpayne@68 2890 A mix of compressed and uncompressed files can be decompressed
jpayne@68 2891 to standard output with a single command:
jpayne@68 2892 .RS
jpayne@68 2893 .PP
jpayne@68 2894 .nf
jpayne@68 2895 .ft CR
jpayne@68 2896 xz \-dcf a.txt b.txt.xz c.txt d.txt.lzma > abcd.txt
jpayne@68 2897 .ft R
jpayne@68 2898 .fi
jpayne@68 2899 .RE
jpayne@68 2900 .
jpayne@68 2901 .SS "Parallel compression of many files"
jpayne@68 2902 On GNU and *BSD,
jpayne@68 2903 .BR find (1)
jpayne@68 2904 and
jpayne@68 2905 .BR xargs (1)
jpayne@68 2906 can be used to parallelize compression of many files:
jpayne@68 2907 .RS
jpayne@68 2908 .PP
jpayne@68 2909 .nf
jpayne@68 2910 .ft CR
jpayne@68 2911 find . \-type f \e! \-name '*.xz' \-print0 \e
jpayne@68 2912 | xargs \-0r \-P4 \-n16 xz \-T1
jpayne@68 2913 .ft R
jpayne@68 2914 .fi
jpayne@68 2915 .RE
jpayne@68 2916 .PP
jpayne@68 2917 The
jpayne@68 2918 .B \-P
jpayne@68 2919 option to
jpayne@68 2920 .BR xargs (1)
jpayne@68 2921 sets the number of parallel
jpayne@68 2922 .B xz
jpayne@68 2923 processes.
jpayne@68 2924 The best value for the
jpayne@68 2925 .B \-n
jpayne@68 2926 option depends on how many files there are to be compressed.
jpayne@68 2927 If there are only a couple of files,
jpayne@68 2928 the value should probably be 1;
jpayne@68 2929 with tens of thousands of files,
jpayne@68 2930 100 or even more may be appropriate to reduce the number of
jpayne@68 2931 .B xz
jpayne@68 2932 processes that
jpayne@68 2933 .BR xargs (1)
jpayne@68 2934 will eventually create.
jpayne@68 2935 .PP
jpayne@68 2936 The option
jpayne@68 2937 .B \-T1
jpayne@68 2938 for
jpayne@68 2939 .B xz
jpayne@68 2940 is there to force it to single-threaded mode, because
jpayne@68 2941 .BR xargs (1)
jpayne@68 2942 is used to control the amount of parallelization.
jpayne@68 2943 .
jpayne@68 2944 .SS "Robot mode"
jpayne@68 2945 Calculate how many bytes have been saved in total
jpayne@68 2946 after compressing multiple files:
jpayne@68 2947 .RS
jpayne@68 2948 .PP
jpayne@68 2949 .nf
jpayne@68 2950 .ft CR
jpayne@68 2951 xz \-\-robot \-\-list *.xz | awk '/^totals/{print $5\-$4}'
jpayne@68 2952 .ft R
jpayne@68 2953 .fi
jpayne@68 2954 .RE
jpayne@68 2955 .PP
jpayne@68 2956 A script may want to know that it is using new enough
jpayne@68 2957 .BR xz .
jpayne@68 2958 The following
jpayne@68 2959 .BR sh (1)
jpayne@68 2960 script checks that the version number of the
jpayne@68 2961 .B xz
jpayne@68 2962 tool is at least 5.0.0.
jpayne@68 2963 This method is compatible with old beta versions,
jpayne@68 2964 which didn't support the
jpayne@68 2965 .B \-\-robot
jpayne@68 2966 option:
jpayne@68 2967 .RS
jpayne@68 2968 .PP
jpayne@68 2969 .nf
jpayne@68 2970 .ft CR
jpayne@68 2971 if ! eval "$(xz \-\-robot \-\-version 2> /dev/null)" ||
jpayne@68 2972 [ "$XZ_VERSION" \-lt 50000002 ]; then
jpayne@68 2973 echo "Your xz is too old."
jpayne@68 2974 fi
jpayne@68 2975 unset XZ_VERSION LIBLZMA_VERSION
jpayne@68 2976 .ft R
jpayne@68 2977 .fi
jpayne@68 2978 .RE
jpayne@68 2979 .PP
jpayne@68 2980 Set a memory usage limit for decompression using
jpayne@68 2981 .BR XZ_OPT ,
jpayne@68 2982 but if a limit has already been set, don't increase it:
jpayne@68 2983 .RS
jpayne@68 2984 .PP
jpayne@68 2985 .nf
jpayne@68 2986 .ft CR
jpayne@68 2987 NEWLIM=$((123 << 20))\ \ # 123 MiB
jpayne@68 2988 OLDLIM=$(xz \-\-robot \-\-info\-memory | cut \-f3)
jpayne@68 2989 if [ $OLDLIM \-eq 0 \-o $OLDLIM \-gt $NEWLIM ]; then
jpayne@68 2990 XZ_OPT="$XZ_OPT \-\-memlimit\-decompress=$NEWLIM"
jpayne@68 2991 export XZ_OPT
jpayne@68 2992 fi
jpayne@68 2993 .ft R
jpayne@68 2994 .fi
jpayne@68 2995 .RE
jpayne@68 2996 .
jpayne@68 2997 .SS "Custom compressor filter chains"
jpayne@68 2998 The simplest use for custom filter chains is
jpayne@68 2999 customizing a LZMA2 preset.
jpayne@68 3000 This can be useful,
jpayne@68 3001 because the presets cover only a subset of the
jpayne@68 3002 potentially useful combinations of compression settings.
jpayne@68 3003 .PP
jpayne@68 3004 The CompCPU columns of the tables
jpayne@68 3005 from the descriptions of the options
jpayne@68 3006 .BR "\-0" " ... " "\-9"
jpayne@68 3007 and
jpayne@68 3008 .B \-\-extreme
jpayne@68 3009 are useful when customizing LZMA2 presets.
jpayne@68 3010 Here are the relevant parts collected from those two tables:
jpayne@68 3011 .RS
jpayne@68 3012 .PP
jpayne@68 3013 .TS
jpayne@68 3014 tab(;);
jpayne@68 3015 c c
jpayne@68 3016 n n.
jpayne@68 3017 Preset;CompCPU
jpayne@68 3018 \-0;0
jpayne@68 3019 \-1;1
jpayne@68 3020 \-2;2
jpayne@68 3021 \-3;3
jpayne@68 3022 \-4;4
jpayne@68 3023 \-5;5
jpayne@68 3024 \-6;6
jpayne@68 3025 \-5e;7
jpayne@68 3026 \-6e;8
jpayne@68 3027 .TE
jpayne@68 3028 .RE
jpayne@68 3029 .PP
jpayne@68 3030 If you know that a file requires
jpayne@68 3031 somewhat big dictionary (for example, 32\ MiB) to compress well,
jpayne@68 3032 but you want to compress it quicker than
jpayne@68 3033 .B "xz \-8"
jpayne@68 3034 would do, a preset with a low CompCPU value (for example, 1)
jpayne@68 3035 can be modified to use a bigger dictionary:
jpayne@68 3036 .RS
jpayne@68 3037 .PP
jpayne@68 3038 .nf
jpayne@68 3039 .ft CR
jpayne@68 3040 xz \-\-lzma2=preset=1,dict=32MiB foo.tar
jpayne@68 3041 .ft R
jpayne@68 3042 .fi
jpayne@68 3043 .RE
jpayne@68 3044 .PP
jpayne@68 3045 With certain files, the above command may be faster than
jpayne@68 3046 .B "xz \-6"
jpayne@68 3047 while compressing significantly better.
jpayne@68 3048 However, it must be emphasized that only some files benefit from
jpayne@68 3049 a big dictionary while keeping the CompCPU value low.
jpayne@68 3050 The most obvious situation,
jpayne@68 3051 where a big dictionary can help a lot,
jpayne@68 3052 is an archive containing very similar files
jpayne@68 3053 of at least a few megabytes each.
jpayne@68 3054 The dictionary size has to be significantly bigger
jpayne@68 3055 than any individual file to allow LZMA2 to take
jpayne@68 3056 full advantage of the similarities between consecutive files.
jpayne@68 3057 .PP
jpayne@68 3058 If very high compressor and decompressor memory usage is fine,
jpayne@68 3059 and the file being compressed is
jpayne@68 3060 at least several hundred megabytes, it may be useful
jpayne@68 3061 to use an even bigger dictionary than the 64 MiB that
jpayne@68 3062 .B "xz \-9"
jpayne@68 3063 would use:
jpayne@68 3064 .RS
jpayne@68 3065 .PP
jpayne@68 3066 .nf
jpayne@68 3067 .ft CR
jpayne@68 3068 xz \-vv \-\-lzma2=dict=192MiB big_foo.tar
jpayne@68 3069 .ft R
jpayne@68 3070 .fi
jpayne@68 3071 .RE
jpayne@68 3072 .PP
jpayne@68 3073 Using
jpayne@68 3074 .B \-vv
jpayne@68 3075 .RB ( "\-\-verbose \-\-verbose" )
jpayne@68 3076 like in the above example can be useful
jpayne@68 3077 to see the memory requirements
jpayne@68 3078 of the compressor and decompressor.
jpayne@68 3079 Remember that using a dictionary bigger than
jpayne@68 3080 the size of the uncompressed file is waste of memory,
jpayne@68 3081 so the above command isn't useful for small files.
jpayne@68 3082 .PP
jpayne@68 3083 Sometimes the compression time doesn't matter,
jpayne@68 3084 but the decompressor memory usage has to be kept low, for example,
jpayne@68 3085 to make it possible to decompress the file on an embedded system.
jpayne@68 3086 The following command uses
jpayne@68 3087 .B \-6e
jpayne@68 3088 .RB ( "\-6 \-\-extreme" )
jpayne@68 3089 as a base and sets the dictionary to only 64\ KiB.
jpayne@68 3090 The resulting file can be decompressed with XZ Embedded
jpayne@68 3091 (that's why there is
jpayne@68 3092 .BR \-\-check=crc32 )
jpayne@68 3093 using about 100\ KiB of memory.
jpayne@68 3094 .RS
jpayne@68 3095 .PP
jpayne@68 3096 .nf
jpayne@68 3097 .ft CR
jpayne@68 3098 xz \-\-check=crc32 \-\-lzma2=preset=6e,dict=64KiB foo
jpayne@68 3099 .ft R
jpayne@68 3100 .fi
jpayne@68 3101 .RE
jpayne@68 3102 .PP
jpayne@68 3103 If you want to squeeze out as many bytes as possible,
jpayne@68 3104 adjusting the number of literal context bits
jpayne@68 3105 .RI ( lc )
jpayne@68 3106 and number of position bits
jpayne@68 3107 .RI ( pb )
jpayne@68 3108 can sometimes help.
jpayne@68 3109 Adjusting the number of literal position bits
jpayne@68 3110 .RI ( lp )
jpayne@68 3111 might help too, but usually
jpayne@68 3112 .I lc
jpayne@68 3113 and
jpayne@68 3114 .I pb
jpayne@68 3115 are more important.
jpayne@68 3116 For example, a source code archive contains mostly US-ASCII text,
jpayne@68 3117 so something like the following might give
jpayne@68 3118 slightly (like 0.1\ %) smaller file than
jpayne@68 3119 .B "xz \-6e"
jpayne@68 3120 (try also without
jpayne@68 3121 .BR lc=4 ):
jpayne@68 3122 .RS
jpayne@68 3123 .PP
jpayne@68 3124 .nf
jpayne@68 3125 .ft CR
jpayne@68 3126 xz \-\-lzma2=preset=6e,pb=0,lc=4 source_code.tar
jpayne@68 3127 .ft R
jpayne@68 3128 .fi
jpayne@68 3129 .RE
jpayne@68 3130 .PP
jpayne@68 3131 Using another filter together with LZMA2 can improve
jpayne@68 3132 compression with certain file types.
jpayne@68 3133 For example, to compress a x86-32 or x86-64 shared library
jpayne@68 3134 using the x86 BCJ filter:
jpayne@68 3135 .RS
jpayne@68 3136 .PP
jpayne@68 3137 .nf
jpayne@68 3138 .ft CR
jpayne@68 3139 xz \-\-x86 \-\-lzma2 libfoo.so
jpayne@68 3140 .ft R
jpayne@68 3141 .fi
jpayne@68 3142 .RE
jpayne@68 3143 .PP
jpayne@68 3144 Note that the order of the filter options is significant.
jpayne@68 3145 If
jpayne@68 3146 .B \-\-x86
jpayne@68 3147 is specified after
jpayne@68 3148 .BR \-\-lzma2 ,
jpayne@68 3149 .B xz
jpayne@68 3150 will give an error,
jpayne@68 3151 because there cannot be any filter after LZMA2,
jpayne@68 3152 and also because the x86 BCJ filter cannot be used
jpayne@68 3153 as the last filter in the chain.
jpayne@68 3154 .PP
jpayne@68 3155 The Delta filter together with LZMA2
jpayne@68 3156 can give good results with bitmap images.
jpayne@68 3157 It should usually beat PNG,
jpayne@68 3158 which has a few more advanced filters than simple
jpayne@68 3159 delta but uses Deflate for the actual compression.
jpayne@68 3160 .PP
jpayne@68 3161 The image has to be saved in uncompressed format,
jpayne@68 3162 for example, as uncompressed TIFF.
jpayne@68 3163 The distance parameter of the Delta filter is set
jpayne@68 3164 to match the number of bytes per pixel in the image.
jpayne@68 3165 For example, 24-bit RGB bitmap needs
jpayne@68 3166 .BR dist=3 ,
jpayne@68 3167 and it is also good to pass
jpayne@68 3168 .B pb=0
jpayne@68 3169 to LZMA2 to accommodate the three-byte alignment:
jpayne@68 3170 .RS
jpayne@68 3171 .PP
jpayne@68 3172 .nf
jpayne@68 3173 .ft CR
jpayne@68 3174 xz \-\-delta=dist=3 \-\-lzma2=pb=0 foo.tiff
jpayne@68 3175 .ft R
jpayne@68 3176 .fi
jpayne@68 3177 .RE
jpayne@68 3178 .PP
jpayne@68 3179 If multiple images have been put into a single archive (for example,
jpayne@68 3180 .BR .tar ),
jpayne@68 3181 the Delta filter will work on that too as long as all images
jpayne@68 3182 have the same number of bytes per pixel.
jpayne@68 3183 .
jpayne@68 3184 .SH "SEE ALSO"
jpayne@68 3185 .BR xzdec (1),
jpayne@68 3186 .BR xzdiff (1),
jpayne@68 3187 .BR xzgrep (1),
jpayne@68 3188 .BR xzless (1),
jpayne@68 3189 .BR xzmore (1),
jpayne@68 3190 .BR gzip (1),
jpayne@68 3191 .BR bzip2 (1),
jpayne@68 3192 .BR 7z (1)
jpayne@68 3193 .PP
jpayne@68 3194 XZ Utils: <https://tukaani.org/xz/>
jpayne@68 3195 .br
jpayne@68 3196 XZ Embedded: <https://tukaani.org/xz/embedded.html>
jpayne@68 3197 .br
jpayne@68 3198 LZMA SDK: <https://7-zip.org/sdk.html>