lbunzip2(1)

1LBZIP2(1)                        User commands                       LBZIP2(1)
2
3
4

NAME

6       lbzip2 - parallel bzip2 utility
7
8

SYNOPSIS

10       lbzip2|bzip2  [-n  WTHRS]  [-k|-c|-t]  [-d] [-1 .. -9] [-f] [-v] [-S] [
11       FILE ... ]
12
13
14       lbunzip2|bunzip2 [-n WTHRS] [-k|-c|-t] [-z] [-f] [-v] [-S] [ FILE ... ]
15
16
17       lbzcat|bzcat [-n WTHRS] [-z] [-f] [-v] [-S] [ FILE ... ]
18
19
20       lbzip2|bzip2|lbunzip2|bunzip2|lbzcat|bzcat -h
21
22

DESCRIPTION

24       Compress or decompress FILE operands or standard input to regular files
25       or  standard  output,  by  calling Julian Seward's libbz2 from multiple
26       threads. The lbzip2 utility employs multiple threads and an input-bound
27       splitter  even  when decompressing .bz2 files created by standard bzip2
28       (but see BUGS below).
29
30

INVOCATION

32       The default mode of operation is compression. If the utility is invoked
33       as  lbunzip2  or  bunzip2, the MO is switched to decompression. Calling
34       the utility as lbzcat or bzcat selects decompression, with  the  decom‐
35       pressed byte-stream written to standard output.
36
37

OPTIONS

39       -n WTHRS
40              Set  the  number  of  (de)compressor  threads to WTHRS.  If this
41              option is not specified, lbzip2 either queries  the  system  for
42              the  number  of online processors (if both the compilation envi‐
43              ronment and the execution environment support that), or it exits
44              with an error.
45
46
47       -k, --keep
48              Don't  remove  FILE  operands  after successful (de)compression.
49              Open regular input files with more than one links.
50
51
52       -c, --stdout
53              Write output to standard output, even  when  FILE  operands  are
54              present. Implies -k and excludes -t.
55
56
57       -t, --test
58              Test  decompression;  discard  output  instead  of writing it to
59              files or standard output. Implies -k and excludes -c.
60
61
62       -d, --decompress
63              Force decompression over the mode of operation selected  by  the
64              invocation name.
65
66
67       -z, --compress
68              Force  compression  over  the  mode of operation selected by the
69              invocation name.
70
71
72       -1 .. -9
73              Set the compression block size to 100K .. 900K, in  100K  incre‐
74              ments.
75
76
77       --fast Alias for -1.
78
79
80       --best Alias for -9. This is the default.
81
82
83       -f, --force
84              Open  non-regular  input  files. Open input files with more than
85              one links, breaking links when -k isn't specified  in  addition.
86              Try to remove each output file before opening it.
87
88
89       -v, --verbose
90              Print  a short message to standard error whenever a (de)compres‐
91              sion operation commences.
92
93
94       -S     Print condition variable statistics to standard error  for  each
95              completed (de)compression operation.
96
97
98       -s, --small, -q, --quiet, --repetitive-fast, --repetitive-best
99              Accepted for compatibility with bzip2, otherwise ignored.
100
101
102       -h, --help, -L, --license, -V, --version
103              Display  license  and version information, plus help on command-
104              line usage.
105
106

ENVIRONMENT

108       LBZIP2, BZIP2, BZIP
109              Before parsing the command line, lbzip2 inserts the contents  of
110              these  variables, in the order specified, between the invocation
111              name and the rest of the command line. Tokens are  separated  by
112              spaces and tabs, which cannot be escaped.
113
114
115       LBZIP2_TRACE_ALLOC
116              If  this  variable  is set to a non-empty value, lbzip2 prints a
117              memory allocation trace to standard  error.  The  trace  can  be
118              checked with the malloc_trace.pl Perl script (part of the source
119              distribution).
120
121

OPERANDS

123       FILE   Specify files to compress or decompress. If no  FILE  is  given,
124              lbzip2 works as a filter.  FILEs with .bz2, .tbz, .tbz2 and .tz2
125              name suffixes will be skipped when compressing. When decompress‐
126              ing,  .bz2  suffixes  will be removed in output filenames; .tbz,
127              .tbz2 and .tz2 suffixes will be replaced by  .tar;  other  file‐
128              names  will  be  suffixed with .out. If an INT or TERM signal is
129              delivered to lbzip2, then it removes  the  regular  output  file
130              currently open before exiting.
131
132

EXIT STATUS

134       0      if  lbzip2 finishes successfully. This presumes that whenever it
135              tries, lbzip2 never fails to write to standard error.
136
137
138       1      if lbzip2 encounters a fatal error.
139
140
141       4      if lbzip2 issues warnings without encountering  a  fatal  error.
142              This  presumes  that  whenever  it  tries, lbzip2 never fails to
143              write to standard error.
144
145
146       SIGPIPE, SIGXFSZ
147              if lbzip2 intends to exit with status 1 due to any fatal  error,
148              but  any such signal with inherited SIG_DFL action was generated
149              for lbzip2 previously, then lbzip2 terminates by way of  one  of
150              said signals, after cleaning up any interrupted output file.
151
152
153       SIGABRT
154              (via assert()) if a runtime assertion fails (ie.  lbzip2 detects
155              a bug in itself). Hopefully whoever compiled your binary  wasn't
156              bold enough to #define NDEBUG.
157
158
159       SIGINT, SIGTERM
160              lbzip2  catches  these  signals  so that it can remove an inter‐
161              rupted output file. In such cases, lbzip2  exits  by  re-raising
162              (one of) the received signal(s).
163
164

BUGS

166       The  compressed  output  is  a  sequence of single-block bzip2 streams,
167       instead of being a single multi-block bzip2  stream.  Thus  no  output-
168       global  combined  CRC  can be written, and the resulting .bz2 file will
169       return multiple BZ_STREAM_ENDs when decompressed with libbz2.
170
171
172       The multiple-workers decompressor (lbzip2 -d -n WTHRS, where  WTHRS  is
173       greater than 1, either by default or by manual selection) doesn't check
174       stream-level (combined) CRCs, only block-level CRCs. It can  also  fail
175       to  decompress some rare valid .bz2 files. (See the Bugs section of the
176       README in the source distribution for more on this.) Since  the  author
177       cannot  rule  out that such a failure may get reported as corrupt input
178       instead of the dedicated error message, lbzip2 doesn't reserve a  sepa‐
179       rate exit status for corrupt input -- it could be misleading.
180
181
182       The bit-string search algorithm used in the multiple-workers decompres‐
183       sor is naive and slow.
184
185
186       Separate input files don't share worker threads; at most one input file
187       is worked on at any moment.
188
189

AUTHOR

191       Written by Laszlo Ersek <lacos@caesar.elte.hu>, http://lacos.hu/.
192
193

COPYRIGHT

195       Copyright (C) 2008, 2009, 2010 Laszlo Ersek.
196
197
198       This  is  free  software.  You  may redistribute copies of it under the
199       terms of the GNU General Public License, version 2:
200
201
202       http://www.gnu.org/licenses/gpl-2.0.html
203
204
205       or -- at your opinion -- any later version, eg.
206
207
208       http://www.gnu.org/licenses/gpl.html
209
210

THANKS

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