PageRenderTime 62ms CodeModel.GetById 20ms app.highlight 27ms RepoModel.GetById 1ms app.codeStats 0ms

/StormLib/stormlib/bzip2/manual.html

http://ghostcb.googlecode.com/
HTML | 2540 lines | 2509 code | 31 blank | 0 comment | 0 complexity | 9363d211e9b4a49a3f325c1d65e8adec MD5 | raw file

Large files files are truncated, but you can click here to view the full file

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

Large files files are truncated, but you can click here to view the full file