bz2lib/manual_3.html

   1 <HTML>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   3 <!-- Created on January, 5  2002 by texi2html 1.64 -->
   4 <!--
   5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
   6             Karl Berry  <karl@freefriends.org>
   7             Olaf Bachmann <obachman@mathematik.uni-kl.de>
   8             and many others.
   9 Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
  10 Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
  11
  12 -->
  13 <HEAD>
  14 <TITLE>Untitled Document: 3. Programming with <CODE>libbzip2</CODE></TITLE>
  15
  16 <META NAME="description" CONTENT="Untitled Document: 3. Programming with <CODE>libbzip2</CODE>">
  17 <META NAME="keywords" CONTENT="Untitled Document: 3. Programming with <CODE>libbzip2</CODE>">
  18 <META NAME="resource-type" CONTENT="document">
  19 <META NAME="distribution" CONTENT="global">
  20 <META NAME="Generator" CONTENT="texi2html 1.64">
  21
  22 </HEAD>
  23
  24 <BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
  25
  26 <A NAME="SEC12"></A>
  27 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
  28 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_2.html#SEC11"> &lt; </A>]</TD>
  29 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC13"> &gt; </A>]</TD>
  30 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
  31 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
  32 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
  33 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
  34 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
  35 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
  36 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
  37 </TR></TABLE>
  38 <H1> 3. Programming with <CODE>libbzip2</CODE> </H1>
  39 <!--docid::SEC12::-->
  40 <P>
  41
  42 This chapter describes the programming interface to <CODE>libbzip2</CODE>.
  43 </P><P>
  44
  45 For general background information, particularly about memory
  46 use and performance aspects, you'd be well advised to read Chapter 2
  47 as well.
  48 </P><P>
  49
  50 <HR SIZE="6">
  51 <A NAME="SEC13"></A>
  52 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
  53 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC12"> &lt; </A>]</TD>
  54 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC14"> &gt; </A>]</TD>
  55 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
  56 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
  57 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
  58 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
  59 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
  60 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
  61 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
  62 </TR></TABLE>
  63 <H2> 3.1 Top-level structure </H2>
  64 <!--docid::SEC13::-->
  65 <P>
  66
  67 <CODE>libbzip2</CODE> is a flexible library for compressing and decompressing
  68 data in the <CODE>bzip2</CODE> data format.  Although packaged as a single
  69 entity, it helps to regard the library as three separate parts: the low
  70 level interface, and the high level interface, and some utility
  71 functions.
  72 </P><P>
  73
  74 The structure of <CODE>libbzip2</CODE>'s interfaces is similar to
  75 that of Jean-loup Gailly's and Mark Adler's excellent <CODE>zlib</CODE>
  76 library.
  77 </P><P>
  78
  79 All externally visible symbols have names beginning <CODE>BZ2_</CODE>.
  80 This is new in version 1.0.  The intention is to minimise pollution
  81 of the namespaces of library clients.
  82 </P><P>
  83
  84 <HR SIZE="6">
  85 <A NAME="SEC14"></A>
  86 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
  87 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC13"> &lt; </A>]</TD>
  88 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC15"> &gt; </A>]</TD>
  89 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
  90 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
  91 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
  92 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
  93 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
  94 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
  95 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
  96 </TR></TABLE>
  97 <H3> 3.1.1 Low-level summary </H3>
  98 <!--docid::SEC14::-->
  99 <P>
 100
 101 This interface provides services for compressing and decompressing
 102 data in memory.  There's no provision for dealing with files, streams
 103 or any other I/O mechanisms, just straight memory-to-memory work.
 104 In fact, this part of the library can be compiled without inclusion
 105 of <CODE>stdio.h</CODE>, which may be helpful for embedded applications.
 106 </P><P>
 107
 108 The low-level part of the library has no global variables and
 109 is therefore thread-safe.
 110 </P><P>
 111
 112 Six routines make up the low level interface:
 113 <CODE>BZ2_bzCompressInit</CODE>, <CODE>BZ2_bzCompress</CODE>, and <BR> <CODE>BZ2_bzCompressEnd</CODE>
 114 for compression,
 115 and a corresponding trio <CODE>BZ2_bzDecompressInit</CODE>, <BR> <CODE>BZ2_bzDecompress</CODE>
 116 and <CODE>BZ2_bzDecompressEnd</CODE> for decompression.
 117 The <CODE>*Init</CODE> functions allocate
 118 memory for compression/decompression and do other
 119 initialisations, whilst the <CODE>*End</CODE> functions close down operations
 120 and release memory.
 121 </P><P>
 122
 123 The real work is done by <CODE>BZ2_bzCompress</CODE> and <CODE>BZ2_bzDecompress</CODE>.
 124 These compress and decompress data from a user-supplied input buffer
 125 to a user-supplied output buffer.  These buffers can be any size;
 126 arbitrary quantities of data are handled by making repeated calls
 127 to these functions.  This is a flexible mechanism allowing a
 128 consumer-pull style of activity, or producer-push, or a mixture of
 129 both.
 130 </P><P>
 131
 132 <HR SIZE="6">
 133 <A NAME="SEC15"></A>
 134 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 135 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC14"> &lt; </A>]</TD>
 136 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC16"> &gt; </A>]</TD>
 137 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 138 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 139 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 140 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 141 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 142 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 143 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 144 </TR></TABLE>
 145 <H3> 3.1.2 High-level summary </H3>
 146 <!--docid::SEC15::-->
 147 <P>
 148
 149 This interface provides some handy wrappers around the low-level
 150 interface to facilitate reading and writing <CODE>bzip2</CODE> format
 151 files (<CODE>.bz2</CODE> files).  The routines provide hooks to facilitate
 152 reading files in which the <CODE>bzip2</CODE> data stream is embedded
 153 within some larger-scale file structure, or where there are
 154 multiple <CODE>bzip2</CODE> data streams concatenated end-to-end.
 155 </P><P>
 156
 157 For reading files, <CODE>BZ2_bzReadOpen</CODE>, <CODE>BZ2_bzRead</CODE>,
 158 <CODE>BZ2_bzReadClose</CODE> and <BR> <CODE>BZ2_bzReadGetUnused</CODE> are supplied.  For
 159 writing files, <CODE>BZ2_bzWriteOpen</CODE>, <CODE>BZ2_bzWrite</CODE> and
 160 <CODE>BZ2_bzWriteFinish</CODE> are available.
 161 </P><P>
 162
 163 As with the low-level library, no global variables are used
 164 so the library is per se thread-safe.  However, if I/O errors
 165 occur whilst reading or writing the underlying compressed files,
 166 you may have to consult <CODE>errno</CODE> to determine the cause of
 167 the error.  In that case, you'd need a C library which correctly
 168 supports <CODE>errno</CODE> in a multithreaded environment.
 169 </P><P>
 170
 171 To make the library a little simpler and more portable,
 172 <CODE>BZ2_bzReadOpen</CODE> and <CODE>BZ2_bzWriteOpen</CODE> require you to pass them file
 173 handles (<CODE>FILE*</CODE>s) which have previously been opened for reading or
 174 writing respectively.  That avoids portability problems associated with
 175 file operations and file attributes, whilst not being much of an
 176 imposition on the programmer.
 177 </P><P>
 178
 179 <HR SIZE="6">
 180 <A NAME="SEC16"></A>
 181 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 182 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC15"> &lt; </A>]</TD>
 183 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC17"> &gt; </A>]</TD>
 184 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 185 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 186 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 187 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 188 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 189 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 190 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 191 </TR></TABLE>
 192 <H3> 3.1.3 Utility functions summary </H3>
 193 <!--docid::SEC16::-->
 194 For very simple needs, <CODE>BZ2_bzBuffToBuffCompress</CODE> and
 195 <CODE>BZ2_bzBuffToBuffDecompress</CODE> are provided.  These compress
 196 data in memory from one buffer to another buffer in a single
 197 function call.  You should assess whether these functions
 198 fulfill your memory-to-memory compression/decompression
 199 requirements before investing effort in understanding the more
 200 general but more complex low-level interface.
 201 <P>
 202
 203 Yoshioka Tsuneo (<CODE>QWF00133@niftyserve.or.jp</CODE> /
 204 <CODE>tsuneo-y@is.aist-nara.ac.jp</CODE>) has contributed some functions to
 205 give better <CODE>zlib</CODE> compatibility.  These functions are
 206 <CODE>BZ2_bzopen</CODE>, <CODE>BZ2_bzread</CODE>, <CODE>BZ2_bzwrite</CODE>, <CODE>BZ2_bzflush</CODE>,
 207 <CODE>BZ2_bzclose</CODE>,
 208 <CODE>BZ2_bzerror</CODE> and <CODE>BZ2_bzlibVersion</CODE>.  You may find these functions
 209 more convenient for simple file reading and writing, than those in the
 210 high-level interface.  These functions are not (yet) officially part of
 211 the library, and are minimally documented here.  If they break, you
 212 get to keep all the pieces.  I hope to document them properly when time
 213 permits.
 214 </P><P>
 215
 216 Yoshioka also contributed modifications to allow the library to be
 217 built as a Windows DLL.
 218 </P><P>
 219
 220 <HR SIZE="6">
 221 <A NAME="SEC17"></A>
 222 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 223 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC16"> &lt; </A>]</TD>
 224 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC18"> &gt; </A>]</TD>
 225 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 226 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 227 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 228 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 229 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 230 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 231 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 232 </TR></TABLE>
 233 <H2> 3.2 Error handling </H2>
 234 <!--docid::SEC17::-->
 235 <P>
 236
 237 The library is designed to recover cleanly in all situations, including
 238 the worst-case situation of decompressing random data.  I'm not
 239 100% sure that it can always do this, so you might want to add
 240 a signal handler to catch segmentation violations during decompression
 241 if you are feeling especially paranoid.  I would be interested in
 242 hearing more about the robustness of the library to corrupted
 243 compressed data.
 244 </P><P>
 245
 246 Version 1.0 is much more robust in this respect than
 247 0.9.0 or 0.9.5.  Investigations with Checker (a tool for
 248 detecting problems with memory management, similar to Purify)
 249 indicate that, at least for the few files I tested, all single-bit
 250 errors in the decompressed data are caught properly, with no
 251 segmentation faults, no reads of uninitialised data and no
 252 out of range reads or writes.  So it's certainly much improved,
 253 although I wouldn't claim it to be totally bombproof.
 254 </P><P>
 255
 256 The file <CODE>bzlib.h</CODE> contains all definitions needed to use
 257 the library.  In particular, you should definitely not include
 258 <CODE>bzlib_private.h</CODE>.
 259 </P><P>
 260
 261 In <CODE>bzlib.h</CODE>, the various return values are defined.  The following
 262 list is not intended as an exhaustive description of the circumstances
 263 in which a given value may be returned -- those descriptions are given
 264 later.  Rather, it is intended to convey the rough meaning of each
 265 return value.  The first five actions are normal and not intended to
 266 denote an error situation.
 267 <DL COMPACT>
 268 <DT><CODE>BZ_OK</CODE>
 269 <DD>The requested action was completed successfully.
 270 <DT><CODE>BZ_RUN_OK</CODE>
 271 <DD><DT><CODE>BZ_FLUSH_OK</CODE>
 272 <DD><DT><CODE>BZ_FINISH_OK</CODE>
 273 <DD>In <CODE>BZ2_bzCompress</CODE>, the requested flush/finish/nothing-special action
 274 was completed successfully.
 275 <DT><CODE>BZ_STREAM_END</CODE>
 276 <DD>Compression of data was completed, or the logical stream end was
 277 detected during decompression.
 278 </DL>
 279 <P>
 280
 281 The following return values indicate an error of some kind.
 282 <DL COMPACT>
 283 <DT><CODE>BZ_CONFIG_ERROR</CODE>
 284 <DD>Indicates that the library has been improperly compiled on your
 285 platform -- a major configuration error.  Specifically, it means
 286 that <CODE>sizeof(char)</CODE>, <CODE>sizeof(short)</CODE> and <CODE>sizeof(int)</CODE>
 287 are not 1, 2 and 4 respectively, as they should be.  Note that the
 288 library should still work properly on 64-bit platforms which follow
 289 the LP64 programming model -- that is, where <CODE>sizeof(long)</CODE>
 290 and <CODE>sizeof(void*)</CODE> are 8.  Under LP64, <CODE>sizeof(int)</CODE> is
 291 still 4, so <CODE>libbzip2</CODE>, which doesn't use the <CODE>long</CODE> type,
 292 is OK.
 293 <DT><CODE>BZ_SEQUENCE_ERROR</CODE>
 294 <DD>When using the library, it is important to call the functions in the
 295 correct sequence and with data structures (buffers etc) in the correct
 296 states.  <CODE>libbzip2</CODE> checks as much as it can to ensure this is
 297 happening, and returns <CODE>BZ_SEQUENCE_ERROR</CODE> if not.  Code which
 298 complies precisely with the function semantics, as detailed below,
 299 should never receive this value; such an event denotes buggy code
 300 which you should investigate.
 301 <DT><CODE>BZ_PARAM_ERROR</CODE>
 302 <DD>Returned when a parameter to a function call is out of range
 303 or otherwise manifestly incorrect.  As with <CODE>BZ_SEQUENCE_ERROR</CODE>,
 304 this denotes a bug in the client code.  The distinction between
 305 <CODE>BZ_PARAM_ERROR</CODE> and <CODE>BZ_SEQUENCE_ERROR</CODE> is a bit hazy, but still worth
 306 making.
 307 <DT><CODE>BZ_MEM_ERROR</CODE>
 308 <DD>Returned when a request to allocate memory failed.  Note that the
 309 quantity of memory needed to decompress a stream cannot be determined
 310 until the stream's header has been read.  So <CODE>BZ2_bzDecompress</CODE> and
 311 <CODE>BZ2_bzRead</CODE> may return <CODE>BZ_MEM_ERROR</CODE> even though some of
 312 the compressed data has been read.  The same is not true for
 313 compression; once <CODE>BZ2_bzCompressInit</CODE> or <CODE>BZ2_bzWriteOpen</CODE> have
 314 successfully completed, <CODE>BZ_MEM_ERROR</CODE> cannot occur.
 315 <DT><CODE>BZ_DATA_ERROR</CODE>
 316 <DD>Returned when a data integrity error is detected during decompression.
 317 Most importantly, this means when stored and computed CRCs for the
 318 data do not match.  This value is also returned upon detection of any
 319 other anomaly in the compressed data.
 320 <DT><CODE>BZ_DATA_ERROR_MAGIC</CODE>
 321 <DD>As a special case of <CODE>BZ_DATA_ERROR</CODE>, it is sometimes useful to
 322 know when the compressed stream does not start with the correct
 323 magic bytes (<CODE>'B' 'Z' 'h'</CODE>).
 324 <DT><CODE>BZ_IO_ERROR</CODE>
 325 <DD>Returned by <CODE>BZ2_bzRead</CODE> and <CODE>BZ2_bzWrite</CODE> when there is an error
 326 reading or writing in the compressed file, and by <CODE>BZ2_bzReadOpen</CODE>
 327 and <CODE>BZ2_bzWriteOpen</CODE> for attempts to use a file for which the
 328 error indicator (viz, <CODE>ferror(f)</CODE>) is set.
 329 On receipt of <CODE>BZ_IO_ERROR</CODE>, the caller should consult
 330 <CODE>errno</CODE> and/or <CODE>perror</CODE> to acquire operating-system
 331 specific information about the problem.
 332 <DT><CODE>BZ_UNEXPECTED_EOF</CODE>
 333 <DD>Returned by <CODE>BZ2_bzRead</CODE> when the compressed file finishes
 334 before the logical end of stream is detected.
 335 <DT><CODE>BZ_OUTBUFF_FULL</CODE>
 336 <DD>Returned by <CODE>BZ2_bzBuffToBuffCompress</CODE> and
 337 <CODE>BZ2_bzBuffToBuffDecompress</CODE> to indicate that the output data
 338 will not fit into the output buffer provided.
 339 </DL>
 340 <P>
 341
 342 <HR SIZE="6">
 343 <A NAME="SEC18"></A>
 344 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 345 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC17"> &lt; </A>]</TD>
 346 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC19"> &gt; </A>]</TD>
 347 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 348 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 349 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 350 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 351 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 352 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 353 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 354 </TR></TABLE>
 355 <H2> 3.3 Low-level interface </H2>
 356 <!--docid::SEC18::-->
 357 <P>
 358
 359 <HR SIZE="6">
 360 <A NAME="SEC19"></A>
 361 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 362 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC18"> &lt; </A>]</TD>
 363 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC20"> &gt; </A>]</TD>
 364 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 365 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 366 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 367 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 368 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 369 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 370 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 371 </TR></TABLE>
 372 <H3> 3.3.1 <CODE>BZ2_bzCompressInit</CODE> </H3>
 373 <!--docid::SEC19::-->
 374 <TABLE><tr><td>&nbsp;</td><td class=example><pre>typedef
 375    struct {
 376       char *next_in;
 377       unsigned int avail_in;
 378       unsigned int total_in_lo32;
 379       unsigned int total_in_hi32;
 380
 381       char *next_out;
 382       unsigned int avail_out;
 383       unsigned int total_out_lo32;
 384       unsigned int total_out_hi32;
 385
 386       void *state;
 387
 388       void *(*bzalloc)(void *,int,int);
 389       void (*bzfree)(void *,void *);
 390       void *opaque;
 391    }
 392    bz_stream;
 393
 394 int BZ2_bzCompressInit ( bz_stream *strm,
 395                          int blockSize100k,
 396                          int verbosity,
 397                          int workFactor );
 398
 399 </pre></td></tr></table><P>
 400
 401 Prepares for compression.  The <CODE>bz_stream</CODE> structure
 402 holds all data pertaining to the compression activity.
 403 A <CODE>bz_stream</CODE> structure should be allocated and initialised
 404 prior to the call.
 405 The fields of <CODE>bz_stream</CODE>
 406 comprise the entirety of the user-visible data.  <CODE>state</CODE>
 407 is a pointer to the private data structures required for compression.
 408 </P><P>
 409
 410 Custom memory allocators are supported, via fields <CODE>bzalloc</CODE>,
 411 <CODE>bzfree</CODE>,
 412 and <CODE>opaque</CODE>.  The value
 413 <CODE>opaque</CODE> is passed to as the first argument to
 414 all calls to <CODE>bzalloc</CODE> and <CODE>bzfree</CODE>, but is
 415 otherwise ignored by the library.
 416 The call <CODE>bzalloc ( opaque, n, m )</CODE> is expected to return a
 417 pointer <CODE>p</CODE> to
 418 <CODE>n * m</CODE> bytes of memory, and <CODE>bzfree ( opaque, p )</CODE>
 419 should free
 420 that memory.
 421 </P><P>
 422
 423 If you don't want to use a custom memory allocator, set <CODE>bzalloc</CODE>,
 424 <CODE>bzfree</CODE> and
 425 <CODE>opaque</CODE> to <CODE>NULL</CODE>,
 426 and the library will then use the standard <CODE>malloc</CODE>/<CODE>free</CODE>
 427 routines.
 428 </P><P>
 429
 430 Before calling <CODE>BZ2_bzCompressInit</CODE>, fields <CODE>bzalloc</CODE>,
 431 <CODE>bzfree</CODE> and <CODE>opaque</CODE> should
 432 be filled appropriately, as just described.  Upon return, the internal
 433 state will have been allocated and initialised, and <CODE>total_in_lo32</CODE>,
 434 <CODE>total_in_hi32</CODE>, <CODE>total_out_lo32</CODE> and
 435 <CODE>total_out_hi32</CODE> will have been set to zero.
 436 These four fields are used by the library
 437 to inform the caller of the total amount of data passed into and out of
 438 the library, respectively.  You should not try to change them.
 439 As of version 1.0, 64-bit counts are maintained, even on 32-bit
 440 platforms, using the <CODE>_hi32</CODE> fields to store the upper 32 bits
 441 of the count.  So, for example, the total amount of data in
 442 is <CODE>(total_in_hi32 &#60;&#60; 32) + total_in_lo32</CODE>.
 443 </P><P>
 444
 445 Parameter <CODE>blockSize100k</CODE> specifies the block size to be used for
 446 compression.  It should be a value between 1 and 9 inclusive, and the
 447 actual block size used is 100000 x this figure.  9 gives the best
 448 compression but takes most memory.
 449 </P><P>
 450
 451 Parameter <CODE>verbosity</CODE> should be set to a number between 0 and 4
 452 inclusive.  0 is silent, and greater numbers give increasingly verbose
 453 monitoring/debugging output.  If the library has been compiled with
 454 <CODE>-DBZ_NO_STDIO</CODE>, no such output will appear for any verbosity
 455 setting.
 456 </P><P>
 457
 458 Parameter <CODE>workFactor</CODE> controls how the compression phase behaves
 459 when presented with worst case, highly repetitive, input data.  If
 460 compression runs into difficulties caused by repetitive data, the
 461 library switches from the standard sorting algorithm to a fallback
 462 algorithm.  The fallback is slower than the standard algorithm by
 463 perhaps a factor of three, but always behaves reasonably, no matter how
 464 bad the input.
 465 </P><P>
 466
 467 Lower values of <CODE>workFactor</CODE> reduce the amount of effort the
 468 standard algorithm will expend before resorting to the fallback.  You
 469 should set this parameter carefully; too low, and many inputs will be
 470 handled by the fallback algorithm and so compress rather slowly, too
 471 high, and your average-to-worst case compression times can become very
 472 large.  The default value of 30 gives reasonable behaviour over a wide
 473 range of circumstances.
 474 </P><P>
 475
 476 Allowable values range from 0 to 250 inclusive.  0 is a special case,
 477 equivalent to using the default value of 30.
 478 </P><P>
 479
 480 Note that the compressed output generated is the same regardless of
 481 whether or not the fallback algorithm is used.
 482 </P><P>
 483
 484 Be aware also that this parameter may disappear entirely in future
 485 versions of the library.  In principle it should be possible to devise a
 486 good way to automatically choose which algorithm to use.  Such a
 487 mechanism would render the parameter obsolete.
 488 </P><P>
 489
 490 Possible return values:
 491 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_CONFIG_ERROR</CODE>
 492          if the library has been mis-compiled
 493       <CODE>BZ_PARAM_ERROR</CODE>
 494          if <CODE>strm</CODE> is <CODE>NULL</CODE>
 495          or <CODE>blockSize</CODE> &#60; 1 or <CODE>blockSize</CODE> &#62; 9
 496          or <CODE>verbosity</CODE> &#60; 0 or <CODE>verbosity</CODE> &#62; 4
 497          or <CODE>workFactor</CODE> &#60; 0 or <CODE>workFactor</CODE> &#62; 250
 498       <CODE>BZ_MEM_ERROR</CODE>
 499          if not enough memory is available
 500       <CODE>BZ_OK</CODE>
 501          otherwise
 502 </pre></td></tr></table>Allowable next actions:
 503 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ2_bzCompress</CODE>
 504          if <CODE>BZ_OK</CODE> is returned
 505       no specific action needed in case of error
 506 </pre></td></tr></table></P><P>
 507
 508 <HR SIZE="6">
 509 <A NAME="SEC20"></A>
 510 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 511 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC19"> &lt; </A>]</TD>
 512 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC21"> &gt; </A>]</TD>
 513 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 514 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 515 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 516 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 517 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 518 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 519 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 520 </TR></TABLE>
 521 <H3> 3.3.2 <CODE>BZ2_bzCompress</CODE> </H3>
 522 <!--docid::SEC20::-->
 523 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   int BZ2_bzCompress ( bz_stream *strm, int action );
 524 </pre></td></tr></table>Provides more input and/or output buffer space for the library.  The
 525 caller maintains input and output buffers, and calls <CODE>BZ2_bzCompress</CODE> to
 526 transfer data between them.
 527 <P>
 528
 529 Before each call to <CODE>BZ2_bzCompress</CODE>, <CODE>next_in</CODE> should point at
 530 the data to be compressed, and <CODE>avail_in</CODE> should indicate how many
 531 bytes the library may read.  <CODE>BZ2_bzCompress</CODE> updates <CODE>next_in</CODE>,
 532 <CODE>avail_in</CODE> and <CODE>total_in</CODE> to reflect the number of bytes it
 533 has read.
 534 </P><P>
 535
 536 Similarly, <CODE>next_out</CODE> should point to a buffer in which the
 537 compressed data is to be placed, with <CODE>avail_out</CODE> indicating how
 538 much output space is available.  <CODE>BZ2_bzCompress</CODE> updates
 539 <CODE>next_out</CODE>, <CODE>avail_out</CODE> and <CODE>total_out</CODE> to reflect the
 540 number of bytes output.
 541 </P><P>
 542
 543 You may provide and remove as little or as much data as you like on each
 544 call of <CODE>BZ2_bzCompress</CODE>.  In the limit, it is acceptable to supply and
 545 remove data one byte at a time, although this would be terribly
 546 inefficient.  You should always ensure that at least one byte of output
 547 space is available at each call.
 548 </P><P>
 549
 550 A second purpose of <CODE>BZ2_bzCompress</CODE> is to request a change of mode of the
 551 compressed stream.
 552 </P><P>
 553
 554 Conceptually, a compressed stream can be in one of four states: IDLE,
 555 RUNNING, FLUSHING and FINISHING.  Before initialisation
 556 (<CODE>BZ2_bzCompressInit</CODE>) and after termination (<CODE>BZ2_bzCompressEnd</CODE>), a
 557 stream is regarded as IDLE.
 558 </P><P>
 559
 560 Upon initialisation (<CODE>BZ2_bzCompressInit</CODE>), the stream is placed in the
 561 RUNNING state.  Subsequent calls to <CODE>BZ2_bzCompress</CODE> should pass
 562 <CODE>BZ_RUN</CODE> as the requested action; other actions are illegal and
 563 will result in <CODE>BZ_SEQUENCE_ERROR</CODE>.
 564 </P><P>
 565
 566 At some point, the calling program will have provided all the input data
 567 it wants to.  It will then want to finish up -- in effect, asking the
 568 library to process any data it might have buffered internally.  In this
 569 state, <CODE>BZ2_bzCompress</CODE> will no longer attempt to read data from
 570 <CODE>next_in</CODE>, but it will want to write data to <CODE>next_out</CODE>.
 571 Because the output buffer supplied by the user can be arbitrarily small,
 572 the finishing-up operation cannot necessarily be done with a single call
 573 of <CODE>BZ2_bzCompress</CODE>.
 574 </P><P>
 575
 576 Instead, the calling program passes <CODE>BZ_FINISH</CODE> as an action to
 577 <CODE>BZ2_bzCompress</CODE>.  This changes the stream's state to FINISHING.  Any
 578 remaining input (ie, <CODE>next_in[0 .. avail_in-1]</CODE>) is compressed and
 579 transferred to the output buffer.  To do this, <CODE>BZ2_bzCompress</CODE> must be
 580 called repeatedly until all the output has been consumed.  At that
 581 point, <CODE>BZ2_bzCompress</CODE> returns <CODE>BZ_STREAM_END</CODE>, and the stream's
 582 state is set back to IDLE.  <CODE>BZ2_bzCompressEnd</CODE> should then be
 583 called.
 584 </P><P>
 585
 586 Just to make sure the calling program does not cheat, the library makes
 587 a note of <CODE>avail_in</CODE> at the time of the first call to
 588 <CODE>BZ2_bzCompress</CODE> which has <CODE>BZ_FINISH</CODE> as an action (ie, at the
 589 time the program has announced its intention to not supply any more
 590 input).  By comparing this value with that of <CODE>avail_in</CODE> over
 591 subsequent calls to <CODE>BZ2_bzCompress</CODE>, the library can detect any
 592 attempts to slip in more data to compress.  Any calls for which this is
 593 detected will return <CODE>BZ_SEQUENCE_ERROR</CODE>.  This indicates a
 594 programming mistake which should be corrected.
 595 </P><P>
 596
 597 Instead of asking to finish, the calling program may ask
 598 <CODE>BZ2_bzCompress</CODE> to take all the remaining input, compress it and
 599 terminate the current (Burrows-Wheeler) compression block.  This could
 600 be useful for error control purposes.  The mechanism is analogous to
 601 that for finishing: call <CODE>BZ2_bzCompress</CODE> with an action of
 602 <CODE>BZ_FLUSH</CODE>, remove output data, and persist with the
 603 <CODE>BZ_FLUSH</CODE> action until the value <CODE>BZ_RUN</CODE> is returned.  As
 604 with finishing, <CODE>BZ2_bzCompress</CODE> detects any attempt to provide more
 605 input data once the flush has begun.
 606 </P><P>
 607
 608 Once the flush is complete, the stream returns to the normal RUNNING
 609 state.
 610 </P><P>
 611
 612 This all sounds pretty complex, but isn't really.  Here's a table
 613 which shows which actions are allowable in each state, what action
 614 will be taken, what the next state is, and what the non-error return
 615 values are.  Note that you can't explicitly ask what state the
 616 stream is in, but nor do you need to -- it can be inferred from the
 617 values returned by <CODE>BZ2_bzCompress</CODE>.
 618 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">IDLE/<CODE>any</CODE>
 619       Illegal.  IDLE state only exists after <CODE>BZ2_bzCompressEnd</CODE> or
 620       before <CODE>BZ2_bzCompressInit</CODE>.
 621       Return value = <CODE>BZ_SEQUENCE_ERROR</CODE>
 622
 623 RUNNING/<CODE>BZ_RUN</CODE>
 624       Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible.
 625       Next state = RUNNING
 626       Return value = <CODE>BZ_RUN_OK</CODE>
 627
 628 RUNNING/<CODE>BZ_FLUSH</CODE>
 629       Remember current value of <CODE>next_in</CODE>.  Compress from <CODE>next_in</CODE>
 630       to <CODE>next_out</CODE> as much as possible, but do not accept any more input.
 631       Next state = FLUSHING
 632       Return value = <CODE>BZ_FLUSH_OK</CODE>
 633
 634 RUNNING/<CODE>BZ_FINISH</CODE>
 635       Remember current value of <CODE>next_in</CODE>.  Compress from <CODE>next_in</CODE>
 636       to <CODE>next_out</CODE> as much as possible, but do not accept any more input.
 637       Next state = FINISHING
 638       Return value = <CODE>BZ_FINISH_OK</CODE>
 639
 640 FLUSHING/<CODE>BZ_FLUSH</CODE>
 641       Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible,
 642       but do not accept any more input.
 643       If all the existing input has been used up and all compressed
 644       output has been removed
 645          Next state = RUNNING; Return value = <CODE>BZ_RUN_OK</CODE>
 646       else
 647          Next state = FLUSHING; Return value = <CODE>BZ_FLUSH_OK</CODE>
 648
 649 FLUSHING/other
 650       Illegal.
 651       Return value = <CODE>BZ_SEQUENCE_ERROR</CODE>
 652
 653 FINISHING/<CODE>BZ_FINISH</CODE>
 654       Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible,
 655       but to not accept any more input.
 656       If all the existing input has been used up and all compressed
 657       output has been removed
 658          Next state = IDLE; Return value = <CODE>BZ_STREAM_END</CODE>
 659       else
 660          Next state = FINISHING; Return value = <CODE>BZ_FINISHING</CODE>
 661
 662 FINISHING/other
 663       Illegal.
 664       Return value = <CODE>BZ_SEQUENCE_ERROR</CODE>
 665 </pre></td></tr></table></P><P>
 666
 667 That still looks complicated?  Well, fair enough.  The usual sequence
 668 of calls for compressing a load of data is:
 669 <UL>
 670 <LI>Get started with <CODE>BZ2_bzCompressInit</CODE>.
 671 <LI>Shovel data in and shlurp out its compressed form using zero or more
 672 calls of <CODE>BZ2_bzCompress</CODE> with action = <CODE>BZ_RUN</CODE>.
 673 <LI>Finish up.
 674 Repeatedly call <CODE>BZ2_bzCompress</CODE> with action = <CODE>BZ_FINISH</CODE>,
 675 copying out the compressed output, until <CODE>BZ_STREAM_END</CODE> is returned.
 676 <LI>Close up and go home.  Call <CODE>BZ2_bzCompressEnd</CODE>.
 677 </UL>
 678 If the data you want to compress fits into your input buffer all
 679 at once, you can skip the calls of <CODE>BZ2_bzCompress ( ..., BZ_RUN )</CODE> and
 680 just do the <CODE>BZ2_bzCompress ( ..., BZ_FINISH )</CODE> calls.
 681 <P>
 682
 683 All required memory is allocated by <CODE>BZ2_bzCompressInit</CODE>.  The
 684 compression library can accept any data at all (obviously).  So you
 685 shouldn't get any error return values from the <CODE>BZ2_bzCompress</CODE> calls.
 686 If you do, they will be <CODE>BZ_SEQUENCE_ERROR</CODE>, and indicate a bug in
 687 your programming.
 688 </P><P>
 689
 690 Trivial other possible return values:
 691 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_PARAM_ERROR</CODE>
 692          if <CODE>strm</CODE> is <CODE>NULL</CODE>, or <CODE>strm-&#62;s</CODE> is <CODE>NULL</CODE>
 693 </pre></td></tr></table></P><P>
 694
 695 <HR SIZE="6">
 696 <A NAME="SEC21"></A>
 697 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 698 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC20"> &lt; </A>]</TD>
 699 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC22"> &gt; </A>]</TD>
 700 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 701 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 702 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 703 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 704 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 705 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 706 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 707 </TR></TABLE>
 708 <H3> 3.3.3 <CODE>BZ2_bzCompressEnd</CODE> </H3>
 709 <!--docid::SEC21::-->
 710 <TABLE><tr><td>&nbsp;</td><td class=example><pre>int BZ2_bzCompressEnd ( bz_stream *strm );
 711 </pre></td></tr></table>Releases all memory associated with a compression stream.
 712 <P>
 713
 714 Possible return values:
 715 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">   <CODE>BZ_PARAM_ERROR</CODE>    if <CODE>strm</CODE> is <CODE>NULL</CODE> or <CODE>strm-&#62;s</CODE> is <CODE>NULL</CODE>
 716    <CODE>BZ_OK</CODE>    otherwise
 717 </pre></td></tr></table></P><P>
 718
 719 <HR SIZE="6">
 720 <A NAME="SEC22"></A>
 721 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 722 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC21"> &lt; </A>]</TD>
 723 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC23"> &gt; </A>]</TD>
 724 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 725 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 726 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 727 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 728 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 729 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 730 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 731 </TR></TABLE>
 732 <H3> 3.3.4 <CODE>BZ2_bzDecompressInit</CODE> </H3>
 733 <!--docid::SEC22::-->
 734 <TABLE><tr><td>&nbsp;</td><td class=example><pre>int BZ2_bzDecompressInit ( bz_stream *strm, int verbosity, int small );
 735 </pre></td></tr></table>Prepares for decompression.  As with <CODE>BZ2_bzCompressInit</CODE>, a
 736 <CODE>bz_stream</CODE> record should be allocated and initialised before the
 737 call.  Fields <CODE>bzalloc</CODE>, <CODE>bzfree</CODE> and <CODE>opaque</CODE> should be
 738 set if a custom memory allocator is required, or made <CODE>NULL</CODE> for
 739 the normal <CODE>malloc</CODE>/<CODE>free</CODE> routines.  Upon return, the internal
 740 state will have been initialised, and <CODE>total_in</CODE> and
 741 <CODE>total_out</CODE> will be zero.
 742 <P>
 743
 744 For the meaning of parameter <CODE>verbosity</CODE>, see <CODE>BZ2_bzCompressInit</CODE>.
 745 </P><P>
 746
 747 If <CODE>small</CODE> is nonzero, the library will use an alternative
 748 decompression algorithm which uses less memory but at the cost of
 749 decompressing more slowly (roughly speaking, half the speed, but the
 750 maximum memory requirement drops to around 2300k).  See Chapter 2 for
 751 more information on memory management.
 752 </P><P>
 753
 754 Note that the amount of memory needed to decompress
 755 a stream cannot be determined until the stream's header has been read,
 756 so even if <CODE>BZ2_bzDecompressInit</CODE> succeeds, a subsequent
 757 <CODE>BZ2_bzDecompress</CODE> could fail with <CODE>BZ_MEM_ERROR</CODE>.
 758 </P><P>
 759
 760 Possible return values:
 761 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_CONFIG_ERROR</CODE>
 762          if the library has been mis-compiled
 763       <CODE>BZ_PARAM_ERROR</CODE>
 764          if <CODE>(small != 0 &#38;&#38; small != 1)</CODE>
 765          or <CODE>(verbosity &#60; 0 || verbosity &#62; 4)</CODE>
 766       <CODE>BZ_MEM_ERROR</CODE>
 767          if insufficient memory is available
 768 </pre></td></tr></table></P><P>
 769
 770 Allowable next actions:
 771 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ2_bzDecompress</CODE>
 772          if <CODE>BZ_OK</CODE> was returned
 773       no specific action required in case of error
 774 </pre></td></tr></table></P><P>
 775
 776
 777 </P><P>
 778
 779 <HR SIZE="6">
 780 <A NAME="SEC23"></A>
 781 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 782 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC22"> &lt; </A>]</TD>
 783 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC24"> &gt; </A>]</TD>
 784 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 785 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 786 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 787 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 788 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 789 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 790 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 791 </TR></TABLE>
 792 <H3> 3.3.5 <CODE>BZ2_bzDecompress</CODE> </H3>
 793 <!--docid::SEC23::-->
 794 <TABLE><tr><td>&nbsp;</td><td class=example><pre>int BZ2_bzDecompress ( bz_stream *strm );
 795 </pre></td></tr></table>Provides more input and/out output buffer space for the library.  The
 796 caller maintains input and output buffers, and uses <CODE>BZ2_bzDecompress</CODE>
 797 to transfer data between them.
 798 <P>
 799
 800 Before each call to <CODE>BZ2_bzDecompress</CODE>, <CODE>next_in</CODE>
 801 should point at the compressed data,
 802 and <CODE>avail_in</CODE> should indicate how many bytes the library
 803 may read.  <CODE>BZ2_bzDecompress</CODE> updates <CODE>next_in</CODE>, <CODE>avail_in</CODE>
 804 and <CODE>total_in</CODE>
 805 to reflect the number of bytes it has read.
 806 </P><P>
 807
 808 Similarly, <CODE>next_out</CODE> should point to a buffer in which the uncompressed
 809 output is to be placed, with <CODE>avail_out</CODE> indicating how much output space
 810 is available.  <CODE>BZ2_bzCompress</CODE> updates <CODE>next_out</CODE>,
 811 <CODE>avail_out</CODE> and <CODE>total_out</CODE> to reflect
 812 the number of bytes output.
 813 </P><P>
 814
 815 You may provide and remove as little or as much data as you like on
 816 each call of <CODE>BZ2_bzDecompress</CODE>.
 817 In the limit, it is acceptable to
 818 supply and remove data one byte at a time, although this would be
 819 terribly inefficient.  You should always ensure that at least one
 820 byte of output space is available at each call.
 821 </P><P>
 822
 823 Use of <CODE>BZ2_bzDecompress</CODE> is simpler than <CODE>BZ2_bzCompress</CODE>.
 824 </P><P>
 825
 826 You should provide input and remove output as described above, and
 827 repeatedly call <CODE>BZ2_bzDecompress</CODE> until <CODE>BZ_STREAM_END</CODE> is
 828 returned.  Appearance of <CODE>BZ_STREAM_END</CODE> denotes that
 829 <CODE>BZ2_bzDecompress</CODE> has detected the logical end of the compressed
 830 stream.  <CODE>BZ2_bzDecompress</CODE> will not produce <CODE>BZ_STREAM_END</CODE> until
 831 all output data has been placed into the output buffer, so once
 832 <CODE>BZ_STREAM_END</CODE> appears, you are guaranteed to have available all
 833 the decompressed output, and <CODE>BZ2_bzDecompressEnd</CODE> can safely be
 834 called.
 835 </P><P>
 836
 837 If case of an error return value, you should call <CODE>BZ2_bzDecompressEnd</CODE>
 838 to clean up and release memory.
 839 </P><P>
 840
 841 Possible return values:
 842 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_PARAM_ERROR</CODE>
 843          if <CODE>strm</CODE> is <CODE>NULL</CODE> or <CODE>strm-&#62;s</CODE> is <CODE>NULL</CODE>
 844          or <CODE>strm-&#62;avail_out &#60; 1</CODE>
 845       <CODE>BZ_DATA_ERROR</CODE>
 846          if a data integrity error is detected in the compressed stream
 847       <CODE>BZ_DATA_ERROR_MAGIC</CODE>
 848          if the compressed stream doesn't begin with the right magic bytes
 849       <CODE>BZ_MEM_ERROR</CODE>
 850          if there wasn't enough memory available
 851       <CODE>BZ_STREAM_END</CODE>
 852          if the logical end of the data stream was detected and all
 853          output in has been consumed, eg <CODE>s-&#62;avail_out &#62; 0</CODE>
 854       <CODE>BZ_OK</CODE>
 855          otherwise
 856 </pre></td></tr></table>Allowable next actions:
 857 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ2_bzDecompress</CODE>
 858          if <CODE>BZ_OK</CODE> was returned
 859       <CODE>BZ2_bzDecompressEnd</CODE>
 860          otherwise
 861 </pre></td></tr></table></P><P>
 862
 863 <HR SIZE="6">
 864 <A NAME="SEC24"></A>
 865 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 866 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC23"> &lt; </A>]</TD>
 867 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC25"> &gt; </A>]</TD>
 868 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 869 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 870 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 871 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 872 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 873 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 874 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 875 </TR></TABLE>
 876 <H3> 3.3.6 <CODE>BZ2_bzDecompressEnd</CODE> </H3>
 877 <!--docid::SEC24::-->
 878 <TABLE><tr><td>&nbsp;</td><td class=example><pre>int BZ2_bzDecompressEnd ( bz_stream *strm );
 879 </pre></td></tr></table>Releases all memory associated with a decompression stream.
 880 <P>
 881
 882 Possible return values:
 883 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_PARAM_ERROR</CODE>
 884          if <CODE>strm</CODE> is <CODE>NULL</CODE> or <CODE>strm-&#62;s</CODE> is <CODE>NULL</CODE>
 885       <CODE>BZ_OK</CODE>
 886          otherwise
 887 </pre></td></tr></table></P><P>
 888
 889 Allowable next actions:
 890 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      None.
 891 </pre></td></tr></table></P><P>
 892
 893 <HR SIZE="6">
 894 <A NAME="SEC25"></A>
 895 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 896 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC24"> &lt; </A>]</TD>
 897 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC26"> &gt; </A>]</TD>
 898 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 899 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 900 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 901 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 902 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 903 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 904 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 905 </TR></TABLE>
 906 <H2> 3.4 High-level interface </H2>
 907 <!--docid::SEC25::-->
 908 <P>
 909
 910 This interface provides functions for reading and writing
 911 <CODE>bzip2</CODE> format files.  First, some general points.
 912 </P><P>
 913
 914 <UL>
 915 <LI>All of the functions take an <CODE>int*</CODE> first argument,
 916   <CODE>bzerror</CODE>.
 917   After each call, <CODE>bzerror</CODE> should be consulted first to determine
 918   the outcome of the call.  If <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>,
 919   the call completed
 920   successfully, and only then should the return value of the function
 921   (if any) be consulted.  If <CODE>bzerror</CODE> is <CODE>BZ_IO_ERROR</CODE>,
 922   there was an error
 923   reading/writing the underlying compressed file, and you should
 924   then consult <CODE>errno</CODE>/<CODE>perror</CODE> to determine the
 925   cause of the difficulty.
 926   <CODE>bzerror</CODE> may also be set to various other values; precise details are
 927   given on a per-function basis below.
 928 <LI>If <CODE>bzerror</CODE> indicates an error
 929   (ie, anything except <CODE>BZ_OK</CODE> and <CODE>BZ_STREAM_END</CODE>),
 930   you should immediately call <CODE>BZ2_bzReadClose</CODE> (or <CODE>BZ2_bzWriteClose</CODE>,
 931   depending on whether you are attempting to read or to write)
 932   to free up all resources associated
 933   with the stream.  Once an error has been indicated, behaviour of all calls
 934   except <CODE>BZ2_bzReadClose</CODE> (<CODE>BZ2_bzWriteClose</CODE>) is undefined.
 935   The implication is that (1) <CODE>bzerror</CODE> should
 936   be checked after each call, and (2) if <CODE>bzerror</CODE> indicates an error,
 937   <CODE>BZ2_bzReadClose</CODE> (<CODE>BZ2_bzWriteClose</CODE>) should then be called to clean up.
 938 <LI>The <CODE>FILE*</CODE> arguments passed to
 939    <CODE>BZ2_bzReadOpen</CODE>/<CODE>BZ2_bzWriteOpen</CODE>
 940   should be set to binary mode.
 941   Most Unix systems will do this by default, but other platforms,
 942   including Windows and Mac, will not.  If you omit this, you may
 943   encounter problems when moving code to new platforms.
 944 <LI>Memory allocation requests are handled by
 945   <CODE>malloc</CODE>/<CODE>free</CODE>.
 946   At present
 947   there is no facility for user-defined memory allocators in the file I/O
 948   functions (could easily be added, though).
 949 </UL>
 950 <P>
 951
 952 <HR SIZE="6">
 953 <A NAME="SEC26"></A>
 954 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
 955 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC25"> &lt; </A>]</TD>
 956 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC27"> &gt; </A>]</TD>
 957 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
 958 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
 959 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
 960 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
 961 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
 962 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
 963 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
 964 </TR></TABLE>
 965 <H3> 3.4.1 <CODE>BZ2_bzReadOpen</CODE> </H3>
 966 <!--docid::SEC26::-->
 967 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   typedef void BZFILE;
 968
 969    BZFILE *BZ2_bzReadOpen ( int *bzerror, FILE *f,
 970                             int small, int verbosity,
 971                             void *unused, int nUnused );
 972 </pre></td></tr></table>Prepare to read compressed data from file handle <CODE>f</CODE>.  <CODE>f</CODE>
 973 should refer to a file which has been opened for reading, and for which
 974 the error indicator (<CODE>ferror(f)</CODE>)is not set.  If <CODE>small</CODE> is 1,
 975 the library will try to decompress using less memory, at the expense of
 976 speed.
 977 <P>
 978
 979 For reasons explained below, <CODE>BZ2_bzRead</CODE> will decompress the
 980 <CODE>nUnused</CODE> bytes starting at <CODE>unused</CODE>, before starting to read
 981 from the file <CODE>f</CODE>.  At most <CODE>BZ_MAX_UNUSED</CODE> bytes may be
 982 supplied like this.  If this facility is not required, you should pass
 983 <CODE>NULL</CODE> and <CODE>0</CODE> for <CODE>unused</CODE> and n<CODE>Unused</CODE>
 984 respectively.
 985 </P><P>
 986
 987 For the meaning of parameters <CODE>small</CODE> and <CODE>verbosity</CODE>,
 988 see <CODE>BZ2_bzDecompressInit</CODE>.
 989 </P><P>
 990
 991 The amount of memory needed to decompress a file cannot be determined
 992 until the file's header has been read.  So it is possible that
 993 <CODE>BZ2_bzReadOpen</CODE> returns <CODE>BZ_OK</CODE> but a subsequent call of
 994 <CODE>BZ2_bzRead</CODE> will return <CODE>BZ_MEM_ERROR</CODE>.
 995 </P><P>
 996
 997 Possible assignments to <CODE>bzerror</CODE>:
 998 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_CONFIG_ERROR</CODE>
 999          if the library has been mis-compiled
1000       <CODE>BZ_PARAM_ERROR</CODE>
1001          if <CODE>f</CODE> is <CODE>NULL</CODE>
1002          or <CODE>small</CODE> is neither <CODE>0</CODE> nor <CODE>1</CODE>
1003          or <CODE>(unused == NULL &#38;&#38; nUnused != 0)</CODE>
1004          or <CODE>(unused != NULL &#38;&#38; !(0 &#60;= nUnused &#60;= BZ_MAX_UNUSED))</CODE>
1005       <CODE>BZ_IO_ERROR</CODE>
1006          if <CODE>ferror(f)</CODE> is nonzero
1007       <CODE>BZ_MEM_ERROR</CODE>
1008          if insufficient memory is available
1009       <CODE>BZ_OK</CODE>
1010          otherwise.
1011 </pre></td></tr></table></P><P>
1012
1013 Possible return values:
1014 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      Pointer to an abstract <CODE>BZFILE</CODE>
1015          if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>
1016       <CODE>NULL</CODE>
1017          otherwise
1018 </pre></td></tr></table></P><P>
1019
1020 Allowable next actions:
1021 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ2_bzRead</CODE>
1022          if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>
1023       <CODE>BZ2_bzClose</CODE>
1024          otherwise
1025 </pre></td></tr></table></P><P>
1026
1027 <HR SIZE="6">
1028 <A NAME="SEC27"></A>
1029 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1030 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC26"> &lt; </A>]</TD>
1031 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC28"> &gt; </A>]</TD>
1032 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1033 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1034 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1035 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1036 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1037 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1038 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1039 </TR></TABLE>
1040 <H3> 3.4.2 <CODE>BZ2_bzRead</CODE> </H3>
1041 <!--docid::SEC27::-->
1042 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   int BZ2_bzRead ( int *bzerror, BZFILE *b, void *buf, int len );
1043 </pre></td></tr></table>Reads up to <CODE>len</CODE> (uncompressed) bytes from the compressed file
1044 <CODE>b</CODE> into
1045 the buffer <CODE>buf</CODE>.  If the read was successful,
1046 <CODE>bzerror</CODE> is set to <CODE>BZ_OK</CODE>
1047 and the number of bytes read is returned.  If the logical end-of-stream
1048 was detected, <CODE>bzerror</CODE> will be set to <CODE>BZ_STREAM_END</CODE>,
1049 and the number
1050 of bytes read is returned.  All other <CODE>bzerror</CODE> values denote an error.
1051 <P>
1052
1053 <CODE>BZ2_bzRead</CODE> will supply <CODE>len</CODE> bytes,
1054 unless the logical stream end is detected
1055 or an error occurs.  Because of this, it is possible to detect the
1056 stream end by observing when the number of bytes returned is
1057 less than the number
1058 requested.  Nevertheless, this is regarded as inadvisable; you should
1059 instead check <CODE>bzerror</CODE> after every call and watch out for
1060 <CODE>BZ_STREAM_END</CODE>.
1061 </P><P>
1062
1063 Internally, <CODE>BZ2_bzRead</CODE> copies data from the compressed file in chunks
1064 of size <CODE>BZ_MAX_UNUSED</CODE> bytes
1065 before decompressing it.  If the file contains more bytes than strictly
1066 needed to reach the logical end-of-stream, <CODE>BZ2_bzRead</CODE> will almost certainly
1067 read some of the trailing data before signalling <CODE>BZ_SEQUENCE_END</CODE>.
1068 To collect the read but unused data once <CODE>BZ_SEQUENCE_END</CODE> has
1069 appeared, call <CODE>BZ2_bzReadGetUnused</CODE> immediately before <CODE>BZ2_bzReadClose</CODE>.
1070 </P><P>
1071
1072 Possible assignments to <CODE>bzerror</CODE>:
1073 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_PARAM_ERROR</CODE>
1074          if <CODE>b</CODE> is <CODE>NULL</CODE> or <CODE>buf</CODE> is <CODE>NULL</CODE> or <CODE>len &#60; 0</CODE>
1075       <CODE>BZ_SEQUENCE_ERROR</CODE>
1076          if <CODE>b</CODE> was opened with <CODE>BZ2_bzWriteOpen</CODE>
1077       <CODE>BZ_IO_ERROR</CODE>
1078          if there is an error reading from the compressed file
1079       <CODE>BZ_UNEXPECTED_EOF</CODE>
1080          if the compressed file ended before the logical end-of-stream was detected
1081       <CODE>BZ_DATA_ERROR</CODE>
1082          if a data integrity error was detected in the compressed stream
1083       <CODE>BZ_DATA_ERROR_MAGIC</CODE>
1084          if the stream does not begin with the requisite header bytes (ie, is not
1085          a <CODE>bzip2</CODE> data file).  This is really a special case of <CODE>BZ_DATA_ERROR</CODE>.
1086       <CODE>BZ_MEM_ERROR</CODE>
1087          if insufficient memory was available
1088       <CODE>BZ_STREAM_END</CODE>
1089          if the logical end of stream was detected.
1090       <CODE>BZ_OK</CODE>
1091          otherwise.
1092 </pre></td></tr></table></P><P>
1093
1094 Possible return values:
1095 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      number of bytes read
1096          if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE> or <CODE>BZ_STREAM_END</CODE>
1097       undefined
1098          otherwise
1099 </pre></td></tr></table></P><P>
1100
1101 Allowable next actions:
1102 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      collect data from <CODE>buf</CODE>, then <CODE>BZ2_bzRead</CODE> or <CODE>BZ2_bzReadClose</CODE>
1103          if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>
1104       collect data from <CODE>buf</CODE>, then <CODE>BZ2_bzReadClose</CODE> or <CODE>BZ2_bzReadGetUnused</CODE>
1105          if <CODE>bzerror</CODE> is <CODE>BZ_SEQUENCE_END</CODE>
1106       <CODE>BZ2_bzReadClose</CODE>
1107          otherwise
1108 </pre></td></tr></table></P><P>
1109
1110 <HR SIZE="6">
1111 <A NAME="SEC28"></A>
1112 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1113 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC27"> &lt; </A>]</TD>
1114 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC29"> &gt; </A>]</TD>
1115 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1116 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1117 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1118 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1119 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1120 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1121 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1122 </TR></TABLE>
1123 <H3> 3.4.3 <CODE>BZ2_bzReadGetUnused</CODE> </H3>
1124 <!--docid::SEC28::-->
1125 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   void BZ2_bzReadGetUnused ( int* bzerror, BZFILE *b,
1126                               void** unused, int* nUnused );
1127 </pre></td></tr></table>Returns data which was read from the compressed file but was not needed
1128 to get to the logical end-of-stream.  <CODE>*unused</CODE> is set to the address
1129 of the data, and <CODE>*nUnused</CODE> to the number of bytes.  <CODE>*nUnused</CODE> will
1130 be set to a value between <CODE>0</CODE> and <CODE>BZ_MAX_UNUSED</CODE> inclusive.
1131 <P>
1132
1133 This function may only be called once <CODE>BZ2_bzRead</CODE> has signalled
1134 <CODE>BZ_STREAM_END</CODE> but before <CODE>BZ2_bzReadClose</CODE>.
1135 </P><P>
1136
1137 Possible assignments to <CODE>bzerror</CODE>:
1138 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_PARAM_ERROR</CODE>
1139          if <CODE>b</CODE> is <CODE>NULL</CODE>
1140          or <CODE>unused</CODE> is <CODE>NULL</CODE> or <CODE>nUnused</CODE> is <CODE>NULL</CODE>
1141       <CODE>BZ_SEQUENCE_ERROR</CODE>
1142          if <CODE>BZ_STREAM_END</CODE> has not been signalled
1143          or if <CODE>b</CODE> was opened with <CODE>BZ2_bzWriteOpen</CODE>
1144      <CODE>BZ_OK</CODE>
1145          otherwise
1146 </pre></td></tr></table></P><P>
1147
1148 Allowable next actions:
1149 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ2_bzReadClose</CODE>
1150 </pre></td></tr></table></P><P>
1151
1152 <HR SIZE="6">
1153 <A NAME="SEC29"></A>
1154 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1155 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC28"> &lt; </A>]</TD>
1156 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC30"> &gt; </A>]</TD>
1157 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1158 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1159 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1160 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1161 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1162 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1163 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1164 </TR></TABLE>
1165 <H3> 3.4.4 <CODE>BZ2_bzReadClose</CODE> </H3>
1166 <!--docid::SEC29::-->
1167 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   void BZ2_bzReadClose ( int *bzerror, BZFILE *b );
1168 </pre></td></tr></table>Releases all memory pertaining to the compressed file <CODE>b</CODE>.
1169 <CODE>BZ2_bzReadClose</CODE> does not call <CODE>fclose</CODE> on the underlying file
1170 handle, so you should do that yourself if appropriate.
1171 <CODE>BZ2_bzReadClose</CODE> should be called to clean up after all error
1172 situations.
1173 <P>
1174
1175 Possible assignments to <CODE>bzerror</CODE>:
1176 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_SEQUENCE_ERROR</CODE>
1177          if <CODE>b</CODE> was opened with <CODE>BZ2_bzOpenWrite</CODE>
1178       <CODE>BZ_OK</CODE>
1179          otherwise
1180 </pre></td></tr></table></P><P>
1181
1182 Allowable next actions:
1183 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      none
1184 </pre></td></tr></table></P><P>
1185
1186 <HR SIZE="6">
1187 <A NAME="SEC30"></A>
1188 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1189 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC29"> &lt; </A>]</TD>
1190 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC31"> &gt; </A>]</TD>
1191 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1192 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1193 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1194 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1195 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1196 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1197 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1198 </TR></TABLE>
1199 <H3> 3.4.5 <CODE>BZ2_bzWriteOpen</CODE> </H3>
1200 <!--docid::SEC30::-->
1201 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   BZFILE *BZ2_bzWriteOpen ( int *bzerror, FILE *f,
1202                              int blockSize100k, int verbosity,
1203                              int workFactor );
1204 </pre></td></tr></table>Prepare to write compressed data to file handle <CODE>f</CODE>.
1205 <CODE>f</CODE> should refer to
1206 a file which has been opened for writing, and for which the error
1207 indicator (<CODE>ferror(f)</CODE>)is not set.
1208 <P>
1209
1210 For the meaning of parameters <CODE>blockSize100k</CODE>,
1211 <CODE>verbosity</CODE> and <CODE>workFactor</CODE>, see
1212 <BR> <CODE>BZ2_bzCompressInit</CODE>.
1213 </P><P>
1214
1215 All required memory is allocated at this stage, so if the call
1216 completes successfully, <CODE>BZ_MEM_ERROR</CODE> cannot be signalled by a
1217 subsequent call to <CODE>BZ2_bzWrite</CODE>.
1218 </P><P>
1219
1220 Possible assignments to <CODE>bzerror</CODE>:
1221 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_CONFIG_ERROR</CODE>
1222          if the library has been mis-compiled
1223       <CODE>BZ_PARAM_ERROR</CODE>
1224          if <CODE>f</CODE> is <CODE>NULL</CODE>
1225          or <CODE>blockSize100k &#60; 1</CODE> or <CODE>blockSize100k &#62; 9</CODE>
1226       <CODE>BZ_IO_ERROR</CODE>
1227          if <CODE>ferror(f)</CODE> is nonzero
1228       <CODE>BZ_MEM_ERROR</CODE>
1229          if insufficient memory is available
1230       <CODE>BZ_OK</CODE>
1231          otherwise
1232 </pre></td></tr></table></P><P>
1233
1234 Possible return values:
1235 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      Pointer to an abstract <CODE>BZFILE</CODE>
1236          if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>
1237       <CODE>NULL</CODE>
1238          otherwise
1239 </pre></td></tr></table></P><P>
1240
1241 Allowable next actions:
1242 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ2_bzWrite</CODE>
1243          if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>
1244          (you could go directly to <CODE>BZ2_bzWriteClose</CODE>, but this would be pretty pointless)
1245       <CODE>BZ2_bzWriteClose</CODE>
1246          otherwise
1247 </pre></td></tr></table></P><P>
1248
1249 <HR SIZE="6">
1250 <A NAME="SEC31"></A>
1251 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1252 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC30"> &lt; </A>]</TD>
1253 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC32"> &gt; </A>]</TD>
1254 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1255 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1256 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1257 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1258 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1259 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1260 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1261 </TR></TABLE>
1262 <H3> 3.4.6 <CODE>BZ2_bzWrite</CODE> </H3>
1263 <!--docid::SEC31::-->
1264 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   void BZ2_bzWrite ( int *bzerror, BZFILE *b, void *buf, int len );
1265 </pre></td></tr></table>Absorbs <CODE>len</CODE> bytes from the buffer <CODE>buf</CODE>, eventually to be
1266 compressed and written to the file.
1267 <P>
1268
1269 Possible assignments to <CODE>bzerror</CODE>:
1270 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_PARAM_ERROR</CODE>
1271          if <CODE>b</CODE> is <CODE>NULL</CODE> or <CODE>buf</CODE> is <CODE>NULL</CODE> or <CODE>len &#60; 0</CODE>
1272       <CODE>BZ_SEQUENCE_ERROR</CODE>
1273          if b was opened with <CODE>BZ2_bzReadOpen</CODE>
1274       <CODE>BZ_IO_ERROR</CODE>
1275          if there is an error writing the compressed file.
1276       <CODE>BZ_OK</CODE>
1277          otherwise
1278 </pre></td></tr></table></P><P>
1279
1280 <HR SIZE="6">
1281 <A NAME="SEC32"></A>
1282 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1283 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC31"> &lt; </A>]</TD>
1284 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC33"> &gt; </A>]</TD>
1285 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1286 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1287 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1288 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1289 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1290 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1291 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1292 </TR></TABLE>
1293 <H3> 3.4.7 <CODE>BZ2_bzWriteClose</CODE> </H3>
1294 <!--docid::SEC32::-->
1295 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   void BZ2_bzWriteClose ( int *bzerror, BZFILE* f,
1296                            int abandon,
1297                            unsigned int* nbytes_in,
1298                            unsigned int* nbytes_out );
1299
1300    void BZ2_bzWriteClose64 ( int *bzerror, BZFILE* f,
1301                              int abandon,
1302                              unsigned int* nbytes_in_lo32,
1303                              unsigned int* nbytes_in_hi32,
1304                              unsigned int* nbytes_out_lo32,
1305                              unsigned int* nbytes_out_hi32 );
1306 </pre></td></tr></table><P>
1307
1308 Compresses and flushes to the compressed file all data so far supplied
1309 by <CODE>BZ2_bzWrite</CODE>.  The logical end-of-stream markers are also written, so
1310 subsequent calls to <CODE>BZ2_bzWrite</CODE> are illegal.  All memory associated
1311 with the compressed file <CODE>b</CODE> is released.
1312 <CODE>fflush</CODE> is called on the
1313 compressed file, but it is not <CODE>fclose</CODE>'d.
1314 </P><P>
1315
1316 If <CODE>BZ2_bzWriteClose</CODE> is called to clean up after an error, the only
1317 action is to release the memory.  The library records the error codes
1318 issued by previous calls, so this situation will be detected
1319 automatically.  There is no attempt to complete the compression
1320 operation, nor to <CODE>fflush</CODE> the compressed file.  You can force this
1321 behaviour to happen even in the case of no error, by passing a nonzero
1322 value to <CODE>abandon</CODE>.
1323 </P><P>
1324
1325 If <CODE>nbytes_in</CODE> is non-null, <CODE>*nbytes_in</CODE> will be set to be the
1326 total volume of uncompressed data handled.  Similarly, <CODE>nbytes_out</CODE>
1327 will be set to the total volume of compressed data written.  For
1328 compatibility with older versions of the library, <CODE>BZ2_bzWriteClose</CODE>
1329 only yields the lower 32 bits of these counts.  Use
1330 <CODE>BZ2_bzWriteClose64</CODE> if you want the full 64 bit counts.  These
1331 two functions are otherwise absolutely identical.
1332 </P><P>
1333
1334 Possible assignments to <CODE>bzerror</CODE>:
1335 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_SEQUENCE_ERROR</CODE>
1336          if <CODE>b</CODE> was opened with <CODE>BZ2_bzReadOpen</CODE>
1337       <CODE>BZ_IO_ERROR</CODE>
1338          if there is an error writing the compressed file
1339       <CODE>BZ_OK</CODE>
1340          otherwise
1341 </pre></td></tr></table></P><P>
1342
1343 <HR SIZE="6">
1344 <A NAME="SEC33"></A>
1345 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1346 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC32"> &lt; </A>]</TD>
1347 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC34"> &gt; </A>]</TD>
1348 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1349 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1350 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1351 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1352 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1353 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1354 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1355 </TR></TABLE>
1356 <H3> 3.4.8 Handling embedded compressed data streams </H3>
1357 <!--docid::SEC33::-->
1358 <P>
1359
1360 The high-level library facilitates use of
1361 <CODE>bzip2</CODE> data streams which form some part of a surrounding, larger
1362 data stream.
1363 <UL>
1364 <LI>For writing, the library takes an open file handle, writes
1365 compressed data to it, <CODE>fflush</CODE>es it but does not <CODE>fclose</CODE> it.
1366 The calling application can write its own data before and after the
1367 compressed data stream, using that same file handle.
1368 <LI>Reading is more complex, and the facilities are not as general
1369 as they could be since generality is hard to reconcile with efficiency.
1370 <CODE>BZ2_bzRead</CODE> reads from the compressed file in blocks of size
1371 <CODE>BZ_MAX_UNUSED</CODE> bytes, and in doing so probably will overshoot
1372 the logical end of compressed stream.
1373 To recover this data once decompression has
1374 ended, call <CODE>BZ2_bzReadGetUnused</CODE> after the last call of <CODE>BZ2_bzRead</CODE>
1375 (the one returning <CODE>BZ_STREAM_END</CODE>) but before calling
1376 <CODE>BZ2_bzReadClose</CODE>.
1377 </UL>
1378 <P>
1379
1380 This mechanism makes it easy to decompress multiple <CODE>bzip2</CODE>
1381 streams placed end-to-end.  As the end of one stream, when <CODE>BZ2_bzRead</CODE>
1382 returns <CODE>BZ_STREAM_END</CODE>, call <CODE>BZ2_bzReadGetUnused</CODE> to collect the
1383 unused data (copy it into your own buffer somewhere).
1384 That data forms the start of the next compressed stream.
1385 To start uncompressing that next stream, call <CODE>BZ2_bzReadOpen</CODE> again,
1386 feeding in the unused data via the <CODE>unused</CODE>/<CODE>nUnused</CODE>
1387 parameters.
1388 Keep doing this until <CODE>BZ_STREAM_END</CODE> return coincides with the
1389 physical end of file (<CODE>feof(f)</CODE>).  In this situation
1390 <CODE>BZ2_bzReadGetUnused</CODE>
1391 will of course return no data.
1392 </P><P>
1393
1394 This should give some feel for how the high-level interface can be used.
1395 If you require extra flexibility, you'll have to bite the bullet and get
1396 to grips with the low-level interface.
1397 </P><P>
1398
1399 <HR SIZE="6">
1400 <A NAME="SEC34"></A>
1401 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1402 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC33"> &lt; </A>]</TD>
1403 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC35"> &gt; </A>]</TD>
1404 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1405 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1406 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1407 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1408 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1409 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1410 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1411 </TR></TABLE>
1412 <H3> 3.4.9 Standard file-reading/writing code </H3>
1413 <!--docid::SEC34::-->
1414 Here's how you'd write data to a compressed file:
1415 <TABLE><tr><td>&nbsp;</td><td class=example><pre>FILE*   f;
1416 BZFILE* b;
1417 int     nBuf;
1418 char    buf[ /* whatever size you like */ ];
1419 int     bzerror;
1420 int     nWritten;
1421
1422 f = fopen ( "myfile.bz2", "w" );
1423 if (!f) {
1424    /* handle error */
1425 }
1426 b = BZ2_bzWriteOpen ( &#38;bzerror, f, 9 );
1427 if (bzerror != BZ_OK) {
1428    BZ2_bzWriteClose ( b );
1429    /* handle error */
1430 }
1431
1432 while ( /* condition */ ) {
1433    /* get data to write into buf, and set nBuf appropriately */
1434    nWritten = BZ2_bzWrite ( &#38;bzerror, b, buf, nBuf );
1435    if (bzerror == BZ_IO_ERROR) {
1436       BZ2_bzWriteClose ( &#38;bzerror, b );
1437       /* handle error */
1438    }
1439 }
1440
1441 BZ2_bzWriteClose ( &#38;bzerror, b );
1442 if (bzerror == BZ_IO_ERROR) {
1443    /* handle error */
1444 }
1445 </pre></td></tr></table>And to read from a compressed file:
1446 <TABLE><tr><td>&nbsp;</td><td class=example><pre>FILE*   f;
1447 BZFILE* b;
1448 int     nBuf;
1449 char    buf[ /* whatever size you like */ ];
1450 int     bzerror;
1451 int     nWritten;
1452
1453 f = fopen ( "myfile.bz2", "r" );
1454 if (!f) {
1455    /* handle error */
1456 }
1457 b = BZ2_bzReadOpen ( &#38;bzerror, f, 0, NULL, 0 );
1458 if (bzerror != BZ_OK) {
1459    BZ2_bzReadClose ( &#38;bzerror, b );
1460    /* handle error */
1461 }
1462
1463 bzerror = BZ_OK;
1464 while (bzerror == BZ_OK &#38;&#38; /* arbitrary other conditions */) {
1465    nBuf = BZ2_bzRead ( &#38;bzerror, b, buf, /* size of buf */ );
1466    if (bzerror == BZ_OK) {
1467       /* do something with buf[0 .. nBuf-1] */
1468    }
1469 }
1470 if (bzerror != BZ_STREAM_END) {
1471    BZ2_bzReadClose ( &#38;bzerror, b );
1472    /* handle error */
1473 } else {
1474    BZ2_bzReadClose ( &#38;bzerror );
1475 }
1476 </pre></td></tr></table><P>
1477
1478 <HR SIZE="6">
1479 <A NAME="SEC35"></A>
1480 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1481 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC34"> &lt; </A>]</TD>
1482 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC36"> &gt; </A>]</TD>
1483 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1484 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1485 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1486 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1487 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1488 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1489 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1490 </TR></TABLE>
1491 <H2> 3.5 Utility functions </H2>
1492 <!--docid::SEC35::-->
1493 <HR SIZE="6">
1494 <A NAME="SEC36"></A>
1495 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1496 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC35"> &lt; </A>]</TD>
1497 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC37"> &gt; </A>]</TD>
1498 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1499 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1500 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1501 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1502 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1503 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1504 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1505 </TR></TABLE>
1506 <H3> 3.5.1 <CODE>BZ2_bzBuffToBuffCompress</CODE> </H3>
1507 <!--docid::SEC36::-->
1508 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   int BZ2_bzBuffToBuffCompress( char*         dest,
1509                                  unsigned int* destLen,
1510                                  char*         source,
1511                                  unsigned int  sourceLen,
1512                                  int           blockSize100k,
1513                                  int           verbosity,
1514                                  int           workFactor );
1515 </pre></td></tr></table>Attempts to compress the data in <CODE>source[0 .. sourceLen-1]</CODE>
1516 into the destination buffer, <CODE>dest[0 .. *destLen-1]</CODE>.
1517 If the destination buffer is big enough, <CODE>*destLen</CODE> is
1518 set to the size of the compressed data, and <CODE>BZ_OK</CODE> is
1519 returned.  If the compressed data won't fit, <CODE>*destLen</CODE>
1520 is unchanged, and <CODE>BZ_OUTBUFF_FULL</CODE> is returned.
1521 <P>
1522
1523 Compression in this manner is a one-shot event, done with a single call
1524 to this function.  The resulting compressed data is a complete
1525 <CODE>bzip2</CODE> format data stream.  There is no mechanism for making
1526 additional calls to provide extra input data.  If you want that kind of
1527 mechanism, use the low-level interface.
1528 </P><P>
1529
1530 For the meaning of parameters <CODE>blockSize100k</CODE>, <CODE>verbosity</CODE>
1531 and <CODE>workFactor</CODE>, <BR> see <CODE>BZ2_bzCompressInit</CODE>.
1532 </P><P>
1533
1534 To guarantee that the compressed data will fit in its buffer, allocate
1535 an output buffer of size 1% larger than the uncompressed data, plus
1536 six hundred extra bytes.
1537 </P><P>
1538
1539 <CODE>BZ2_bzBuffToBuffDecompress</CODE> will not write data at or
1540 beyond <CODE>dest[*destLen]</CODE>, even in case of buffer overflow.
1541 </P><P>
1542
1543 Possible return values:
1544 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_CONFIG_ERROR</CODE>
1545          if the library has been mis-compiled
1546       <CODE>BZ_PARAM_ERROR</CODE>
1547          if <CODE>dest</CODE> is <CODE>NULL</CODE> or <CODE>destLen</CODE> is <CODE>NULL</CODE>
1548          or <CODE>blockSize100k &#60; 1</CODE> or <CODE>blockSize100k &#62; 9</CODE>
1549          or <CODE>verbosity &#60; 0</CODE> or <CODE>verbosity &#62; 4</CODE>
1550          or <CODE>workFactor &#60; 0</CODE> or <CODE>workFactor &#62; 250</CODE>
1551       <CODE>BZ_MEM_ERROR</CODE>
1552          if insufficient memory is available
1553       <CODE>BZ_OUTBUFF_FULL</CODE>
1554          if the size of the compressed data exceeds <CODE>*destLen</CODE>
1555       <CODE>BZ_OK</CODE>
1556          otherwise
1557 </pre></td></tr></table></P><P>
1558
1559 <HR SIZE="6">
1560 <A NAME="SEC37"></A>
1561 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1562 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC36"> &lt; </A>]</TD>
1563 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC38"> &gt; </A>]</TD>
1564 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1565 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1566 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1567 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1568 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1569 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1570 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1571 </TR></TABLE>
1572 <H3> 3.5.2 <CODE>BZ2_bzBuffToBuffDecompress</CODE> </H3>
1573 <!--docid::SEC37::-->
1574 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   int BZ2_bzBuffToBuffDecompress ( char*         dest,
1575                                     unsigned int* destLen,
1576                                     char*         source,
1577                                     unsigned int  sourceLen,
1578                                     int           small,
1579                                     int           verbosity );
1580 </pre></td></tr></table>Attempts to decompress the data in <CODE>source[0 .. sourceLen-1]</CODE>
1581 into the destination buffer, <CODE>dest[0 .. *destLen-1]</CODE>.
1582 If the destination buffer is big enough, <CODE>*destLen</CODE> is
1583 set to the size of the uncompressed data, and <CODE>BZ_OK</CODE> is
1584 returned.  If the compressed data won't fit, <CODE>*destLen</CODE>
1585 is unchanged, and <CODE>BZ_OUTBUFF_FULL</CODE> is returned.
1586 <P>
1587
1588 <CODE>source</CODE> is assumed to hold a complete <CODE>bzip2</CODE> format
1589 data stream.  <BR> <CODE>BZ2_bzBuffToBuffDecompress</CODE> tries to decompress
1590 the entirety of the stream into the output buffer.
1591 </P><P>
1592
1593 For the meaning of parameters <CODE>small</CODE> and <CODE>verbosity</CODE>,
1594 see <CODE>BZ2_bzDecompressInit</CODE>.
1595 </P><P>
1596
1597 Because the compression ratio of the compressed data cannot be known in
1598 advance, there is no easy way to guarantee that the output buffer will
1599 be big enough.  You may of course make arrangements in your code to
1600 record the size of the uncompressed data, but such a mechanism is beyond
1601 the scope of this library.
1602 </P><P>
1603
1604 <CODE>BZ2_bzBuffToBuffDecompress</CODE> will not write data at or
1605 beyond <CODE>dest[*destLen]</CODE>, even in case of buffer overflow.
1606 </P><P>
1607
1608 Possible return values:
1609 <TABLE><tr><td>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_CONFIG_ERROR</CODE>
1610          if the library has been mis-compiled
1611       <CODE>BZ_PARAM_ERROR</CODE>
1612          if <CODE>dest</CODE> is <CODE>NULL</CODE> or <CODE>destLen</CODE> is <CODE>NULL</CODE>
1613          or <CODE>small != 0 &#38;&#38; small != 1</CODE>
1614          or <CODE>verbosity &#60; 0</CODE> or <CODE>verbosity &#62; 4</CODE>
1615       <CODE>BZ_MEM_ERROR</CODE>
1616          if insufficient memory is available
1617       <CODE>BZ_OUTBUFF_FULL</CODE>
1618          if the size of the compressed data exceeds <CODE>*destLen</CODE>
1619       <CODE>BZ_DATA_ERROR</CODE>
1620          if a data integrity error was detected in the compressed data
1621       <CODE>BZ_DATA_ERROR_MAGIC</CODE>
1622          if the compressed data doesn't begin with the right magic bytes
1623       <CODE>BZ_UNEXPECTED_EOF</CODE>
1624          if the compressed data ends unexpectedly
1625       <CODE>BZ_OK</CODE>
1626          otherwise
1627 </pre></td></tr></table></P><P>
1628
1629 <HR SIZE="6">
1630 <A NAME="SEC38"></A>
1631 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1632 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC37"> &lt; </A>]</TD>
1633 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC39"> &gt; </A>]</TD>
1634 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1635 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1636 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1637 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1638 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1639 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1640 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1641 </TR></TABLE>
1642 <H2> 3.6 <CODE>zlib</CODE> compatibility functions </H2>
1643 <!--docid::SEC38::-->
1644 Yoshioka Tsuneo has contributed some functions to
1645 give better <CODE>zlib</CODE> compatibility.  These functions are
1646 <CODE>BZ2_bzopen</CODE>, <CODE>BZ2_bzread</CODE>, <CODE>BZ2_bzwrite</CODE>, <CODE>BZ2_bzflush</CODE>,
1647 <CODE>BZ2_bzclose</CODE>,
1648 <CODE>BZ2_bzerror</CODE> and <CODE>BZ2_bzlibVersion</CODE>.
1649 These functions are not (yet) officially part of
1650 the library.  If they break, you get to keep all the pieces.
1651 Nevertheless, I think they work ok.
1652 <TABLE><tr><td>&nbsp;</td><td class=example><pre>typedef void BZFILE;
1653
1654 const char * BZ2_bzlibVersion ( void );
1655 </pre></td></tr></table>Returns a string indicating the library version.
1656 <TABLE><tr><td>&nbsp;</td><td class=example><pre>BZFILE * BZ2_bzopen  ( const char *path, const char *mode );
1657 BZFILE * BZ2_bzdopen ( int        fd,    const char *mode );
1658 </pre></td></tr></table>Opens a <CODE>.bz2</CODE> file for reading or writing, using either its name
1659 or a pre-existing file descriptor.
1660 Analogous to <CODE>fopen</CODE> and <CODE>fdopen</CODE>.
1661 <TABLE><tr><td>&nbsp;</td><td class=example><pre>int BZ2_bzread  ( BZFILE* b, void* buf, int len );
1662 int BZ2_bzwrite ( BZFILE* b, void* buf, int len );
1663 </pre></td></tr></table>Reads/writes data from/to a previously opened <CODE>BZFILE</CODE>.
1664 Analogous to <CODE>fread</CODE> and <CODE>fwrite</CODE>.
1665 <TABLE><tr><td>&nbsp;</td><td class=example><pre>int  BZ2_bzflush ( BZFILE* b );
1666 void BZ2_bzclose ( BZFILE* b );
1667 </pre></td></tr></table>Flushes/closes a <CODE>BZFILE</CODE>.  <CODE>BZ2_bzflush</CODE> doesn't actually do
1668 anything.  Analogous to <CODE>fflush</CODE> and <CODE>fclose</CODE>.
1669 <P>
1670
1671 <TABLE><tr><td>&nbsp;</td><td class=example><pre>const char * BZ2_bzerror ( BZFILE *b, int *errnum )
1672 </pre></td></tr></table>Returns a string describing the more recent error status of
1673 <CODE>b</CODE>, and also sets <CODE>*errnum</CODE> to its numerical value.
1674 </P><P>
1675
1676 <HR SIZE="6">
1677 <A NAME="SEC39"></A>
1678 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1679 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC38"> &lt; </A>]</TD>
1680 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC40"> &gt; </A>]</TD>
1681 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1682 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1683 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1684 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1685 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1686 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1687 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1688 </TR></TABLE>
1689 <H2> 3.7 Using the library in a <CODE>stdio</CODE>-free environment </H2>
1690 <!--docid::SEC39::-->
1691 <P>
1692
1693 <HR SIZE="6">
1694 <A NAME="SEC40"></A>
1695 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1696 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC39"> &lt; </A>]</TD>
1697 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC41"> &gt; </A>]</TD>
1698 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1699 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1700 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1701 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1702 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1703 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1704 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1705 </TR></TABLE>
1706 <H3> 3.7.1 Getting rid of <CODE>stdio</CODE> </H3>
1707 <!--docid::SEC40::-->
1708 <P>
1709
1710 In a deeply embedded application, you might want to use just
1711 the memory-to-memory functions.  You can do this conveniently
1712 by compiling the library with preprocessor symbol <CODE>BZ_NO_STDIO</CODE>
1713 defined.  Doing this gives you a library containing only the following
1714 eight functions:
1715 </P><P>
1716
1717 <CODE>BZ2_bzCompressInit</CODE>, <CODE>BZ2_bzCompress</CODE>, <CODE>BZ2_bzCompressEnd</CODE> <BR>
1718 <CODE>BZ2_bzDecompressInit</CODE>, <CODE>BZ2_bzDecompress</CODE>, <CODE>BZ2_bzDecompressEnd</CODE> <BR>
1719 <CODE>BZ2_bzBuffToBuffCompress</CODE>, <CODE>BZ2_bzBuffToBuffDecompress</CODE>
1720 </P><P>
1721
1722 When compiled like this, all functions will ignore <CODE>verbosity</CODE>
1723 settings.
1724 </P><P>
1725
1726 <HR SIZE="6">
1727 <A NAME="SEC41"></A>
1728 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1729 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC40"> &lt; </A>]</TD>
1730 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC42"> &gt; </A>]</TD>
1731 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1732 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1733 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1734 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1735 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1736 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1737 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1738 </TR></TABLE>
1739 <H3> 3.7.2 Critical error handling </H3>
1740 <!--docid::SEC41::-->
1741 <CODE>libbzip2</CODE> contains a number of internal assertion checks which
1742 should, needless to say, never be activated.  Nevertheless, if an
1743 assertion should fail, behaviour depends on whether or not the library
1744 was compiled with <CODE>BZ_NO_STDIO</CODE> set.
1745 <P>
1746
1747 For a normal compile, an assertion failure yields the message
1748 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   bzip2/libbzip2: internal error number N.
1749    This is a bug in bzip2/libbzip2, 1.0.2, 30-Dec-2001.
1750    Please report it to me at: jseward@acm.org.  If this happened
1751    when you were using some program which uses libbzip2 as a
1752    component, you should also report this bug to the author(s)
1753    of that program.  Please make an effort to report this bug;
1754    timely and accurate bug reports eventually lead to higher
1755    quality software.  Thanks.  Julian Seward, 30 December 2001.
1756 </pre></td></tr></table>where <CODE>N</CODE> is some error code number.  If <CODE>N == 1007</CODE>, it also
1757 prints some extra text advising the reader that unreliable memory is
1758 often associated with internal error 1007.  (This is a
1759 frequently-observed-phenomenon with versions 1.0.0/1.0.1).
1760 </P><P>
1761
1762 <CODE>exit(3)</CODE> is then called.
1763 </P><P>
1764
1765 For a <CODE>stdio</CODE>-free library, assertion failures result
1766 in a call to a function declared as:
1767 <TABLE><tr><td>&nbsp;</td><td class=example><pre>   extern void bz_internal_error ( int errcode );
1768 </pre></td></tr></table>The relevant code is passed as a parameter.  You should supply
1769 such a function.
1770 </P><P>
1771
1772 In either case, once an assertion failure has occurred, any
1773 <CODE>bz_stream</CODE> records involved can be regarded as invalid.
1774 You should not attempt to resume normal operation with them.
1775 </P><P>
1776
1777 You may, of course, change critical error handling to suit
1778 your needs.  As I said above, critical errors indicate bugs
1779 in the library and should not occur.  All "normal" error
1780 situations are indicated via error return codes from functions,
1781 and can be recovered from.
1782 </P><P>
1783
1784 <HR SIZE="6">
1785 <A NAME="SEC42"></A>
1786 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1787 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC41"> &lt; </A>]</TD>
1788 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_4.html#SEC43"> &gt; </A>]</TD>
1789 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1790 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1791 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1792 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1793 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1794 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1795 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1796 </TR></TABLE>
1797 <H2> 3.8 Making a Windows DLL </H2>
1798 <!--docid::SEC42::-->
1799 Everything related to Windows has been contributed by Yoshioka Tsuneo
1800 <BR> (<CODE>QWF00133@niftyserve.or.jp</CODE> /
1801 <CODE>tsuneo-y@is.aist-nara.ac.jp</CODE>), so you should send your queries to
1802 him (but perhaps Cc: me, <CODE>jseward@acm.org</CODE>).
1803 <P>
1804
1805 My vague understanding of what to do is: using Visual C++ 5.0,
1806 open the project file <CODE>libbz2.dsp</CODE>, and build.  That's all.
1807 </P><P>
1808
1809 If you can't
1810 open the project file for some reason, make a new one, naming these files:
1811 <CODE>blocksort.c</CODE>, <CODE>bzlib.c</CODE>, <CODE>compress.c</CODE>,
1812 <CODE>crctable.c</CODE>, <CODE>decompress.c</CODE>, <CODE>huffman.c</CODE>, <BR>
1813 <CODE>randtable.c</CODE> and <CODE>libbz2.def</CODE>.  You will also need
1814 to name the header files <CODE>bzlib.h</CODE> and <CODE>bzlib_private.h</CODE>.
1815 </P><P>
1816
1817 If you don't use VC++, you may need to define the proprocessor symbol
1818 <CODE>_WIN32</CODE>.
1819 </P><P>
1820
1821 Finally, <CODE>dlltest.c</CODE> is a sample program using the DLL.  It has a
1822 project file, <CODE>dlltest.dsp</CODE>.
1823 </P><P>
1824
1825 If you just want a makefile for Visual C, have a look at
1826 <CODE>makefile.msc</CODE>.
1827 </P><P>
1828
1829 Be aware that if you compile <CODE>bzip2</CODE> itself on Win32, you must set
1830 <CODE>BZ_UNIX</CODE> to 0 and <CODE>BZ_LCCWIN32</CODE> to 1, in the file
1831 <CODE>bzip2.c</CODE>, before compiling.  Otherwise the resulting binary won't
1832 work correctly.
1833 </P><P>
1834
1835 I haven't tried any of this stuff myself, but it all looks plausible.
1836 </P><P>
1837
1838 <HR SIZE="6">
1839 <TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1840 <TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
1841 <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
1842 <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD>
1843 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1844 <TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1845 <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1846 </TR></TABLE>
1847 <BR>
1848 <FONT SIZE="-1">
1849 This document was generated
1850 by <I>Julian Seward</I> on <I>January, 5  2002</I>
1851 using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
1852 "><I>texi2html</I></A>
1853
1854 </BODY>
1855 </HTML>