:: bzip3 / bzip3.1.in 5.0 KB raw

.TH @TRANSFORMED_PACKAGE_NAME@ 1 "@MAN_DATE@" "version v@VERSION@"

.

.SH NAME

@TRANSFORMED_PACKAGE_NAME@ \- an efficient statistical file compressor and spiritual successor

to bzip2

​

.SH SYNOPSIS

.B @TRANSFORMED_PACKAGE_NAME@

.RB [ " \-BbcdehftV " ]

[

.I "filenames \&..."

]

.

.P

.B bz3cat

is equivalent to

.B @TRANSFORMED_PACKAGE_NAME@ \-dc

.P

.B bunzip3

is equivalent to

.B @TRANSFORMED_PACKAGE_NAME@ \-d

.SH DESCRIPTION

Compress or decompress a file using run length encoding and Lempel Ziv

prediction, followed by the Burrows-Wheeler transform and arithmetic

coding.

.B @TRANSFORMED_PACKAGE_NAME@,

like its ancestor

.B bzip2,

excels at compressing text or source code.

​

The command-line options are deliberately very similar to

those of

.B bzip2,

but they are not identical.

.PP

.B @TRANSFORMED_PACKAGE_NAME@

expects at most two filenames intertwined with flags.

.B @TRANSFORMED_PACKAGE_NAME@

will by default not overwrite existing files.

If this behaviour is intended, use the \-f flag.

​

If no file names are specified,

.B @TRANSFORMED_PACKAGE_NAME@

will compress from standard input to standard output, refusing

to output binary data to a terminal. The \-e flag (encode) is implied.

​

.B bunzip3

(or,

.B @TRANSFORMED_PACKAGE_NAME@ \-d

equivalently) decompresses data from standard input to the standard

output, refusing to read from a terminal.

​

If two files are specified, the first one is used in place of

standard input, and the second one is used in place of standard

output.

​

If the \-c flag is present, @TRANSFORMED_PACKAGE_NAME@ will read from the specified

file and output data to standard output instead. Otherwise, if decoding,

.B @TRANSFORMED_PACKAGE_NAME@

will try to guess the decompressed filename by removing the

.I .bz3

extension. If not present, an error will be reported. If encoding,

the output filename will be generated by appending the

.I .bz3

extension to the input filename.

​

.SH OPTIONS

.TP

.B \-B --batch

Enable batch mode. By default,

.B @TRANSFORMED_PACKAGE_NAME@

will error if more than two files are passed, and the two files specified

are always treated as input and output. The batch mode makes

.B @TRANSFORMED_PACKAGE_NAME@

treat every file as input, so for example

.I @TRANSFORMED_PACKAGE_NAME@ -Bd *.bz3

will decompress all

.I .bz3

files in the current directory.

.TP

.B \-b --block N

Set the block size to N mebibytes. The minimum is 1MiB, the maximum is

511MiB. The default is 16MiB.

.TP

.B \-c --stdout

Force writing output data to the standard output if one file is

specified.

.TP

.B \-d --decode

Force decompression.

.TP

.B \-e/-z --encode

Force compression (default behaviour).

.TP

.B \-f --force

Overwrite existing files.

.TP

.B \-h --help

Display a help message and exit.

.TP

.B \-j --jobs N

Set the amount of parallel worker threads that process one block each. Default

is to use 1 worker thread.

.TP

.B \--rm

Remove the input files after successful compression or decompression. This is

silently ignored if output is stdout.

.TP

.B \-k --keep

Keep (don't delete) the input files. Set by default, provided only

for compatibility with other compressors.

.TP

.B \-v --verbose

Set verbose output mode to see compression statistics.

.TP

.B \-V --version

Display version information and exit.

.TP

.B \-t --test

Verify the validity of compressed blocks.

.TP

.B \--

Treat all subsequent arguments as file names, even if they start with

a dash. This is so you can handle files with names beginning with a dash.

.SH FILE FORMAT

​

Compression is performed as long as the input block is longer

than 64 bytes. Otherwise, it's coded as a literal block. In all

other cases, the compressed data is written to the file. The

file format has constant overhead of 9 bytes per file and from

9 to 17 bytes per block. Random data is coded so that expansion

is generally under 0.8%.

​

.B @TRANSFORMED_PACKAGE_NAME@

uses 32-bit CRC to ensure that the decompressed version of a file is

identical to the original. This guards against corruption of the

compressed data. 

​

.SH MEMORY MANAGEMENT

​

The \-b flag sets the block size in mebibytes (MiB). The default is 16

MiB. Compression and decompression memory usage can be estimated as:

​

       6 x block size

​

Larger block sizes usually give rapidly diminishing returns.

It is also important to appreciate that the decompression memory

requirement is set at compression time by the choice of block size.

In general, try and use the largest block size memory constraints allow,

since that maximises the compression achieved.  Compression and

decompression speed are virtually unaffected by block size.

​

.SH AUTHOR

Kamila Szewczyk, k@iczelia.net.

​

https://github.com/iczelia/bzip3

​

Thanks to: Ilya Grebnov, Benjamin Strachan, Caleb Maclennan, Ilya Muravyov,

package maintainers - Leah Neukirchen, Grigory Kirillov, Maciej Barc, 

Robert Schutz, Petr Pisar, Przemyslaw Skibinski, Shun Sakai and others.

Also everyone who sent patches, helped with portability problems, encouraged

me to work on bzip3 and lent me machines for performance tests.

​

.SH "SEE ALSO"

\fBbzip2(1)\fR, \fBbz3less(1)\fR, \fBbz3more(1)\fR, \fBbz3grep(1)\fR, \fBbunzip3(1)\fR