/StormLib/stormlib/bzip2/manual.html
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 > 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 <bzlib.h></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