-
Notifications
You must be signed in to change notification settings - Fork 294
/
manual.html
2540 lines (2509 loc) · 125 KB
/
manual.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>bzip2 and libbzip2, version 1.0.6</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<style type="text/css" media="screen">/* Colours:
#74240f dark brown h1, h2, h3, h4
#336699 medium blue links
#339999 turquoise link hover colour
#202020 almost black general text
#761596 purple md5sum text
#626262 dark gray pre border
#eeeeee very light gray pre background
#f2f2f9 very light blue nav table background
#3366cc medium blue nav table border
*/
a, a:link, a:visited, a:active { color: #336699; }
a:hover { color: #339999; }
body { font: 80%/126% sans-serif; }
h1, h2, h3, h4 { color: #74240f; }
dt { color: #336699; font-weight: bold }
dd {
margin-left: 1.5em;
padding-bottom: 0.8em;
}
/* -- ruler -- */
div.hr_blue {
height: 3px;
background:#ffffff url("/images/hr_blue.png") repeat-x; }
div.hr_blue hr { display:none; }
/* release styles */
#release p { margin-top: 0.4em; }
#release .md5sum { color: #761596; }
/* ------ styles for docs|manuals|howto ------ */
/* -- lists -- */
ul {
margin: 0px 4px 16px 16px;
padding: 0px;
list-style: url("/images/li-blue.png");
}
ul li {
margin-bottom: 10px;
}
ul ul {
list-style-type: none;
list-style-image: none;
margin-left: 0px;
}
/* header / footer nav tables */
table.nav {
border: solid 1px #3366cc;
background: #f2f2f9;
background-color: #f2f2f9;
margin-bottom: 0.5em;
}
/* don't have underlined links in chunked nav menus */
table.nav a { text-decoration: none; }
table.nav a:hover { text-decoration: underline; }
table.nav td { font-size: 85%; }
code, tt, pre { font-size: 120%; }
code, tt { color: #761596; }
div.literallayout, pre.programlisting, pre.screen {
color: #000000;
padding: 0.5em;
background: #eeeeee;
border: 1px solid #626262;
background-color: #eeeeee;
margin: 4px 0px 4px 0px;
}
</style>
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book" title="bzip2 and libbzip2, version 1.0.6">
<div class="titlepage">
<div>
<div><h1 class="title">
<a name="userman"></a>bzip2 and libbzip2, version 1.0.6</h1></div>
<div><h2 class="subtitle">A program and library for data compression</h2></div>
<div><div class="authorgroup"><div class="author">
<h3 class="author">
<span class="firstname">Julian</span> <span class="surname">Seward</span>
</h3>
<div class="affiliation"><span class="orgname">http://www.bzip.org<br></span></div>
</div></div></div>
<div><p class="releaseinfo">Version 1.0.6 of 6 September 2010</p></div>
<div><p class="copyright">Copyright © 1996-2010 Julian Seward</p></div>
<div><div class="legalnotice" title="Legal Notice">
<a name="id537185"></a><p>This program, <code class="computeroutput">bzip2</code>, the
associated library <code class="computeroutput">libbzip2</code>, and
all documentation, are copyright © 1996-2010 Julian Seward.
All rights reserved.</p>
<p>Redistribution and use in source and binary forms, with
or without modification, are permitted provided that the
following conditions are met:</p>
<div class="itemizedlist"><ul class="itemizedlist" type="bullet">
<li class="listitem" style="list-style-type: disc"><p>Redistributions of source code must retain the
above copyright notice, this list of conditions and the
following disclaimer.</p></li>
<li class="listitem" style="list-style-type: disc"><p>The origin of this software must not be
misrepresented; you must not claim that you wrote the original
software. If you use this software in a product, an
acknowledgment in the product documentation would be
appreciated but is not required.</p></li>
<li class="listitem" style="list-style-type: disc"><p>Altered source versions must be plainly marked
as such, and must not be misrepresented as being the original
software.</p></li>
<li class="listitem" style="list-style-type: disc"><p>The name of the author may not be used to
endorse or promote products derived from this software without
specific prior written permission.</p></li>
</ul></div>
<p>THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.</p>
<p>PATENTS: To the best of my knowledge,
<code class="computeroutput">bzip2</code> and
<code class="computeroutput">libbzip2</code> do not use any patented
algorithms. However, I do not have the resources to carry
out a patent search. Therefore I cannot give any guarantee of
the above statement.
</p>
</div></div>
</div>
<hr>
</div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="chapter"><a href="#intro">1. Introduction</a></span></dt>
<dt><span class="chapter"><a href="#using">2. How to use bzip2</a></span></dt>
<dd><dl>
<dt><span class="sect1"><a href="#name">2.1. NAME</a></span></dt>
<dt><span class="sect1"><a href="#synopsis">2.2. SYNOPSIS</a></span></dt>
<dt><span class="sect1"><a href="#description">2.3. DESCRIPTION</a></span></dt>
<dt><span class="sect1"><a href="#options">2.4. OPTIONS</a></span></dt>
<dt><span class="sect1"><a href="#memory-management">2.5. MEMORY MANAGEMENT</a></span></dt>
<dt><span class="sect1"><a href="#recovering">2.6. RECOVERING DATA FROM DAMAGED FILES</a></span></dt>
<dt><span class="sect1"><a href="#performance">2.7. PERFORMANCE NOTES</a></span></dt>
<dt><span class="sect1"><a href="#caveats">2.8. CAVEATS</a></span></dt>
<dt><span class="sect1"><a href="#author">2.9. AUTHOR</a></span></dt>
</dl></dd>
<dt><span class="chapter"><a href="#libprog">3.
Programming with <code class="computeroutput">libbzip2</code>
</a></span></dt>
<dd><dl>
<dt><span class="sect1"><a href="#top-level">3.1. Top-level structure</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#ll-summary">3.1.1. Low-level summary</a></span></dt>
<dt><span class="sect2"><a href="#hl-summary">3.1.2. High-level summary</a></span></dt>
<dt><span class="sect2"><a href="#util-fns-summary">3.1.3. Utility functions summary</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#err-handling">3.2. Error handling</a></span></dt>
<dt><span class="sect1"><a href="#low-level">3.3. Low-level interface</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#bzcompress-init">3.3.1. BZ2_bzCompressInit</a></span></dt>
<dt><span class="sect2"><a href="#bzCompress">3.3.2. BZ2_bzCompress</a></span></dt>
<dt><span class="sect2"><a href="#bzCompress-end">3.3.3. BZ2_bzCompressEnd</a></span></dt>
<dt><span class="sect2"><a href="#bzDecompress-init">3.3.4. BZ2_bzDecompressInit</a></span></dt>
<dt><span class="sect2"><a href="#bzDecompress">3.3.5. BZ2_bzDecompress</a></span></dt>
<dt><span class="sect2"><a href="#bzDecompress-end">3.3.6. BZ2_bzDecompressEnd</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#hl-interface">3.4. High-level interface</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#bzreadopen">3.4.1. BZ2_bzReadOpen</a></span></dt>
<dt><span class="sect2"><a href="#bzread">3.4.2. BZ2_bzRead</a></span></dt>
<dt><span class="sect2"><a href="#bzreadgetunused">3.4.3. BZ2_bzReadGetUnused</a></span></dt>
<dt><span class="sect2"><a href="#bzreadclose">3.4.4. BZ2_bzReadClose</a></span></dt>
<dt><span class="sect2"><a href="#bzwriteopen">3.4.5. BZ2_bzWriteOpen</a></span></dt>
<dt><span class="sect2"><a href="#bzwrite">3.4.6. BZ2_bzWrite</a></span></dt>
<dt><span class="sect2"><a href="#bzwriteclose">3.4.7. BZ2_bzWriteClose</a></span></dt>
<dt><span class="sect2"><a href="#embed">3.4.8. Handling embedded compressed data streams</a></span></dt>
<dt><span class="sect2"><a href="#std-rdwr">3.4.9. Standard file-reading/writing code</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#util-fns">3.5. Utility functions</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#bzbufftobuffcompress">3.5.1. BZ2_bzBuffToBuffCompress</a></span></dt>
<dt><span class="sect2"><a href="#bzbufftobuffdecompress">3.5.2. BZ2_bzBuffToBuffDecompress</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#zlib-compat">3.6. zlib compatibility functions</a></span></dt>
<dt><span class="sect1"><a href="#stdio-free">3.7. Using the library in a stdio-free environment</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#stdio-bye">3.7.1. Getting rid of stdio</a></span></dt>
<dt><span class="sect2"><a href="#critical-error">3.7.2. Critical error handling</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#win-dll">3.8. Making a Windows DLL</a></span></dt>
</dl></dd>
<dt><span class="chapter"><a href="#misc">4. Miscellanea</a></span></dt>
<dd><dl>
<dt><span class="sect1"><a href="#limits">4.1. Limitations of the compressed file format</a></span></dt>
<dt><span class="sect1"><a href="#port-issues">4.2. Portability issues</a></span></dt>
<dt><span class="sect1"><a href="#bugs">4.3. Reporting bugs</a></span></dt>
<dt><span class="sect1"><a href="#package">4.4. Did you get the right package?</a></span></dt>
<dt><span class="sect1"><a href="#reading">4.5. Further Reading</a></span></dt>
</dl></dd>
</dl>
</div>
<div class="chapter" title="1. Introduction">
<div class="titlepage"><div><div><h2 class="title">
<a name="intro"></a>1. Introduction</h2></div></div></div>
<p><code class="computeroutput">bzip2</code> compresses files
using the Burrows-Wheeler block-sorting text compression
algorithm, and Huffman coding. Compression is generally
considerably better than that achieved by more conventional
LZ77/LZ78-based compressors, and approaches the performance of
the PPM family of statistical compressors.</p>
<p><code class="computeroutput">bzip2</code> is built on top of
<code class="computeroutput">libbzip2</code>, a flexible library for
handling compressed data in the
<code class="computeroutput">bzip2</code> format. This manual
describes both how to use the program and how to work with the
library interface. Most of the manual is devoted to this
library, not the program, which is good news if your interest is
only in the program.</p>
<div class="itemizedlist"><ul class="itemizedlist" type="bullet">
<li class="listitem" style="list-style-type: disc"><p><a class="xref" href="#using" title="2. How to use bzip2">How to use bzip2</a> describes how to use
<code class="computeroutput">bzip2</code>; this is the only part
you need to read if you just want to know how to operate the
program.</p></li>
<li class="listitem" style="list-style-type: disc"><p><a class="xref" href="#libprog" title="3. Programming with libbzip2">Programming with libbzip2</a> describes the
programming interfaces in detail, and</p></li>
<li class="listitem" style="list-style-type: disc"><p><a class="xref" href="#misc" title="4. Miscellanea">Miscellanea</a> records some
miscellaneous notes which I thought ought to be recorded
somewhere.</p></li>
</ul></div>
</div>
<div class="chapter" title="2. How to use bzip2">
<div class="titlepage"><div><div><h2 class="title">
<a name="using"></a>2. How to use bzip2</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="sect1"><a href="#name">2.1. NAME</a></span></dt>
<dt><span class="sect1"><a href="#synopsis">2.2. SYNOPSIS</a></span></dt>
<dt><span class="sect1"><a href="#description">2.3. DESCRIPTION</a></span></dt>
<dt><span class="sect1"><a href="#options">2.4. OPTIONS</a></span></dt>
<dt><span class="sect1"><a href="#memory-management">2.5. MEMORY MANAGEMENT</a></span></dt>
<dt><span class="sect1"><a href="#recovering">2.6. RECOVERING DATA FROM DAMAGED FILES</a></span></dt>
<dt><span class="sect1"><a href="#performance">2.7. PERFORMANCE NOTES</a></span></dt>
<dt><span class="sect1"><a href="#caveats">2.8. CAVEATS</a></span></dt>
<dt><span class="sect1"><a href="#author">2.9. AUTHOR</a></span></dt>
</dl>
</div>
<p>This chapter contains a copy of the
<code class="computeroutput">bzip2</code> man page, and nothing
else.</p>
<div class="sect1" title="2.1. NAME">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="name"></a>2.1. NAME</h2></div></div></div>
<div class="itemizedlist"><ul class="itemizedlist" type="bullet">
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">bzip2</code>,
<code class="computeroutput">bunzip2</code> - a block-sorting file
compressor, v1.0.6</p></li>
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">bzcat</code> -
decompresses files to stdout</p></li>
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">bzip2recover</code> -
recovers data from damaged bzip2 files</p></li>
</ul></div>
</div>
<div class="sect1" title="2.2. SYNOPSIS">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="synopsis"></a>2.2. SYNOPSIS</h2></div></div></div>
<div class="itemizedlist"><ul class="itemizedlist" type="bullet">
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">bzip2</code> [
-cdfkqstvzVL123456789 ] [ filenames ... ]</p></li>
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">bunzip2</code> [
-fkvsVL ] [ filenames ... ]</p></li>
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">bzcat</code> [ -s ] [
filenames ... ]</p></li>
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">bzip2recover</code>
filename</p></li>
</ul></div>
</div>
<div class="sect1" title="2.3. DESCRIPTION">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="description"></a>2.3. DESCRIPTION</h2></div></div></div>
<p><code class="computeroutput">bzip2</code> compresses files
using the Burrows-Wheeler block sorting text compression
algorithm, and Huffman coding. Compression is generally
considerably better than that achieved by more conventional
LZ77/LZ78-based compressors, and approaches the performance of
the PPM family of statistical compressors.</p>
<p>The command-line options are deliberately very similar to
those of GNU <code class="computeroutput">gzip</code>, but they are
not identical.</p>
<p><code class="computeroutput">bzip2</code> expects a list of
file names to accompany the command-line flags. Each file is
replaced by a compressed version of itself, with the name
<code class="computeroutput">original_name.bz2</code>. Each
compressed file has the same modification date, permissions, and,
when possible, ownership as the corresponding original, so that
these properties can be correctly restored at decompression time.
File name handling is naive in the sense that there is no
mechanism for preserving original file names, permissions,
ownerships or dates in filesystems which lack these concepts, or
have serious file name length restrictions, such as
MS-DOS.</p>
<p><code class="computeroutput">bzip2</code> and
<code class="computeroutput">bunzip2</code> will by default not
overwrite existing files. If you want this to happen, specify
the <code class="computeroutput">-f</code> flag.</p>
<p>If no file names are specified,
<code class="computeroutput">bzip2</code> compresses from standard
input to standard output. In this case,
<code class="computeroutput">bzip2</code> will decline to write
compressed output to a terminal, as this would be entirely
incomprehensible and therefore pointless.</p>
<p><code class="computeroutput">bunzip2</code> (or
<code class="computeroutput">bzip2 -d</code>) decompresses all
specified files. Files which were not created by
<code class="computeroutput">bzip2</code> will be detected and
ignored, and a warning issued.
<code class="computeroutput">bzip2</code> attempts to guess the
filename for the decompressed file from that of the compressed
file as follows:</p>
<div class="itemizedlist"><ul class="itemizedlist" type="bullet">
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">filename.bz2 </code>
becomes
<code class="computeroutput">filename</code></p></li>
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">filename.bz </code>
becomes
<code class="computeroutput">filename</code></p></li>
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">filename.tbz2</code>
becomes
<code class="computeroutput">filename.tar</code></p></li>
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">filename.tbz </code>
becomes
<code class="computeroutput">filename.tar</code></p></li>
<li class="listitem" style="list-style-type: disc"><p><code class="computeroutput">anyothername </code>
becomes
<code class="computeroutput">anyothername.out</code></p></li>
</ul></div>
<p>If the file does not end in one of the recognised endings,
<code class="computeroutput">.bz2</code>,
<code class="computeroutput">.bz</code>,
<code class="computeroutput">.tbz2</code> or
<code class="computeroutput">.tbz</code>,
<code class="computeroutput">bzip2</code> complains that it cannot
guess the name of the original file, and uses the original name
with <code class="computeroutput">.out</code> appended.</p>
<p>As with compression, supplying no filenames causes
decompression from standard input to standard output.</p>
<p><code class="computeroutput">bunzip2</code> will correctly
decompress a file which is the concatenation of two or more
compressed files. The result is the concatenation of the
corresponding uncompressed files. Integrity testing
(<code class="computeroutput">-t</code>) of concatenated compressed
files is also supported.</p>
<p>You can also compress or decompress files to the standard
output by giving the <code class="computeroutput">-c</code> flag.
Multiple files may be compressed and decompressed like this. The
resulting outputs are fed sequentially to stdout. Compression of
multiple files in this manner generates a stream containing
multiple compressed file representations. Such a stream can be
decompressed correctly only by
<code class="computeroutput">bzip2</code> version 0.9.0 or later.
Earlier versions of <code class="computeroutput">bzip2</code> will
stop after decompressing the first file in the stream.</p>
<p><code class="computeroutput">bzcat</code> (or
<code class="computeroutput">bzip2 -dc</code>) decompresses all
specified files to the standard output.</p>
<p><code class="computeroutput">bzip2</code> will read arguments
from the environment variables
<code class="computeroutput">BZIP2</code> and
<code class="computeroutput">BZIP</code>, in that order, and will
process them before any arguments read from the command line.
This gives a convenient way to supply default arguments.</p>
<p>Compression is always performed, even if the compressed
file is slightly larger than the original. Files of less than
about one hundred bytes tend to get larger, since the compression
mechanism has a constant overhead in the region of 50 bytes.
Random data (including the output of most file compressors) is
coded at about 8.05 bits per byte, giving an expansion of around
0.5%.</p>
<p>As a self-check for your protection,
<code class="computeroutput">bzip2</code> 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 undetected bugs in
<code class="computeroutput">bzip2</code> (hopefully very 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 something is wrong. It can't help you
recover the original uncompressed data. You can use
<code class="computeroutput">bzip2recover</code> to try to recover
data from damaged files.</p>
<p>Return values: 0 for a normal exit, 1 for environmental
problems (file not found, invalid flags, I/O errors, etc.), 2
to indicate a corrupt compressed file, 3 for an internal
consistency error (eg, bug) which caused
<code class="computeroutput">bzip2</code> to panic.</p>
</div>
<div class="sect1" title="2.4. OPTIONS">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="options"></a>2.4. OPTIONS</h2></div></div></div>
<div class="variablelist"><dl>
<dt><span class="term"><code class="computeroutput">-c --stdout</code></span></dt>
<dd><p>Compress or decompress to standard
output.</p></dd>
<dt><span class="term"><code class="computeroutput">-d --decompress</code></span></dt>
<dd><p>Force decompression.
<code class="computeroutput">bzip2</code>,
<code class="computeroutput">bunzip2</code> and
<code class="computeroutput">bzcat</code> are really the same
program, and the decision about what actions to take is done on
the basis of which name is used. This flag overrides that
mechanism, and forces bzip2 to decompress.</p></dd>
<dt><span class="term"><code class="computeroutput">-z --compress</code></span></dt>
<dd><p>The complement to
<code class="computeroutput">-d</code>: forces compression,
regardless of the invokation name.</p></dd>
<dt><span class="term"><code class="computeroutput">-t --test</code></span></dt>
<dd><p>Check integrity of the specified file(s), but
don't decompress them. This really performs a trial
decompression and throws away the result.</p></dd>
<dt><span class="term"><code class="computeroutput">-f --force</code></span></dt>
<dd>
<p>Force overwrite of output files. Normally,
<code class="computeroutput">bzip2</code> will not overwrite
existing output files. Also forces
<code class="computeroutput">bzip2</code> to break hard links to
files, which it otherwise wouldn't do.</p>
<p><code class="computeroutput">bzip2</code> normally declines
to decompress files which don't have the correct magic header
bytes. If forced (<code class="computeroutput">-f</code>),
however, it will pass such files through unmodified. This is
how GNU <code class="computeroutput">gzip</code> behaves.</p>
</dd>
<dt><span class="term"><code class="computeroutput">-k --keep</code></span></dt>
<dd><p>Keep (don't delete) input files during
compression or decompression.</p></dd>
<dt><span class="term"><code class="computeroutput">-s --small</code></span></dt>
<dd>
<p>Reduce memory usage, for compression,
decompression and testing. Files are decompressed and tested
using a modified algorithm which only requires 2.5 bytes per
block byte. This means any file can be decompressed in 2300k
of memory, albeit at about half the normal speed.</p>
<p>During compression, <code class="computeroutput">-s</code>
selects a block size of 200k, which limits memory use to around
the same figure, at the expense of your compression ratio. In
short, if your machine is low on memory (8 megabytes or less),
use <code class="computeroutput">-s</code> for everything. See
<a class="xref" href="#memory-management" title="2.5. MEMORY MANAGEMENT">MEMORY MANAGEMENT</a> below.</p>
</dd>
<dt><span class="term"><code class="computeroutput">-q --quiet</code></span></dt>
<dd><p>Suppress non-essential warning messages.
Messages pertaining to I/O errors and other critical events
will not be suppressed.</p></dd>
<dt><span class="term"><code class="computeroutput">-v --verbose</code></span></dt>
<dd><p>Verbose mode -- show the compression ratio for
each file processed. Further
<code class="computeroutput">-v</code>'s increase the verbosity
level, spewing out lots of information which is primarily of
interest for diagnostic purposes.</p></dd>
<dt><span class="term"><code class="computeroutput">-L --license -V --version</code></span></dt>
<dd><p>Display the software version, license terms and
conditions.</p></dd>
<dt><span class="term"><code class="computeroutput">-1</code> (or
<code class="computeroutput">--fast</code>) to
<code class="computeroutput">-9</code> (or
<code class="computeroutput">-best</code>)</span></dt>
<dd><p>Set the block size to 100 k, 200 k ... 900 k
when compressing. Has no effect when decompressing. See <a class="xref" href="#memory-management" title="2.5. MEMORY MANAGEMENT">MEMORY MANAGEMENT</a> below. The
<code class="computeroutput">--fast</code> and
<code class="computeroutput">--best</code> aliases are primarily
for GNU <code class="computeroutput">gzip</code> compatibility.
In particular, <code class="computeroutput">--fast</code> doesn't
make things significantly faster. And
<code class="computeroutput">--best</code> merely selects the
default behaviour.</p></dd>
<dt><span class="term"><code class="computeroutput">--</code></span></dt>
<dd><p>Treats 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, for example:
<code class="computeroutput">bzip2 --
-myfilename</code>.</p></dd>
<dt>
<span class="term"><code class="computeroutput">--repetitive-fast</code>, </span><span class="term"><code class="computeroutput">--repetitive-best</code></span>
</dt>
<dd><p>These flags are redundant in versions 0.9.5 and
above. They provided some coarse control over the behaviour of
the sorting algorithm in earlier versions, which was sometimes
useful. 0.9.5 and above have an improved algorithm which
renders these flags irrelevant.</p></dd>
</dl></div>
</div>
<div class="sect1" title="2.5. MEMORY MANAGEMENT">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="memory-management"></a>2.5. MEMORY MANAGEMENT</h2></div></div></div>
<p><code class="computeroutput">bzip2</code> compresses large
files in blocks. The block size affects both the compression
ratio achieved, and the amount of memory needed for compression
and decompression. The flags <code class="computeroutput">-1</code>
through <code class="computeroutput">-9</code> 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 header of the compressed file, and
<code class="computeroutput">bunzip2</code> then allocates itself
just enough memory to decompress the file. Since block sizes are
stored in compressed files, it follows that the flags
<code class="computeroutput">-1</code> to
<code class="computeroutput">-9</code> are irrelevant to and so
ignored during decompression.</p>
<p>Compression and decompression requirements, in bytes, can be
estimated as:</p>
<pre class="programlisting">Compression: 400k + ( 8 x block size )
Decompression: 100k + ( 4 x block size ), or
100k + ( 2.5 x block size )</pre>
<p>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 <code class="computeroutput">bzip2</code> 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.</p>
<p>For files compressed with the default 900k block size,
<code class="computeroutput">bunzip2</code> will require about 3700
kbytes to decompress. To support decompression of any file on a
4 megabyte machine, <code class="computeroutput">bunzip2</code> has
an option to decompress using approximately half this amount of
memory, about 2300 kbytes. Decompression speed is also halved,
so you should use this option only where necessary. The relevant
flag is <code class="computeroutput">-s</code>.</p>
<p>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.</p>
<p>Another significant point applies to files which fit in a
single block -- that means most files you'd encounter using a
large block size. The amount of real memory touched is
proportional to the size of the file, since the file is smaller
than a block. For example, compressing a file 20,000 bytes long
with the flag <code class="computeroutput">-9</code> will cause the
compressor to allocate around 7600k of memory, but only touch
400k + 20000 * 8 = 560 kbytes of it. Similarly, the decompressor
will allocate 3700k but only touch 100k + 20000 * 4 = 180
kbytes.</p>
<p>Here is a table which summarises the maximum memory usage
for different block sizes. Also recorded is the total compressed
size for 14 files of the Calgary Text Compression Corpus
totalling 3,141,622 bytes. This column gives some feel for how
compression varies with block size. These figures tend to
understate the advantage of larger block sizes for larger files,
since the Corpus is dominated by smaller files.</p>
<pre class="programlisting"> Compress Decompress Decompress Corpus
Flag usage usage -s usage Size
-1 1200k 500k 350k 914704
-2 2000k 900k 600k 877703
-3 2800k 1300k 850k 860338
-4 3600k 1700k 1100k 846899
-5 4400k 2100k 1350k 845160
-6 5200k 2500k 1600k 838626
-7 6100k 2900k 1850k 834096
-8 6800k 3300k 2100k 828642
-9 7600k 3700k 2350k 828642</pre>
</div>
<div class="sect1" title="2.6. RECOVERING DATA FROM DAMAGED FILES">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="recovering"></a>2.6. RECOVERING DATA FROM DAMAGED FILES</h2></div></div></div>
<p><code class="computeroutput">bzip2</code> compresses files in
blocks, usually 900kbytes long. Each block is handled
independently. If a media or transmission error causes a
multi-block <code class="computeroutput">.bz2</code> file to become
damaged, it may be possible to recover data from the undamaged
blocks in the file.</p>
<p>The compressed representation of each block is delimited by
a 48-bit pattern, which makes it possible to find the block
boundaries with reasonable certainty. Each block also carries
its own 32-bit CRC, so damaged blocks can be distinguished from
undamaged ones.</p>
<p><code class="computeroutput">bzip2recover</code> is a simple
program whose purpose is to search for blocks in
<code class="computeroutput">.bz2</code> files, and write each block
out into its own <code class="computeroutput">.bz2</code> file. You
can then use <code class="computeroutput">bzip2 -t</code> to test
the integrity of the resulting files, and decompress those which
are undamaged.</p>
<p><code class="computeroutput">bzip2recover</code> takes a
single argument, the name of the damaged file, and writes a
number of files <code class="computeroutput">rec0001file.bz2</code>,
<code class="computeroutput">rec0002file.bz2</code>, etc, containing
the extracted blocks. The output filenames are designed so that
the use of wildcards in subsequent processing -- for example,
<code class="computeroutput">bzip2 -dc rec*file.bz2 >
recovered_data</code> -- lists the files in the correct
order.</p>
<p><code class="computeroutput">bzip2recover</code> should be of
most use dealing with large <code class="computeroutput">.bz2</code>
files, as these will contain many blocks. It is clearly futile
to use it on damaged single-block files, since a damaged block
cannot be recovered. If you wish to minimise any potential data
loss through media or transmission errors, you might consider
compressing with a smaller block size.</p>
</div>
<div class="sect1" title="2.7. PERFORMANCE NOTES">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="performance"></a>2.7. PERFORMANCE NOTES</h2></div></div></div>
<p>The sorting phase of compression gathers together similar
strings in the file. Because of this, files containing very long
runs of repeated symbols, like "aabaabaabaab ..." (repeated
several hundred times) may compress more slowly than normal.
Versions 0.9.5 and above fare much better than previous versions
in this respect. The ratio between worst-case and average-case
compression time is in the region of 10:1. For previous
versions, this figure was more like 100:1. You can use the
<code class="computeroutput">-vvvv</code> option to monitor progress
in great detail, if you want.</p>
<p>Decompression speed is unaffected by these
phenomena.</p>
<p><code class="computeroutput">bzip2</code> usually allocates
several megabytes of memory to operate in, and then charges all
over it in a fairly random fashion. This means that performance,
both for compressing and decompressing, is largely determined by
the speed at which your machine can service cache misses.
Because of this, small changes to the code to reduce the miss
rate have been observed to give disproportionately large
performance improvements. I imagine
<code class="computeroutput">bzip2</code> will perform best on
machines with very large caches.</p>
</div>
<div class="sect1" title="2.8. CAVEATS">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="caveats"></a>2.8. CAVEATS</h2></div></div></div>
<p>I/O error messages are not as helpful as they could be.
<code class="computeroutput">bzip2</code> tries hard to detect I/O
errors and exit cleanly, but the details of what the problem is
sometimes seem rather misleading.</p>
<p>This manual page pertains to version 1.0.6 of
<code class="computeroutput">bzip2</code>. Compressed data created by
this version is entirely forwards and backwards compatible with the
previous public releases, versions 0.1pl2, 0.9.0 and 0.9.5, 1.0.0,
1.0.1, 1.0.2 and 1.0.3, but with the following exception: 0.9.0 and
above can correctly decompress multiple concatenated compressed files.
0.1pl2 cannot do this; it will stop after decompressing just the first
file in the stream.</p>
<p><code class="computeroutput">bzip2recover</code> versions
prior to 1.0.2 used 32-bit integers to represent bit positions in
compressed files, so it could not handle compressed files more
than 512 megabytes long. Versions 1.0.2 and above use 64-bit ints
on some platforms which support them (GNU supported targets, and
Windows). To establish whether or not
<code class="computeroutput">bzip2recover</code> was built with such
a limitation, run it without arguments. In any event you can
build yourself an unlimited version if you can recompile it with
<code class="computeroutput">MaybeUInt64</code> set to be an
unsigned 64-bit integer.</p>
</div>
<div class="sect1" title="2.9. AUTHOR">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="author"></a>2.9. AUTHOR</h2></div></div></div>
<p>Julian Seward,
<code class="computeroutput">jseward@bzip.org</code></p>
<p>The ideas embodied in
<code class="computeroutput">bzip2</code> are due to (at least) the
following people: Michael Burrows and David Wheeler (for the
block sorting transformation), David Wheeler (again, for the
Huffman coder), Peter Fenwick (for the structured coding model in
the original <code class="computeroutput">bzip</code>, and many
refinements), and Alistair Moffat, Radford Neal and Ian Witten
(for the arithmetic coder in the original
<code class="computeroutput">bzip</code>). I am much indebted for
their help, support and advice. See the manual in the source
distribution for pointers to sources of documentation. Christian
von Roques encouraged me to look for faster sorting algorithms,
so as to speed up compression. Bela Lubkin encouraged me to
improve the worst-case compression performance.
Donna Robinson XMLised the documentation.
Many people sent
patches, helped with portability problems, lent machines, gave
advice and were generally helpful.</p>
</div>
</div>
<div class="chapter" title="3. Programming with libbzip2">
<div class="titlepage"><div><div><h2 class="title">
<a name="libprog"></a>3.
Programming with <code class="computeroutput">libbzip2</code>
</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="sect1"><a href="#top-level">3.1. Top-level structure</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#ll-summary">3.1.1. Low-level summary</a></span></dt>
<dt><span class="sect2"><a href="#hl-summary">3.1.2. High-level summary</a></span></dt>
<dt><span class="sect2"><a href="#util-fns-summary">3.1.3. Utility functions summary</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#err-handling">3.2. Error handling</a></span></dt>
<dt><span class="sect1"><a href="#low-level">3.3. Low-level interface</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#bzcompress-init">3.3.1. BZ2_bzCompressInit</a></span></dt>
<dt><span class="sect2"><a href="#bzCompress">3.3.2. BZ2_bzCompress</a></span></dt>
<dt><span class="sect2"><a href="#bzCompress-end">3.3.3. BZ2_bzCompressEnd</a></span></dt>
<dt><span class="sect2"><a href="#bzDecompress-init">3.3.4. BZ2_bzDecompressInit</a></span></dt>
<dt><span class="sect2"><a href="#bzDecompress">3.3.5. BZ2_bzDecompress</a></span></dt>
<dt><span class="sect2"><a href="#bzDecompress-end">3.3.6. BZ2_bzDecompressEnd</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#hl-interface">3.4. High-level interface</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#bzreadopen">3.4.1. BZ2_bzReadOpen</a></span></dt>
<dt><span class="sect2"><a href="#bzread">3.4.2. BZ2_bzRead</a></span></dt>
<dt><span class="sect2"><a href="#bzreadgetunused">3.4.3. BZ2_bzReadGetUnused</a></span></dt>
<dt><span class="sect2"><a href="#bzreadclose">3.4.4. BZ2_bzReadClose</a></span></dt>
<dt><span class="sect2"><a href="#bzwriteopen">3.4.5. BZ2_bzWriteOpen</a></span></dt>
<dt><span class="sect2"><a href="#bzwrite">3.4.6. BZ2_bzWrite</a></span></dt>
<dt><span class="sect2"><a href="#bzwriteclose">3.4.7. BZ2_bzWriteClose</a></span></dt>
<dt><span class="sect2"><a href="#embed">3.4.8. Handling embedded compressed data streams</a></span></dt>
<dt><span class="sect2"><a href="#std-rdwr">3.4.9. Standard file-reading/writing code</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#util-fns">3.5. Utility functions</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#bzbufftobuffcompress">3.5.1. BZ2_bzBuffToBuffCompress</a></span></dt>
<dt><span class="sect2"><a href="#bzbufftobuffdecompress">3.5.2. BZ2_bzBuffToBuffDecompress</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#zlib-compat">3.6. zlib compatibility functions</a></span></dt>
<dt><span class="sect1"><a href="#stdio-free">3.7. Using the library in a stdio-free environment</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="#stdio-bye">3.7.1. Getting rid of stdio</a></span></dt>
<dt><span class="sect2"><a href="#critical-error">3.7.2. Critical error handling</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#win-dll">3.8. Making a Windows DLL</a></span></dt>
</dl>
</div>
<p>This chapter describes the programming interface to
<code class="computeroutput">libbzip2</code>.</p>
<p>For general background information, particularly about
memory use and performance aspects, you'd be well advised to read
<a class="xref" href="#using" title="2. How to use bzip2">How to use bzip2</a> as well.</p>
<div class="sect1" title="3.1. Top-level structure">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="top-level"></a>3.1. Top-level structure</h2></div></div></div>
<p><code class="computeroutput">libbzip2</code> is a flexible
library for compressing and decompressing data in the
<code class="computeroutput">bzip2</code> data format. Although
packaged as a single entity, it helps to regard the library as
three separate parts: the low level interface, and the high level
interface, and some utility functions.</p>
<p>The structure of
<code class="computeroutput">libbzip2</code>'s interfaces is similar
to that of Jean-loup Gailly's and Mark Adler's excellent
<code class="computeroutput">zlib</code> library.</p>
<p>All externally visible symbols have names beginning
<code class="computeroutput">BZ2_</code>. This is new in version
1.0. The intention is to minimise pollution of the namespaces of
library clients.</p>
<p>To use any part of the library, you need to
<code class="computeroutput">#include <bzlib.h></code>
into your sources.</p>
<div class="sect2" title="3.1.1. Low-level summary">
<div class="titlepage"><div><div><h3 class="title">
<a name="ll-summary"></a>3.1.1. Low-level summary</h3></div></div></div>
<p>This interface provides services for compressing and
decompressing data in memory. There's no provision for dealing
with files, streams or any other I/O mechanisms, just straight
memory-to-memory work. In fact, this part of the library can be
compiled without inclusion of
<code class="computeroutput">stdio.h</code>, which may be helpful
for embedded applications.</p>
<p>The low-level part of the library has no global variables
and is therefore thread-safe.</p>
<p>Six routines make up the low level interface:
<code class="computeroutput">BZ2_bzCompressInit</code>,
<code class="computeroutput">BZ2_bzCompress</code>, and
<code class="computeroutput">BZ2_bzCompressEnd</code> for
compression, and a corresponding trio
<code class="computeroutput">BZ2_bzDecompressInit</code>,
<code class="computeroutput">BZ2_bzDecompress</code> and
<code class="computeroutput">BZ2_bzDecompressEnd</code> for
decompression. The <code class="computeroutput">*Init</code>
functions allocate memory for compression/decompression and do
other initialisations, whilst the
<code class="computeroutput">*End</code> functions close down
operations and release memory.</p>
<p>The real work is done by
<code class="computeroutput">BZ2_bzCompress</code> and
<code class="computeroutput">BZ2_bzDecompress</code>. These
compress and decompress data from a user-supplied input buffer to
a user-supplied output buffer. These buffers can be any size;
arbitrary quantities of data are handled by making repeated calls
to these functions. This is a flexible mechanism allowing a
consumer-pull style of activity, or producer-push, or a mixture
of both.</p>
</div>
<div class="sect2" title="3.1.2. High-level summary">
<div class="titlepage"><div><div><h3 class="title">
<a name="hl-summary"></a>3.1.2. High-level summary</h3></div></div></div>
<p>This interface provides some handy wrappers around the
low-level interface to facilitate reading and writing
<code class="computeroutput">bzip2</code> format files
(<code class="computeroutput">.bz2</code> files). The routines
provide hooks to facilitate reading files in which the
<code class="computeroutput">bzip2</code> data stream is embedded
within some larger-scale file structure, or where there are
multiple <code class="computeroutput">bzip2</code> data streams
concatenated end-to-end.</p>
<p>For reading files,
<code class="computeroutput">BZ2_bzReadOpen</code>,
<code class="computeroutput">BZ2_bzRead</code>,
<code class="computeroutput">BZ2_bzReadClose</code> and
<code class="computeroutput">BZ2_bzReadGetUnused</code> are
supplied. For writing files,
<code class="computeroutput">BZ2_bzWriteOpen</code>,
<code class="computeroutput">BZ2_bzWrite</code> and
<code class="computeroutput">BZ2_bzWriteFinish</code> are
available.</p>
<p>As with the low-level library, no global variables are used
so the library is per se thread-safe. However, if I/O errors
occur whilst reading or writing the underlying compressed files,
you may have to consult <code class="computeroutput">errno</code> to
determine the cause of the error. In that case, you'd need a C
library which correctly supports
<code class="computeroutput">errno</code> in a multithreaded
environment.</p>
<p>To make the library a little simpler and more portable,
<code class="computeroutput">BZ2_bzReadOpen</code> and
<code class="computeroutput">BZ2_bzWriteOpen</code> require you to
pass them file handles (<code class="computeroutput">FILE*</code>s)
which have previously been opened for reading or writing
respectively. That avoids portability problems associated with
file operations and file attributes, whilst not being much of an
imposition on the programmer.</p>
</div>
<div class="sect2" title="3.1.3. Utility functions summary">
<div class="titlepage"><div><div><h3 class="title">
<a name="util-fns-summary"></a>3.1.3. Utility functions summary</h3></div></div></div>
<p>For very simple needs,
<code class="computeroutput">BZ2_bzBuffToBuffCompress</code> and
<code class="computeroutput">BZ2_bzBuffToBuffDecompress</code> are
provided. These compress data in memory from one buffer to
another buffer in a single function call. You should assess
whether these functions fulfill your memory-to-memory
compression/decompression requirements before investing effort in
understanding the more general but more complex low-level
interface.</p>
<p>Yoshioka Tsuneo
(<code class="computeroutput">tsuneo@rr.iij4u.or.jp</code>) has
contributed some functions to give better
<code class="computeroutput">zlib</code> compatibility. These
functions are <code class="computeroutput">BZ2_bzopen</code>,
<code class="computeroutput">BZ2_bzread</code>,
<code class="computeroutput">BZ2_bzwrite</code>,
<code class="computeroutput">BZ2_bzflush</code>,
<code class="computeroutput">BZ2_bzclose</code>,
<code class="computeroutput">BZ2_bzerror</code> and
<code class="computeroutput">BZ2_bzlibVersion</code>. You may find
these functions more convenient for simple file reading and
writing, than those in the high-level interface. These functions
are not (yet) officially part of the library, and are minimally
documented here. If they break, you get to keep all the pieces.
I hope to document them properly when time permits.</p>
<p>Yoshioka also contributed modifications to allow the
library to be built as a Windows DLL.</p>
</div>
</div>
<div class="sect1" title="3.2. Error handling">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="err-handling"></a>3.2. Error handling</h2></div></div></div>
<p>The library is designed to recover cleanly in all
situations, including the worst-case situation of decompressing
random data. I'm not 100% sure that it can always do this, so
you might want to add a signal handler to catch segmentation
violations during decompression if you are feeling especially
paranoid. I would be interested in hearing more about the
robustness of the library to corrupted compressed data.</p>
<p>Version 1.0.3 more robust in this respect than any
previous version. Investigations with Valgrind (a tool for detecting
problems with memory management) indicate
that, at least for the few files I tested, all single-bit errors
in the decompressed data are caught properly, with no
segmentation faults, no uses of uninitialised data, no out of
range reads or writes, and no infinite looping in the decompressor.
So it's certainly pretty robust, although
I wouldn't claim it to be totally bombproof.</p>
<p>The file <code class="computeroutput">bzlib.h</code> contains
all definitions needed to use the library. In particular, you
should definitely not include
<code class="computeroutput">bzlib_private.h</code>.</p>
<p>In <code class="computeroutput">bzlib.h</code>, the various
return values are defined. The following list is not intended as
an exhaustive description of the circumstances in which a given
value may be returned -- those descriptions are given later.
Rather, it is intended to convey the rough meaning of each return
value. The first five actions are normal and not intended to
denote an error situation.</p>
<div class="variablelist"><dl>
<dt><span class="term"><code class="computeroutput">BZ_OK</code></span></dt>
<dd><p>The requested action was completed
successfully.</p></dd>
<dt><span class="term"><code class="computeroutput">BZ_RUN_OK, BZ_FLUSH_OK,
BZ_FINISH_OK</code></span></dt>
<dd><p>In
<code class="computeroutput">BZ2_bzCompress</code>, the requested
flush/finish/nothing-special action was completed
successfully.</p></dd>
<dt><span class="term"><code class="computeroutput">BZ_STREAM_END</code></span></dt>
<dd><p>Compression of data was completed, or the
logical stream end was detected during
decompression.</p></dd>
</dl></div>
<p>The following return values indicate an error of some
kind.</p>
<div class="variablelist"><dl>
<dt><span class="term"><code class="computeroutput">BZ_CONFIG_ERROR</code></span></dt>
<dd><p>Indicates that the library has been improperly
compiled on your platform -- a major configuration error.
Specifically, it means that
<code class="computeroutput">sizeof(char)</code>,
<code class="computeroutput">sizeof(short)</code> and
<code class="computeroutput">sizeof(int)</code> are not 1, 2 and
4 respectively, as they should be. Note that the library
should still work properly on 64-bit platforms which follow
the LP64 programming model -- that is, where
<code class="computeroutput">sizeof(long)</code> and
<code class="computeroutput">sizeof(void*)</code> are 8. Under
LP64, <code class="computeroutput">sizeof(int)</code> is still 4,
so <code class="computeroutput">libbzip2</code>, which doesn't
use the <code class="computeroutput">long</code> type, is
OK.</p></dd>
<dt><span class="term"><code class="computeroutput">BZ_SEQUENCE_ERROR</code></span></dt>
<dd><p>When using the library, it is important to call
the functions in the correct sequence and with data structures
(buffers etc) in the correct states.
<code class="computeroutput">libbzip2</code> checks as much as it
can to ensure this is happening, and returns
<code class="computeroutput">BZ_SEQUENCE_ERROR</code> if not.
Code which complies precisely with the function semantics, as
detailed below, should never receive this value; such an event
denotes buggy code which you should
investigate.</p></dd>
<dt><span class="term"><code class="computeroutput">BZ_PARAM_ERROR</code></span></dt>
<dd><p>Returned when a parameter to a function call is
out of range or otherwise manifestly incorrect. As with
<code class="computeroutput">BZ_SEQUENCE_ERROR</code>, this
denotes a bug in the client code. The distinction between
<code class="computeroutput">BZ_PARAM_ERROR</code> and
<code class="computeroutput">BZ_SEQUENCE_ERROR</code> is a bit
hazy, but still worth making.</p></dd>
<dt><span class="term"><code class="computeroutput">BZ_MEM_ERROR</code></span></dt>
<dd><p>Returned when a request to allocate memory
failed. Note that the quantity of memory needed to decompress
a stream cannot be determined until the stream's header has
been read. So
<code class="computeroutput">BZ2_bzDecompress</code> and
<code class="computeroutput">BZ2_bzRead</code> may return
<code class="computeroutput">BZ_MEM_ERROR</code> even though some
of the compressed data has been read. The same is not true
for compression; once
<code class="computeroutput">BZ2_bzCompressInit</code> or
<code class="computeroutput">BZ2_bzWriteOpen</code> have
successfully completed,
<code class="computeroutput">BZ_MEM_ERROR</code> cannot
occur.</p></dd>
<dt><span class="term"><code class="computeroutput">BZ_DATA_ERROR</code></span></dt>
<dd><p>Returned when a data integrity error is
detected during decompression. Most importantly, this means
when stored and computed CRCs for the data do not match. This
value is also returned upon detection of any other anomaly in
the compressed data.</p></dd>
<dt><span class="term"><code class="computeroutput">BZ_DATA_ERROR_MAGIC</code></span></dt>
<dd><p>As a special case of
<code class="computeroutput">BZ_DATA_ERROR</code>, it is
sometimes useful to know when the compressed stream does not
start with the correct magic bytes (<code class="computeroutput">'B' 'Z'
'h'</code>).</p></dd>
<dt><span class="term"><code class="computeroutput">BZ_IO_ERROR</code></span></dt>
<dd><p>Returned by
<code class="computeroutput">BZ2_bzRead</code> and
<code class="computeroutput">BZ2_bzWrite</code> when there is an
error reading or writing in the compressed file, and by
<code class="computeroutput">BZ2_bzReadOpen</code> and
<code class="computeroutput">BZ2_bzWriteOpen</code> for attempts
to use a file for which the error indicator (viz,
<code class="computeroutput">ferror(f)</code>) is set. On
receipt of <code class="computeroutput">BZ_IO_ERROR</code>, the
caller should consult <code class="computeroutput">errno</code>
and/or <code class="computeroutput">perror</code> to acquire
operating-system specific information about the
problem.</p></dd>
<dt><span class="term"><code class="computeroutput">BZ_UNEXPECTED_EOF</code></span></dt>
<dd><p>Returned by
<code class="computeroutput">BZ2_bzRead</code> when the