manual_3.html

bzip2是一个免费的

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"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC19"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
<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>
<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"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC20"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[ &lt;&lt; ]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[ &gt;&gt; ]</TD>
<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>
<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>&nbsp;</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 &#60;&#60; 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>&nbsp;</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> &#60; 1 or <CODE>blockSize</CODE> &#62; 9
         or <CODE>verbosity</CODE> &#60; 0 or <CODE>verbosity</CODE> &#62; 4
         or <CODE>workFactor</CODE> &#60; 0 or <CODE>workFactor</CODE> &#62; 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>&nbsp;</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"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC21"> &gt; </A>]</TD>