aboutsummaryrefslogtreecommitdiff
path: root/src/xz
diff options
context:
space:
mode:
Diffstat (limited to 'src/xz')
-rw-r--r--src/xz/xz.1106
1 files changed, 80 insertions, 26 deletions
diff --git a/src/xz/xz.1 b/src/xz/xz.1
index 004add7a..d8025a27 100644
--- a/src/xz/xz.1
+++ b/src/xz/xz.1
@@ -915,36 +915,77 @@ The lack of size information also means that a future version of
.B xz
won't be able decompress the files in multi-threaded mode.
.TP
-.BI \-\-block\-list= sizes
+.BI \-\-block\-list= items
When compressing to the
.B .xz
-format, start a new block after
+format, start a new block with an optional custom filter chain after
the given intervals of uncompressed data.
.IP ""
-The uncompressed
-.I sizes
-of the blocks are specified as a comma-separated list.
-Omitting a size (two or more consecutive commas) is a shorthand
-to use the size of the previous block.
+The
+.I items
+are a comma-separated list.
+Each item consists of an optional filter chain number
+between 0 and 9 followed by a colon
+.RB ( : )
+and a required size of uncompressed data.
+Omitting an item (two or more consecutive commas) is a
+shorthand to use the size and filters of the previous item.
.IP ""
If the input file is bigger than the sum of
-.IR sizes ,
-the last value in
-.I sizes
-is repeated until the end of the file.
+the sizes in
+.IR items ,
+the last item is repeated until the end of the file.
A special value of
.B 0
-may be used as the last value to indicate that
+may be used as the last size to indicate that
the rest of the file should be encoded as a single block.
.IP ""
-If one specifies
-.I sizes
-that exceed the encoder's block size
+An alternative custom filter chain for each block can be
+specified in combination with the
+.BI \-\-filters1= filters
+\&...\&
+.BI \-\-filters9= filters
+options.
+These options define filter chains with an identifier
+between 1\(en9.
+Filter chain 0 can be used to refer to the default filter chain,
+which is the same as not specifying a filter chain.
+The filter chain identifier can be used before the uncompressed
+size, followed by a colon
+.RB ( : ).
+For example, if one specifies
+.B \-\-block\-list=1:2MiB,3:2MiB,2:4MiB,,2MiB,0:4MiB
+then blocks will be created using:
+.RS
+.IP \(bu 3
+The filter chain specified by
+.B \-\-filters1
+and 2 MiB input
+.IP \(bu 3
+The filter chain specified by
+.B \-\-filters3
+and 2 MiB input
+.IP \(bu 3
+The filter chain specified by
+.B \-\-filters2
+and 4 MiB input
+.IP \(bu 3
+The filter chain specified by
+.B \-\-filters2
+and 4 MiB input
+.IP \(bu 3
+The default filter chain and 2 MiB input
+.IP \(bu 3
+The default filter chain and 4 MiB input for every block until
+end of input.
+.RE
+.IP ""
+If one specifies a size that exceeds the encoder's block size
(either the default value in threaded mode or
the value specified with \fB\-\-block\-size=\fIsize\fR),
the encoder will create additional blocks while
keeping the boundaries specified in
-.IR sizes .
+.IR items .
For example, if one specifies
.B \-\-block\-size=10MiB
.B \-\-block\-list=5MiB,10MiB,8MiB,12MiB,24MiB
@@ -1295,18 +1336,24 @@ in the chain.
Depending on the filter, this limitation is either inherent to
the filter design or exists to prevent security issues.
.PP
-A custom filter chain is specified in two different ways.
-The option
+A custom filter chain can be specified in two different ways.
+The options
.BI \-\-filters= filters
-allows specifying the entire filter chain in one option.
-Alternatively, filter chains can be specified by using one or more
+and
+.BI \-\-filters1= filters
+\&...\&
+.BI \-\-filters9= filters
+allows specifying an entire filter chain in one option using the
+liblzma filter string syntax.
+Alternatively, a filter chain can be specified by using one or more
individual filter options in the order they are wanted in the filter chain.
-That is, the order of individual filter options is significant!
+That is, the order of the individual filter options is significant!
When decoding raw streams
.RB ( \-\-format=raw ),
the filter chain must be specified in the same order as
it was specified when compressing.
-Any individual filters or presets specified before the full chain option
+Any individual filter or preset options specified before the full
+chain option
(\fB\-\-filters=\fIfilters\fR)
will be forgotten.
Individual filters specified after the full chain option will reset the
@@ -1318,8 +1365,8 @@ as a comma-separated list.
Extra commas in
.I options
are ignored.
-Every option has a default value, so you need to
-specify only those you want to change.
+Every option has a default value, so
+specify those you want to change.
.PP
To see the whole filter chain and
.IR options ,
@@ -1330,8 +1377,7 @@ use
twice).
This works also for viewing the filter chain options used by presets.
.TP
-\fB\-\-filters\fR\fB=\fIfilters\fR
-.PD
+.BI \-\-filters= filters
Specify the full filter chain or a preset in a single option.
Each filter can be separated by spaces or two dashes
.RB ( \-\- ).
@@ -1352,6 +1398,14 @@ The only supported flag is
to apply the same options as
.BR \-\-extreme .
.TP
+\fB\-\-filters1\fR=\fIfilters\fR ... \fB\-\-filters9\fR=\fIfilters
+Specify up to nine additional filter chains that can be used with
+.BR \-\-block\-list .
+.IP ""
+For example, when compressing an archive with executable files
+followed by text files, the executable part could use a filter
+chain with a BCJ filter and the text part only the LZMA2 filter.
+.TP
\fB\-\-lzma1\fR[\fB=\fIoptions\fR]
.PD 0
.TP