Ubuntu Manpage: lbzip2 - parallel bzip2 utility

NAME

       lbzip2 - parallel bzip2 utility

SYNOPSIS

       lbzip2|bzip2 [-n WTHRS] [-k|-c|-t] [-d] [-1 .. -9] [-f] [-v] [-S] [ FILE ... ]

       lbunzip2|bunzip2 [-n WTHRS] [-k|-c|-t] [-z] [-f] [-v] [-S] [ FILE ... ]

       lbzcat|bzcat [-n WTHRS] [-z] [-f] [-v] [-S] [ FILE ... ]

       lbzip2|bzip2|lbunzip2|bunzip2|lbzcat|bzcat -h

DESCRIPTION

       Compress  or  decompress  FILE  operands  or standard input to regular files or standard output using the
       Burrows-Wheeler block-sorting text compression algorithm. The lbzip2 utility employs multiple threads and
       an input-bound splitter even when decompressing .bz2 files created by standard bzip2.

       Compression is generally considerably better than that  achieved  by  more  conventional  LZ77/LZ78-based
       compressors, and competitive with all but the best of the PPM family of statistical compressors.

       Compression  is  always  performed, even if the compressed file is slightly larger than the original. The
       worst case expansion is for files of zero length, which expand to fourteen bytes. Random data  (including
       the output of most file compressors) is coded with asymptotic expansion of around 0.5%.

       The  command-line  options  are  deliberately  very  similar to those of bzip2 and gzip, but they are not
       identical.

INVOCATION

       The default mode of operation is compression. If the utility is invoked as lbunzip2 or bunzip2, the  mode
       is  switched  to  decompression.  Calling  the utility as lbzcat or bzcat selects decompression, with the
       decompressed byte-stream written to standard output.

OPTIONS

-n WTHRS
Set the number of (de)compressor threads to WTHRS. If this option is not specified, lbzip2 tries
to query the system for the number of online processors (if both the compilation environment and
the execution environment support that), or exits with an error (if it's unable to determine the
number of processors online).

-k, --keep
Don't remove FILE operands after successful (de)compression. Open regular input files with more
than one link.

-c, --stdout
Write output to standard output, even when FILE operands are present. Implies -k and excludes -t.

-t, --test
Test decompression; discard output instead of writing it to files or standard output. Implies -k
and excludes -c. Roughly equivalent to passing -c and redirecting standard output to the bit
bucket.

-d, --decompress
Force decompression over the mode of operation selected by the invocation name.

-z, --compress
Force compression over the mode of operation selected by the invocation name.

-1 .. -9
Set the compression block size to 100K .. 900K, in 100K increments. Ignored during decompression.
See also the BLOCK SIZE section below.

--fast Alias for -1.

--best Alias for -9. This is the default.

-f, --force
Open non-regular input files. Open input files with more than one link, breaking links when -k
isn't specified in addition. Try to remove each output file before opening it. By default lbzip2
will not overwrite existing files; if you want this to happen, you should specify -f. If -c and
-d are also given don't reject files not in bzip2 format, just copy them without change; without
-f lbzip2 would stop after reaching a file that is not in bzip2 format.

-v, --verbose
Be more verbose. Print more detailed information about (de)compression progress to standard error:
before processing each file, print a message stating the names of input and output files; during
(de)compression, print a rough percentage of completeness and estimated time of arrival (only if
standard error is connected to a terminal); after processing each file print a message showing
compression ratio, space savings, total compression time (wall time) and average (de)compression
speed (bytes of plain data processed per second).

-S Print condition variable statistics to standard error for each completed (de)compression
operation. Useful in profiling.

-s, --small, -q, --quiet, --repetitive-fast, --repetitive-best, --exponential
Accepted for compatibility with bzip2, otherwise ignored.

-h, --help
Print help on command-line usage on standard output and exit successfully.

-L, --license, -V, --version
Print license and version information on standard output and exit successfully.

ENVIRONMENT

       LBZIP2, BZIP2, BZIP
              Before  parsing  the  command  line,  lbzip2 inserts the contents of these variables, in the order
              specified, between the invocation name and the rest of the command line. Tokens are  separated  by
              spaces and tabs, which cannot be escaped.

OPERANDS

       FILE   Specify files to compress or decompress.

              FILEs  with  .bz2,  .tbz,  .tbz2  and  .tz2  name  suffixes will be skipped when compressing. When
              decompressing, .bz2 suffixes will be removed in output filenames; .tbz, .tbz2  and  .tz2  suffixes
              will  be replaced by .tar; other filenames will be suffixed with .out. If an INT or TERM signal is
              delivered to lbzip2, then it removes the regular output file currently open before exiting.

              If no FILE is given, lbzip2 works as a filter, processing standard input to  standard  output.  In
              this  case, lbzip2 will decline to write compressed output to a terminal (or read compressed input
              from a terminal), as this would be entirely incomprehensible and therefore pointless.

EXIT STATUS

       0      if lbzip2 finishes successfully. This presumes that whenever it tries, lbzip2 never fails to write
              to standard error.

       1      if lbzip2 encounters a fatal error.

       4      if lbzip2 issues warnings without encountering a fatal  error.  This  presumes  that  whenever  it
              tries, lbzip2 never fails to write to standard error.

       SIGPIPE, SIGXFSZ
              if lbzip2 intends to exit with status 1 due to any fatal error, but any such signal with inherited
              SIG_DFL  action  was generated for lbzip2 previously, then lbzip2 terminates by way of one of said
              signals, after cleaning up any interrupted output file.

       SIGABRT
              if a runtime assertion fails (i.e.  lbzip2 detects a bug in itself).  Hopefully  whoever  compiled
              your binary wasn't bold enough to #define NDEBUG.

       SIGINT, SIGTERM
              lbzip2  catches  these  signals  so  that it can remove an interrupted output file. In such cases,
              lbzip2 exits by re-raising (one of) the received signal(s).

BLOCK SIZE

lbzip2 compresses large files in blocks. It can operate at various block sizes, ranging from 100k to 900k
in 100k steps, and it allocates only as much memory as it needs to. The block size affects both the
compression ratio achieved, and the amount of memory needed both for compression and decompression.
Compression and decompression speed is virtually unaffected by block size, provided that the file being
processed is large enough to be split among all worker threads.

The flags -1 through -9 specify the block size to be 100,000 bytes through 900,000 bytes (the default)
respectively. At decompression-time, the block size used for compression is read from the compressed file
-- the flags -1 to -9 are irrelevant to and so ignored during decompression.

Larger block sizes give rapidly diminishing marginal returns; most of the compression comes from the
first two or three hundred k of block size, a fact worth bearing in mind when using lbzip2 on small
machines. It is also important to appreciate that the decompression memory requirement is set at
compression-time by the choice of block size. In general you should try and use the largest block size
memory constraints allow.

Another significant point applies to small files. By design, only one of lbzip2's worker threads can work
on a single block. This means that if the number of blocks in the compressed file is less than the number
of processors online, then some of worker threads will remain idle for the entire time. Compressing small
files with smaller block sizes can therefore significantly increase both compression and decompression
speed. The speed difference is more noticeable as the number of CPU cores grows.

ERROR HANDLING

       Dealing with error conditions is the least satisfactory aspect of lbzip2.  The policy is to try and leave
       the  filesystem  in  a  consistent  state,  then  quit, even if it means not processing some of the files
       mentioned in the command line.

       `A consistent state' means that a file exists either in its compressed  or  uncompressed  form,  but  not
       both. This boils down to the rule `delete the output file if an error condition occurs, leaving the input
       intact'.  Input  files  are  only deleted when we can be pretty sure the output file has been written and
       closed successfully.

RESOURCE ALLOCATION

       lbzip2 needs various kinds of system resources to operate. Those include  memory,  threads,  mutexes  and
       condition variables. The policy is to simply give up if a resource allocation failure occurs.

       Resource  consumption  grows  linearly  with number of worker threads. If lbzip2 fails because of lack of
       some resources, decreasing number of worker threads may help. It would be possible for lbzip2 to  try  to
       reduce  number  of worker threads (and hence the resource consumption), or to move on to subsequent files
       in the hope that some might need less resources, but the complications for doing this seem  more  trouble
       than they are worth.

DAMAGED FILES

lbzip2 attempts to compress data by performing several non-trivial transformations on it. Every
compression of a file implies an assumption that the compressed file can be decompressed to reproduce the
original. Great efforts in design, coding and testing have been made to ensure that this program works
correctly. However, the complexity of the algorithms, and, in particular, the presence of various
special cases in the code which occur with very low but non-zero probability make it very difficult to
rule out the possibility of bugs remaining in the program. That is not to say this program is inherently
unreliable. Indeed, I very much hope the opposite is true -- lbzip2 has been carefully constructed and
extensively tested.

As a self-check for your protection, lbzip2 uses 32-bit CRCs to make sure that the decompressed version
of a file is identical to the original. This guards against corruption of the compressed data, and
against undiscovered bugs in lbzip2 (hopefully unlikely). The chances of data corruption going undetected
is microscopic, about one chance in four billion for each file processed. Be aware, though, that the
check occurs upon decompression, so it can only tell you that that something is wrong.

CRCs can only detect corrupted files, they can't help you recover the original, uncompressed data.
However, because of the block nature of the compression algorithm, it may be possible to recover some
parts of the damaged file, even if some blocks are destroyed.

BUGS

       Separate input files don't share worker threads; at most one input file is worked on at any moment.

AUTHORS

       lbzip2 was originally written by Laszlo Ersek <lacos@caesar.elte.hu>, http://lacos.hu/. Versions 2.0  and
       later were written by Mikolaj Izdebski.

COPYRIGHT

       Copyright (C) 2011, 2012, 2013 Mikolaj Izdebski
       Copyright (C) 2008, 2009, 2010 Laszlo Ersek
       Copyright (C) 1996 Julian Seward

       This  manual page is part of lbzip2, version 2.3. lbzip2 is free software: you can redistribute it and/or
       modify it under the terms of the GNU General Public License as published by the Free Software Foundation,
       either version 3 of the License, or (at your option) any later version.

       lbzip2 is distributed in the hope that it will be useful, but WITHOUT  ANY  WARRANTY;  without  even  the
       implied  warranty  of  MERCHANTABILITY  or  FITNESS  FOR A PARTICULAR PURPOSE. See the GNU General Public
       License for more details.

       You should have received a copy of the GNU  General  Public  License  along  with  lbzip2.  If  not,  see
       <http://www.gnu.org/licenses/>.

THANKS

       Adam  Maulis  at  ELTE IIG; Julian Seward; Paul Sladen; Michael Thomas from Caltech HEP; Bryan Stillwell;
       Zsolt Bartos-Elekes; Imre Csatlos; Gabor Kovesdan; Paul Wise; Paolo Bonzini; Department of Electrical and
       Information Engineering at the University of Oulu; Yuta Mori.