manual_3.html

bzip2是一个免费的

Allowable next actions:
<TABLE><tr><td>&nbsp;</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"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC24"> &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.5 <CODE>BZ2_bzDecompress</CODE> </H3>
<!--docid::SEC23::-->
<TABLE><tr><td>&nbsp;</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>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_PARAM_ERROR</CODE>
         if <CODE>strm</CODE> is <CODE>NULL</CODE> or <CODE>strm-&#62;s</CODE> is <CODE>NULL</CODE>
         or <CODE>strm-&#62;avail_out &#60; 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-&#62;avail_out &#62; 0</CODE>
      <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_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"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC25"> &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.6 <CODE>BZ2_bzDecompressEnd</CODE> </H3>
<!--docid::SEC24::-->
<TABLE><tr><td>&nbsp;</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>&nbsp;</td><td class=display><pre style="font-family: serif">      <CODE>BZ_PARAM_ERROR</CODE>
         if <CODE>strm</CODE> is <CODE>NULL</CODE> or <CODE>strm-&#62;s</CODE> is <CODE>NULL</CODE>
      <CODE>BZ_OK</CODE>
         otherwise
</pre></td></tr></table></P><P>

Allowable next actions:
<TABLE><tr><td>&nbsp;</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"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC26"> &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.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"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC27"> &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.4.1 <CODE>BZ2_bzReadOpen</CODE> </H3>
<!--docid::SEC26::-->
<TABLE><tr><td>&nbsp;</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>&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>f</CODE> is <CODE>NULL</CODE> 
         or <CODE>small</CODE> is neither <CODE>0</CODE> nor <CODE>1</CODE>                 
         or <CODE>(unused == NULL &#38;&#38; nUnused != 0)</CODE>
         or <CODE>(unused != NULL &#38;&#38; !(0 &#60;= nUnused &#60;= 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>&nbsp;</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>&nbsp;</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