From 009823448b82aa5f465668878a544c5842885407 Mon Sep 17 00:00:00 2001 From: Lasse Collin Date: Tue, 16 Dec 2014 20:57:43 +0200 Subject: [PATCH] xz: Update the man page about --block-size. --- src/xz/xz.1 | 41 +++++++++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 8 deletions(-) diff --git a/src/xz/xz.1 b/src/xz/xz.1 index 49b07784..a006bc45 100644 --- a/src/xz/xz.1 +++ b/src/xz/xz.1 @@ -5,7 +5,7 @@ .\" This file has been put into the public domain. .\" You can do whatever you want with this file. .\" -.TH XZ 1 "2013-11-12" "Tukaani" "XZ Utils" +.TH XZ 1 "2014-12-16" "Tukaani" "XZ Utils" . .SH NAME xz, unxz, xzcat, lzma, unlzma, lzcat \- Compress or decompress .xz and .lzma files @@ -826,14 +826,39 @@ When compressing to the format, split the input data into blocks of .I size bytes. -The blocks are compressed independently from each other. -.\" FIXME: Explain how to these can be used for random access and threading. +The blocks are compressed independently from each other, +which helps with multi-threading and +makes limited random-access decompression possible. +This option is typically used to override the default +block size in multi-threaded mode, +but this option can be used in single-threaded mode too. .IP "" -In multi-threaded mode the sizes of the blocks -are stored in the block headers. -This isn't done in single-threaded mode, -so the encoded output won't be -identical to that of the multi-threaded mode. +In multi-threaded mode about three times +.I size +bytes will be allocated in each thread for buffering input and output. +The default +.I size +is three times the LZMA2 dictionary size or 1 MiB, +whichever is more. +Typically a good value is 2\-4 times +the size of the LZMA2 dictionary or at least 1 MiB. +Using +.I size +less than the LZMA2 dictionary size is waste of RAM +because then the LZMA2 dictionary buffer will never get fully used. +The sizes of the blocks are stored in the block headers, +which a future version of +.B xz +will use for multi-threaded decompression. +.IP "" +In single-threaded mode no block splitting is done by default. +Setting this option doesn't affect memory usage. +No size information is stored in block headers, +thus files created in single-threaded mode +won't be identical to files created in multi-threaded mode. +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 When compressing to the