summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMark Wielaard <mark@klomp.org>2019-07-21 17:09:25 +0200
committerMark Wielaard <mark@klomp.org>2019-07-21 17:09:25 +0200
commit8d9410ce881e43ec8ea82ec7a3b0541c0ffbc3dd (patch)
tree68699c2fc3392afef7f54b51ea705f58ea0189e4
parentPrepare for 1.0.8 release. (diff)
downloadbzip2-8d9410ce881e43ec8ea82ec7a3b0541c0ffbc3dd.tar.gz
bzip2-8d9410ce881e43ec8ea82ec7a3b0541c0ffbc3dd.tar.bz2
bzip2-8d9410ce881e43ec8ea82ec7a3b0541c0ffbc3dd.tar.xz
bzip2.1: remove blank spaces in man page and drop the .PU macro.
Author: Bjarni Ingi Gislason Bug-Debian: https://bugs.debian.org/675380
-rw-r--r--bzip2.1138
1 files changed, 68 insertions, 70 deletions
diff --git a/bzip2.1 b/bzip2.1
index 0cbcdab..174b15f 100644
--- a/bzip2.1
+++ b/bzip2.1
@@ -1,4 +1,3 @@
1.PU
2.TH bzip2 1 1.TH bzip2 1
3.SH NAME 2.SH NAME
4bzip2, bunzip2 \- a block-sorting file compressor, v1.0.8 3bzip2, bunzip2 \- a block-sorting file compressor, v1.0.8
@@ -18,13 +17,13 @@ bzip2recover \- recovers data from damaged bzip2 files
18.br 17.br
19.B bunzip2 18.B bunzip2
20.RB [ " \-fkvsVL " ] 19.RB [ " \-fkvsVL " ]
21[ 20[
22.I "filenames \&..." 21.I "filenames \&..."
23] 22]
24.br 23.br
25.B bzcat 24.B bzcat
26.RB [ " \-s " ] 25.RB [ " \-s " ]
27[ 26[
28.I "filenames \&..." 27.I "filenames \&..."
29] 28]
30.br 29.br
@@ -39,15 +38,15 @@ generally considerably better than that achieved by more conventional
39LZ77/LZ78-based compressors, and approaches the performance of the PPM 38LZ77/LZ78-based compressors, and approaches the performance of the PPM
40family of statistical compressors. 39family of statistical compressors.
41 40
42The command-line options are deliberately very similar to 41The command-line options are deliberately very similar to
43those of 42those of
44.I GNU gzip, 43.I GNU gzip,
45but they are not identical. 44but they are not identical.
46 45
47.I bzip2 46.I bzip2
48expects a list of file names to accompany the 47expects a list of file names to accompany the
49command-line flags. Each file is replaced by a compressed version of 48command-line flags. Each file is replaced by a compressed version of
50itself, with the name "original_name.bz2". 49itself, with the name "original_name.bz2".
51Each compressed file 50Each compressed file
52has the same modification date, permissions, and, when possible, 51has the same modification date, permissions, and, when possible,
53ownership as the corresponding original, so that these properties can 52ownership as the corresponding original, so that these properties can
@@ -74,13 +73,13 @@ incomprehensible and therefore pointless.
74 73
75.I bunzip2 74.I bunzip2
76(or 75(or
77.I bzip2 \-d) 76.I bzip2 \-d)
78decompresses all 77decompresses all
79specified files. Files which were not created by 78specified files. Files which were not created by
80.I bzip2 79.I bzip2
81will be detected and ignored, and a warning issued. 80will be detected and ignored, and a warning issued.
82.I bzip2 81.I bzip2
83attempts to guess the filename for the decompressed file 82attempts to guess the filename for the decompressed file
84from that of the compressed file as follows: 83from that of the compressed file as follows:
85 84
86 filename.bz2 becomes filename 85 filename.bz2 becomes filename
@@ -89,13 +88,13 @@ from that of the compressed file as follows:
89 filename.tbz becomes filename.tar 88 filename.tbz becomes filename.tar
90 anyothername becomes anyothername.out 89 anyothername becomes anyothername.out
91 90
92If the file does not end in one of the recognised endings, 91If the file does not end in one of the recognised endings,
93.I .bz2, 92.I .bz2,
94.I .bz, 93.I .bz,
95.I .tbz2 94.I .tbz2
96or 95or
97.I .tbz, 96.I .tbz,
98.I bzip2 97.I bzip2
99complains that it cannot 98complains that it cannot
100guess the name of the original file, and uses the original name 99guess the name of the original file, and uses the original name
101with 100with
@@ -103,25 +102,25 @@ with
103appended. 102appended.
104 103
105As with compression, supplying no 104As with compression, supplying no
106filenames causes decompression from 105filenames causes decompression from
107standard input to standard output. 106standard input to standard output.
108 107
109.I bunzip2 108.I bunzip2
110will correctly decompress a file which is the 109will correctly decompress a file which is the
111concatenation of two or more compressed files. The result is the 110concatenation of two or more compressed files. The result is the
112concatenation of the corresponding uncompressed files. Integrity 111concatenation of the corresponding uncompressed files. Integrity
113testing (\-t) 112testing (\-t)
114of concatenated 113of concatenated
115compressed files is also supported. 114compressed files is also supported.
116 115
117You can also compress or decompress files to the standard output by 116You can also compress or decompress files to the standard output by
118giving the \-c flag. Multiple files may be compressed and 117giving the \-c flag. Multiple files may be compressed and
119decompressed like this. The resulting outputs are fed sequentially to 118decompressed like this. The resulting outputs are fed sequentially to
120stdout. Compression of multiple files 119stdout. Compression of multiple files
121in this manner generates a stream 120in this manner generates a stream
122containing multiple compressed file representations. Such a stream 121containing multiple compressed file representations. Such a stream
123can be decompressed correctly only by 122can be decompressed correctly only by
124.I bzip2 123.I bzip2
125version 0.9.0 or 124version 0.9.0 or
126later. Earlier versions of 125later. Earlier versions of
127.I bzip2 126.I bzip2
@@ -130,7 +129,7 @@ the first file in the stream.
130 129
131.I bzcat 130.I bzcat
132(or 131(or
133.I bzip2 -dc) 132.I bzip2 -dc)
134decompresses all specified files to 133decompresses all specified files to
135the standard output. 134the standard output.
136 135
@@ -140,10 +139,10 @@ will read arguments from the environment variables
140and 139and
141.I BZIP, 140.I BZIP,
142in that order, and will process them 141in that order, and will process them
143before any arguments read from the command line. This gives a 142before any arguments read from the command line. This gives a
144convenient way to supply default arguments. 143convenient way to supply default arguments.
145 144
146Compression is always performed, even if the compressed 145Compression is always performed, even if the compressed
147file is slightly 146file is slightly
148larger than the original. Files of less than about one hundred bytes 147larger than the original. Files of less than about one hundred bytes
149tend to get larger, since the compression mechanism has a constant 148tend to get larger, since the compression mechanism has a constant
@@ -151,9 +150,8 @@ overhead in the region of 50 bytes. Random data (including the output
151of most file compressors) is coded at about 8.05 bits per byte, giving 150of most file compressors) is coded at about 8.05 bits per byte, giving
152an expansion of around 0.5%. 151an expansion of around 0.5%.
153 152
154As a self-check for your protection, 153As a self-check for your protection,
155.I 154.I bzip2
156bzip2
157uses 32-bit CRCs to 155uses 32-bit CRCs to
158make sure that the decompressed version of a file is identical to the 156make sure that the decompressed version of a file is identical to the
159original. This guards against corruption of the compressed data, and 157original. This guards against corruption of the compressed data, and
@@ -163,9 +161,9 @@ against undetected bugs in
163chances of data corruption going undetected is microscopic, about one 161chances of data corruption going undetected is microscopic, about one
164chance in four billion for each file processed. Be aware, though, that 162chance in four billion for each file processed. Be aware, though, that
165the check occurs upon decompression, so it can only tell you that 163the check occurs upon decompression, so it can only tell you that
166something is wrong. It can't help you 164something is wrong. It can't help you
167recover the original uncompressed 165recover the original uncompressed
168data. You can use 166data. You can use
169.I bzip2recover 167.I bzip2recover
170to try to recover data from 168to try to recover data from
171damaged files. 169damaged files.
@@ -183,15 +181,15 @@ to panic.
183Compress or decompress to standard output. 181Compress or decompress to standard output.
184.TP 182.TP
185.B \-d --decompress 183.B \-d --decompress
186Force decompression. 184Force decompression.
187.I bzip2, 185.I bzip2,
188.I bunzip2 186.I bunzip2
189and 187and
190.I bzcat 188.I bzcat
191are 189are
192really the same program, and the decision about what actions to take is 190really the same program, and the decision about what actions to take is
193done on the basis of which name is used. This flag overrides that 191done on the basis of which name is used. This flag overrides that
194mechanism, and forces 192mechanism, and forces
195.I bzip2 193.I bzip2
196to decompress. 194to decompress.
197.TP 195.TP
@@ -205,10 +203,10 @@ This really performs a trial decompression and throws away the result.
205.TP 203.TP
206.B \-f --force 204.B \-f --force
207Force overwrite of output files. Normally, 205Force overwrite of output files. Normally,
208.I bzip2 206.I bzip2
209will not overwrite 207will not overwrite
210existing output files. Also forces 208existing output files. Also forces
211.I bzip2 209.I bzip2
212to break hard links 210to break hard links
213to files, which it otherwise wouldn't do. 211to files, which it otherwise wouldn't do.
214 212
@@ -224,9 +222,9 @@ or decompression.
224Reduce memory usage, for compression, decompression and testing. Files 222Reduce memory usage, for compression, decompression and testing. Files
225are decompressed and tested using a modified algorithm which only 223are decompressed and tested using a modified algorithm which only
226requires 2.5 bytes per block byte. This means any file can be 224requires 2.5 bytes per block byte. This means any file can be
227decompressed in 2300k of memory, albeit at about half the normal speed. 225decompressed in 2300\ k of memory, albeit at about half the normal speed.
228 226
229During compression, \-s selects a block size of 200k, which limits 227During compression, \-s selects a block size of 200\ k, which limits
230memory use to around the same figure, at the expense of your compression 228memory use to around the same figure, at the expense of your compression
231ratio. In short, if your machine is low on memory (8 megabytes or 229ratio. In short, if your machine is low on memory (8 megabytes or
232less), use \-s for everything. See MEMORY MANAGEMENT below. 230less), use \-s for everything. See MEMORY MANAGEMENT below.
@@ -244,11 +242,11 @@ information which is primarily of interest for diagnostic purposes.
244Display the software version, license terms and conditions. 242Display the software version, license terms and conditions.
245.TP 243.TP
246.B \-1 (or \-\-fast) to \-9 (or \-\-best) 244.B \-1 (or \-\-fast) to \-9 (or \-\-best)
247Set the block size to 100 k, 200 k .. 900 k when compressing. Has no 245Set the block size to 100 k, 200 k ... 900 k when compressing. Has no
248effect when decompressing. See MEMORY MANAGEMENT below. 246effect when decompressing. See MEMORY MANAGEMENT below.
249The \-\-fast and \-\-best aliases are primarily for GNU gzip 247The \-\-fast and \-\-best aliases are primarily for GNU gzip
250compatibility. In particular, \-\-fast doesn't make things 248compatibility. In particular, \-\-fast doesn't make things
251significantly faster. 249significantly faster.
252And \-\-best merely selects the default behaviour. 250And \-\-best merely selects the default behaviour.
253.TP 251.TP
254.B \-- 252.B \--
@@ -263,7 +261,7 @@ earlier versions, which was sometimes useful. 0.9.5 and above have an
263improved algorithm which renders these flags irrelevant. 261improved algorithm which renders these flags irrelevant.
264 262
265.SH MEMORY MANAGEMENT 263.SH MEMORY MANAGEMENT
266.I bzip2 264.I bzip2
267compresses large files in blocks. The block size affects 265compresses large files in blocks. The block size affects
268both the compression ratio achieved, and the amount of memory needed for 266both the compression ratio achieved, and the amount of memory needed for
269compression and decompression. The flags \-1 through \-9 267compression and decompression. The flags \-1 through \-9
@@ -276,13 +274,13 @@ the file. Since block sizes are stored in compressed files, it follows
276that the flags \-1 to \-9 are irrelevant to and so ignored 274that the flags \-1 to \-9 are irrelevant to and so ignored
277during decompression. 275during decompression.
278 276
279Compression and decompression requirements, 277Compression and decompression requirements,
280in bytes, can be estimated as: 278in bytes, can be estimated as:
281 279
282 Compression: 400k + ( 8 x block size ) 280 Compression: 400\ k + ( 8 x block size )
283 281
284 Decompression: 100k + ( 4 x block size ), or 282 Decompression: 100\ k + ( 4 x block size ), or
285 100k + ( 2.5 x block size ) 283 100\ k + ( 2.5 x block size )
286 284
287Larger block sizes give rapidly diminishing marginal returns. Most of 285Larger block sizes give rapidly diminishing marginal returns. Most of
288the compression comes from the first two or three hundred k of block 286the compression comes from the first two or three hundred k of block
@@ -292,10 +290,10 @@ on small machines.
292It is also important to appreciate that the decompression memory 290It is also important to appreciate that the decompression memory
293requirement is set at compression time by the choice of block size. 291requirement is set at compression time by the choice of block size.
294 292
295For files compressed with the default 900k block size, 293For files compressed with the default 900\ k block size,
296.I bunzip2 294.I bunzip2
297will require about 3700 kbytes to decompress. To support decompression 295will require about 3700 kbytes to decompress. To support decompression
298of any file on a 4 megabyte machine, 296of any file on a 4 megabyte machine,
299.I bunzip2 297.I bunzip2
300has an option to 298has an option to
301decompress using approximately half this amount of memory, about 2300 299decompress using approximately half this amount of memory, about 2300
@@ -311,9 +309,9 @@ Another significant point applies to files which fit in a single block
311amount of real memory touched is proportional to the size of the file, 309amount of real memory touched is proportional to the size of the file,
312since the file is smaller than a block. For example, compressing a file 310since the file is smaller than a block. For example, compressing a file
31320,000 bytes long with the flag -9 will cause the compressor to 31120,000 bytes long with the flag -9 will cause the compressor to
314allocate around 7600k of memory, but only touch 400k + 20000 * 8 = 560 312allocate around 7600\ k of memory, but only touch 400\ k + 20000 * 8 = 560
315kbytes of it. Similarly, the decompressor will allocate 3700k but only 313kbytes of it. Similarly, the decompressor will allocate 3700\ k but only
316touch 100k + 20000 * 4 = 180 kbytes. 314touch 100\ k + 20000 * 4 = 180 kbytes.
317 315
318Here is a table which summarises the maximum memory usage for different 316Here is a table which summarises the maximum memory usage for different
319block sizes. Also recorded is the total compressed size for 14 files of 317block sizes. Also recorded is the total compressed size for 14 files of
@@ -337,7 +335,7 @@ larger files, since the Corpus is dominated by smaller files.
337 335
338.SH RECOVERING DATA FROM DAMAGED FILES 336.SH RECOVERING DATA FROM DAMAGED FILES
339.I bzip2 337.I bzip2
340compresses files in blocks, usually 900kbytes long. Each 338compresses files in blocks, usually 900\ kbytes long. Each
341block is handled independently. If a media or transmission error causes 339block is handled independently. If a media or transmission error causes
342a multi-block .bz2 340a multi-block .bz2
343file to become damaged, it may be possible to 341file to become damaged, it may be possible to
@@ -350,36 +348,36 @@ damaged blocks can be distinguished from undamaged ones.
350 348
351.I bzip2recover 349.I bzip2recover
352is a simple program whose purpose is to search for 350is a simple program whose purpose is to search for
353blocks in .bz2 files, and write each block out into its own .bz2 351blocks in .bz2 files, and write each block out into its own .bz2
354file. You can then use 352file. You can then use
355.I bzip2 353.I bzip2
356\-t 354\-t
357to test the 355to test the
358integrity of the resulting files, and decompress those which are 356integrity of the resulting files, and decompress those which are
359undamaged. 357undamaged.
360 358
361.I bzip2recover 359.I bzip2recover
362takes a single argument, the name of the damaged file, 360takes a single argument, the name of the damaged file,
363and writes a number of files "rec00001file.bz2", 361and writes a number of files "rec00001file.bz2",
364"rec00002file.bz2", etc, containing the extracted blocks. 362"rec00002file.bz2", etc., containing the extracted blocks.
365The output filenames are designed so that the use of 363The output filenames are designed so that the use of
366wildcards in subsequent processing -- for example, 364wildcards in subsequent processing -- for example,
367"bzip2 -dc rec*file.bz2 > recovered_data" -- processes the files in 365"bzip2 -dc rec*file.bz2 > recovered_data" -- processes the files in
368the correct order. 366the correct order.
369 367
370.I bzip2recover 368.I bzip2recover
371should be of most use dealing with large .bz2 369should be of most use dealing with large .bz2
372files, as these will contain many blocks. It is clearly 370files, as these will contain many blocks. It is clearly
373futile to use it on damaged single-block files, since a 371futile to use it on damaged single-block files, since a
374damaged block cannot be recovered. If you wish to minimise 372damaged block cannot be recovered. If you wish to minimise
375any potential data loss through media or transmission errors, 373any potential data loss through media or transmission errors,
376you might consider compressing with a smaller 374you might consider compressing with a smaller
377block size. 375block size.
378 376
379.SH PERFORMANCE NOTES 377.SH PERFORMANCE NOTES
380The sorting phase of compression gathers together similar strings in the 378The sorting phase of compression gathers together similar strings in the
381file. Because of this, files containing very long runs of repeated 379file. Because of this, files containing very long runs of repeated
382symbols, like "aabaabaabaab ..." (repeated several hundred times) may 380symbols, like "aabaabaabaab ...\&" (repeated several hundred times) may
383compress more slowly than normal. Versions 0.9.5 and above fare much 381compress more slowly than normal. Versions 0.9.5 and above fare much
384better than previous versions in this respect. The ratio between 382better than previous versions in this respect. The ratio between
385worst-case and average-case compression time is in the region of 10:1. 383worst-case and average-case compression time is in the region of 10:1.
@@ -395,7 +393,7 @@ that performance, both for compressing and decompressing, is largely
395determined by the speed at which your machine can service cache misses. 393determined by the speed at which your machine can service cache misses.
396Because of this, small changes to the code to reduce the miss rate have 394Because of this, small changes to the code to reduce the miss rate have
397been observed to give disproportionately large performance improvements. 395been observed to give disproportionately large performance improvements.
398I imagine 396I imagine
399.I bzip2 397.I bzip2
400will perform best on machines with very large caches. 398will perform best on machines with very large caches.
401 399
@@ -406,7 +404,7 @@ tries hard to detect I/O errors and exit cleanly, but the details of
406what the problem is sometimes seem rather misleading. 404what the problem is sometimes seem rather misleading.
407 405
408This manual page pertains to version 1.0.8 of 406This manual page pertains to version 1.0.8 of
409.I bzip2. 407.I bzip2.
410Compressed data created by this version is entirely forwards and 408Compressed data created by this version is entirely forwards and
411backwards compatible with the previous public releases, versions 409backwards compatible with the previous public releases, versions
4120.1pl2, 0.9.0, 0.9.5, 1.0.0, 1.0.1, 1.0.2 and above, but with the following 4100.1pl2, 0.9.0, 0.9.5, 1.0.0, 1.0.1, 1.0.2 and above, but with the following
@@ -440,13 +438,13 @@ Fenwick (for the structured coding model in the original
440.I bzip, 438.I bzip,
441and many refinements), and Alistair Moffat, Radford Neal and Ian Witten 439and many refinements), and Alistair Moffat, Radford Neal and Ian Witten
442(for the arithmetic coder in the original 440(for the arithmetic coder in the original
443.I bzip). 441.I bzip).
444I am much 442I am much
445indebted for their help, support and advice. See the manual in the 443indebted for their help, support and advice. See the manual in the
446source distribution for pointers to sources of documentation. Christian 444source distribution for pointers to sources of documentation. Christian
447von Roques encouraged me to look for faster sorting algorithms, so as to 445von Roques encouraged me to look for faster sorting algorithms, so as to
448speed up compression. Bela Lubkin encouraged me to improve the 446speed up compression. Bela Lubkin encouraged me to improve the
449worst-case compression performance. 447worst-case compression performance.
450Donna Robinson XMLised the documentation. 448Donna Robinson XMLised the documentation.
451The bz* scripts are derived from those of GNU gzip. 449The bz* scripts are derived from those of GNU gzip.
452Many people sent patches, helped 450Many people sent patches, helped