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