diff options
Diffstat (limited to 'Build/source/utils/bzip2/manual_3.html')
-rw-r--r-- | Build/source/utils/bzip2/manual_3.html | 1855 |
1 files changed, 0 insertions, 1855 deletions
diff --git a/Build/source/utils/bzip2/manual_3.html b/Build/source/utils/bzip2/manual_3.html deleted file mode 100644 index 841d14d3e8c..00000000000 --- a/Build/source/utils/bzip2/manual_3.html +++ /dev/null @@ -1,1855 +0,0 @@ -<HTML> -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<!-- Created on January, 5 2002 by texi2html 1.64 --> -<!-- -Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author) - Karl Berry <karl@freefriends.org> - Olaf Bachmann <obachman@mathematik.uni-kl.de> - and many others. -Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de> -Send bugs and suggestions to <texi2html@mathematik.uni-kl.de> - ---> -<HEAD> -<TITLE>Untitled Document: 3. Programming with <CODE>libbzip2</CODE></TITLE> - -<META NAME="description" CONTENT="Untitled Document: 3. Programming with <CODE>libbzip2</CODE>"> -<META NAME="keywords" CONTENT="Untitled Document: 3. Programming with <CODE>libbzip2</CODE>"> -<META NAME="resource-type" CONTENT="document"> -<META NAME="distribution" CONTENT="global"> -<META NAME="Generator" CONTENT="texi2html 1.64"> - -</HEAD> - -<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000"> - -<A NAME="SEC12"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_2.html#SEC11"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC13"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H1> 3. Programming with <CODE>libbzip2</CODE> </H1> -<!--docid::SEC12::--> -<P> - -This chapter describes the programming interface to <CODE>libbzip2</CODE>. -</P><P> - -For general background information, particularly about memory -use and performance aspects, you'd be well advised to read Chapter 2 -as well. -</P><P> - -<HR SIZE="6"> -<A NAME="SEC13"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC12"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC14"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H2> 3.1 Top-level structure </H2> -<!--docid::SEC13::--> -<P> - -<CODE>libbzip2</CODE> is a flexible library for compressing and decompressing -data in the <CODE>bzip2</CODE> data format. Although packaged as a single -entity, it helps to regard the library as three separate parts: the low -level interface, and the high level interface, and some utility -functions. -</P><P> - -The structure of <CODE>libbzip2</CODE>'s interfaces is similar to -that of Jean-loup Gailly's and Mark Adler's excellent <CODE>zlib</CODE> -library. -</P><P> - -All externally visible symbols have names beginning <CODE>BZ2_</CODE>. -This is new in version 1.0. The intention is to minimise pollution -of the namespaces of library clients. -</P><P> - -<HR SIZE="6"> -<A NAME="SEC14"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC13"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC15"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.1.1 Low-level summary </H3> -<!--docid::SEC14::--> -<P> - -This interface provides services for compressing and decompressing -data in memory. There's no provision for dealing with files, streams -or any other I/O mechanisms, just straight memory-to-memory work. -In fact, this part of the library can be compiled without inclusion -of <CODE>stdio.h</CODE>, which may be helpful for embedded applications. -</P><P> - -The low-level part of the library has no global variables and -is therefore thread-safe. -</P><P> - -Six routines make up the low level interface: -<CODE>BZ2_bzCompressInit</CODE>, <CODE>BZ2_bzCompress</CODE>, and <BR> <CODE>BZ2_bzCompressEnd</CODE> -for compression, -and a corresponding trio <CODE>BZ2_bzDecompressInit</CODE>, <BR> <CODE>BZ2_bzDecompress</CODE> -and <CODE>BZ2_bzDecompressEnd</CODE> for decompression. -The <CODE>*Init</CODE> functions allocate -memory for compression/decompression and do other -initialisations, whilst the <CODE>*End</CODE> functions close down operations -and release memory. -</P><P> - -The real work is done by <CODE>BZ2_bzCompress</CODE> and <CODE>BZ2_bzDecompress</CODE>. -These compress and decompress data from a user-supplied input buffer -to a user-supplied output buffer. These buffers can be any size; -arbitrary quantities of data are handled by making repeated calls -to these functions. This is a flexible mechanism allowing a -consumer-pull style of activity, or producer-push, or a mixture of -both. -</P><P> - -<HR SIZE="6"> -<A NAME="SEC15"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC14"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC16"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.1.2 High-level summary </H3> -<!--docid::SEC15::--> -<P> - -This interface provides some handy wrappers around the low-level -interface to facilitate reading and writing <CODE>bzip2</CODE> format -files (<CODE>.bz2</CODE> files). The routines provide hooks to facilitate -reading files in which the <CODE>bzip2</CODE> data stream is embedded -within some larger-scale file structure, or where there are -multiple <CODE>bzip2</CODE> data streams concatenated end-to-end. -</P><P> - -For reading files, <CODE>BZ2_bzReadOpen</CODE>, <CODE>BZ2_bzRead</CODE>, -<CODE>BZ2_bzReadClose</CODE> and <BR> <CODE>BZ2_bzReadGetUnused</CODE> are supplied. For -writing files, <CODE>BZ2_bzWriteOpen</CODE>, <CODE>BZ2_bzWrite</CODE> and -<CODE>BZ2_bzWriteFinish</CODE> are available. -</P><P> - -As with the low-level library, no global variables are used -so the library is per se thread-safe. However, if I/O errors -occur whilst reading or writing the underlying compressed files, -you may have to consult <CODE>errno</CODE> to determine the cause of -the error. In that case, you'd need a C library which correctly -supports <CODE>errno</CODE> in a multithreaded environment. -</P><P> - -To make the library a little simpler and more portable, -<CODE>BZ2_bzReadOpen</CODE> and <CODE>BZ2_bzWriteOpen</CODE> require you to pass them file -handles (<CODE>FILE*</CODE>s) which have previously been opened for reading or -writing respectively. That avoids portability problems associated with -file operations and file attributes, whilst not being much of an -imposition on the programmer. -</P><P> - -<HR SIZE="6"> -<A NAME="SEC16"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC15"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC17"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.1.3 Utility functions summary </H3> -<!--docid::SEC16::--> -For very simple needs, <CODE>BZ2_bzBuffToBuffCompress</CODE> and -<CODE>BZ2_bzBuffToBuffDecompress</CODE> are provided. These compress -data in memory from one buffer to another buffer in a single -function call. You should assess whether these functions -fulfill your memory-to-memory compression/decompression -requirements before investing effort in understanding the more -general but more complex low-level interface. -<P> - -Yoshioka Tsuneo (<CODE>QWF00133@niftyserve.or.jp</CODE> / -<CODE>tsuneo-y@is.aist-nara.ac.jp</CODE>) has contributed some functions to -give better <CODE>zlib</CODE> compatibility. These functions are -<CODE>BZ2_bzopen</CODE>, <CODE>BZ2_bzread</CODE>, <CODE>BZ2_bzwrite</CODE>, <CODE>BZ2_bzflush</CODE>, -<CODE>BZ2_bzclose</CODE>, -<CODE>BZ2_bzerror</CODE> and <CODE>BZ2_bzlibVersion</CODE>. You may find these functions -more convenient for simple file reading and writing, than those in the -high-level interface. These functions are not (yet) officially part of -the library, and are minimally documented here. If they break, you -get to keep all the pieces. I hope to document them properly when time -permits. -</P><P> - -Yoshioka also contributed modifications to allow the library to be -built as a Windows DLL. -</P><P> - -<HR SIZE="6"> -<A NAME="SEC17"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC16"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC18"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H2> 3.2 Error handling </H2> -<!--docid::SEC17::--> -<P> - -The library is designed to recover cleanly in all situations, including -the worst-case situation of decompressing random data. I'm not -100% sure that it can always do this, so you might want to add -a signal handler to catch segmentation violations during decompression -if you are feeling especially paranoid. I would be interested in -hearing more about the robustness of the library to corrupted -compressed data. -</P><P> - -Version 1.0 is much more robust in this respect than -0.9.0 or 0.9.5. Investigations with Checker (a tool for -detecting problems with memory management, similar to Purify) -indicate that, at least for the few files I tested, all single-bit -errors in the decompressed data are caught properly, with no -segmentation faults, no reads of uninitialised data and no -out of range reads or writes. So it's certainly much improved, -although I wouldn't claim it to be totally bombproof. -</P><P> - -The file <CODE>bzlib.h</CODE> contains all definitions needed to use -the library. In particular, you should definitely not include -<CODE>bzlib_private.h</CODE>. -</P><P> - -In <CODE>bzlib.h</CODE>, the various return values are defined. The following -list is not intended as an exhaustive description of the circumstances -in which a given value may be returned -- those descriptions are given -later. Rather, it is intended to convey the rough meaning of each -return value. The first five actions are normal and not intended to -denote an error situation. -<DL COMPACT> -<DT><CODE>BZ_OK</CODE> -<DD>The requested action was completed successfully. -<DT><CODE>BZ_RUN_OK</CODE> -<DD><DT><CODE>BZ_FLUSH_OK</CODE> -<DD><DT><CODE>BZ_FINISH_OK</CODE> -<DD>In <CODE>BZ2_bzCompress</CODE>, the requested flush/finish/nothing-special action -was completed successfully. -<DT><CODE>BZ_STREAM_END</CODE> -<DD>Compression of data was completed, or the logical stream end was -detected during decompression. -</DL> -<P> - -The following return values indicate an error of some kind. -<DL COMPACT> -<DT><CODE>BZ_CONFIG_ERROR</CODE> -<DD>Indicates that the library has been improperly compiled on your -platform -- a major configuration error. Specifically, it means -that <CODE>sizeof(char)</CODE>, <CODE>sizeof(short)</CODE> and <CODE>sizeof(int)</CODE> -are not 1, 2 and 4 respectively, as they should be. Note that the -library should still work properly on 64-bit platforms which follow -the LP64 programming model -- that is, where <CODE>sizeof(long)</CODE> -and <CODE>sizeof(void*)</CODE> are 8. Under LP64, <CODE>sizeof(int)</CODE> is -still 4, so <CODE>libbzip2</CODE>, which doesn't use the <CODE>long</CODE> type, -is OK. -<DT><CODE>BZ_SEQUENCE_ERROR</CODE> -<DD>When using the library, it is important to call the functions in the -correct sequence and with data structures (buffers etc) in the correct -states. <CODE>libbzip2</CODE> checks as much as it can to ensure this is -happening, and returns <CODE>BZ_SEQUENCE_ERROR</CODE> if not. Code which -complies precisely with the function semantics, as detailed below, -should never receive this value; such an event denotes buggy code -which you should investigate. -<DT><CODE>BZ_PARAM_ERROR</CODE> -<DD>Returned when a parameter to a function call is out of range -or otherwise manifestly incorrect. As with <CODE>BZ_SEQUENCE_ERROR</CODE>, -this denotes a bug in the client code. The distinction between -<CODE>BZ_PARAM_ERROR</CODE> and <CODE>BZ_SEQUENCE_ERROR</CODE> is a bit hazy, but still worth -making. -<DT><CODE>BZ_MEM_ERROR</CODE> -<DD>Returned when a request to allocate memory failed. Note that the -quantity of memory needed to decompress a stream cannot be determined -until the stream's header has been read. So <CODE>BZ2_bzDecompress</CODE> and -<CODE>BZ2_bzRead</CODE> may return <CODE>BZ_MEM_ERROR</CODE> even though some of -the compressed data has been read. The same is not true for -compression; once <CODE>BZ2_bzCompressInit</CODE> or <CODE>BZ2_bzWriteOpen</CODE> have -successfully completed, <CODE>BZ_MEM_ERROR</CODE> cannot occur. -<DT><CODE>BZ_DATA_ERROR</CODE> -<DD>Returned when a data integrity error is detected during decompression. -Most importantly, this means when stored and computed CRCs for the -data do not match. This value is also returned upon detection of any -other anomaly in the compressed data. -<DT><CODE>BZ_DATA_ERROR_MAGIC</CODE> -<DD>As a special case of <CODE>BZ_DATA_ERROR</CODE>, it is sometimes useful to -know when the compressed stream does not start with the correct -magic bytes (<CODE>'B' 'Z' 'h'</CODE>). -<DT><CODE>BZ_IO_ERROR</CODE> -<DD>Returned by <CODE>BZ2_bzRead</CODE> and <CODE>BZ2_bzWrite</CODE> when there is an error -reading or writing in the compressed file, and by <CODE>BZ2_bzReadOpen</CODE> -and <CODE>BZ2_bzWriteOpen</CODE> for attempts to use a file for which the -error indicator (viz, <CODE>ferror(f)</CODE>) is set. -On receipt of <CODE>BZ_IO_ERROR</CODE>, the caller should consult -<CODE>errno</CODE> and/or <CODE>perror</CODE> to acquire operating-system -specific information about the problem. -<DT><CODE>BZ_UNEXPECTED_EOF</CODE> -<DD>Returned by <CODE>BZ2_bzRead</CODE> when the compressed file finishes -before the logical end of stream is detected. -<DT><CODE>BZ_OUTBUFF_FULL</CODE> -<DD>Returned by <CODE>BZ2_bzBuffToBuffCompress</CODE> and -<CODE>BZ2_bzBuffToBuffDecompress</CODE> to indicate that the output data -will not fit into the output buffer provided. -</DL> -<P> - -<HR SIZE="6"> -<A NAME="SEC18"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC17"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC19"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H2> 3.3 Low-level interface </H2> -<!--docid::SEC18::--> -<P> - -<HR SIZE="6"> -<A NAME="SEC19"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC18"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC20"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.3.1 <CODE>BZ2_bzCompressInit</CODE> </H3> -<!--docid::SEC19::--> -<TABLE><tr><td> </td><td class=example><pre>typedef - struct { - char *next_in; - unsigned int avail_in; - unsigned int total_in_lo32; - unsigned int total_in_hi32; - - char *next_out; - unsigned int avail_out; - unsigned int total_out_lo32; - unsigned int total_out_hi32; - - void *state; - - void *(*bzalloc)(void *,int,int); - void (*bzfree)(void *,void *); - void *opaque; - } - bz_stream; - -int BZ2_bzCompressInit ( bz_stream *strm, - int blockSize100k, - int verbosity, - int workFactor ); - -</pre></td></tr></table><P> - -Prepares for compression. The <CODE>bz_stream</CODE> structure -holds all data pertaining to the compression activity. -A <CODE>bz_stream</CODE> structure should be allocated and initialised -prior to the call. -The fields of <CODE>bz_stream</CODE> -comprise the entirety of the user-visible data. <CODE>state</CODE> -is a pointer to the private data structures required for compression. -</P><P> - -Custom memory allocators are supported, via fields <CODE>bzalloc</CODE>, -<CODE>bzfree</CODE>, -and <CODE>opaque</CODE>. The value -<CODE>opaque</CODE> is passed to as the first argument to -all calls to <CODE>bzalloc</CODE> and <CODE>bzfree</CODE>, but is -otherwise ignored by the library. -The call <CODE>bzalloc ( opaque, n, m )</CODE> is expected to return a -pointer <CODE>p</CODE> to -<CODE>n * m</CODE> bytes of memory, and <CODE>bzfree ( opaque, p )</CODE> -should free -that memory. -</P><P> - -If you don't want to use a custom memory allocator, set <CODE>bzalloc</CODE>, -<CODE>bzfree</CODE> and -<CODE>opaque</CODE> to <CODE>NULL</CODE>, -and the library will then use the standard <CODE>malloc</CODE>/<CODE>free</CODE> -routines. -</P><P> - -Before calling <CODE>BZ2_bzCompressInit</CODE>, fields <CODE>bzalloc</CODE>, -<CODE>bzfree</CODE> and <CODE>opaque</CODE> should -be filled appropriately, as just described. Upon return, the internal -state will have been allocated and initialised, and <CODE>total_in_lo32</CODE>, -<CODE>total_in_hi32</CODE>, <CODE>total_out_lo32</CODE> and -<CODE>total_out_hi32</CODE> will have been set to zero. -These four fields are used by the library -to inform the caller of the total amount of data passed into and out of -the library, respectively. You should not try to change them. -As of version 1.0, 64-bit counts are maintained, even on 32-bit -platforms, using the <CODE>_hi32</CODE> fields to store the upper 32 bits -of the count. So, for example, the total amount of data in -is <CODE>(total_in_hi32 << 32) + total_in_lo32</CODE>. -</P><P> - -Parameter <CODE>blockSize100k</CODE> specifies the block size to be used for -compression. It should be a value between 1 and 9 inclusive, and the -actual block size used is 100000 x this figure. 9 gives the best -compression but takes most memory. -</P><P> - -Parameter <CODE>verbosity</CODE> should be set to a number between 0 and 4 -inclusive. 0 is silent, and greater numbers give increasingly verbose -monitoring/debugging output. If the library has been compiled with -<CODE>-DBZ_NO_STDIO</CODE>, no such output will appear for any verbosity -setting. -</P><P> - -Parameter <CODE>workFactor</CODE> controls how the compression phase behaves -when presented with worst case, highly repetitive, input data. If -compression runs into difficulties caused by repetitive data, the -library switches from the standard sorting algorithm to a fallback -algorithm. The fallback is slower than the standard algorithm by -perhaps a factor of three, but always behaves reasonably, no matter how -bad the input. -</P><P> - -Lower values of <CODE>workFactor</CODE> reduce the amount of effort the -standard algorithm will expend before resorting to the fallback. You -should set this parameter carefully; too low, and many inputs will be -handled by the fallback algorithm and so compress rather slowly, too -high, and your average-to-worst case compression times can become very -large. The default value of 30 gives reasonable behaviour over a wide -range of circumstances. -</P><P> - -Allowable values range from 0 to 250 inclusive. 0 is a special case, -equivalent to using the default value of 30. -</P><P> - -Note that the compressed output generated is the same regardless of -whether or not the fallback algorithm is used. -</P><P> - -Be aware also that this parameter may disappear entirely in future -versions of the library. In principle it should be possible to devise a -good way to automatically choose which algorithm to use. Such a -mechanism would render the parameter obsolete. -</P><P> - -Possible return values: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE> - if the library has been mis-compiled - <CODE>BZ_PARAM_ERROR</CODE> - if <CODE>strm</CODE> is <CODE>NULL</CODE> - or <CODE>blockSize</CODE> < 1 or <CODE>blockSize</CODE> > 9 - or <CODE>verbosity</CODE> < 0 or <CODE>verbosity</CODE> > 4 - or <CODE>workFactor</CODE> < 0 or <CODE>workFactor</CODE> > 250 - <CODE>BZ_MEM_ERROR</CODE> - if not enough memory is available - <CODE>BZ_OK</CODE> - otherwise -</pre></td></tr></table>Allowable next actions: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzCompress</CODE> - if <CODE>BZ_OK</CODE> is returned - no specific action needed in case of error -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC20"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC19"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC21"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.3.2 <CODE>BZ2_bzCompress</CODE> </H3> -<!--docid::SEC20::--> -<TABLE><tr><td> </td><td class=example><pre> int BZ2_bzCompress ( bz_stream *strm, int action ); -</pre></td></tr></table>Provides more input and/or output buffer space for the library. The -caller maintains input and output buffers, and calls <CODE>BZ2_bzCompress</CODE> to -transfer data between them. -<P> - -Before each call to <CODE>BZ2_bzCompress</CODE>, <CODE>next_in</CODE> should point at -the data to be compressed, and <CODE>avail_in</CODE> should indicate how many -bytes the library may read. <CODE>BZ2_bzCompress</CODE> updates <CODE>next_in</CODE>, -<CODE>avail_in</CODE> and <CODE>total_in</CODE> to reflect the number of bytes it -has read. -</P><P> - -Similarly, <CODE>next_out</CODE> should point to a buffer in which the -compressed data is to be placed, with <CODE>avail_out</CODE> indicating how -much output space is available. <CODE>BZ2_bzCompress</CODE> updates -<CODE>next_out</CODE>, <CODE>avail_out</CODE> and <CODE>total_out</CODE> to reflect the -number of bytes output. -</P><P> - -You may provide and remove as little or as much data as you like on each -call of <CODE>BZ2_bzCompress</CODE>. In the limit, it is acceptable to supply and -remove data one byte at a time, although this would be terribly -inefficient. You should always ensure that at least one byte of output -space is available at each call. -</P><P> - -A second purpose of <CODE>BZ2_bzCompress</CODE> is to request a change of mode of the -compressed stream. -</P><P> - -Conceptually, a compressed stream can be in one of four states: IDLE, -RUNNING, FLUSHING and FINISHING. Before initialisation -(<CODE>BZ2_bzCompressInit</CODE>) and after termination (<CODE>BZ2_bzCompressEnd</CODE>), a -stream is regarded as IDLE. -</P><P> - -Upon initialisation (<CODE>BZ2_bzCompressInit</CODE>), the stream is placed in the -RUNNING state. Subsequent calls to <CODE>BZ2_bzCompress</CODE> should pass -<CODE>BZ_RUN</CODE> as the requested action; other actions are illegal and -will result in <CODE>BZ_SEQUENCE_ERROR</CODE>. -</P><P> - -At some point, the calling program will have provided all the input data -it wants to. It will then want to finish up -- in effect, asking the -library to process any data it might have buffered internally. In this -state, <CODE>BZ2_bzCompress</CODE> will no longer attempt to read data from -<CODE>next_in</CODE>, but it will want to write data to <CODE>next_out</CODE>. -Because the output buffer supplied by the user can be arbitrarily small, -the finishing-up operation cannot necessarily be done with a single call -of <CODE>BZ2_bzCompress</CODE>. -</P><P> - -Instead, the calling program passes <CODE>BZ_FINISH</CODE> as an action to -<CODE>BZ2_bzCompress</CODE>. This changes the stream's state to FINISHING. Any -remaining input (ie, <CODE>next_in[0 .. avail_in-1]</CODE>) is compressed and -transferred to the output buffer. To do this, <CODE>BZ2_bzCompress</CODE> must be -called repeatedly until all the output has been consumed. At that -point, <CODE>BZ2_bzCompress</CODE> returns <CODE>BZ_STREAM_END</CODE>, and the stream's -state is set back to IDLE. <CODE>BZ2_bzCompressEnd</CODE> should then be -called. -</P><P> - -Just to make sure the calling program does not cheat, the library makes -a note of <CODE>avail_in</CODE> at the time of the first call to -<CODE>BZ2_bzCompress</CODE> which has <CODE>BZ_FINISH</CODE> as an action (ie, at the -time the program has announced its intention to not supply any more -input). By comparing this value with that of <CODE>avail_in</CODE> over -subsequent calls to <CODE>BZ2_bzCompress</CODE>, the library can detect any -attempts to slip in more data to compress. Any calls for which this is -detected will return <CODE>BZ_SEQUENCE_ERROR</CODE>. This indicates a -programming mistake which should be corrected. -</P><P> - -Instead of asking to finish, the calling program may ask -<CODE>BZ2_bzCompress</CODE> to take all the remaining input, compress it and -terminate the current (Burrows-Wheeler) compression block. This could -be useful for error control purposes. The mechanism is analogous to -that for finishing: call <CODE>BZ2_bzCompress</CODE> with an action of -<CODE>BZ_FLUSH</CODE>, remove output data, and persist with the -<CODE>BZ_FLUSH</CODE> action until the value <CODE>BZ_RUN</CODE> is returned. As -with finishing, <CODE>BZ2_bzCompress</CODE> detects any attempt to provide more -input data once the flush has begun. -</P><P> - -Once the flush is complete, the stream returns to the normal RUNNING -state. -</P><P> - -This all sounds pretty complex, but isn't really. Here's a table -which shows which actions are allowable in each state, what action -will be taken, what the next state is, and what the non-error return -values are. Note that you can't explicitly ask what state the -stream is in, but nor do you need to -- it can be inferred from the -values returned by <CODE>BZ2_bzCompress</CODE>. -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif">IDLE/<CODE>any</CODE> - Illegal. IDLE state only exists after <CODE>BZ2_bzCompressEnd</CODE> or - before <CODE>BZ2_bzCompressInit</CODE>. - Return value = <CODE>BZ_SEQUENCE_ERROR</CODE> - -RUNNING/<CODE>BZ_RUN</CODE> - Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible. - Next state = RUNNING - Return value = <CODE>BZ_RUN_OK</CODE> - -RUNNING/<CODE>BZ_FLUSH</CODE> - Remember current value of <CODE>next_in</CODE>. Compress from <CODE>next_in</CODE> - to <CODE>next_out</CODE> as much as possible, but do not accept any more input. - Next state = FLUSHING - Return value = <CODE>BZ_FLUSH_OK</CODE> - -RUNNING/<CODE>BZ_FINISH</CODE> - Remember current value of <CODE>next_in</CODE>. Compress from <CODE>next_in</CODE> - to <CODE>next_out</CODE> as much as possible, but do not accept any more input. - Next state = FINISHING - Return value = <CODE>BZ_FINISH_OK</CODE> - -FLUSHING/<CODE>BZ_FLUSH</CODE> - Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible, - but do not accept any more input. - If all the existing input has been used up and all compressed - output has been removed - Next state = RUNNING; Return value = <CODE>BZ_RUN_OK</CODE> - else - Next state = FLUSHING; Return value = <CODE>BZ_FLUSH_OK</CODE> - -FLUSHING/other - Illegal. - Return value = <CODE>BZ_SEQUENCE_ERROR</CODE> - -FINISHING/<CODE>BZ_FINISH</CODE> - Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible, - but to not accept any more input. - If all the existing input has been used up and all compressed - output has been removed - Next state = IDLE; Return value = <CODE>BZ_STREAM_END</CODE> - else - Next state = FINISHING; Return value = <CODE>BZ_FINISHING</CODE> - -FINISHING/other - Illegal. - Return value = <CODE>BZ_SEQUENCE_ERROR</CODE> -</pre></td></tr></table></P><P> - -That still looks complicated? Well, fair enough. The usual sequence -of calls for compressing a load of data is: -<UL> -<LI>Get started with <CODE>BZ2_bzCompressInit</CODE>. -<LI>Shovel data in and shlurp out its compressed form using zero or more -calls of <CODE>BZ2_bzCompress</CODE> with action = <CODE>BZ_RUN</CODE>. -<LI>Finish up. -Repeatedly call <CODE>BZ2_bzCompress</CODE> with action = <CODE>BZ_FINISH</CODE>, -copying out the compressed output, until <CODE>BZ_STREAM_END</CODE> is returned. -<LI>Close up and go home. Call <CODE>BZ2_bzCompressEnd</CODE>. -</UL> -If the data you want to compress fits into your input buffer all -at once, you can skip the calls of <CODE>BZ2_bzCompress ( ..., BZ_RUN )</CODE> and -just do the <CODE>BZ2_bzCompress ( ..., BZ_FINISH )</CODE> calls. -<P> - -All required memory is allocated by <CODE>BZ2_bzCompressInit</CODE>. The -compression library can accept any data at all (obviously). So you -shouldn't get any error return values from the <CODE>BZ2_bzCompress</CODE> calls. -If you do, they will be <CODE>BZ_SEQUENCE_ERROR</CODE>, and indicate a bug in -your programming. -</P><P> - -Trivial other possible return values: -<TABLE><tr><td> </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->s</CODE> is <CODE>NULL</CODE> -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC21"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC20"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC22"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.3.3 <CODE>BZ2_bzCompressEnd</CODE> </H3> -<!--docid::SEC21::--> -<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzCompressEnd ( bz_stream *strm ); -</pre></td></tr></table>Releases all memory associated with a compression stream. -<P> - -Possible return values: -<TABLE><tr><td> </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->s</CODE> is <CODE>NULL</CODE> - <CODE>BZ_OK</CODE> otherwise -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC22"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC21"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC23"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.3.4 <CODE>BZ2_bzDecompressInit</CODE> </H3> -<!--docid::SEC22::--> -<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzDecompressInit ( bz_stream *strm, int verbosity, int small ); -</pre></td></tr></table>Prepares for decompression. As with <CODE>BZ2_bzCompressInit</CODE>, a -<CODE>bz_stream</CODE> record should be allocated and initialised before the -call. Fields <CODE>bzalloc</CODE>, <CODE>bzfree</CODE> and <CODE>opaque</CODE> should be -set if a custom memory allocator is required, or made <CODE>NULL</CODE> for -the normal <CODE>malloc</CODE>/<CODE>free</CODE> routines. Upon return, the internal -state will have been initialised, and <CODE>total_in</CODE> and -<CODE>total_out</CODE> will be zero. -<P> - -For the meaning of parameter <CODE>verbosity</CODE>, see <CODE>BZ2_bzCompressInit</CODE>. -</P><P> - -If <CODE>small</CODE> is nonzero, the library will use an alternative -decompression algorithm which uses less memory but at the cost of -decompressing more slowly (roughly speaking, half the speed, but the -maximum memory requirement drops to around 2300k). See Chapter 2 for -more information on memory management. -</P><P> - -Note that the amount of memory needed to decompress -a stream cannot be determined until the stream's header has been read, -so even if <CODE>BZ2_bzDecompressInit</CODE> succeeds, a subsequent -<CODE>BZ2_bzDecompress</CODE> could fail with <CODE>BZ_MEM_ERROR</CODE>. -</P><P> - -Possible return values: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE> - if the library has been mis-compiled - <CODE>BZ_PARAM_ERROR</CODE> - if <CODE>(small != 0 && small != 1)</CODE> - or <CODE>(verbosity < 0 || verbosity > 4)</CODE> - <CODE>BZ_MEM_ERROR</CODE> - if insufficient memory is available -</pre></td></tr></table></P><P> - -Allowable next actions: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzDecompress</CODE> - if <CODE>BZ_OK</CODE> was returned - no specific action required in case of error -</pre></td></tr></table></P><P> - - -</P><P> - -<HR SIZE="6"> -<A NAME="SEC23"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC22"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC24"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.3.5 <CODE>BZ2_bzDecompress</CODE> </H3> -<!--docid::SEC23::--> -<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzDecompress ( bz_stream *strm ); -</pre></td></tr></table>Provides more input and/out output buffer space for the library. The -caller maintains input and output buffers, and uses <CODE>BZ2_bzDecompress</CODE> -to transfer data between them. -<P> - -Before each call to <CODE>BZ2_bzDecompress</CODE>, <CODE>next_in</CODE> -should point at the compressed data, -and <CODE>avail_in</CODE> should indicate how many bytes the library -may read. <CODE>BZ2_bzDecompress</CODE> updates <CODE>next_in</CODE>, <CODE>avail_in</CODE> -and <CODE>total_in</CODE> -to reflect the number of bytes it has read. -</P><P> - -Similarly, <CODE>next_out</CODE> should point to a buffer in which the uncompressed -output is to be placed, with <CODE>avail_out</CODE> indicating how much output space -is available. <CODE>BZ2_bzCompress</CODE> updates <CODE>next_out</CODE>, -<CODE>avail_out</CODE> and <CODE>total_out</CODE> to reflect -the number of bytes output. -</P><P> - -You may provide and remove as little or as much data as you like on -each call of <CODE>BZ2_bzDecompress</CODE>. -In the limit, it is acceptable to -supply and remove data one byte at a time, although this would be -terribly inefficient. You should always ensure that at least one -byte of output space is available at each call. -</P><P> - -Use of <CODE>BZ2_bzDecompress</CODE> is simpler than <CODE>BZ2_bzCompress</CODE>. -</P><P> - -You should provide input and remove output as described above, and -repeatedly call <CODE>BZ2_bzDecompress</CODE> until <CODE>BZ_STREAM_END</CODE> is -returned. Appearance of <CODE>BZ_STREAM_END</CODE> denotes that -<CODE>BZ2_bzDecompress</CODE> has detected the logical end of the compressed -stream. <CODE>BZ2_bzDecompress</CODE> will not produce <CODE>BZ_STREAM_END</CODE> until -all output data has been placed into the output buffer, so once -<CODE>BZ_STREAM_END</CODE> appears, you are guaranteed to have available all -the decompressed output, and <CODE>BZ2_bzDecompressEnd</CODE> can safely be -called. -</P><P> - -If case of an error return value, you should call <CODE>BZ2_bzDecompressEnd</CODE> -to clean up and release memory. -</P><P> - -Possible return values: -<TABLE><tr><td> </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->s</CODE> is <CODE>NULL</CODE> - or <CODE>strm->avail_out < 1</CODE> - <CODE>BZ_DATA_ERROR</CODE> - if a data integrity error is detected in the compressed stream - <CODE>BZ_DATA_ERROR_MAGIC</CODE> - if the compressed stream doesn't begin with the right magic bytes - <CODE>BZ_MEM_ERROR</CODE> - if there wasn't enough memory available - <CODE>BZ_STREAM_END</CODE> - if the logical end of the data stream was detected and all - output in has been consumed, eg <CODE>s->avail_out > 0</CODE> - <CODE>BZ_OK</CODE> - otherwise -</pre></td></tr></table>Allowable next actions: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzDecompress</CODE> - if <CODE>BZ_OK</CODE> was returned - <CODE>BZ2_bzDecompressEnd</CODE> - otherwise -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC24"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC23"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC25"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.3.6 <CODE>BZ2_bzDecompressEnd</CODE> </H3> -<!--docid::SEC24::--> -<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzDecompressEnd ( bz_stream *strm ); -</pre></td></tr></table>Releases all memory associated with a decompression stream. -<P> - -Possible return values: -<TABLE><tr><td> </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->s</CODE> is <CODE>NULL</CODE> - <CODE>BZ_OK</CODE> - otherwise -</pre></td></tr></table></P><P> - -Allowable next actions: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> None. -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC25"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC24"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC26"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H2> 3.4 High-level interface </H2> -<!--docid::SEC25::--> -<P> - -This interface provides functions for reading and writing -<CODE>bzip2</CODE> format files. First, some general points. -</P><P> - -<UL> -<LI>All of the functions take an <CODE>int*</CODE> first argument, - <CODE>bzerror</CODE>. - After each call, <CODE>bzerror</CODE> should be consulted first to determine - the outcome of the call. If <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>, - the call completed - successfully, and only then should the return value of the function - (if any) be consulted. If <CODE>bzerror</CODE> is <CODE>BZ_IO_ERROR</CODE>, - there was an error - reading/writing the underlying compressed file, and you should - then consult <CODE>errno</CODE>/<CODE>perror</CODE> to determine the - cause of the difficulty. - <CODE>bzerror</CODE> may also be set to various other values; precise details are - given on a per-function basis below. -<LI>If <CODE>bzerror</CODE> indicates an error - (ie, anything except <CODE>BZ_OK</CODE> and <CODE>BZ_STREAM_END</CODE>), - you should immediately call <CODE>BZ2_bzReadClose</CODE> (or <CODE>BZ2_bzWriteClose</CODE>, - depending on whether you are attempting to read or to write) - to free up all resources associated - with the stream. Once an error has been indicated, behaviour of all calls - except <CODE>BZ2_bzReadClose</CODE> (<CODE>BZ2_bzWriteClose</CODE>) is undefined. - The implication is that (1) <CODE>bzerror</CODE> should - be checked after each call, and (2) if <CODE>bzerror</CODE> indicates an error, - <CODE>BZ2_bzReadClose</CODE> (<CODE>BZ2_bzWriteClose</CODE>) should then be called to clean up. -<LI>The <CODE>FILE*</CODE> arguments passed to - <CODE>BZ2_bzReadOpen</CODE>/<CODE>BZ2_bzWriteOpen</CODE> - should be set to binary mode. - Most Unix systems will do this by default, but other platforms, - including Windows and Mac, will not. If you omit this, you may - encounter problems when moving code to new platforms. -<LI>Memory allocation requests are handled by - <CODE>malloc</CODE>/<CODE>free</CODE>. - At present - there is no facility for user-defined memory allocators in the file I/O - functions (could easily be added, though). -</UL> -<P> - -<HR SIZE="6"> -<A NAME="SEC26"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC25"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC27"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.4.1 <CODE>BZ2_bzReadOpen</CODE> </H3> -<!--docid::SEC26::--> -<TABLE><tr><td> </td><td class=example><pre> typedef void BZFILE; - - BZFILE *BZ2_bzReadOpen ( int *bzerror, FILE *f, - int small, int verbosity, - void *unused, int nUnused ); -</pre></td></tr></table>Prepare to read compressed data from file handle <CODE>f</CODE>. <CODE>f</CODE> -should refer to a file which has been opened for reading, and for which -the error indicator (<CODE>ferror(f)</CODE>)is not set. If <CODE>small</CODE> is 1, -the library will try to decompress using less memory, at the expense of -speed. -<P> - -For reasons explained below, <CODE>BZ2_bzRead</CODE> will decompress the -<CODE>nUnused</CODE> bytes starting at <CODE>unused</CODE>, before starting to read -from the file <CODE>f</CODE>. At most <CODE>BZ_MAX_UNUSED</CODE> bytes may be -supplied like this. If this facility is not required, you should pass -<CODE>NULL</CODE> and <CODE>0</CODE> for <CODE>unused</CODE> and n<CODE>Unused</CODE> -respectively. -</P><P> - -For the meaning of parameters <CODE>small</CODE> and <CODE>verbosity</CODE>, -see <CODE>BZ2_bzDecompressInit</CODE>. -</P><P> - -The amount of memory needed to decompress a file cannot be determined -until the file's header has been read. So it is possible that -<CODE>BZ2_bzReadOpen</CODE> returns <CODE>BZ_OK</CODE> but a subsequent call of -<CODE>BZ2_bzRead</CODE> will return <CODE>BZ_MEM_ERROR</CODE>. -</P><P> - -Possible assignments to <CODE>bzerror</CODE>: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE> - if the library has been mis-compiled - <CODE>BZ_PARAM_ERROR</CODE> - if <CODE>f</CODE> is <CODE>NULL</CODE> - or <CODE>small</CODE> is neither <CODE>0</CODE> nor <CODE>1</CODE> - or <CODE>(unused == NULL && nUnused != 0)</CODE> - or <CODE>(unused != NULL && !(0 <= nUnused <= BZ_MAX_UNUSED))</CODE> - <CODE>BZ_IO_ERROR</CODE> - if <CODE>ferror(f)</CODE> is nonzero - <CODE>BZ_MEM_ERROR</CODE> - if insufficient memory is available - <CODE>BZ_OK</CODE> - otherwise. -</pre></td></tr></table></P><P> - -Possible return values: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> Pointer to an abstract <CODE>BZFILE</CODE> - if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE> - <CODE>NULL</CODE> - otherwise -</pre></td></tr></table></P><P> - -Allowable next actions: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzRead</CODE> - if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE> - <CODE>BZ2_bzClose</CODE> - otherwise -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC27"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC26"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC28"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.4.2 <CODE>BZ2_bzRead</CODE> </H3> -<!--docid::SEC27::--> -<TABLE><tr><td> </td><td class=example><pre> int BZ2_bzRead ( int *bzerror, BZFILE *b, void *buf, int len ); -</pre></td></tr></table>Reads up to <CODE>len</CODE> (uncompressed) bytes from the compressed file -<CODE>b</CODE> into -the buffer <CODE>buf</CODE>. If the read was successful, -<CODE>bzerror</CODE> is set to <CODE>BZ_OK</CODE> -and the number of bytes read is returned. If the logical end-of-stream -was detected, <CODE>bzerror</CODE> will be set to <CODE>BZ_STREAM_END</CODE>, -and the number -of bytes read is returned. All other <CODE>bzerror</CODE> values denote an error. -<P> - -<CODE>BZ2_bzRead</CODE> will supply <CODE>len</CODE> bytes, -unless the logical stream end is detected -or an error occurs. Because of this, it is possible to detect the -stream end by observing when the number of bytes returned is -less than the number -requested. Nevertheless, this is regarded as inadvisable; you should -instead check <CODE>bzerror</CODE> after every call and watch out for -<CODE>BZ_STREAM_END</CODE>. -</P><P> - -Internally, <CODE>BZ2_bzRead</CODE> copies data from the compressed file in chunks -of size <CODE>BZ_MAX_UNUSED</CODE> bytes -before decompressing it. If the file contains more bytes than strictly -needed to reach the logical end-of-stream, <CODE>BZ2_bzRead</CODE> will almost certainly -read some of the trailing data before signalling <CODE>BZ_SEQUENCE_END</CODE>. -To collect the read but unused data once <CODE>BZ_SEQUENCE_END</CODE> has -appeared, call <CODE>BZ2_bzReadGetUnused</CODE> immediately before <CODE>BZ2_bzReadClose</CODE>. -</P><P> - -Possible assignments to <CODE>bzerror</CODE>: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_PARAM_ERROR</CODE> - if <CODE>b</CODE> is <CODE>NULL</CODE> or <CODE>buf</CODE> is <CODE>NULL</CODE> or <CODE>len < 0</CODE> - <CODE>BZ_SEQUENCE_ERROR</CODE> - if <CODE>b</CODE> was opened with <CODE>BZ2_bzWriteOpen</CODE> - <CODE>BZ_IO_ERROR</CODE> - if there is an error reading from the compressed file - <CODE>BZ_UNEXPECTED_EOF</CODE> - if the compressed file ended before the logical end-of-stream was detected - <CODE>BZ_DATA_ERROR</CODE> - if a data integrity error was detected in the compressed stream - <CODE>BZ_DATA_ERROR_MAGIC</CODE> - if the stream does not begin with the requisite header bytes (ie, is not - a <CODE>bzip2</CODE> data file). This is really a special case of <CODE>BZ_DATA_ERROR</CODE>. - <CODE>BZ_MEM_ERROR</CODE> - if insufficient memory was available - <CODE>BZ_STREAM_END</CODE> - if the logical end of stream was detected. - <CODE>BZ_OK</CODE> - otherwise. -</pre></td></tr></table></P><P> - -Possible return values: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> number of bytes read - if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE> or <CODE>BZ_STREAM_END</CODE> - undefined - otherwise -</pre></td></tr></table></P><P> - -Allowable next actions: -<TABLE><tr><td> </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> - if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE> - collect data from <CODE>buf</CODE>, then <CODE>BZ2_bzReadClose</CODE> or <CODE>BZ2_bzReadGetUnused</CODE> - if <CODE>bzerror</CODE> is <CODE>BZ_SEQUENCE_END</CODE> - <CODE>BZ2_bzReadClose</CODE> - otherwise -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC28"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC27"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC29"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.4.3 <CODE>BZ2_bzReadGetUnused</CODE> </H3> -<!--docid::SEC28::--> -<TABLE><tr><td> </td><td class=example><pre> void BZ2_bzReadGetUnused ( int* bzerror, BZFILE *b, - void** unused, int* nUnused ); -</pre></td></tr></table>Returns data which was read from the compressed file but was not needed -to get to the logical end-of-stream. <CODE>*unused</CODE> is set to the address -of the data, and <CODE>*nUnused</CODE> to the number of bytes. <CODE>*nUnused</CODE> will -be set to a value between <CODE>0</CODE> and <CODE>BZ_MAX_UNUSED</CODE> inclusive. -<P> - -This function may only be called once <CODE>BZ2_bzRead</CODE> has signalled -<CODE>BZ_STREAM_END</CODE> but before <CODE>BZ2_bzReadClose</CODE>. -</P><P> - -Possible assignments to <CODE>bzerror</CODE>: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_PARAM_ERROR</CODE> - if <CODE>b</CODE> is <CODE>NULL</CODE> - or <CODE>unused</CODE> is <CODE>NULL</CODE> or <CODE>nUnused</CODE> is <CODE>NULL</CODE> - <CODE>BZ_SEQUENCE_ERROR</CODE> - if <CODE>BZ_STREAM_END</CODE> has not been signalled - or if <CODE>b</CODE> was opened with <CODE>BZ2_bzWriteOpen</CODE> - <CODE>BZ_OK</CODE> - otherwise -</pre></td></tr></table></P><P> - -Allowable next actions: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzReadClose</CODE> -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC29"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC28"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC30"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.4.4 <CODE>BZ2_bzReadClose</CODE> </H3> -<!--docid::SEC29::--> -<TABLE><tr><td> </td><td class=example><pre> void BZ2_bzReadClose ( int *bzerror, BZFILE *b ); -</pre></td></tr></table>Releases all memory pertaining to the compressed file <CODE>b</CODE>. -<CODE>BZ2_bzReadClose</CODE> does not call <CODE>fclose</CODE> on the underlying file -handle, so you should do that yourself if appropriate. -<CODE>BZ2_bzReadClose</CODE> should be called to clean up after all error -situations. -<P> - -Possible assignments to <CODE>bzerror</CODE>: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_SEQUENCE_ERROR</CODE> - if <CODE>b</CODE> was opened with <CODE>BZ2_bzOpenWrite</CODE> - <CODE>BZ_OK</CODE> - otherwise -</pre></td></tr></table></P><P> - -Allowable next actions: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> none -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC30"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC29"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC31"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.4.5 <CODE>BZ2_bzWriteOpen</CODE> </H3> -<!--docid::SEC30::--> -<TABLE><tr><td> </td><td class=example><pre> BZFILE *BZ2_bzWriteOpen ( int *bzerror, FILE *f, - int blockSize100k, int verbosity, - int workFactor ); -</pre></td></tr></table>Prepare to write compressed data to file handle <CODE>f</CODE>. -<CODE>f</CODE> should refer to -a file which has been opened for writing, and for which the error -indicator (<CODE>ferror(f)</CODE>)is not set. -<P> - -For the meaning of parameters <CODE>blockSize100k</CODE>, -<CODE>verbosity</CODE> and <CODE>workFactor</CODE>, see -<BR> <CODE>BZ2_bzCompressInit</CODE>. -</P><P> - -All required memory is allocated at this stage, so if the call -completes successfully, <CODE>BZ_MEM_ERROR</CODE> cannot be signalled by a -subsequent call to <CODE>BZ2_bzWrite</CODE>. -</P><P> - -Possible assignments to <CODE>bzerror</CODE>: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE> - if the library has been mis-compiled - <CODE>BZ_PARAM_ERROR</CODE> - if <CODE>f</CODE> is <CODE>NULL</CODE> - or <CODE>blockSize100k < 1</CODE> or <CODE>blockSize100k > 9</CODE> - <CODE>BZ_IO_ERROR</CODE> - if <CODE>ferror(f)</CODE> is nonzero - <CODE>BZ_MEM_ERROR</CODE> - if insufficient memory is available - <CODE>BZ_OK</CODE> - otherwise -</pre></td></tr></table></P><P> - -Possible return values: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> Pointer to an abstract <CODE>BZFILE</CODE> - if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE> - <CODE>NULL</CODE> - otherwise -</pre></td></tr></table></P><P> - -Allowable next actions: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzWrite</CODE> - if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE> - (you could go directly to <CODE>BZ2_bzWriteClose</CODE>, but this would be pretty pointless) - <CODE>BZ2_bzWriteClose</CODE> - otherwise -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC31"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC30"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC32"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.4.6 <CODE>BZ2_bzWrite</CODE> </H3> -<!--docid::SEC31::--> -<TABLE><tr><td> </td><td class=example><pre> void BZ2_bzWrite ( int *bzerror, BZFILE *b, void *buf, int len ); -</pre></td></tr></table>Absorbs <CODE>len</CODE> bytes from the buffer <CODE>buf</CODE>, eventually to be -compressed and written to the file. -<P> - -Possible assignments to <CODE>bzerror</CODE>: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_PARAM_ERROR</CODE> - if <CODE>b</CODE> is <CODE>NULL</CODE> or <CODE>buf</CODE> is <CODE>NULL</CODE> or <CODE>len < 0</CODE> - <CODE>BZ_SEQUENCE_ERROR</CODE> - if b was opened with <CODE>BZ2_bzReadOpen</CODE> - <CODE>BZ_IO_ERROR</CODE> - if there is an error writing the compressed file. - <CODE>BZ_OK</CODE> - otherwise -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC32"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC31"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC33"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.4.7 <CODE>BZ2_bzWriteClose</CODE> </H3> -<!--docid::SEC32::--> -<TABLE><tr><td> </td><td class=example><pre> void BZ2_bzWriteClose ( int *bzerror, BZFILE* f, - int abandon, - unsigned int* nbytes_in, - unsigned int* nbytes_out ); - - void BZ2_bzWriteClose64 ( int *bzerror, BZFILE* f, - int abandon, - unsigned int* nbytes_in_lo32, - unsigned int* nbytes_in_hi32, - unsigned int* nbytes_out_lo32, - unsigned int* nbytes_out_hi32 ); -</pre></td></tr></table><P> - -Compresses and flushes to the compressed file all data so far supplied -by <CODE>BZ2_bzWrite</CODE>. The logical end-of-stream markers are also written, so -subsequent calls to <CODE>BZ2_bzWrite</CODE> are illegal. All memory associated -with the compressed file <CODE>b</CODE> is released. -<CODE>fflush</CODE> is called on the -compressed file, but it is not <CODE>fclose</CODE>'d. -</P><P> - -If <CODE>BZ2_bzWriteClose</CODE> is called to clean up after an error, the only -action is to release the memory. The library records the error codes -issued by previous calls, so this situation will be detected -automatically. There is no attempt to complete the compression -operation, nor to <CODE>fflush</CODE> the compressed file. You can force this -behaviour to happen even in the case of no error, by passing a nonzero -value to <CODE>abandon</CODE>. -</P><P> - -If <CODE>nbytes_in</CODE> is non-null, <CODE>*nbytes_in</CODE> will be set to be the -total volume of uncompressed data handled. Similarly, <CODE>nbytes_out</CODE> -will be set to the total volume of compressed data written. For -compatibility with older versions of the library, <CODE>BZ2_bzWriteClose</CODE> -only yields the lower 32 bits of these counts. Use -<CODE>BZ2_bzWriteClose64</CODE> if you want the full 64 bit counts. These -two functions are otherwise absolutely identical. -</P><P> - -Possible assignments to <CODE>bzerror</CODE>: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_SEQUENCE_ERROR</CODE> - if <CODE>b</CODE> was opened with <CODE>BZ2_bzReadOpen</CODE> - <CODE>BZ_IO_ERROR</CODE> - if there is an error writing the compressed file - <CODE>BZ_OK</CODE> - otherwise -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC33"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC32"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC34"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.4.8 Handling embedded compressed data streams </H3> -<!--docid::SEC33::--> -<P> - -The high-level library facilitates use of -<CODE>bzip2</CODE> data streams which form some part of a surrounding, larger -data stream. -<UL> -<LI>For writing, the library takes an open file handle, writes -compressed data to it, <CODE>fflush</CODE>es it but does not <CODE>fclose</CODE> it. -The calling application can write its own data before and after the -compressed data stream, using that same file handle. -<LI>Reading is more complex, and the facilities are not as general -as they could be since generality is hard to reconcile with efficiency. -<CODE>BZ2_bzRead</CODE> reads from the compressed file in blocks of size -<CODE>BZ_MAX_UNUSED</CODE> bytes, and in doing so probably will overshoot -the logical end of compressed stream. -To recover this data once decompression has -ended, call <CODE>BZ2_bzReadGetUnused</CODE> after the last call of <CODE>BZ2_bzRead</CODE> -(the one returning <CODE>BZ_STREAM_END</CODE>) but before calling -<CODE>BZ2_bzReadClose</CODE>. -</UL> -<P> - -This mechanism makes it easy to decompress multiple <CODE>bzip2</CODE> -streams placed end-to-end. As the end of one stream, when <CODE>BZ2_bzRead</CODE> -returns <CODE>BZ_STREAM_END</CODE>, call <CODE>BZ2_bzReadGetUnused</CODE> to collect the -unused data (copy it into your own buffer somewhere). -That data forms the start of the next compressed stream. -To start uncompressing that next stream, call <CODE>BZ2_bzReadOpen</CODE> again, -feeding in the unused data via the <CODE>unused</CODE>/<CODE>nUnused</CODE> -parameters. -Keep doing this until <CODE>BZ_STREAM_END</CODE> return coincides with the -physical end of file (<CODE>feof(f)</CODE>). In this situation -<CODE>BZ2_bzReadGetUnused</CODE> -will of course return no data. -</P><P> - -This should give some feel for how the high-level interface can be used. -If you require extra flexibility, you'll have to bite the bullet and get -to grips with the low-level interface. -</P><P> - -<HR SIZE="6"> -<A NAME="SEC34"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC33"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC35"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.4.9 Standard file-reading/writing code </H3> -<!--docid::SEC34::--> -Here's how you'd write data to a compressed file: -<TABLE><tr><td> </td><td class=example><pre>FILE* f; -BZFILE* b; -int nBuf; -char buf[ /* whatever size you like */ ]; -int bzerror; -int nWritten; - -f = fopen ( "myfile.bz2", "w" ); -if (!f) { - /* handle error */ -} -b = BZ2_bzWriteOpen ( &bzerror, f, 9 ); -if (bzerror != BZ_OK) { - BZ2_bzWriteClose ( b ); - /* handle error */ -} - -while ( /* condition */ ) { - /* get data to write into buf, and set nBuf appropriately */ - nWritten = BZ2_bzWrite ( &bzerror, b, buf, nBuf ); - if (bzerror == BZ_IO_ERROR) { - BZ2_bzWriteClose ( &bzerror, b ); - /* handle error */ - } -} - -BZ2_bzWriteClose ( &bzerror, b ); -if (bzerror == BZ_IO_ERROR) { - /* handle error */ -} -</pre></td></tr></table>And to read from a compressed file: -<TABLE><tr><td> </td><td class=example><pre>FILE* f; -BZFILE* b; -int nBuf; -char buf[ /* whatever size you like */ ]; -int bzerror; -int nWritten; - -f = fopen ( "myfile.bz2", "r" ); -if (!f) { - /* handle error */ -} -b = BZ2_bzReadOpen ( &bzerror, f, 0, NULL, 0 ); -if (bzerror != BZ_OK) { - BZ2_bzReadClose ( &bzerror, b ); - /* handle error */ -} - -bzerror = BZ_OK; -while (bzerror == BZ_OK && /* arbitrary other conditions */) { - nBuf = BZ2_bzRead ( &bzerror, b, buf, /* size of buf */ ); - if (bzerror == BZ_OK) { - /* do something with buf[0 .. nBuf-1] */ - } -} -if (bzerror != BZ_STREAM_END) { - BZ2_bzReadClose ( &bzerror, b ); - /* handle error */ -} else { - BZ2_bzReadClose ( &bzerror ); -} -</pre></td></tr></table><P> - -<HR SIZE="6"> -<A NAME="SEC35"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC34"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC36"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H2> 3.5 Utility functions </H2> -<!--docid::SEC35::--> -<HR SIZE="6"> -<A NAME="SEC36"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC35"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC37"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.5.1 <CODE>BZ2_bzBuffToBuffCompress</CODE> </H3> -<!--docid::SEC36::--> -<TABLE><tr><td> </td><td class=example><pre> int BZ2_bzBuffToBuffCompress( char* dest, - unsigned int* destLen, - char* source, - unsigned int sourceLen, - int blockSize100k, - int verbosity, - int workFactor ); -</pre></td></tr></table>Attempts to compress the data in <CODE>source[0 .. sourceLen-1]</CODE> -into the destination buffer, <CODE>dest[0 .. *destLen-1]</CODE>. -If the destination buffer is big enough, <CODE>*destLen</CODE> is -set to the size of the compressed data, and <CODE>BZ_OK</CODE> is -returned. If the compressed data won't fit, <CODE>*destLen</CODE> -is unchanged, and <CODE>BZ_OUTBUFF_FULL</CODE> is returned. -<P> - -Compression in this manner is a one-shot event, done with a single call -to this function. The resulting compressed data is a complete -<CODE>bzip2</CODE> format data stream. There is no mechanism for making -additional calls to provide extra input data. If you want that kind of -mechanism, use the low-level interface. -</P><P> - -For the meaning of parameters <CODE>blockSize100k</CODE>, <CODE>verbosity</CODE> -and <CODE>workFactor</CODE>, <BR> see <CODE>BZ2_bzCompressInit</CODE>. -</P><P> - -To guarantee that the compressed data will fit in its buffer, allocate -an output buffer of size 1% larger than the uncompressed data, plus -six hundred extra bytes. -</P><P> - -<CODE>BZ2_bzBuffToBuffDecompress</CODE> will not write data at or -beyond <CODE>dest[*destLen]</CODE>, even in case of buffer overflow. -</P><P> - -Possible return values: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE> - if the library has been mis-compiled - <CODE>BZ_PARAM_ERROR</CODE> - if <CODE>dest</CODE> is <CODE>NULL</CODE> or <CODE>destLen</CODE> is <CODE>NULL</CODE> - or <CODE>blockSize100k < 1</CODE> or <CODE>blockSize100k > 9</CODE> - or <CODE>verbosity < 0</CODE> or <CODE>verbosity > 4</CODE> - or <CODE>workFactor < 0</CODE> or <CODE>workFactor > 250</CODE> - <CODE>BZ_MEM_ERROR</CODE> - if insufficient memory is available - <CODE>BZ_OUTBUFF_FULL</CODE> - if the size of the compressed data exceeds <CODE>*destLen</CODE> - <CODE>BZ_OK</CODE> - otherwise -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC37"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC36"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC38"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.5.2 <CODE>BZ2_bzBuffToBuffDecompress</CODE> </H3> -<!--docid::SEC37::--> -<TABLE><tr><td> </td><td class=example><pre> int BZ2_bzBuffToBuffDecompress ( char* dest, - unsigned int* destLen, - char* source, - unsigned int sourceLen, - int small, - int verbosity ); -</pre></td></tr></table>Attempts to decompress the data in <CODE>source[0 .. sourceLen-1]</CODE> -into the destination buffer, <CODE>dest[0 .. *destLen-1]</CODE>. -If the destination buffer is big enough, <CODE>*destLen</CODE> is -set to the size of the uncompressed data, and <CODE>BZ_OK</CODE> is -returned. If the compressed data won't fit, <CODE>*destLen</CODE> -is unchanged, and <CODE>BZ_OUTBUFF_FULL</CODE> is returned. -<P> - -<CODE>source</CODE> is assumed to hold a complete <CODE>bzip2</CODE> format -data stream. <BR> <CODE>BZ2_bzBuffToBuffDecompress</CODE> tries to decompress -the entirety of the stream into the output buffer. -</P><P> - -For the meaning of parameters <CODE>small</CODE> and <CODE>verbosity</CODE>, -see <CODE>BZ2_bzDecompressInit</CODE>. -</P><P> - -Because the compression ratio of the compressed data cannot be known in -advance, there is no easy way to guarantee that the output buffer will -be big enough. You may of course make arrangements in your code to -record the size of the uncompressed data, but such a mechanism is beyond -the scope of this library. -</P><P> - -<CODE>BZ2_bzBuffToBuffDecompress</CODE> will not write data at or -beyond <CODE>dest[*destLen]</CODE>, even in case of buffer overflow. -</P><P> - -Possible return values: -<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE> - if the library has been mis-compiled - <CODE>BZ_PARAM_ERROR</CODE> - if <CODE>dest</CODE> is <CODE>NULL</CODE> or <CODE>destLen</CODE> is <CODE>NULL</CODE> - or <CODE>small != 0 && small != 1</CODE> - or <CODE>verbosity < 0</CODE> or <CODE>verbosity > 4</CODE> - <CODE>BZ_MEM_ERROR</CODE> - if insufficient memory is available - <CODE>BZ_OUTBUFF_FULL</CODE> - if the size of the compressed data exceeds <CODE>*destLen</CODE> - <CODE>BZ_DATA_ERROR</CODE> - if a data integrity error was detected in the compressed data - <CODE>BZ_DATA_ERROR_MAGIC</CODE> - if the compressed data doesn't begin with the right magic bytes - <CODE>BZ_UNEXPECTED_EOF</CODE> - if the compressed data ends unexpectedly - <CODE>BZ_OK</CODE> - otherwise -</pre></td></tr></table></P><P> - -<HR SIZE="6"> -<A NAME="SEC38"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC37"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC39"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H2> 3.6 <CODE>zlib</CODE> compatibility functions </H2> -<!--docid::SEC38::--> -Yoshioka Tsuneo has contributed some functions to -give better <CODE>zlib</CODE> compatibility. These functions are -<CODE>BZ2_bzopen</CODE>, <CODE>BZ2_bzread</CODE>, <CODE>BZ2_bzwrite</CODE>, <CODE>BZ2_bzflush</CODE>, -<CODE>BZ2_bzclose</CODE>, -<CODE>BZ2_bzerror</CODE> and <CODE>BZ2_bzlibVersion</CODE>. -These functions are not (yet) officially part of -the library. If they break, you get to keep all the pieces. -Nevertheless, I think they work ok. -<TABLE><tr><td> </td><td class=example><pre>typedef void BZFILE; - -const char * BZ2_bzlibVersion ( void ); -</pre></td></tr></table>Returns a string indicating the library version. -<TABLE><tr><td> </td><td class=example><pre>BZFILE * BZ2_bzopen ( const char *path, const char *mode ); -BZFILE * BZ2_bzdopen ( int fd, const char *mode ); -</pre></td></tr></table>Opens a <CODE>.bz2</CODE> file for reading or writing, using either its name -or a pre-existing file descriptor. -Analogous to <CODE>fopen</CODE> and <CODE>fdopen</CODE>. -<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzread ( BZFILE* b, void* buf, int len ); -int BZ2_bzwrite ( BZFILE* b, void* buf, int len ); -</pre></td></tr></table>Reads/writes data from/to a previously opened <CODE>BZFILE</CODE>. -Analogous to <CODE>fread</CODE> and <CODE>fwrite</CODE>. -<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzflush ( BZFILE* b ); -void BZ2_bzclose ( BZFILE* b ); -</pre></td></tr></table>Flushes/closes a <CODE>BZFILE</CODE>. <CODE>BZ2_bzflush</CODE> doesn't actually do -anything. Analogous to <CODE>fflush</CODE> and <CODE>fclose</CODE>. -<P> - -<TABLE><tr><td> </td><td class=example><pre>const char * BZ2_bzerror ( BZFILE *b, int *errnum ) -</pre></td></tr></table>Returns a string describing the more recent error status of -<CODE>b</CODE>, and also sets <CODE>*errnum</CODE> to its numerical value. -</P><P> - -<HR SIZE="6"> -<A NAME="SEC39"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC38"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC40"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H2> 3.7 Using the library in a <CODE>stdio</CODE>-free environment </H2> -<!--docid::SEC39::--> -<P> - -<HR SIZE="6"> -<A NAME="SEC40"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC39"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC41"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.7.1 Getting rid of <CODE>stdio</CODE> </H3> -<!--docid::SEC40::--> -<P> - -In a deeply embedded application, you might want to use just -the memory-to-memory functions. You can do this conveniently -by compiling the library with preprocessor symbol <CODE>BZ_NO_STDIO</CODE> -defined. Doing this gives you a library containing only the following -eight functions: -</P><P> - -<CODE>BZ2_bzCompressInit</CODE>, <CODE>BZ2_bzCompress</CODE>, <CODE>BZ2_bzCompressEnd</CODE> <BR> -<CODE>BZ2_bzDecompressInit</CODE>, <CODE>BZ2_bzDecompress</CODE>, <CODE>BZ2_bzDecompressEnd</CODE> <BR> -<CODE>BZ2_bzBuffToBuffCompress</CODE>, <CODE>BZ2_bzBuffToBuffDecompress</CODE> -</P><P> - -When compiled like this, all functions will ignore <CODE>verbosity</CODE> -settings. -</P><P> - -<HR SIZE="6"> -<A NAME="SEC41"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC40"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC42"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H3> 3.7.2 Critical error handling </H3> -<!--docid::SEC41::--> -<CODE>libbzip2</CODE> contains a number of internal assertion checks which -should, needless to say, never be activated. Nevertheless, if an -assertion should fail, behaviour depends on whether or not the library -was compiled with <CODE>BZ_NO_STDIO</CODE> set. -<P> - -For a normal compile, an assertion failure yields the message -<TABLE><tr><td> </td><td class=example><pre> bzip2/libbzip2: internal error number N. - This is a bug in bzip2/libbzip2, 1.0.2, 30-Dec-2001. - Please report it to me at: jseward@acm.org. If this happened - when you were using some program which uses libbzip2 as a - component, you should also report this bug to the author(s) - of that program. Please make an effort to report this bug; - timely and accurate bug reports eventually lead to higher - quality software. Thanks. Julian Seward, 30 December 2001. -</pre></td></tr></table>where <CODE>N</CODE> is some error code number. If <CODE>N == 1007</CODE>, it also -prints some extra text advising the reader that unreliable memory is -often associated with internal error 1007. (This is a -frequently-observed-phenomenon with versions 1.0.0/1.0.1). -</P><P> - -<CODE>exit(3)</CODE> is then called. -</P><P> - -For a <CODE>stdio</CODE>-free library, assertion failures result -in a call to a function declared as: -<TABLE><tr><td> </td><td class=example><pre> extern void bz_internal_error ( int errcode ); -</pre></td></tr></table>The relevant code is passed as a parameter. You should supply -such a function. -</P><P> - -In either case, once an assertion failure has occurred, any -<CODE>bz_stream</CODE> records involved can be regarded as invalid. -You should not attempt to resume normal operation with them. -</P><P> - -You may, of course, change critical error handling to suit -your needs. As I said above, critical errors indicate bugs -in the library and should not occur. All "normal" error -situations are indicated via error return codes from functions, -and can be recovered from. -</P><P> - -<HR SIZE="6"> -<A NAME="SEC42"></A> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC41"> < </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_4.html#SEC43"> > </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<H2> 3.8 Making a Windows DLL </H2> -<!--docid::SEC42::--> -Everything related to Windows has been contributed by Yoshioka Tsuneo -<BR> (<CODE>QWF00133@niftyserve.or.jp</CODE> / -<CODE>tsuneo-y@is.aist-nara.ac.jp</CODE>), so you should send your queries to -him (but perhaps Cc: me, <CODE>jseward@acm.org</CODE>). -<P> - -My vague understanding of what to do is: using Visual C++ 5.0, -open the project file <CODE>libbz2.dsp</CODE>, and build. That's all. -</P><P> - -If you can't -open the project file for some reason, make a new one, naming these files: -<CODE>blocksort.c</CODE>, <CODE>bzlib.c</CODE>, <CODE>compress.c</CODE>, -<CODE>crctable.c</CODE>, <CODE>decompress.c</CODE>, <CODE>huffman.c</CODE>, <BR> -<CODE>randtable.c</CODE> and <CODE>libbz2.def</CODE>. You will also need -to name the header files <CODE>bzlib.h</CODE> and <CODE>bzlib_private.h</CODE>. -</P><P> - -If you don't use VC++, you may need to define the proprocessor symbol -<CODE>_WIN32</CODE>. -</P><P> - -Finally, <CODE>dlltest.c</CODE> is a sample program using the DLL. It has a -project file, <CODE>dlltest.dsp</CODE>. -</P><P> - -If you just want a makefile for Visual C, have a look at -<CODE>makefile.msc</CODE>. -</P><P> - -Be aware that if you compile <CODE>bzip2</CODE> itself on Win32, you must set -<CODE>BZ_UNIX</CODE> to 0 and <CODE>BZ_LCCWIN32</CODE> to 1, in the file -<CODE>bzip2.c</CODE>, before compiling. Otherwise the resulting binary won't -work correctly. -</P><P> - -I haven't tried any of this stuff myself, but it all looks plausible. -</P><P> - -<HR SIZE="6"> -<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0> -<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD> -<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD> -</TR></TABLE> -<BR> -<FONT SIZE="-1"> -This document was generated -by <I>Julian Seward</I> on <I>January, 5 2002</I> -using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html -"><I>texi2html</I></A> - -</BODY> -</HTML> |