diff options
Diffstat (limited to 'Master')
| -rwxr-xr-x | Master/bin/win32/bzip2.exe | bin | 67072 -> 0 bytes | |||
| -rwxr-xr-x | Master/bin/win32/bzip2recover.exe | bin | 8192 -> 0 bytes | |||
| -rwxr-xr-x | Master/bin/win32/tl90bzip2.dll | bin | 57344 -> 0 bytes | |||
| -rw-r--r-- | Master/texmf/doc/bzip2/bzip2.html | 2141 | ||||
| -rw-r--r-- | Master/texmf/doc/bzip2/bzip2.pdf | bin | 210902 -> 0 bytes | |||
| -rw-r--r-- | Master/texmf/doc/bzip2/manual.html | 117 | ||||
| -rw-r--r-- | Master/tlpkg/tlpsrc/bin-bzip2.tlpsrc | 9 | ||||
| -rw-r--r-- | Master/tlpkg/tlpsrc/collection-wintools.tlpsrc | 3 |
8 files changed, 1 insertions, 2269 deletions
diff --git a/Master/bin/win32/bzip2.exe b/Master/bin/win32/bzip2.exe Binary files differdeleted file mode 100755 index 8f3efcd7d28..00000000000 --- a/Master/bin/win32/bzip2.exe +++ /dev/null diff --git a/Master/bin/win32/bzip2recover.exe b/Master/bin/win32/bzip2recover.exe Binary files differdeleted file mode 100755 index 9cd3bd122bf..00000000000 --- a/Master/bin/win32/bzip2recover.exe +++ /dev/null diff --git a/Master/bin/win32/tl90bzip2.dll b/Master/bin/win32/tl90bzip2.dll Binary files differdeleted file mode 100755 index a7bd8ca12c7..00000000000 --- a/Master/bin/win32/tl90bzip2.dll +++ /dev/null diff --git a/Master/texmf/doc/bzip2/bzip2.html b/Master/texmf/doc/bzip2/bzip2.html deleted file mode 100644 index 0443d233166..00000000000 --- a/Master/texmf/doc/bzip2/bzip2.html +++ /dev/null @@ -1,2141 +0,0 @@ -<html lang="en"> -<head> -<title>Untitled</title> -<meta http-equiv="Content-Type" content="text/html"> -<meta name="description" content="Untitled"> -<meta name="generator" content="makeinfo 4.7"> -<link title="Top" rel="top" href="#Top"> -<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> -<meta http-equiv="Content-Style-Type" content="text/css"> -<style type="text/css"><!-- - pre.display { font-family:inherit } - pre.format { font-family:inherit } - pre.smalldisplay { font-family:inherit; font-size:smaller } - pre.smallformat { font-family:inherit; font-size:smaller } - pre.smallexample { font-size:smaller } - pre.smalllisp { font-size:smaller } - span.sc { font-variant:small-caps } - span.roman { font-family: serif; font-weight: normal; } ---></style> -</head> -<body> -<div class="node"> -<p><hr> -<a name="Top"></a>Up: <a rel="up" accesskey="u" href="#dir">(dir)</a> -<br> -</div> - - <p>The following text is the License for this software. You should -find it identical to that contained in the file LICENSE in the -source distribution. - - <p>————————– START OF THE LICENSE ————————– - - <p>This program, <code>bzip2</code>, -and associated library <code>libbzip2</code>, are -Copyright (C) 1996-2002 Julian R Seward. All rights reserved. - - <p>Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: - <ul> -<li> Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. -<li> The origin of this software must not be misrepresented; you must - not claim that you wrote the original software. If you use this - software in a product, an acknowledgment in the product - documentation would be appreciated but is not required. -<li> Altered source versions must be plainly marked as such, and must - not be misrepresented as being the original software. -<li> The name of the author may not be used to endorse or promote - products derived from this software without specific prior written - permission. -</ul> - THIS SOFTWARE IS PROVIDED BY THE AUTHOR “AS IS” AND ANY EXPRESS -OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY -DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE -GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, -WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - <p>Julian Seward, Cambridge, UK. - - <p><code>jseward@acm.org</code> - - <p><code>bzip2</code>/<code>libbzip2</code> version 1.0.2 of 30 December 2001. - - <p>————————– END OF THE LICENSE ————————– - - <p>Web sites: - - <p><code>http://sources.redhat.com/bzip2</code> - - <p><code>http://www.cacheprof.org</code> - - <p>PATENTS: To the best of my knowledge, <code>bzip2</code> does not use any patented -algorithms. However, I do not have the resources available to carry out -a full patent search. Therefore I cannot give any guarantee of the -above statement. - -<h2 class="chapter">1 Introduction</h2> - -<p><code>bzip2</code> compresses files using the Burrows-Wheeler -block-sorting text compression algorithm, and Huffman coding. -Compression is generally considerably better than that -achieved by more conventional LZ77/LZ78-based compressors, -and approaches the performance of the PPM family of statistical compressors. - - <p><code>bzip2</code> is built on top of <code>libbzip2</code>, a flexible library -for handling compressed data in the <code>bzip2</code> format. This manual -describes both how to use the program and -how to work with the library interface. Most of the -manual is devoted to this library, not the program, -which is good news if your interest is only in the program. - - <p>Chapter 2 describes how to use <code>bzip2</code>; this is the only part -you need to read if you just want to know how to operate the program. -Chapter 3 describes the programming interfaces in detail, and -Chapter 4 records some miscellaneous notes which I thought -ought to be recorded somewhere. - -<h2 class="chapter">2 How to use <code>bzip2</code></h2> - -<p>This chapter contains a copy of the <code>bzip2</code> man page, -and nothing else. - - <blockquote> - -<h5 class="unnumberedsubsubsec">NAME</h5> - - <ul> -<li><code>bzip2</code>, <code>bunzip2</code> -- a block-sorting file compressor, v1.0.2 -<li><code>bzcat</code> -- decompresses files to stdout -<li><code>bzip2recover</code> -- recovers data from damaged bzip2 files -</ul> - -<h5 class="unnumberedsubsubsec">SYNOPSIS</h5> - - <ul> -<li><code>bzip2</code> [ -cdfkqstvzVL123456789 ] [ filenames ... ] -<li><code>bunzip2</code> [ -fkvsVL ] [ filenames ... ] -<li><code>bzcat</code> [ -s ] [ filenames ... ] -<li><code>bzip2recover</code> filename -</ul> - -<h5 class="unnumberedsubsubsec">DESCRIPTION</h5> - - <p><code>bzip2</code> compresses files using the Burrows-Wheeler block sorting -text compression algorithm, and Huffman coding. Compression is -generally considerably better than that achieved by more conventional -LZ77/LZ78-based compressors, and approaches the performance of the PPM -family of statistical compressors. - - <p>The command-line options are deliberately very similar to those of GNU -<code>gzip</code>, but they are not identical. - - <p><code>bzip2</code> expects a list of file names to accompany the command-line -flags. Each file is replaced by a compressed version of itself, with -the name <code>original_name.bz2</code>. Each compressed file has the same -modification date, permissions, and, when possible, ownership as the -corresponding original, so that these properties can be correctly -restored at decompression time. File name handling is naive in the -sense that there is no mechanism for preserving original file names, -permissions, ownerships or dates in filesystems which lack these -concepts, or have serious file name length restrictions, such as MS-DOS. - - <p><code>bzip2</code> and <code>bunzip2</code> will by default not overwrite existing -files. If you want this to happen, specify the <code>-f</code> flag. - - <p>If no file names are specified, <code>bzip2</code> compresses from standard -input to standard output. In this case, <code>bzip2</code> will decline to -write compressed output to a terminal, as this would be entirely -incomprehensible and therefore pointless. - - <p><code>bunzip2</code> (or <code>bzip2 -d</code>) decompresses all -specified files. Files which were not created by <code>bzip2</code> -will be detected and ignored, and a warning issued. -<code>bzip2</code> attempts to guess the filename for the decompressed file -from that of the compressed file as follows: - <ul> -<li><code>filename.bz2 </code> becomes <code>filename</code> -<li><code>filename.bz </code> becomes <code>filename</code> -<li><code>filename.tbz2</code> becomes <code>filename.tar</code> -<li><code>filename.tbz </code> becomes <code>filename.tar</code> -<li><code>anyothername </code> becomes <code>anyothername.out</code> -</ul> - If the file does not end in one of the recognised endings, -<code>.bz2</code>, <code>.bz</code>, -<code>.tbz2</code> or <code>.tbz</code>, <code>bzip2</code> complains that it cannot -guess the name of the original file, and uses the original name -with <code>.out</code> appended. - - <p>As with compression, supplying no -filenames causes decompression from standard input to standard output. - - <p><code>bunzip2</code> will correctly decompress a file which is the -concatenation of two or more compressed files. The result is the -concatenation of the corresponding uncompressed files. Integrity -testing (<code>-t</code>) of concatenated compressed files is also supported. - - <p>You can also compress or decompress files to the standard output by -giving the <code>-c</code> flag. Multiple files may be compressed and -decompressed like this. The resulting outputs are fed sequentially to -stdout. Compression of multiple files in this manner generates a stream -containing multiple compressed file representations. Such a stream -can be decompressed correctly only by <code>bzip2</code> version 0.9.0 or -later. Earlier versions of <code>bzip2</code> will stop after decompressing -the first file in the stream. - - <p><code>bzcat</code> (or <code>bzip2 -dc</code>) decompresses all specified files to -the standard output. - - <p><code>bzip2</code> will read arguments from the environment variables -<code>BZIP2</code> and <code>BZIP</code>, in that order, and will process them -before any arguments read from the command line. This gives a -convenient way to supply default arguments. - - <p>Compression is always performed, even if the compressed file is slightly -larger than the original. Files of less than about one hundred bytes -tend to get larger, since the compression mechanism has a constant -overhead in the region of 50 bytes. Random data (including the output -of most file compressors) is coded at about 8.05 bits per byte, giving -an expansion of around 0.5%. - - <p>As a self-check for your protection, <code>bzip2</code> uses 32-bit CRCs to -make sure that the decompressed version of a file is identical to the -original. This guards against corruption of the compressed data, and -against undetected bugs in <code>bzip2</code> (hopefully very unlikely). The -chances of data corruption going undetected is microscopic, about one -chance in four billion for each file processed. Be aware, though, that -the check occurs upon decompression, so it can only tell you that -something is wrong. It can't help you recover the original uncompressed -data. You can use <code>bzip2recover</code> to try to recover data from -damaged files. - - <p>Return values: 0 for a normal exit, 1 for environmental problems (file -not found, invalid flags, I/O errors, &c), 2 to indicate a corrupt -compressed file, 3 for an internal consistency error (eg, bug) which -caused <code>bzip2</code> to panic. - -<h5 class="unnumberedsubsubsec">OPTIONS</h5> - - <dl> -<dt><code>-c --stdout</code><dd>Compress or decompress to standard output. -<br><dt><code>-d --decompress</code><dd>Force decompression. <code>bzip2</code>, <code>bunzip2</code> and <code>bzcat</code> are -really the same program, and the decision about what actions to take is -done on the basis of which name is used. This flag overrides that -mechanism, and forces bzip2 to decompress. -<br><dt><code>-z --compress</code><dd>The complement to <code>-d</code>: forces compression, regardless of the -invokation name. -<br><dt><code>-t --test</code><dd>Check integrity of the specified file(s), but don't decompress them. -This really performs a trial decompression and throws away the result. -<br><dt><code>-f --force</code><dd>Force overwrite of output files. Normally, <code>bzip2</code> will not overwrite -existing output files. Also forces <code>bzip2</code> to break hard links -to files, which it otherwise wouldn't do. - - <p><code>bzip2</code> normally declines to decompress files which don't have the -correct magic header bytes. If forced (<code>-f</code>), however, it will -pass such files through unmodified. This is how GNU <code>gzip</code> -behaves. -<br><dt><code>-k --keep</code><dd>Keep (don't delete) input files during compression -or decompression. -<br><dt><code>-s --small</code><dd>Reduce memory usage, for compression, decompression and testing. Files -are decompressed and tested using a modified algorithm which only -requires 2.5 bytes per block byte. This means any file can be -decompressed in 2300k of memory, albeit at about half the normal speed. - - <p>During compression, <code>-s</code> selects a block size of 200k, which limits -memory use to around the same figure, at the expense of your compression -ratio. In short, if your machine is low on memory (8 megabytes or -less), use -s for everything. See MEMORY MANAGEMENT below. -<br><dt><code>-q --quiet</code><dd>Suppress non-essential warning messages. Messages pertaining to -I/O errors and other critical events will not be suppressed. -<br><dt><code>-v --verbose</code><dd>Verbose mode – show the compression ratio for each file processed. -Further <code>-v</code>'s increase the verbosity level, spewing out lots of -information which is primarily of interest for diagnostic purposes. -<br><dt><code>-L --license -V --version</code><dd>Display the software version, license terms and conditions. -<br><dt><code>-1 (or --fast) to -9 (or --best)</code><dd>Set the block size to 100 k, 200 k .. 900 k when compressing. Has no -effect when decompressing. See MEMORY MANAGEMENT below. -The <code>--fast</code> and <code>--best</code> aliases are primarily for GNU -<code>gzip</code> compatibility. In particular, <code>--fast</code> doesn't make -things significantly faster. And <code>--best</code> merely selects the -default behaviour. -<br><dt><code>--</code><dd>Treats all subsequent arguments as file names, even if they start -with a dash. This is so you can handle files with names beginning -with a dash, for example: <code>bzip2 -- -myfilename</code>. -<br><dt><code>--repetitive-fast</code><br><dt><code>--repetitive-best</code><dd>These flags are redundant in versions 0.9.5 and above. They provided -some coarse control over the behaviour of the sorting algorithm in -earlier versions, which was sometimes useful. 0.9.5 and above have an -improved algorithm which renders these flags irrelevant. -</dl> - -<h5 class="unnumberedsubsubsec">MEMORY MANAGEMENT</h5> - - <p><code>bzip2</code> compresses large files in blocks. The block size affects -both the compression ratio achieved, and the amount of memory needed for -compression and decompression. The flags <code>-1</code> through <code>-9</code> -specify the block size to be 100,000 bytes through 900,000 bytes (the -default) respectively. At decompression time, the block size used for -compression is read from the header of the compressed file, and -<code>bunzip2</code> then allocates itself just enough memory to decompress -the file. Since block sizes are stored in compressed files, it follows -that the flags <code>-1</code> to <code>-9</code> are irrelevant to and so ignored -during decompression. - - <p>Compression and decompression requirements, in bytes, can be estimated -as: - <pre class="example"> Compression: 400k + ( 8 x block size ) - - Decompression: 100k + ( 4 x block size ), or - 100k + ( 2.5 x block size ) - </pre> - <p>Larger block sizes give rapidly diminishing marginal returns. Most of -the compression comes from the first two or three hundred k of block -size, a fact worth bearing in mind when using <code>bzip2</code> on small machines. -It is also important to appreciate that the decompression memory -requirement is set at compression time by the choice of block size. - - <p>For files compressed with the default 900k block size, <code>bunzip2</code> -will require about 3700 kbytes to decompress. To support decompression -of any file on a 4 megabyte machine, <code>bunzip2</code> has an option to -decompress using approximately half this amount of memory, about 2300 -kbytes. Decompression speed is also halved, so you should use this -option only where necessary. The relevant flag is <code>-s</code>. - - <p>In general, try and use the largest block size memory constraints allow, -since that maximises the compression achieved. Compression and -decompression speed are virtually unaffected by block size. - - <p>Another significant point applies to files which fit in a single block -– that means most files you'd encounter using a large block size. The -amount of real memory touched is proportional to the size of the file, -since the file is smaller than a block. For example, compressing a file -20,000 bytes long with the flag <code>-9</code> will cause the compressor to -allocate around 7600k of memory, but only touch 400k + 20000 * 8 = 560 -kbytes of it. Similarly, the decompressor will allocate 3700k but only -touch 100k + 20000 * 4 = 180 kbytes. - - <p>Here is a table which summarises the maximum memory usage for different -block sizes. Also recorded is the total compressed size for 14 files of -the Calgary Text Compression Corpus totalling 3,141,622 bytes. This -column gives some feel for how compression varies with block size. -These figures tend to understate the advantage of larger block sizes for -larger files, since the Corpus is dominated by smaller files. - <pre class="example"> Compress Decompress Decompress Corpus - Flag usage usage -s usage Size - - -1 1200k 500k 350k 914704 - -2 2000k 900k 600k 877703 - -3 2800k 1300k 850k 860338 - -4 3600k 1700k 1100k 846899 - -5 4400k 2100k 1350k 845160 - -6 5200k 2500k 1600k 838626 - -7 6100k 2900k 1850k 834096 - -8 6800k 3300k 2100k 828642 - -9 7600k 3700k 2350k 828642 - </pre> - <h5 class="unnumberedsubsubsec">RECOVERING DATA FROM DAMAGED FILES</h5> - - <p><code>bzip2</code> compresses files in blocks, usually 900kbytes long. Each -block is handled independently. If a media or transmission error causes -a multi-block <code>.bz2</code> file to become damaged, it may be possible to -recover data from the undamaged blocks in the file. - - <p>The compressed representation of each block is delimited by a 48-bit -pattern, which makes it possible to find the block boundaries with -reasonable certainty. Each block also carries its own 32-bit CRC, so -damaged blocks can be distinguished from undamaged ones. - - <p><code>bzip2recover</code> is a simple program whose purpose is to search for -blocks in <code>.bz2</code> files, and write each block out into its own -<code>.bz2</code> file. You can then use <code>bzip2 -t</code> to test the -integrity of the resulting files, and decompress those which are -undamaged. - - <p><code>bzip2recover</code> -takes a single argument, the name of the damaged file, and writes a -number of files <code>rec00001file.bz2</code>, <code>rec00002file.bz2</code>, etc, -containing the extracted blocks. The output filenames are designed so -that the use of wildcards in subsequent processing – for example, -<code>bzip2 -dc rec*file.bz2 > recovered_data</code> – processes the files in -the correct order. - - <p><code>bzip2recover</code> should be of most use dealing with large <code>.bz2</code> -files, as these will contain many blocks. It is clearly futile to use -it on damaged single-block files, since a damaged block cannot be -recovered. If you wish to minimise any potential data loss through -media or transmission errors, you might consider compressing with a -smaller block size. - -<h5 class="unnumberedsubsubsec">PERFORMANCE NOTES</h5> - - <p>The sorting phase of compression gathers together similar strings in the -file. Because of this, files containing very long runs of repeated -symbols, like "aabaabaabaab ..." (repeated several hundred times) may -compress more slowly than normal. Versions 0.9.5 and above fare much -better than previous versions in this respect. The ratio between -worst-case and average-case compression time is in the region of 10:1. -For previous versions, this figure was more like 100:1. You can use the -<code>-vvvv</code> option to monitor progress in great detail, if you want. - - <p>Decompression speed is unaffected by these phenomena. - - <p><code>bzip2</code> usually allocates several megabytes of memory to operate -in, and then charges all over it in a fairly random fashion. This means -that performance, both for compressing and decompressing, is largely -determined by the speed at which your machine can service cache misses. -Because of this, small changes to the code to reduce the miss rate have -been observed to give disproportionately large performance improvements. -I imagine <code>bzip2</code> will perform best on machines with very large -caches. - -<h5 class="unnumberedsubsubsec">CAVEATS</h5> - - <p>I/O error messages are not as helpful as they could be. <code>bzip2</code> -tries hard to detect I/O errors and exit cleanly, but the details of -what the problem is sometimes seem rather misleading. - - <p>This manual page pertains to version 1.0.2 of <code>bzip2</code>. Compressed -data created by this version is entirely forwards and backwards -compatible with the previous public releases, versions 0.1pl2, 0.9.0, -0.9.5, 1.0.0 and 1.0.1, but with the following exception: 0.9.0 and -above can correctly decompress multiple concatenated compressed files. -0.1pl2 cannot do this; it will stop after decompressing just the first -file in the stream. - - <p><code>bzip2recover</code> versions prior to this one, 1.0.2, used 32-bit -integers to represent bit positions in compressed files, so it could not -handle compressed files more than 512 megabytes long. Version 1.0.2 and -above uses 64-bit ints on some platforms which support them (GNU -supported targets, and Windows). To establish whether or not -<code>bzip2recover</code> was built with such a limitation, run it without -arguments. In any event you can build yourself an unlimited version if -you can recompile it with <code>MaybeUInt64</code> set to be an unsigned -64-bit integer. - -<h5 class="unnumberedsubsubsec">AUTHOR</h5> - - <p>Julian Seward, <code>jseward@acm.org</code>. - - <p><code>http://sources.redhat.com/bzip2</code> - - <p>The ideas embodied in <code>bzip2</code> are due to (at least) the following -people: Michael Burrows and David Wheeler (for the block sorting -transformation), David Wheeler (again, for the Huffman coder), Peter -Fenwick (for the structured coding model in the original <code>bzip</code>, -and many refinements), and Alistair Moffat, Radford Neal and Ian Witten -(for the arithmetic coder in the original <code>bzip</code>). I am much -indebted for their help, support and advice. See the manual in the -source distribution for pointers to sources of documentation. Christian -von Roques encouraged me to look for faster sorting algorithms, so as to -speed up compression. Bela Lubkin encouraged me to improve the -worst-case compression performance. The <code>bz*</code> scripts are derived -from those of GNU <code>gzip</code>. Many people sent patches, helped with -portability problems, lent machines, gave advice and were generally -helpful. - - </blockquote> - -<h2 class="chapter">3 Programming with <code>libbzip2</code></h2> - -<p>This chapter describes the programming interface to <code>libbzip2</code>. - - <p>For general background information, particularly about memory -use and performance aspects, you'd be well advised to read Chapter 2 -as well. - -<h3 class="section">3.1 Top-level structure</h3> - -<p><code>libbzip2</code> is a flexible library for compressing and decompressing -data in the <code>bzip2</code> data format. Although packaged as a single -entity, it helps to regard the library as three separate parts: the low -level interface, and the high level interface, and some utility -functions. - - <p>The structure of <code>libbzip2</code>'s interfaces is similar to -that of Jean-loup Gailly's and Mark Adler's excellent <code>zlib</code> -library. - - <p>All externally visible symbols have names beginning <code>BZ2_</code>. -This is new in version 1.0. The intention is to minimise pollution -of the namespaces of library clients. - -<h4 class="subsection">3.1.1 Low-level summary</h4> - -<p>This interface provides services for compressing and decompressing -data in memory. There's no provision for dealing with files, streams -or any other I/O mechanisms, just straight memory-to-memory work. -In fact, this part of the library can be compiled without inclusion -of <code>stdio.h</code>, which may be helpful for embedded applications. - - <p>The low-level part of the library has no global variables and -is therefore thread-safe. - - <p>Six routines make up the low level interface: -<code>BZ2_bzCompressInit</code>, <code>BZ2_bzCompress</code>, and <br> <code>BZ2_bzCompressEnd</code> -for compression, -and a corresponding trio <code>BZ2_bzDecompressInit</code>, <br> <code>BZ2_bzDecompress</code> -and <code>BZ2_bzDecompressEnd</code> for decompression. -The <code>*Init</code> functions allocate -memory for compression/decompression and do other -initialisations, whilst the <code>*End</code> functions close down operations -and release memory. - - <p>The real work is done by <code>BZ2_bzCompress</code> and <code>BZ2_bzDecompress</code>. -These compress and decompress data from a user-supplied input buffer -to a user-supplied output buffer. These buffers can be any size; -arbitrary quantities of data are handled by making repeated calls -to these functions. This is a flexible mechanism allowing a -consumer-pull style of activity, or producer-push, or a mixture of -both. - -<h4 class="subsection">3.1.2 High-level summary</h4> - -<p>This interface provides some handy wrappers around the low-level -interface to facilitate reading and writing <code>bzip2</code> format -files (<code>.bz2</code> files). The routines provide hooks to facilitate -reading files in which the <code>bzip2</code> data stream is embedded -within some larger-scale file structure, or where there are -multiple <code>bzip2</code> data streams concatenated end-to-end. - - <p>For reading files, <code>BZ2_bzReadOpen</code>, <code>BZ2_bzRead</code>, -<code>BZ2_bzReadClose</code> and <br> <code>BZ2_bzReadGetUnused</code> are supplied. For -writing files, <code>BZ2_bzWriteOpen</code>, <code>BZ2_bzWrite</code> and -<code>BZ2_bzWriteFinish</code> are available. - - <p>As with the low-level library, no global variables are used -so the library is per se thread-safe. However, if I/O errors -occur whilst reading or writing the underlying compressed files, -you may have to consult <code>errno</code> to determine the cause of -the error. In that case, you'd need a C library which correctly -supports <code>errno</code> in a multithreaded environment. - - <p>To make the library a little simpler and more portable, -<code>BZ2_bzReadOpen</code> and <code>BZ2_bzWriteOpen</code> require you to pass them file -handles (<code>FILE*</code>s) which have previously been opened for reading or -writing respectively. That avoids portability problems associated with -file operations and file attributes, whilst not being much of an -imposition on the programmer. - -<h4 class="subsection">3.1.3 Utility functions summary</h4> - -<p>For very simple needs, <code>BZ2_bzBuffToBuffCompress</code> and -<code>BZ2_bzBuffToBuffDecompress</code> are provided. These compress -data in memory from one buffer to another buffer in a single -function call. You should assess whether these functions -fulfill your memory-to-memory compression/decompression -requirements before investing effort in understanding the more -general but more complex low-level interface. - - <p>Yoshioka Tsuneo (<code>QWF00133@niftyserve.or.jp</code> / -<code>tsuneo-y@is.aist-nara.ac.jp</code>) has contributed some functions to -give better <code>zlib</code> compatibility. These functions are -<code>BZ2_bzopen</code>, <code>BZ2_bzread</code>, <code>BZ2_bzwrite</code>, <code>BZ2_bzflush</code>, -<code>BZ2_bzclose</code>, -<code>BZ2_bzerror</code> and <code>BZ2_bzlibVersion</code>. You may find these functions -more convenient for simple file reading and writing, than those in the -high-level interface. These functions are not (yet) officially part of -the library, and are minimally documented here. If they break, you -get to keep all the pieces. I hope to document them properly when time -permits. - - <p>Yoshioka also contributed modifications to allow the library to be -built as a Windows DLL. - -<h3 class="section">3.2 Error handling</h3> - -<p>The library is designed to recover cleanly in all situations, including -the worst-case situation of decompressing random data. I'm not -100% sure that it can always do this, so you might want to add -a signal handler to catch segmentation violations during decompression -if you are feeling especially paranoid. I would be interested in -hearing more about the robustness of the library to corrupted -compressed data. - - <p>Version 1.0 is much more robust in this respect than -0.9.0 or 0.9.5. Investigations with Checker (a tool for -detecting problems with memory management, similar to Purify) -indicate that, at least for the few files I tested, all single-bit -errors in the decompressed data are caught properly, with no -segmentation faults, no reads of uninitialised data and no -out of range reads or writes. So it's certainly much improved, -although I wouldn't claim it to be totally bombproof. - - <p>The file <code>bzlib.h</code> contains all definitions needed to use -the library. In particular, you should definitely not include -<code>bzlib_private.h</code>. - - <p>In <code>bzlib.h</code>, the various return values are defined. The following -list is not intended as an exhaustive description of the circumstances -in which a given value may be returned – those descriptions are given -later. Rather, it is intended to convey the rough meaning of each -return value. The first five actions are normal and not intended to -denote an error situation. - <dl> -<dt><code>BZ_OK</code><dd>The requested action was completed successfully. -<br><dt><code>BZ_RUN_OK</code><dt><code>BZ_FLUSH_OK</code><dt><code>BZ_FINISH_OK</code><dd>In <code>BZ2_bzCompress</code>, the requested flush/finish/nothing-special action -was completed successfully. -<br><dt><code>BZ_STREAM_END</code><dd>Compression of data was completed, or the logical stream end was -detected during decompression. -</dl> - - <p>The following return values indicate an error of some kind. - <dl> -<dt><code>BZ_CONFIG_ERROR</code><dd>Indicates that the library has been improperly compiled on your -platform – a major configuration error. Specifically, it means -that <code>sizeof(char)</code>, <code>sizeof(short)</code> and <code>sizeof(int)</code> -are not 1, 2 and 4 respectively, as they should be. Note that the -library should still work properly on 64-bit platforms which follow -the LP64 programming model – that is, where <code>sizeof(long)</code> -and <code>sizeof(void*)</code> are 8. Under LP64, <code>sizeof(int)</code> is -still 4, so <code>libbzip2</code>, which doesn't use the <code>long</code> type, -is OK. -<br><dt><code>BZ_SEQUENCE_ERROR</code><dd>When using the library, it is important to call the functions in the -correct sequence and with data structures (buffers etc) in the correct -states. <code>libbzip2</code> checks as much as it can to ensure this is -happening, and returns <code>BZ_SEQUENCE_ERROR</code> if not. Code which -complies precisely with the function semantics, as detailed below, -should never receive this value; such an event denotes buggy code -which you should investigate. -<br><dt><code>BZ_PARAM_ERROR</code><dd>Returned when a parameter to a function call is out of range -or otherwise manifestly incorrect. As with <code>BZ_SEQUENCE_ERROR</code>, -this denotes a bug in the client code. The distinction between -<code>BZ_PARAM_ERROR</code> and <code>BZ_SEQUENCE_ERROR</code> is a bit hazy, but still worth -making. -<br><dt><code>BZ_MEM_ERROR</code><dd>Returned when a request to allocate memory failed. Note that the -quantity of memory needed to decompress a stream cannot be determined -until the stream's header has been read. So <code>BZ2_bzDecompress</code> and -<code>BZ2_bzRead</code> may return <code>BZ_MEM_ERROR</code> even though some of -the compressed data has been read. The same is not true for -compression; once <code>BZ2_bzCompressInit</code> or <code>BZ2_bzWriteOpen</code> have -successfully completed, <code>BZ_MEM_ERROR</code> cannot occur. -<br><dt><code>BZ_DATA_ERROR</code><dd>Returned when a data integrity error is detected during decompression. -Most importantly, this means when stored and computed CRCs for the -data do not match. This value is also returned upon detection of any -other anomaly in the compressed data. -<br><dt><code>BZ_DATA_ERROR_MAGIC</code><dd>As a special case of <code>BZ_DATA_ERROR</code>, it is sometimes useful to -know when the compressed stream does not start with the correct -magic bytes (<code>'B' 'Z' 'h'</code>). -<br><dt><code>BZ_IO_ERROR</code><dd>Returned by <code>BZ2_bzRead</code> and <code>BZ2_bzWrite</code> when there is an error -reading or writing in the compressed file, and by <code>BZ2_bzReadOpen</code> -and <code>BZ2_bzWriteOpen</code> for attempts to use a file for which the -error indicator (viz, <code>ferror(f)</code>) is set. -On receipt of <code>BZ_IO_ERROR</code>, the caller should consult -<code>errno</code> and/or <code>perror</code> to acquire operating-system -specific information about the problem. -<br><dt><code>BZ_UNEXPECTED_EOF</code><dd>Returned by <code>BZ2_bzRead</code> when the compressed file finishes -before the logical end of stream is detected. -<br><dt><code>BZ_OUTBUFF_FULL</code><dd>Returned by <code>BZ2_bzBuffToBuffCompress</code> and -<code>BZ2_bzBuffToBuffDecompress</code> to indicate that the output data -will not fit into the output buffer provided. -</dl> - -<h3 class="section">3.3 Low-level interface</h3> - -<h4 class="subsection">3.3.1 <code>BZ2_bzCompressInit</code></h4> - -<pre class="example"> typedef - struct { - char *next_in; - unsigned int avail_in; - unsigned int total_in_lo32; - unsigned int total_in_hi32; - - char *next_out; - unsigned int avail_out; - unsigned int total_out_lo32; - unsigned int total_out_hi32; - - void *state; - - void *(*bzalloc)(void *,int,int); - void (*bzfree)(void *,void *); - void *opaque; - } - bz_stream; - - int BZ2_bzCompressInit ( bz_stream *strm, - int blockSize100k, - int verbosity, - int workFactor ); - -</pre> - <p>Prepares for compression. The <code>bz_stream</code> structure -holds all data pertaining to the compression activity. -A <code>bz_stream</code> structure should be allocated and initialised -prior to the call. -The fields of <code>bz_stream</code> -comprise the entirety of the user-visible data. <code>state</code> -is a pointer to the private data structures required for compression. - - <p>Custom memory allocators are supported, via fields <code>bzalloc</code>, -<code>bzfree</code>, -and <code>opaque</code>. The value -<code>opaque</code> is passed to as the first argument to -all calls to <code>bzalloc</code> and <code>bzfree</code>, but is -otherwise ignored by the library. -The call <code>bzalloc ( opaque, n, m )</code> is expected to return a -pointer <code>p</code> to -<code>n * m</code> bytes of memory, and <code>bzfree ( opaque, p )</code> -should free -that memory. - - <p>If you don't want to use a custom memory allocator, set <code>bzalloc</code>, -<code>bzfree</code> and -<code>opaque</code> to <code>NULL</code>, -and the library will then use the standard <code>malloc</code>/<code>free</code> -routines. - - <p>Before calling <code>BZ2_bzCompressInit</code>, fields <code>bzalloc</code>, -<code>bzfree</code> and <code>opaque</code> should -be filled appropriately, as just described. Upon return, the internal -state will have been allocated and initialised, and <code>total_in_lo32</code>, -<code>total_in_hi32</code>, <code>total_out_lo32</code> and -<code>total_out_hi32</code> will have been set to zero. -These four fields are used by the library -to inform the caller of the total amount of data passed into and out of -the library, respectively. You should not try to change them. -As of version 1.0, 64-bit counts are maintained, even on 32-bit -platforms, using the <code>_hi32</code> fields to store the upper 32 bits -of the count. So, for example, the total amount of data in -is <code>(total_in_hi32 << 32) + total_in_lo32</code>. - - <p>Parameter <code>blockSize100k</code> specifies the block size to be used for -compression. It should be a value between 1 and 9 inclusive, and the -actual block size used is 100000 x this figure. 9 gives the best -compression but takes most memory. - - <p>Parameter <code>verbosity</code> should be set to a number between 0 and 4 -inclusive. 0 is silent, and greater numbers give increasingly verbose -monitoring/debugging output. If the library has been compiled with -<code>-DBZ_NO_STDIO</code>, no such output will appear for any verbosity -setting. - - <p>Parameter <code>workFactor</code> controls how the compression phase behaves -when presented with worst case, highly repetitive, input data. If -compression runs into difficulties caused by repetitive data, the -library switches from the standard sorting algorithm to a fallback -algorithm. The fallback is slower than the standard algorithm by -perhaps a factor of three, but always behaves reasonably, no matter how -bad the input. - - <p>Lower values of <code>workFactor</code> reduce the amount of effort the -standard algorithm will expend before resorting to the fallback. You -should set this parameter carefully; too low, and many inputs will be -handled by the fallback algorithm and so compress rather slowly, too -high, and your average-to-worst case compression times can become very -large. The default value of 30 gives reasonable behaviour over a wide -range of circumstances. - - <p>Allowable values range from 0 to 250 inclusive. 0 is a special case, -equivalent to using the default value of 30. - - <p>Note that the compressed output generated is the same regardless of -whether or not the fallback algorithm is used. - - <p>Be aware also that this parameter may disappear entirely in future -versions of the library. In principle it should be possible to devise a -good way to automatically choose which algorithm to use. Such a -mechanism would render the parameter obsolete. - - <p>Possible return values: -<pre class="display"> <code>BZ_CONFIG_ERROR</code> - if the library has been mis-compiled - <code>BZ_PARAM_ERROR</code> - if <code>strm</code> is <code>NULL</code> - or <code>blockSize</code> < 1 or <code>blockSize</code> > 9 - or <code>verbosity</code> < 0 or <code>verbosity</code> > 4 - or <code>workFactor</code> < 0 or <code>workFactor</code> > 250 - <code>BZ_MEM_ERROR</code> - if not enough memory is available - <code>BZ_OK</code> - otherwise -</pre> - <p>Allowable next actions: -<pre class="display"> <code>BZ2_bzCompress</code> - if <code>BZ_OK</code> is returned - no specific action needed in case of error -</pre> - <h4 class="subsection">3.3.2 <code>BZ2_bzCompress</code></h4> - -<pre class="example"> int BZ2_bzCompress ( bz_stream *strm, int action ); -</pre> - <p>Provides more input and/or output buffer space for the library. The -caller maintains input and output buffers, and calls <code>BZ2_bzCompress</code> to -transfer data between them. - - <p>Before each call to <code>BZ2_bzCompress</code>, <code>next_in</code> should point at -the data to be compressed, and <code>avail_in</code> should indicate how many -bytes the library may read. <code>BZ2_bzCompress</code> updates <code>next_in</code>, -<code>avail_in</code> and <code>total_in</code> to reflect the number of bytes it -has read. - - <p>Similarly, <code>next_out</code> should point to a buffer in which the -compressed data is to be placed, with <code>avail_out</code> indicating how -much output space is available. <code>BZ2_bzCompress</code> updates -<code>next_out</code>, <code>avail_out</code> and <code>total_out</code> to reflect the -number of bytes output. - - <p>You may provide and remove as little or as much data as you like on each -call of <code>BZ2_bzCompress</code>. In the limit, it is acceptable to supply and -remove data one byte at a time, although this would be terribly -inefficient. You should always ensure that at least one byte of output -space is available at each call. - - <p>A second purpose of <code>BZ2_bzCompress</code> is to request a change of mode of the -compressed stream. - - <p>Conceptually, a compressed stream can be in one of four states: IDLE, -RUNNING, FLUSHING and FINISHING. Before initialisation -(<code>BZ2_bzCompressInit</code>) and after termination (<code>BZ2_bzCompressEnd</code>), a -stream is regarded as IDLE. - - <p>Upon initialisation (<code>BZ2_bzCompressInit</code>), the stream is placed in the -RUNNING state. Subsequent calls to <code>BZ2_bzCompress</code> should pass -<code>BZ_RUN</code> as the requested action; other actions are illegal and -will result in <code>BZ_SEQUENCE_ERROR</code>. - - <p>At some point, the calling program will have provided all the input data -it wants to. It will then want to finish up – in effect, asking the -library to process any data it might have buffered internally. In this -state, <code>BZ2_bzCompress</code> will no longer attempt to read data from -<code>next_in</code>, but it will want to write data to <code>next_out</code>. -Because the output buffer supplied by the user can be arbitrarily small, -the finishing-up operation cannot necessarily be done with a single call -of <code>BZ2_bzCompress</code>. - - <p>Instead, the calling program passes <code>BZ_FINISH</code> as an action to -<code>BZ2_bzCompress</code>. This changes the stream's state to FINISHING. Any -remaining input (ie, <code>next_in[0 .. avail_in-1]</code>) is compressed and -transferred to the output buffer. To do this, <code>BZ2_bzCompress</code> must be -called repeatedly until all the output has been consumed. At that -point, <code>BZ2_bzCompress</code> returns <code>BZ_STREAM_END</code>, and the stream's -state is set back to IDLE. <code>BZ2_bzCompressEnd</code> should then be -called. - - <p>Just to make sure the calling program does not cheat, the library makes -a note of <code>avail_in</code> at the time of the first call to -<code>BZ2_bzCompress</code> which has <code>BZ_FINISH</code> as an action (ie, at the -time the program has announced its intention to not supply any more -input). By comparing this value with that of <code>avail_in</code> over -subsequent calls to <code>BZ2_bzCompress</code>, the library can detect any -attempts to slip in more data to compress. Any calls for which this is -detected will return <code>BZ_SEQUENCE_ERROR</code>. This indicates a -programming mistake which should be corrected. - - <p>Instead of asking to finish, the calling program may ask -<code>BZ2_bzCompress</code> to take all the remaining input, compress it and -terminate the current (Burrows-Wheeler) compression block. This could -be useful for error control purposes. The mechanism is analogous to -that for finishing: call <code>BZ2_bzCompress</code> with an action of -<code>BZ_FLUSH</code>, remove output data, and persist with the -<code>BZ_FLUSH</code> action until the value <code>BZ_RUN</code> is returned. As -with finishing, <code>BZ2_bzCompress</code> detects any attempt to provide more -input data once the flush has begun. - - <p>Once the flush is complete, the stream returns to the normal RUNNING -state. - - <p>This all sounds pretty complex, but isn't really. Here's a table -which shows which actions are allowable in each state, what action -will be taken, what the next state is, and what the non-error return -values are. Note that you can't explicitly ask what state the -stream is in, but nor do you need to – it can be inferred from the -values returned by <code>BZ2_bzCompress</code>. -<pre class="display"> IDLE/<code>any</code> - Illegal. IDLE state only exists after <code>BZ2_bzCompressEnd</code> or - before <code>BZ2_bzCompressInit</code>. - Return value = <code>BZ_SEQUENCE_ERROR</code> - - RUNNING/<code>BZ_RUN</code> - Compress from <code>next_in</code> to <code>next_out</code> as much as possible. - Next state = RUNNING - Return value = <code>BZ_RUN_OK</code> - - RUNNING/<code>BZ_FLUSH</code> - Remember current value of <code>next_in</code>. Compress from <code>next_in</code> - to <code>next_out</code> as much as possible, but do not accept any more input. - Next state = FLUSHING - Return value = <code>BZ_FLUSH_OK</code> - - RUNNING/<code>BZ_FINISH</code> - Remember current value of <code>next_in</code>. Compress from <code>next_in</code> - to <code>next_out</code> as much as possible, but do not accept any more input. - Next state = FINISHING - Return value = <code>BZ_FINISH_OK</code> - - FLUSHING/<code>BZ_FLUSH</code> - Compress from <code>next_in</code> to <code>next_out</code> as much as possible, - but do not accept any more input. - If all the existing input has been used up and all compressed - output has been removed - Next state = RUNNING; Return value = <code>BZ_RUN_OK</code> - else - Next state = FLUSHING; Return value = <code>BZ_FLUSH_OK</code> - - FLUSHING/other - Illegal. - Return value = <code>BZ_SEQUENCE_ERROR</code> - - FINISHING/<code>BZ_FINISH</code> - Compress from <code>next_in</code> to <code>next_out</code> as much as possible, - but to not accept any more input. - If all the existing input has been used up and all compressed - output has been removed - Next state = IDLE; Return value = <code>BZ_STREAM_END</code> - else - Next state = FINISHING; Return value = <code>BZ_FINISHING</code> - - FINISHING/other - Illegal. - Return value = <code>BZ_SEQUENCE_ERROR</code> -</pre> - <p>That still looks complicated? Well, fair enough. The usual sequence -of calls for compressing a load of data is: - <ul> -<li>Get started with <code>BZ2_bzCompressInit</code>. -<li>Shovel data in and shlurp out its compressed form using zero or more -calls of <code>BZ2_bzCompress</code> with action = <code>BZ_RUN</code>. -<li>Finish up. -Repeatedly call <code>BZ2_bzCompress</code> with action = <code>BZ_FINISH</code>, -copying out the compressed output, until <code>BZ_STREAM_END</code> is returned. -<li>Close up and go home. Call <code>BZ2_bzCompressEnd</code>. -</ul> - If the data you want to compress fits into your input buffer all -at once, you can skip the calls of <code>BZ2_bzCompress ( ..., BZ_RUN )</code> and -just do the <code>BZ2_bzCompress ( ..., BZ_FINISH )</code> calls. - - <p>All required memory is allocated by <code>BZ2_bzCompressInit</code>. The -compression library can accept any data at all (obviously). So you -shouldn't get any error return values from the <code>BZ2_bzCompress</code> calls. -If you do, they will be <code>BZ_SEQUENCE_ERROR</code>, and indicate a bug in -your programming. - - <p>Trivial other possible return values: -<pre class="display"> <code>BZ_PARAM_ERROR</code> - if <code>strm</code> is <code>NULL</code>, or <code>strm->s</code> is <code>NULL</code> -</pre> - <h4 class="subsection">3.3.3 <code>BZ2_bzCompressEnd</code></h4> - -<pre class="example"> int BZ2_bzCompressEnd ( bz_stream *strm ); -</pre> - <p>Releases all memory associated with a compression stream. - - <p>Possible return values: -<pre class="display"> <code>BZ_PARAM_ERROR</code> if <code>strm</code> is <code>NULL</code> or <code>strm->s</code> is <code>NULL</code> - <code>BZ_OK</code> otherwise -</pre> - <h4 class="subsection">3.3.4 <code>BZ2_bzDecompressInit</code></h4> - -<pre class="example"> int BZ2_bzDecompressInit ( bz_stream *strm, int verbosity, int small ); -</pre> - <p>Prepares for decompression. As with <code>BZ2_bzCompressInit</code>, a -<code>bz_stream</code> record should be allocated and initialised before the -call. Fields <code>bzalloc</code>, <code>bzfree</code> and <code>opaque</code> should be -set if a custom memory allocator is required, or made <code>NULL</code> for -the normal <code>malloc</code>/<code>free</code> routines. Upon return, the internal -state will have been initialised, and <code>total_in</code> and -<code>total_out</code> will be zero. - - <p>For the meaning of parameter <code>verbosity</code>, see <code>BZ2_bzCompressInit</code>. - - <p>If <code>small</code> is nonzero, the library will use an alternative -decompression algorithm which uses less memory but at the cost of -decompressing more slowly (roughly speaking, half the speed, but the -maximum memory requirement drops to around 2300k). See Chapter 2 for -more information on memory management. - - <p>Note that the amount of memory needed to decompress -a stream cannot be determined until the stream's header has been read, -so even if <code>BZ2_bzDecompressInit</code> succeeds, a subsequent -<code>BZ2_bzDecompress</code> could fail with <code>BZ_MEM_ERROR</code>. - - <p>Possible return values: -<pre class="display"> <code>BZ_CONFIG_ERROR</code> - if the library has been mis-compiled - <code>BZ_PARAM_ERROR</code> - if <code>(small != 0 && small != 1)</code> - or <code>(verbosity < 0 || verbosity > 4)</code> - <code>BZ_MEM_ERROR</code> - if insufficient memory is available -</pre> - <p>Allowable next actions: -<pre class="display"> <code>BZ2_bzDecompress</code> - if <code>BZ_OK</code> was returned - no specific action required in case of error -</pre> - <h4 class="subsection">3.3.5 <code>BZ2_bzDecompress</code></h4> - -<pre class="example"> int BZ2_bzDecompress ( bz_stream *strm ); -</pre> - <p>Provides more input and/out output buffer space for the library. The -caller maintains input and output buffers, and uses <code>BZ2_bzDecompress</code> -to transfer data between them. - - <p>Before each call to <code>BZ2_bzDecompress</code>, <code>next_in</code> -should point at the compressed data, -and <code>avail_in</code> should indicate how many bytes the library -may read. <code>BZ2_bzDecompress</code> updates <code>next_in</code>, <code>avail_in</code> -and <code>total_in</code> -to reflect the number of bytes it has read. - - <p>Similarly, <code>next_out</code> should point to a buffer in which the uncompressed -output is to be placed, with <code>avail_out</code> indicating how much output space -is available. <code>BZ2_bzCompress</code> updates <code>next_out</code>, -<code>avail_out</code> and <code>total_out</code> to reflect -the number of bytes output. - - <p>You may provide and remove as little or as much data as you like on -each call of <code>BZ2_bzDecompress</code>. -In the limit, it is acceptable to -supply and remove data one byte at a time, although this would be -terribly inefficient. You should always ensure that at least one -byte of output space is available at each call. - - <p>Use of <code>BZ2_bzDecompress</code> is simpler than <code>BZ2_bzCompress</code>. - - <p>You should provide input and remove output as described above, and -repeatedly call <code>BZ2_bzDecompress</code> until <code>BZ_STREAM_END</code> is -returned. Appearance of <code>BZ_STREAM_END</code> denotes that -<code>BZ2_bzDecompress</code> has detected the logical end of the compressed -stream. <code>BZ2_bzDecompress</code> will not produce <code>BZ_STREAM_END</code> until -all output data has been placed into the output buffer, so once -<code>BZ_STREAM_END</code> appears, you are guaranteed to have available all -the decompressed output, and <code>BZ2_bzDecompressEnd</code> can safely be -called. - - <p>If case of an error return value, you should call <code>BZ2_bzDecompressEnd</code> -to clean up and release memory. - - <p>Possible return values: -<pre class="display"> <code>BZ_PARAM_ERROR</code> - if <code>strm</code> is <code>NULL</code> or <code>strm->s</code> is <code>NULL</code> - or <code>strm->avail_out < 1</code> - <code>BZ_DATA_ERROR</code> - if a data integrity error is detected in the compressed stream - <code>BZ_DATA_ERROR_MAGIC</code> - if the compressed stream doesn't begin with the right magic bytes - <code>BZ_MEM_ERROR</code> - if there wasn't enough memory available - <code>BZ_STREAM_END</code> - if the logical end of the data stream was detected and all - output in has been consumed, eg <code>s->avail_out > 0</code> - <code>BZ_OK</code> - otherwise -</pre> - <p>Allowable next actions: -<pre class="display"> <code>BZ2_bzDecompress</code> - if <code>BZ_OK</code> was returned - <code>BZ2_bzDecompressEnd</code> - otherwise -</pre> - <h4 class="subsection">3.3.6 <code>BZ2_bzDecompressEnd</code></h4> - -<pre class="example"> int BZ2_bzDecompressEnd ( bz_stream *strm ); -</pre> - <p>Releases all memory associated with a decompression stream. - - <p>Possible return values: -<pre class="display"> <code>BZ_PARAM_ERROR</code> - if <code>strm</code> is <code>NULL</code> or <code>strm->s</code> is <code>NULL</code> - <code>BZ_OK</code> - otherwise -</pre> - <p>Allowable next actions: -<pre class="display"> None. -</pre> - <h3 class="section">3.4 High-level interface</h3> - -<p>This interface provides functions for reading and writing -<code>bzip2</code> format files. First, some general points. - - <ul> -<li>All of the functions take an <code>int*</code> first argument, - <code>bzerror</code>. - After each call, <code>bzerror</code> should be consulted first to determine - the outcome of the call. If <code>bzerror</code> is <code>BZ_OK</code>, - the call completed - successfully, and only then should the return value of the function - (if any) be consulted. If <code>bzerror</code> is <code>BZ_IO_ERROR</code>, - there was an error - reading/writing the underlying compressed file, and you should - then consult <code>errno</code>/<code>perror</code> to determine the - cause of the difficulty. - <code>bzerror</code> may also be set to various other values; precise details are - given on a per-function basis below. -<li>If <code>bzerror</code> indicates an error - (ie, anything except <code>BZ_OK</code> and <code>BZ_STREAM_END</code>), - you should immediately call <code>BZ2_bzReadClose</code> (or <code>BZ2_bzWriteClose</code>, - depending on whether you are attempting to read or to write) - to free up all resources associated - with the stream. Once an error has been indicated, behaviour of all calls - except <code>BZ2_bzReadClose</code> (<code>BZ2_bzWriteClose</code>) is undefined. - The implication is that (1) <code>bzerror</code> should - be checked after each call, and (2) if <code>bzerror</code> indicates an error, - <code>BZ2_bzReadClose</code> (<code>BZ2_bzWriteClose</code>) should then be called to clean up. -<li>The <code>FILE*</code> arguments passed to - <code>BZ2_bzReadOpen</code>/<code>BZ2_bzWriteOpen</code> - should be set to binary mode. - Most Unix systems will do this by default, but other platforms, - including Windows and Mac, will not. If you omit this, you may - encounter problems when moving code to new platforms. -<li>Memory allocation requests are handled by - <code>malloc</code>/<code>free</code>. - At present - there is no facility for user-defined memory allocators in the file I/O - functions (could easily be added, though). -</ul> - -<h4 class="subsection">3.4.1 <code>BZ2_bzReadOpen</code></h4> - -<pre class="example"> typedef void BZFILE; - - BZFILE *BZ2_bzReadOpen ( int *bzerror, FILE *f, - int small, int verbosity, - void *unused, int nUnused ); -</pre> - <p>Prepare to read compressed data from file handle <code>f</code>. <code>f</code> -should refer to a file which has been opened for reading, and for which -the error indicator (<code>ferror(f)</code>)is not set. If <code>small</code> is 1, -the library will try to decompress using less memory, at the expense of -speed. - - <p>For reasons explained below, <code>BZ2_bzRead</code> will decompress the -<code>nUnused</code> bytes starting at <code>unused</code>, before starting to read -from the file <code>f</code>. At most <code>BZ_MAX_UNUSED</code> bytes may be -supplied like this. If this facility is not required, you should pass -<code>NULL</code> and <code>0</code> for <code>unused</code> and n<code>Unused</code> -respectively. - - <p>For the meaning of parameters <code>small</code> and <code>verbosity</code>, -see <code>BZ2_bzDecompressInit</code>. - - <p>The amount of memory needed to decompress a file cannot be determined -until the file's header has been read. So it is possible that -<code>BZ2_bzReadOpen</code> returns <code>BZ_OK</code> but a subsequent call of -<code>BZ2_bzRead</code> will return <code>BZ_MEM_ERROR</code>. - - <p>Possible assignments to <code>bzerror</code>: -<pre class="display"> <code>BZ_CONFIG_ERROR</code> - if the library has been mis-compiled - <code>BZ_PARAM_ERROR</code> - if <code>f</code> is <code>NULL</code> - or <code>small</code> is neither <code>0</code> nor <code>1</code> - or <code>(unused == NULL && nUnused != 0)</code> - or <code>(unused != NULL && !(0 <= nUnused <= BZ_MAX_UNUSED))</code> - <code>BZ_IO_ERROR</code> - if <code>ferror(f)</code> is nonzero - <code>BZ_MEM_ERROR</code> - if insufficient memory is available - <code>BZ_OK</code> - otherwise. -</pre> - <p>Possible return values: -<pre class="display"> Pointer to an abstract <code>BZFILE</code> - if <code>bzerror</code> is <code>BZ_OK</code> - <code>NULL</code> - otherwise -</pre> - <p>Allowable next actions: -<pre class="display"> <code>BZ2_bzRead</code> - if <code>bzerror</code> is <code>BZ_OK</code> - <code>BZ2_bzClose</code> - otherwise -</pre> - <h4 class="subsection">3.4.2 <code>BZ2_bzRead</code></h4> - -<pre class="example"> int BZ2_bzRead ( int *bzerror, BZFILE *b, void *buf, int len ); -</pre> - <p>Reads up to <code>len</code> (uncompressed) bytes from the compressed file -<code>b</code> into -the buffer <code>buf</code>. If the read was successful, -<code>bzerror</code> is set to <code>BZ_OK</code> -and the number of bytes read is returned. If the logical end-of-stream -was detected, <code>bzerror</code> will be set to <code>BZ_STREAM_END</code>, -and the number -of bytes read is returned. All other <code>bzerror</code> values denote an error. - - <p><code>BZ2_bzRead</code> will supply <code>len</code> bytes, -unless the logical stream end is detected -or an error occurs. Because of this, it is possible to detect the -stream end by observing when the number of bytes returned is -less than the number -requested. Nevertheless, this is regarded as inadvisable; you should -instead check <code>bzerror</code> after every call and watch out for -<code>BZ_STREAM_END</code>. - - <p>Internally, <code>BZ2_bzRead</code> copies data from the compressed file in chunks -of size <code>BZ_MAX_UNUSED</code> bytes -before decompressing it. If the file contains more bytes than strictly -needed to reach the logical end-of-stream, <code>BZ2_bzRead</code> will almost certainly -read some of the trailing data before signalling <code>BZ_SEQUENCE_END</code>. -To collect the read but unused data once <code>BZ_SEQUENCE_END</code> has -appeared, call <code>BZ2_bzReadGetUnused</code> immediately before <code>BZ2_bzReadClose</code>. - - <p>Possible assignments to <code>bzerror</code>: -<pre class="display"> <code>BZ_PARAM_ERROR</code> - if <code>b</code> is <code>NULL</code> or <code>buf</code> is <code>NULL</code> or <code>len < 0</code> - <code>BZ_SEQUENCE_ERROR</code> - if <code>b</code> was opened with <code>BZ2_bzWriteOpen</code> - <code>BZ_IO_ERROR</code> - if there is an error reading from the compressed file - <code>BZ_UNEXPECTED_EOF</code> - if the compressed file ended before the logical end-of-stream was detected - <code>BZ_DATA_ERROR</code> - if a data integrity error was detected in the compressed stream - <code>BZ_DATA_ERROR_MAGIC</code> - if the stream does not begin with the requisite header bytes (ie, is not - a <code>bzip2</code> data file). This is really a special case of <code>BZ_DATA_ERROR</code>. - <code>BZ_MEM_ERROR</code> - if insufficient memory was available - <code>BZ_STREAM_END</code> - if the logical end of stream was detected. - <code>BZ_OK</code> - otherwise. -</pre> - <p>Possible return values: -<pre class="display"> number of bytes read - if <code>bzerror</code> is <code>BZ_OK</code> or <code>BZ_STREAM_END</code> - undefined - otherwise -</pre> - <p>Allowable next actions: -<pre class="display"> collect data from <code>buf</code>, then <code>BZ2_bzRead</code> or <code>BZ2_bzReadClose</code> - if <code>bzerror</code> is <code>BZ_OK</code> - collect data from <code>buf</code>, then <code>BZ2_bzReadClose</code> or <code>BZ2_bzReadGetUnused</code> - if <code>bzerror</code> is <code>BZ_SEQUENCE_END</code> - <code>BZ2_bzReadClose</code> - otherwise -</pre> - <h4 class="subsection">3.4.3 <code>BZ2_bzReadGetUnused</code></h4> - -<pre class="example"> void BZ2_bzReadGetUnused ( int* bzerror, BZFILE *b, - void** unused, int* nUnused ); -</pre> - <p>Returns data which was read from the compressed file but was not needed -to get to the logical end-of-stream. <code>*unused</code> is set to the address -of the data, and <code>*nUnused</code> to the number of bytes. <code>*nUnused</code> will -be set to a value between <code>0</code> and <code>BZ_MAX_UNUSED</code> inclusive. - - <p>This function may only be called once <code>BZ2_bzRead</code> has signalled -<code>BZ_STREAM_END</code> but before <code>BZ2_bzReadClose</code>. - - <p>Possible assignments to <code>bzerror</code>: -<pre class="display"> <code>BZ_PARAM_ERROR</code> - if <code>b</code> is <code>NULL</code> - or <code>unused</code> is <code>NULL</code> or <code>nUnused</code> is <code>NULL</code> - <code>BZ_SEQUENCE_ERROR</code> - if <code>BZ_STREAM_END</code> has not been signalled - or if <code>b</code> was opened with <code>BZ2_bzWriteOpen</code> - <code>BZ_OK</code> - otherwise -</pre> - <p>Allowable next actions: -<pre class="display"> <code>BZ2_bzReadClose</code> -</pre> - <h4 class="subsection">3.4.4 <code>BZ2_bzReadClose</code></h4> - -<pre class="example"> void BZ2_bzReadClose ( int *bzerror, BZFILE *b ); -</pre> - <p>Releases all memory pertaining to the compressed file <code>b</code>. -<code>BZ2_bzReadClose</code> does not call <code>fclose</code> on the underlying file -handle, so you should do that yourself if appropriate. -<code>BZ2_bzReadClose</code> should be called to clean up after all error -situations. - - <p>Possible assignments to <code>bzerror</code>: -<pre class="display"> <code>BZ_SEQUENCE_ERROR</code> - if <code>b</code> was opened with <code>BZ2_bzOpenWrite</code> - <code>BZ_OK</code> - otherwise -</pre> - <p>Allowable next actions: -<pre class="display"> none -</pre> - <h4 class="subsection">3.4.5 <code>BZ2_bzWriteOpen</code></h4> - -<pre class="example"> BZFILE *BZ2_bzWriteOpen ( int *bzerror, FILE *f, - int blockSize100k, int verbosity, - int workFactor ); -</pre> - <p>Prepare to write compressed data to file handle <code>f</code>. -<code>f</code> should refer to -a file which has been opened for writing, and for which the error -indicator (<code>ferror(f)</code>)is not set. - - <p>For the meaning of parameters <code>blockSize100k</code>, -<code>verbosity</code> and <code>workFactor</code>, see -<br> <code>BZ2_bzCompressInit</code>. - - <p>All required memory is allocated at this stage, so if the call -completes successfully, <code>BZ_MEM_ERROR</code> cannot be signalled by a -subsequent call to <code>BZ2_bzWrite</code>. - - <p>Possible assignments to <code>bzerror</code>: -<pre class="display"> <code>BZ_CONFIG_ERROR</code> - if the library has been mis-compiled - <code>BZ_PARAM_ERROR</code> - if <code>f</code> is <code>NULL</code> - or <code>blockSize100k < 1</code> or <code>blockSize100k > 9</code> - <code>BZ_IO_ERROR</code> - if <code>ferror(f)</code> is nonzero - <code>BZ_MEM_ERROR</code> - if insufficient memory is available - <code>BZ_OK</code> - otherwise -</pre> - <p>Possible return values: -<pre class="display"> Pointer to an abstract <code>BZFILE</code> - if <code>bzerror</code> is <code>BZ_OK</code> - <code>NULL</code> - otherwise -</pre> - <p>Allowable next actions: -<pre class="display"> <code>BZ2_bzWrite</code> - if <code>bzerror</code> is <code>BZ_OK</code> - (you could go directly to <code>BZ2_bzWriteClose</code>, but this would be pretty pointless) - <code>BZ2_bzWriteClose</code> - otherwise -</pre> - <h4 class="subsection">3.4.6 <code>BZ2_bzWrite</code></h4> - -<pre class="example"> void BZ2_bzWrite ( int *bzerror, BZFILE *b, void *buf, int len ); -</pre> - <p>Absorbs <code>len</code> bytes from the buffer <code>buf</code>, eventually to be -compressed and written to the file. - - <p>Possible assignments to <code>bzerror</code>: -<pre class="display"> <code>BZ_PARAM_ERROR</code> - if <code>b</code> is <code>NULL</code> or <code>buf</code> is <code>NULL</code> or <code>len < 0</code> - <code>BZ_SEQUENCE_ERROR</code> - if b was opened with <code>BZ2_bzReadOpen</code> - <code>BZ_IO_ERROR</code> - if there is an error writing the compressed file. - <code>BZ_OK</code> - otherwise -</pre> - <h4 class="subsection">3.4.7 <code>BZ2_bzWriteClose</code></h4> - -<pre class="example"> void BZ2_bzWriteClose ( int *bzerror, BZFILE* f, - int abandon, - unsigned int* nbytes_in, - unsigned int* nbytes_out ); - - void BZ2_bzWriteClose64 ( int *bzerror, BZFILE* f, - int abandon, - unsigned int* nbytes_in_lo32, - unsigned int* nbytes_in_hi32, - unsigned int* nbytes_out_lo32, - unsigned int* nbytes_out_hi32 ); -</pre> - <p>Compresses and flushes to the compressed file all data so far supplied -by <code>BZ2_bzWrite</code>. The logical end-of-stream markers are also written, so -subsequent calls to <code>BZ2_bzWrite</code> are illegal. All memory associated -with the compressed file <code>b</code> is released. -<code>fflush</code> is called on the -compressed file, but it is not <code>fclose</code>'d. - - <p>If <code>BZ2_bzWriteClose</code> is called to clean up after an error, the only -action is to release the memory. The library records the error codes -issued by previous calls, so this situation will be detected -automatically. There is no attempt to complete the compression -operation, nor to <code>fflush</code> the compressed file. You can force this -behaviour to happen even in the case of no error, by passing a nonzero -value to <code>abandon</code>. - - <p>If <code>nbytes_in</code> is non-null, <code>*nbytes_in</code> will be set to be the -total volume of uncompressed data handled. Similarly, <code>nbytes_out</code> -will be set to the total volume of compressed data written. For -compatibility with older versions of the library, <code>BZ2_bzWriteClose</code> -only yields the lower 32 bits of these counts. Use -<code>BZ2_bzWriteClose64</code> if you want the full 64 bit counts. These -two functions are otherwise absolutely identical. - - <p>Possible assignments to <code>bzerror</code>: -<pre class="display"> <code>BZ_SEQUENCE_ERROR</code> - if <code>b</code> was opened with <code>BZ2_bzReadOpen</code> - <code>BZ_IO_ERROR</code> - if there is an error writing the compressed file - <code>BZ_OK</code> - otherwise -</pre> - <h4 class="subsection">3.4.8 Handling embedded compressed data streams</h4> - -<p>The high-level library facilitates use of -<code>bzip2</code> data streams which form some part of a surrounding, larger -data stream. - <ul> -<li>For writing, the library takes an open file handle, writes -compressed data to it, <code>fflush</code>es it but does not <code>fclose</code> it. -The calling application can write its own data before and after the -compressed data stream, using that same file handle. -<li>Reading is more complex, and the facilities are not as general -as they could be since generality is hard to reconcile with efficiency. -<code>BZ2_bzRead</code> reads from the compressed file in blocks of size -<code>BZ_MAX_UNUSED</code> bytes, and in doing so probably will overshoot -the logical end of compressed stream. -To recover this data once decompression has -ended, call <code>BZ2_bzReadGetUnused</code> after the last call of <code>BZ2_bzRead</code> -(the one returning <code>BZ_STREAM_END</code>) but before calling -<code>BZ2_bzReadClose</code>. -</ul> - - <p>This mechanism makes it easy to decompress multiple <code>bzip2</code> -streams placed end-to-end. As the end of one stream, when <code>BZ2_bzRead</code> -returns <code>BZ_STREAM_END</code>, call <code>BZ2_bzReadGetUnused</code> to collect the -unused data (copy it into your own buffer somewhere). -That data forms the start of the next compressed stream. -To start uncompressing that next stream, call <code>BZ2_bzReadOpen</code> again, -feeding in the unused data via the <code>unused</code>/<code>nUnused</code> -parameters. -Keep doing this until <code>BZ_STREAM_END</code> return coincides with the -physical end of file (<code>feof(f)</code>). In this situation -<code>BZ2_bzReadGetUnused</code> -will of course return no data. - - <p>This should give some feel for how the high-level interface can be used. -If you require extra flexibility, you'll have to bite the bullet and get -to grips with the low-level interface. - -<h4 class="subsection">3.4.9 Standard file-reading/writing code</h4> - -<p>Here's how you'd write data to a compressed file: -<pre class="example"> FILE* f; - BZFILE* b; - int nBuf; - char buf[ /* whatever size you like */ ]; - int bzerror; - int nWritten; - - f = fopen ( "myfile.bz2", "w" ); - if (!f) { - /* handle error */ - } - b = BZ2_bzWriteOpen ( &bzerror, f, 9 ); - if (bzerror != BZ_OK) { - BZ2_bzWriteClose ( b ); - /* handle error */ - } - - while ( /* condition */ ) { - /* get data to write into buf, and set nBuf appropriately */ - nWritten = BZ2_bzWrite ( &bzerror, b, buf, nBuf ); - if (bzerror == BZ_IO_ERROR) { - BZ2_bzWriteClose ( &bzerror, b ); - /* handle error */ - } - } - - BZ2_bzWriteClose ( &bzerror, b ); - if (bzerror == BZ_IO_ERROR) { - /* handle error */ - } -</pre> - <p>And to read from a compressed file: -<pre class="example"> FILE* f; - BZFILE* b; - int nBuf; - char buf[ /* whatever size you like */ ]; - int bzerror; - int nWritten; - - f = fopen ( "myfile.bz2", "r" ); - if (!f) { - /* handle error */ - } - b = BZ2_bzReadOpen ( &bzerror, f, 0, NULL, 0 ); - if (bzerror != BZ_OK) { - BZ2_bzReadClose ( &bzerror, b ); - /* handle error */ - } - - bzerror = BZ_OK; - while (bzerror == BZ_OK && /* arbitrary other conditions */) { - nBuf = BZ2_bzRead ( &bzerror, b, buf, /* size of buf */ ); - if (bzerror == BZ_OK) { - /* do something with buf[0 .. nBuf-1] */ - } - } - if (bzerror != BZ_STREAM_END) { - BZ2_bzReadClose ( &bzerror, b ); - /* handle error */ - } else { - BZ2_bzReadClose ( &bzerror ); - } -</pre> - <h3 class="section">3.5 Utility functions</h3> - -<h4 class="subsection">3.5.1 <code>BZ2_bzBuffToBuffCompress</code></h4> - -<pre class="example"> int BZ2_bzBuffToBuffCompress( char* dest, - unsigned int* destLen, - char* source, - unsigned int sourceLen, - int blockSize100k, - int verbosity, - int workFactor ); -</pre> - <p>Attempts to compress the data in <code>source[0 .. sourceLen-1]</code> -into the destination buffer, <code>dest[0 .. *destLen-1]</code>. -If the destination buffer is big enough, <code>*destLen</code> is -set to the size of the compressed data, and <code>BZ_OK</code> is -returned. If the compressed data won't fit, <code>*destLen</code> -is unchanged, and <code>BZ_OUTBUFF_FULL</code> is returned. - - <p>Compression in this manner is a one-shot event, done with a single call -to this function. The resulting compressed data is a complete -<code>bzip2</code> format data stream. There is no mechanism for making -additional calls to provide extra input data. If you want that kind of -mechanism, use the low-level interface. - - <p>For the meaning of parameters <code>blockSize100k</code>, <code>verbosity</code> -and <code>workFactor</code>, <br> see <code>BZ2_bzCompressInit</code>. - - <p>To guarantee that the compressed data will fit in its buffer, allocate -an output buffer of size 1% larger than the uncompressed data, plus -six hundred extra bytes. - - <p><code>BZ2_bzBuffToBuffDecompress</code> will not write data at or -beyond <code>dest[*destLen]</code>, even in case of buffer overflow. - - <p>Possible return values: -<pre class="display"> <code>BZ_CONFIG_ERROR</code> - if the library has been mis-compiled - <code>BZ_PARAM_ERROR</code> - if <code>dest</code> is <code>NULL</code> or <code>destLen</code> is <code>NULL</code> - or <code>blockSize100k < 1</code> or <code>blockSize100k > 9</code> - or <code>verbosity < 0</code> or <code>verbosity > 4</code> - or <code>workFactor < 0</code> or <code>workFactor > 250</code> - <code>BZ_MEM_ERROR</code> - if insufficient memory is available - <code>BZ_OUTBUFF_FULL</code> - if the size of the compressed data exceeds <code>*destLen</code> - <code>BZ_OK</code> - otherwise -</pre> - <h4 class="subsection">3.5.2 <code>BZ2_bzBuffToBuffDecompress</code></h4> - -<pre class="example"> int BZ2_bzBuffToBuffDecompress ( char* dest, - unsigned int* destLen, - char* source, - unsigned int sourceLen, - int small, - int verbosity ); -</pre> - <p>Attempts to decompress the data in <code>source[0 .. sourceLen-1]</code> -into the destination buffer, <code>dest[0 .. *destLen-1]</code>. -If the destination buffer is big enough, <code>*destLen</code> is -set to the size of the uncompressed data, and <code>BZ_OK</code> is -returned. If the compressed data won't fit, <code>*destLen</code> -is unchanged, and <code>BZ_OUTBUFF_FULL</code> is returned. - - <p><code>source</code> is assumed to hold a complete <code>bzip2</code> format -data stream. <br> <code>BZ2_bzBuffToBuffDecompress</code> tries to decompress -the entirety of the stream into the output buffer. - - <p>For the meaning of parameters <code>small</code> and <code>verbosity</code>, -see <code>BZ2_bzDecompressInit</code>. - - <p>Because the compression ratio of the compressed data cannot be known in -advance, there is no easy way to guarantee that the output buffer will -be big enough. You may of course make arrangements in your code to -record the size of the uncompressed data, but such a mechanism is beyond -the scope of this library. - - <p><code>BZ2_bzBuffToBuffDecompress</code> will not write data at or -beyond <code>dest[*destLen]</code>, even in case of buffer overflow. - - <p>Possible return values: -<pre class="display"> <code>BZ_CONFIG_ERROR</code> - if the library has been mis-compiled - <code>BZ_PARAM_ERROR</code> - if <code>dest</code> is <code>NULL</code> or <code>destLen</code> is <code>NULL</code> - or <code>small != 0 && small != 1</code> - or <code>verbosity < 0</code> or <code>verbosity > 4</code> - <code>BZ_MEM_ERROR</code> - if insufficient memory is available - <code>BZ_OUTBUFF_FULL</code> - if the size of the compressed data exceeds <code>*destLen</code> - <code>BZ_DATA_ERROR</code> - if a data integrity error was detected in the compressed data - <code>BZ_DATA_ERROR_MAGIC</code> - if the compressed data doesn't begin with the right magic bytes - <code>BZ_UNEXPECTED_EOF</code> - if the compressed data ends unexpectedly - <code>BZ_OK</code> - otherwise -</pre> - <h3 class="section">3.6 <code>zlib</code> compatibility functions</h3> - -<p>Yoshioka Tsuneo has contributed some functions to -give better <code>zlib</code> compatibility. These functions are -<code>BZ2_bzopen</code>, <code>BZ2_bzread</code>, <code>BZ2_bzwrite</code>, <code>BZ2_bzflush</code>, -<code>BZ2_bzclose</code>, -<code>BZ2_bzerror</code> and <code>BZ2_bzlibVersion</code>. -These functions are not (yet) officially part of -the library. If they break, you get to keep all the pieces. -Nevertheless, I think they work ok. -<pre class="example"> typedef void BZFILE; - - const char * BZ2_bzlibVersion ( void ); -</pre> - <p>Returns a string indicating the library version. -<pre class="example"> BZFILE * BZ2_bzopen ( const char *path, const char *mode ); - BZFILE * BZ2_bzdopen ( int fd, const char *mode ); -</pre> - <p>Opens a <code>.bz2</code> file for reading or writing, using either its name -or a pre-existing file descriptor. -Analogous to <code>fopen</code> and <code>fdopen</code>. -<pre class="example"> int BZ2_bzread ( BZFILE* b, void* buf, int len ); - int BZ2_bzwrite ( BZFILE* b, void* buf, int len ); -</pre> - <p>Reads/writes data from/to a previously opened <code>BZFILE</code>. -Analogous to <code>fread</code> and <code>fwrite</code>. -<pre class="example"> int BZ2_bzflush ( BZFILE* b ); - void BZ2_bzclose ( BZFILE* b ); -</pre> - <p>Flushes/closes a <code>BZFILE</code>. <code>BZ2_bzflush</code> doesn't actually do -anything. Analogous to <code>fflush</code> and <code>fclose</code>. - -<pre class="example"> const char * BZ2_bzerror ( BZFILE *b, int *errnum ) -</pre> - <p>Returns a string describing the more recent error status of -<code>b</code>, and also sets <code>*errnum</code> to its numerical value. - -<h3 class="section">3.7 Using the library in a <code>stdio</code>-free environment</h3> - -<h4 class="subsection">3.7.1 Getting rid of <code>stdio</code></h4> - -<p>In a deeply embedded application, you might want to use just -the memory-to-memory functions. You can do this conveniently -by compiling the library with preprocessor symbol <code>BZ_NO_STDIO</code> -defined. Doing this gives you a library containing only the following -eight functions: - - <p><code>BZ2_bzCompressInit</code>, <code>BZ2_bzCompress</code>, <code>BZ2_bzCompressEnd</code> <br> -<code>BZ2_bzDecompressInit</code>, <code>BZ2_bzDecompress</code>, <code>BZ2_bzDecompressEnd</code> <br> -<code>BZ2_bzBuffToBuffCompress</code>, <code>BZ2_bzBuffToBuffDecompress</code> - - <p>When compiled like this, all functions will ignore <code>verbosity</code> -settings. - -<h4 class="subsection">3.7.2 Critical error handling</h4> - -<p><code>libbzip2</code> contains a number of internal assertion checks which -should, needless to say, never be activated. Nevertheless, if an -assertion should fail, behaviour depends on whether or not the library -was compiled with <code>BZ_NO_STDIO</code> set. - - <p>For a normal compile, an assertion failure yields the message -<pre class="example"> bzip2/libbzip2: internal error number N. - This is a bug in bzip2/libbzip2, 1.0.2, 30-Dec-2001. - Please report it to me at: jseward@acm.org. If this happened - when you were using some program which uses libbzip2 as a - component, you should also report this bug to the author(s) - of that program. Please make an effort to report this bug; - timely and accurate bug reports eventually lead to higher - quality software. Thanks. Julian Seward, 30 December 2001. -</pre> - <p>where <code>N</code> is some error code number. If <code>N == 1007</code>, it also -prints some extra text advising the reader that unreliable memory is -often associated with internal error 1007. (This is a -frequently-observed-phenomenon with versions 1.0.0/1.0.1). - - <p><code>exit(3)</code> is then called. - - <p>For a <code>stdio</code>-free library, assertion failures result -in a call to a function declared as: -<pre class="example"> extern void bz_internal_error ( int errcode ); -</pre> - <p>The relevant code is passed as a parameter. You should supply -such a function. - - <p>In either case, once an assertion failure has occurred, any -<code>bz_stream</code> records involved can be regarded as invalid. -You should not attempt to resume normal operation with them. - - <p>You may, of course, change critical error handling to suit -your needs. As I said above, critical errors indicate bugs -in the library and should not occur. All "normal" error -situations are indicated via error return codes from functions, -and can be recovered from. - -<h3 class="section">3.8 Making a Windows DLL</h3> - -<p>Everything related to Windows has been contributed by Yoshioka Tsuneo -<br> (<code>QWF00133@niftyserve.or.jp</code> / -<code>tsuneo-y@is.aist-nara.ac.jp</code>), so you should send your queries to -him (but perhaps Cc: me, <code>jseward@acm.org</code>). - - <p>My vague understanding of what to do is: using Visual C++ 5.0, -open the project file <code>libbz2.dsp</code>, and build. That's all. - - <p>If you can't -open the project file for some reason, make a new one, naming these files: -<code>blocksort.c</code>, <code>bzlib.c</code>, <code>compress.c</code>, -<code>crctable.c</code>, <code>decompress.c</code>, <code>huffman.c</code>, <br> -<code>randtable.c</code> and <code>libbz2.def</code>. You will also need -to name the header files <code>bzlib.h</code> and <code>bzlib_private.h</code>. - - <p>If you don't use VC++, you may need to define the proprocessor symbol -<code>_WIN32</code>. - - <p>Finally, <code>dlltest.c</code> is a sample program using the DLL. It has a -project file, <code>dlltest.dsp</code>. - - <p>If you just want a makefile for Visual C, have a look at -<code>makefile.msc</code>. - - <p>Be aware that if you compile <code>bzip2</code> itself on Win32, you must set -<code>BZ_UNIX</code> to 0 and <code>BZ_LCCWIN32</code> to 1, in the file -<code>bzip2.c</code>, before compiling. Otherwise the resulting binary won't -work correctly. - - <p>I haven't tried any of this stuff myself, but it all looks plausible. - -<h2 class="chapter">4 Miscellanea</h2> - -<p>These are just some random thoughts of mine. Your mileage may -vary. - -<h3 class="section">4.1 Limitations of the compressed file format</h3> - -<p><code>bzip2-1.0</code>, <code>0.9.5</code> and <code>0.9.0</code> -use exactly the same file format as the previous -version, <code>bzip2-0.1</code>. This decision was made in the interests of -stability. Creating yet another incompatible compressed file format -would create further confusion and disruption for users. - - <p>Nevertheless, this is not a painless decision. Development -work since the release of <code>bzip2-0.1</code> in August 1997 -has shown complexities in the file format which slow down -decompression and, in retrospect, are unnecessary. These are: - <ul> -<li>The run-length encoder, which is the first of the - compression transformations, is entirely irrelevant. - The original purpose was to protect the sorting algorithm - from the very worst case input: a string of repeated - symbols. But algorithm steps Q6a and Q6b in the original - Burrows-Wheeler technical report (SRC-124) show how - repeats can be handled without difficulty in block - sorting. -<li>The randomisation mechanism doesn't really need to be - there. Udi Manber and Gene Myers published a suffix - array construction algorithm a few years back, which - can be employed to sort any block, no matter how - repetitive, in O(N log N) time. Subsequent work by - Kunihiko Sadakane has produced a derivative O(N (log N)^2) - algorithm which usually outperforms the Manber-Myers - algorithm. - - <p>I could have changed to Sadakane's algorithm, but I find - it to be slower than <code>bzip2</code>'s existing algorithm for - most inputs, and the randomisation mechanism protects - adequately against bad cases. I didn't think it was - a good tradeoff to make. Partly this is due to the fact - that I was not flooded with email complaints about - <code>bzip2-0.1</code>'s performance on repetitive data, so - perhaps it isn't a problem for real inputs. - - <p>Probably the best long-term solution, - and the one I have incorporated into 0.9.5 and above, - is to use the existing sorting - algorithm initially, and fall back to a O(N (log N)^2) - algorithm if the standard algorithm gets into difficulties. -<li>The compressed file format was never designed to be - handled by a library, and I have had to jump though - some hoops to produce an efficient implementation of - decompression. It's a bit hairy. Try passing - <code>decompress.c</code> through the C preprocessor - and you'll see what I mean. Much of this complexity - could have been avoided if the compressed size of - each block of data was recorded in the data stream. -<li>An Adler-32 checksum, rather than a CRC32 checksum, - would be faster to compute. -</ul> - It would be fair to say that the <code>bzip2</code> format was frozen -before I properly and fully understood the performance -consequences of doing so. - - <p>Improvements which I was able to incorporate into -0.9.0, despite using the same file format, are: - <ul> -<li>Single array implementation of the inverse BWT. This - significantly speeds up decompression, presumably - because it reduces the number of cache misses. -<li>Faster inverse MTF transform for large MTF values. The - new implementation is based on the notion of sliding blocks - of values. -<li><code>bzip2-0.9.0</code> now reads and writes files with <code>fread</code> - and <code>fwrite</code>; version 0.1 used <code>putc</code> and <code>getc</code>. - Duh! Well, you live and learn. - - </ul> - Further ahead, it would be nice -to be able to do random access into files. This will -require some careful design of compressed file formats. - -<h3 class="section">4.2 Portability issues</h3> - -<p>After some consideration, I have decided not to use -GNU <code>autoconf</code> to configure 0.9.5 or 1.0. - - <p><code>autoconf</code>, admirable and wonderful though it is, -mainly assists with portability problems between Unix-like -platforms. But <code>bzip2</code> doesn't have much in the way -of portability problems on Unix; most of the difficulties appear -when porting to the Mac, or to Microsoft's operating systems. -<code>autoconf</code> doesn't help in those cases, and brings in a -whole load of new complexity. - - <p>Most people should be able to compile the library and program -under Unix straight out-of-the-box, so to speak, especially -if you have a version of GNU C available. - - <p>There are a couple of <code>__inline__</code> directives in the code. GNU C -(<code>gcc</code>) should be able to handle them. If you're not using -GNU C, your C compiler shouldn't see them at all. -If your compiler does, for some reason, see them and doesn't -like them, just <code>#define</code> <code>__inline__</code> to be <code>/* */</code>. One -easy way to do this is to compile with the flag <code>-D__inline__=</code>, -which should be understood by most Unix compilers. - - <p>If you still have difficulties, try compiling with the macro -<code>BZ_STRICT_ANSI</code> defined. This should enable you to build the -library in a strictly ANSI compliant environment. Building the program -itself like this is dangerous and not supported, since you remove -<code>bzip2</code>'s checks against compressing directories, symbolic links, -devices, and other not-really-a-file entities. This could cause -filesystem corruption! - - <p>One other thing: if you create a <code>bzip2</code> binary for public -distribution, please try and link it statically (<code>gcc -s</code>). This -avoids all sorts of library-version issues that others may encounter -later on. - - <p>If you build <code>bzip2</code> on Win32, you must set <code>BZ_UNIX</code> to 0 and -<code>BZ_LCCWIN32</code> to 1, in the file <code>bzip2.c</code>, before compiling. -Otherwise the resulting binary won't work correctly. - -<h3 class="section">4.3 Reporting bugs</h3> - -<p>I tried pretty hard to make sure <code>bzip2</code> is -bug free, both by design and by testing. Hopefully -you'll never need to read this section for real. - - <p>Nevertheless, if <code>bzip2</code> dies with a segmentation -fault, a bus error or an internal assertion failure, it -will ask you to email me a bug report. Experience with -version 0.1 shows that almost all these problems can -be traced to either compiler bugs or hardware problems. - <ul> -<li>Recompile the program with no optimisation, and see if it -works. And/or try a different compiler. -I heard all sorts of stories about various flavours -of GNU C (and other compilers) generating bad code for -<code>bzip2</code>, and I've run across two such examples myself. - - <p>2.7.X versions of GNU C are known to generate bad code from -time to time, at high optimisation levels. -If you get problems, try using the flags -<code>-O2</code> <code>-fomit-frame-pointer</code> <code>-fno-strength-reduce</code>. -You should specifically <em>not</em> use <code>-funroll-loops</code>. - - <p>You may notice that the Makefile runs six tests as part of -the build process. If the program passes all of these, it's -a pretty good (but not 100%) indication that the compiler has -done its job correctly. -<li>If <code>bzip2</code> crashes randomly, and the crashes are not -repeatable, you may have a flaky memory subsystem. <code>bzip2</code> -really hammers your memory hierarchy, and if it's a bit marginal, -you may get these problems. Ditto if your disk or I/O subsystem -is slowly failing. Yup, this really does happen. - - <p>Try using a different machine of the same type, and see if -you can repeat the problem. -<li>This isn't really a bug, but ... If <code>bzip2</code> tells -you your file is corrupted on decompression, and you -obtained the file via FTP, there is a possibility that you -forgot to tell FTP to do a binary mode transfer. That absolutely -will cause the file to be non-decompressible. You'll have to transfer -it again. -</ul> - - <p>If you've incorporated <code>libbzip2</code> into your own program -and are getting problems, please, please, please, check that the -parameters you are passing in calls to the library, are -correct, and in accordance with what the documentation says -is allowable. I have tried to make the library robust against -such problems, but I'm sure I haven't succeeded. - - <p>Finally, if the above comments don't help, you'll have to send -me a bug report. Now, it's just amazing how many people will -send me a bug report saying something like -<pre class="display"> bzip2 crashed with segmentation fault on my machine -</pre> - <p>and absolutely nothing else. Needless to say, a such a report -is <em>totally, utterly, completely and comprehensively 100% useless; -a waste of your time, my time, and net bandwidth</em>. -With no details at all, there's no way I can possibly begin -to figure out what the problem is. - - <p>The rules of the game are: facts, facts, facts. Don't omit -them because "oh, they won't be relevant". At the bare -minimum: -<pre class="display"> Machine type. Operating system version. - Exact version of <code>bzip2</code> (do <code>bzip2 -V</code>). - Exact version of the compiler used. - Flags passed to the compiler. -</pre> - <p>However, the most important single thing that will help me is -the file that you were trying to compress or decompress at the -time the problem happened. Without that, my ability to do anything -more than speculate about the cause, is limited. - - <p>Please remember that I connect to the Internet with a modem, so -you should contact me before mailing me huge files. - -<h3 class="section">4.4 Did you get the right package?</h3> - -<p><code>bzip2</code> is a resource hog. It soaks up large amounts of CPU cycles -and memory. Also, it gives very large latencies. In the worst case, you -can feed many megabytes of uncompressed data into the library before -getting any compressed output, so this probably rules out applications -requiring interactive behaviour. - - <p>These aren't faults of my implementation, I hope, but more -an intrinsic property of the Burrows-Wheeler transform (unfortunately). -Maybe this isn't what you want. - - <p>If you want a compressor and/or library which is faster, uses less -memory but gets pretty good compression, and has minimal latency, -consider Jean-loup -Gailly's and Mark Adler's work, <code>zlib-1.1.3</code> and -<code>gzip-1.2.4</code>. Look for them at - - <p><code>http://www.zlib.org</code> and -<code>http://www.gzip.org</code> respectively. - - <p>For something faster and lighter still, you might try Markus F X J -Oberhumer's <code>LZO</code> real-time compression/decompression library, at -<br> <code>http://wildsau.idv.uni-linz.ac.at/mfx/lzo.html</code>. - - <p>If you want to use the <code>bzip2</code> algorithms to compress small blocks -of data, 64k bytes or smaller, for example on an on-the-fly disk -compressor, you'd be well advised not to use this library. Instead, -I've made a special library tuned for that kind of use. It's part of -<code>e2compr-0.40</code>, an on-the-fly disk compressor for the Linux -<code>ext2</code> filesystem. Look at -<code>http://www.netspace.net.au/~reiter/e2compr</code>. - -<h3 class="section">4.5 Testing</h3> - -<p>A record of the tests I've done. - - <p>First, some data sets: - <ul> -<li>B: a directory containing 6001 files, one for every length in the - range 0 to 6000 bytes. The files contain random lowercase - letters. 18.7 megabytes. -<li>H: my home directory tree. Documents, source code, mail files, - compressed data. H contains B, and also a directory of - files designed as boundary cases for the sorting; mostly very - repetitive, nasty files. 565 megabytes. -<li>A: directory tree holding various applications built from source: - <code>egcs</code>, <code>gcc-2.8.1</code>, KDE, GTK, Octave, etc. - 2200 megabytes. -</ul> - The tests conducted are as follows. Each test means compressing -(a copy of) each file in the data set, decompressing it and -comparing it against the original. - - <p>First, a bunch of tests with block sizes and internal buffer -sizes set very small, -to detect any problems with the -blocking and buffering mechanisms. -This required modifying the source code so as to try to -break it. - <ol type=1 start=1> -<li>Data set H, with - buffer size of 1 byte, and block size of 23 bytes. -<li>Data set B, buffer sizes 1 byte, block size 1 byte. -<li>As (2) but small-mode decompression. -<li>As (2) with block size 2 bytes. -<li>As (2) with block size 3 bytes. -<li>As (2) with block size 4 bytes. -<li>As (2) with block size 5 bytes. -<li>As (2) with block size 6 bytes and small-mode decompression. -<li>H with buffer size of 1 byte, but normal block - size (up to 900000 bytes). - </ol> -Then some tests with unmodified source code. - <ol type=1 start=1> -<li>H, all settings normal. -<li>As (1), with small-mode decompress. -<li>H, compress with flag <code>-1</code>. -<li>H, compress with flag <code>-s</code>, decompress with flag <code>-s</code>. -<li>Forwards compatibility: H, <code>bzip2-0.1pl2</code> compressing, - <code>bzip2-0.9.5</code> decompressing, all settings normal. -<li>Backwards compatibility: H, <code>bzip2-0.9.5</code> compressing, - <code>bzip2-0.1pl2</code> decompressing, all settings normal. -<li>Bigger tests: A, all settings normal. -<li>As (7), using the fallback (Sadakane-like) sorting algorithm. -<li>As (8), compress with flag <code>-1</code>, decompress with flag - <code>-s</code>. -<li>H, using the fallback sorting algorithm. -<li>Forwards compatibility: A, <code>bzip2-0.1pl2</code> compressing, - <code>bzip2-0.9.5</code> decompressing, all settings normal. -<li>Backwards compatibility: A, <code>bzip2-0.9.5</code> compressing, - <code>bzip2-0.1pl2</code> decompressing, all settings normal. -<li>Misc test: about 400 megabytes of <code>.tar</code> files with - <code>bzip2</code> compiled with Checker (a memory access error - detector, like Purify). -<li>Misc tests to make sure it builds and runs ok on non-Linux/x86 - platforms. - </ol> -These tests were conducted on a 225 MHz IDT WinChip machine, running -Linux 2.0.36. They represent nearly a week of continuous computation. -All tests completed successfully. - -<h3 class="section">4.6 Further reading</h3> - -<p><code>bzip2</code> is not research work, in the sense that it doesn't present -any new ideas. Rather, it's an engineering exercise based on existing -ideas. - - <p>Four documents describe essentially all the ideas behind <code>bzip2</code>: -<pre class="example"> Michael Burrows and D. J. Wheeler: - "A block-sorting lossless data compression algorithm" - 10th May 1994. - Digital SRC Research Report 124. - ftp://ftp.digital.com/pub/DEC/SRC/research-reports/SRC-124.ps.gz - If you have trouble finding it, try searching at the - New Zealand Digital Library, http://www.nzdl.org. - - Daniel S. Hirschberg and Debra A. LeLewer - "Efficient Decoding of Prefix Codes" - Communications of the ACM, April 1990, Vol 33, Number 4. - You might be able to get an electronic copy of this - from the ACM Digital Library. - - David J. Wheeler - Program bred3.c and accompanying document bred3.ps. - This contains the idea behind the multi-table Huffman - coding scheme. - ftp://ftp.cl.cam.ac.uk/users/djw3/ - - Jon L. Bentley and Robert Sedgewick - "Fast Algorithms for Sorting and Searching Strings" - Available from Sedgewick's web page, - www.cs.princeton.edu/~rs -</pre> - <p>The following paper gives valuable additional insights into the -algorithm, but is not immediately the basis of any code -used in bzip2. -<pre class="example"> Peter Fenwick: - Block Sorting Text Compression - Proceedings of the 19th Australasian Computer Science Conference, - Melbourne, Australia. Jan 31 - Feb 2, 1996. - ftp://ftp.cs.auckland.ac.nz/pub/peter-f/ACSC96paper.ps -</pre> - <p>Kunihiko Sadakane's sorting algorithm, mentioned above, -is available from: -<pre class="example"> http://naomi.is.s.u-tokyo.ac.jp/~sada/papers/Sada98b.ps.gz -</pre> - <p>The Manber-Myers suffix array construction -algorithm is described in a paper -available from: -<pre class="example"> http://www.cs.arizona.edu/people/gene/PAPERS/suffix.ps -</pre> - <p>Finally, the following paper documents some recent investigations -I made into the performance of sorting algorithms: -<pre class="example"> Julian Seward: - On the Performance of BWT Sorting Algorithms - Proceedings of the IEEE Data Compression Conference 2000 - Snowbird, Utah. 28-30 March 2000. -</pre> - <div class="contents"> -<h2>Table of Contents</h2> -<ul> -<li><a name="toc_Top" href="#Top">1 Introduction</a> -<li><a name="toc_Top" href="#Top">2 How to use <code>bzip2</code></a> -<ul> -<ul> -<ul> -<li><a href="#Top">NAME</a> -<li><a href="#Top">SYNOPSIS</a> -<li><a href="#Top">DESCRIPTION</a> -<li><a href="#Top">OPTIONS</a> -<li><a href="#Top">MEMORY MANAGEMENT</a> -<li><a href="#Top">RECOVERING DATA FROM DAMAGED FILES</a> -<li><a href="#Top">PERFORMANCE NOTES</a> -<li><a href="#Top">CAVEATS</a> -<li><a href="#Top">AUTHOR</a> -</li></ul> -</li></ul> -</li></ul> -<li><a name="toc_Top" href="#Top">3 Programming with <code>libbzip2</code></a> -<ul> -<li><a href="#Top">3.1 Top-level structure</a> -<ul> -<li><a href="#Top">3.1.1 Low-level summary</a> -<li><a href="#Top">3.1.2 High-level summary</a> -<li><a href="#Top">3.1.3 Utility functions summary</a> -</li></ul> -<li><a href="#Top">3.2 Error handling</a> -<li><a href="#Top">3.3 Low-level interface</a> -<ul> -<li><a href="#Top">3.3.1 <code>BZ2_bzCompressInit</code></a> -<li><a href="#Top">3.3.2 <code>BZ2_bzCompress</code></a> -<li><a href="#Top">3.3.3 <code>BZ2_bzCompressEnd</code></a> -<li><a href="#Top">3.3.4 <code>BZ2_bzDecompressInit</code></a> -<li><a href="#Top">3.3.5 <code>BZ2_bzDecompress</code></a> -<li><a href="#Top">3.3.6 <code>BZ2_bzDecompressEnd</code></a> -</li></ul> -<li><a href="#Top">3.4 High-level interface</a> -<ul> -<li><a href="#Top">3.4.1 <code>BZ2_bzReadOpen</code></a> -<li><a href="#Top">3.4.2 <code>BZ2_bzRead</code></a> -<li><a href="#Top">3.4.3 <code>BZ2_bzReadGetUnused</code></a> -<li><a href="#Top">3.4.4 <code>BZ2_bzReadClose</code></a> -<li><a href="#Top">3.4.5 <code>BZ2_bzWriteOpen</code></a> -<li><a href="#Top">3.4.6 <code>BZ2_bzWrite</code></a> -<li><a href="#Top">3.4.7 <code>BZ2_bzWriteClose</code></a> -<li><a href="#Top">3.4.8 Handling embedded compressed data streams</a> -<li><a href="#Top">3.4.9 Standard file-reading/writing code</a> -</li></ul> -<li><a href="#Top">3.5 Utility functions</a> -<ul> -<li><a href="#Top">3.5.1 <code>BZ2_bzBuffToBuffCompress</code></a> -<li><a href="#Top">3.5.2 <code>BZ2_bzBuffToBuffDecompress</code></a> -</li></ul> -<li><a href="#Top">3.6 <code>zlib</code> compatibility functions</a> -<li><a href="#Top">3.7 Using the library in a <code>stdio</code>-free environment</a> -<ul> -<li><a href="#Top">3.7.1 Getting rid of <code>stdio</code></a> -<li><a href="#Top">3.7.2 Critical error handling</a> -</li></ul> -<li><a href="#Top">3.8 Making a Windows DLL</a> -</li></ul> -<li><a name="toc_Top" href="#Top">4 Miscellanea</a> -<ul> -<li><a href="#Top">4.1 Limitations of the compressed file format</a> -<li><a href="#Top">4.2 Portability issues</a> -<li><a href="#Top">4.3 Reporting bugs</a> -<li><a href="#Top">4.4 Did you get the right package?</a> -<li><a href="#Top">4.5 Testing</a> -<li><a href="#Top">4.6 Further reading</a> -</li></ul> -</li></ul> -</div> - -</body></html> - diff --git a/Master/texmf/doc/bzip2/bzip2.pdf b/Master/texmf/doc/bzip2/bzip2.pdf Binary files differdeleted file mode 100644 index e48ed05e1da..00000000000 --- a/Master/texmf/doc/bzip2/bzip2.pdf +++ /dev/null diff --git a/Master/texmf/doc/bzip2/manual.html b/Master/texmf/doc/bzip2/manual.html deleted file mode 100644 index 2c4980ede03..00000000000 --- a/Master/texmf/doc/bzip2/manual.html +++ /dev/null @@ -1,117 +0,0 @@ -<HTML> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<!-- Created on May, 24 2004 by texi2html @T2H_VERSION@ --> -<!-- -Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author) - Karl Berry <karl@freefriends.org> - Olaf Bachmann <obachman@mathematik.uni-kl.de> - and many others. -Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de> -Send bugs and suggestions to <texi2html@mathematik.uni-kl.de> - ---> -<HEAD> -<TITLE>Untitled Document: Untitled Document</TITLE> - -<META NAME="description" CONTENT="Untitled Document: Untitled Document"> -<META NAME="keywords" CONTENT="Untitled Document: Untitled Document"> -<META NAME="resource-type" CONTENT="document"> -<META NAME="distribution" CONTENT="global"> -<META NAME="Generator" CONTENT="texi2html @T2H_VERSION@"> - -</HEAD> - -<BODY LANG="en" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000"> - -<A NAME="SEC_Top"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H1>Untitled Document</H1></P><P> - -The following text is the License for this software. You should -find it identical to that contained in the file LICENSE in the -source distribution. -</P><P> - -@bf{------------------ START OF THE LICENSE ------------------} -</P><P> - -This program, <CODE>bzip2</CODE>, -and associated library <CODE>libbzip2</CODE>, are -Copyright (C) 1996-2002 Julian R Seward. All rights reserved. -</P><P> - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: -<UL> -<LI> - Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. -<LI> - The origin of this software must not be misrepresented; you must - not claim that you wrote the original software. If you use this - software in a product, an acknowledgment in the product - documentation would be appreciated but is not required. -<LI> - Altered source versions must be plainly marked as such, and must - not be misrepresented as being the original software. -<LI> - The name of the author may not be used to endorse or promote - products derived from this software without specific prior written - permission. -</UL> -THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS -OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY -DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE -GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, -WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -<P> - -Julian Seward, Cambridge, UK. -</P><P> - -<CODE>jseward@acm.org</CODE> -</P><P> - -<CODE>bzip2</CODE>/<CODE>libbzip2</CODE> version 1.0.2 of 30 December 2001. -</P><P> - -@bf{------------------ END OF THE LICENSE ------------------} -</P><P> - -Web sites: -</P><P> - -<CODE>http://sources.redhat.com/bzip2</CODE> -</P><P> - -<CODE>http://www.cacheprof.org</CODE> -</P><P> - -PATENTS: To the best of my knowledge, <CODE>bzip2</CODE> does not use any patented -algorithms. However, I do not have the resources available to carry out -a full patent search. Therefore I cannot give any guarantee of the -above statement. -</P><P> - -<HR SIZE=1> -<BR> -<FONT SIZE="-1"> -This document was generated -on <I>May, 24 2004</I> -using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html -"><I>texi2html</I></A> - -</BODY> -</HTML> diff --git a/Master/tlpkg/tlpsrc/bin-bzip2.tlpsrc b/Master/tlpkg/tlpsrc/bin-bzip2.tlpsrc deleted file mode 100644 index 45374cfabc7..00000000000 --- a/Master/tlpkg/tlpsrc/bin-bzip2.tlpsrc +++ /dev/null @@ -1,9 +0,0 @@ -name bin-bzip2 -category TLCore -docpattern f texmf/doc/bzip2/* -docpattern f texmf/doc/info/bzip2.info -docpattern f texmf/doc/man/man1/bzip2.1 -docpattern f texmf/doc/man/man1/bzip2.1.html -binpattern f bin/win32/bzip2.exe -binpattern f bin/win32/bzip2recover.exe -binpattern f bin/win32/tl90bzip2.dll diff --git a/Master/tlpkg/tlpsrc/collection-wintools.tlpsrc b/Master/tlpkg/tlpsrc/collection-wintools.tlpsrc index 1d1e7ee946a..80767a71157 100644 --- a/Master/tlpkg/tlpsrc/collection-wintools.tlpsrc +++ b/Master/tlpkg/tlpsrc/collection-wintools.tlpsrc @@ -2,8 +2,7 @@ name collection-wintools category Collection shortdesc Windows support programs longdesc Utilities for Windows, since they are not readily available there: -longdesc gzip, bzip2, chktex, jpeg2ps, unzip, wget, xpdf. -depend bin-bzip2 +longdesc gzip, chktex, jpeg2ps, unzip, wget, xpdf. depend bin-chktex depend bin-gzip depend bin-jpeg2ps |