manual_3.html

高效率的一种通用压缩/解压程序

<P>
This interface provides functions for reading and writing 
<CODE>bzip2</CODE> format files.  First, some general points.

</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>bzReadClose</CODE> (or <CODE>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>bzReadClose</CODE> (<CODE>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>bzReadClose</CODE> (<CODE>bzWriteClose</CODE>) should then be called to clean up.
<LI>The <CODE>FILE*</CODE> arguments passed to

   <CODE>bzReadOpen</CODE>/<CODE>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>



<H3><A NAME="SEC17" HREF="manual_toc.html#TOC17"><CODE>bzReadOpen</CODE></A></H3>

<PRE>
   typedef void BZFILE;

   BZFILE *bzReadOpen ( int *bzerror, FILE *f, 
                        int small, int verbosity,
                        void *unused, int nUnused );
</PRE>

<P>
Prepare to read compressed data from file handle <CODE>f</CODE>.  <CODE>f</CODE>
should refer to a file which has been opened for reading, and for which
the error indicator (<CODE>ferror(f)</CODE>)is not set.  If <CODE>small</CODE> is 1,
the library will try to decompress using less memory, at the expense of
speed.

</P>
<P>
For reasons explained below, <CODE>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>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>bzReadOpen</CODE> returns <CODE>BZ_OK</CODE> but a subsequent call of
<CODE>bzRead</CODE> will return <CODE>BZ_MEM_ERROR</CODE>.

</P>
<P>
Possible assignments to <CODE>bzerror</CODE>:

<PRE>
      <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>

<P>
Possible return values:

<PRE>
      Pointer to an abstract <CODE>BZFILE</CODE>        
         if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>   
      <CODE>NULL</CODE>
         otherwise
</PRE>

<P>
Allowable next actions:

<PRE>
      <CODE>bzRead</CODE>
         if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>   
      <CODE>bzClose</CODE> 
         otherwise
</PRE>



<H3><A NAME="SEC18" HREF="manual_toc.html#TOC18"><CODE>bzRead</CODE></A></H3>

<PRE>
   int bzRead ( int *bzerror, BZFILE *b, void *buf, int len );
</PRE>

<P>
Reads up to <CODE>len</CODE> (uncompressed) bytes from the compressed file 
<CODE>b</CODE> into
the buffer <CODE>buf</CODE>.  If the read was successful, 
<CODE>bzerror</CODE> is set to <CODE>BZ_OK</CODE>
and the number of bytes read is returned.  If the logical end-of-stream
was detected, <CODE>bzerror</CODE> will be set to <CODE>BZ_STREAM_END</CODE>, 
and the number
of bytes read is returned.  All other <CODE>bzerror</CODE> values denote an error.

</P>
<P>
<CODE>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>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>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>bzReadGetUnused</CODE> immediately before <CODE>bzReadClose</CODE>.

</P>
<P>
Possible assignments to <CODE>bzerror</CODE>:

<PRE>
      <CODE>BZ_PARAM_ERROR</CODE>
         if <CODE>b</CODE> is <CODE>NULL</CODE> or <CODE>buf</CODE> is <CODE>NULL</CODE> or <CODE>len &#60; 0</CODE>
      <CODE>BZ_SEQUENCE_ERROR</CODE> 
         if <CODE>b</CODE> was opened with <CODE>bzWriteOpen</CODE>
      <CODE>BZ_IO_ERROR</CODE> 
         if there is an error reading from the compressed file
      <CODE>BZ_UNEXPECTED_EOF</CODE> 
         if the compressed file ended before the logical end-of-stream was detected
      <CODE>BZ_DATA_ERROR</CODE> 
         if a data integrity error was detected in the compressed stream
      <CODE>BZ_DATA_ERROR_MAGIC</CODE>
         if the stream does not begin with the requisite header bytes (ie, is not 
         a <CODE>bzip2</CODE> data file).  This is really a special case of <CODE>BZ_DATA_ERROR</CODE>.
      <CODE>BZ_MEM_ERROR</CODE> 
         if insufficient memory was available
      <CODE>BZ_STREAM_END</CODE> 
         if the logical end of stream was detected.
      <CODE>BZ_OK</CODE>
         otherwise.
</PRE>

<P>
Possible return values:

<PRE>
      number of bytes read
         if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE> or <CODE>BZ_STREAM_END</CODE>
      undefined
         otherwise
</PRE>

<P>
Allowable next actions:

<PRE>
      collect data from <CODE>buf</CODE>, then <CODE>bzRead</CODE> or <CODE>bzReadClose</CODE>
         if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE> 
      collect data from <CODE>buf</CODE>, then <CODE>bzReadClose</CODE> or <CODE>bzReadGetUnused</CODE> 
         if <CODE>bzerror</CODE> is <CODE>BZ_SEQUENCE_END</CODE>   
      <CODE>bzReadClose</CODE> 
         otherwise
</PRE>



<H3><A NAME="SEC19" HREF="manual_toc.html#TOC19"><CODE>bzReadGetUnused</CODE></A></H3>

<PRE>
   void bzReadGetUnused ( int* bzerror, BZFILE *b, 
                          void** unused, int* nUnused );
</PRE>

<P>
Returns data which was read from the compressed file but was not needed
to get to the logical end-of-stream.  <CODE>*unused</CODE> is set to the address
of the data, and <CODE>*nUnused</CODE> to the number of bytes.  <CODE>*nUnused</CODE> will
be set to a value between <CODE>0</CODE> and <CODE>BZ_MAX_UNUSED</CODE> inclusive.

</P>
<P>
This function may only be called once <CODE>bzRead</CODE> has signalled 
<CODE>BZ_STREAM_END</CODE> but before <CODE>bzReadClose</CODE>.

</P>
<P>
Possible assignments to <CODE>bzerror</CODE>:

<PRE>
      <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>bzWriteOpen</CODE>
     <CODE>BZ_OK</CODE>
         otherwise
</PRE>

<P>
Allowable next actions:

<PRE>
      <CODE>bzReadClose</CODE>
</PRE>



<H3><A NAME="SEC20" HREF="manual_toc.html#TOC20"><CODE>bzReadClose</CODE></A></H3>

<PRE>
   void bzReadClose ( int *bzerror, BZFILE *b );
</PRE>

<P>
Releases all memory pertaining to the compressed file <CODE>b</CODE>.  
<CODE>bzReadClose</CODE> does not call <CODE>fclose</CODE> on the underlying file
handle, so you should do that yourself if appropriate.
<CODE>bzReadClose</CODE> should be called to clean up after all error
situations.

</P>
<P>
Possible assignments to <CODE>bzerror</CODE>:

<PRE>
      <CODE>BZ_SEQUENCE_ERROR</CODE> 
         if <CODE>b</CODE> was opened with <CODE>bzOpenWrite</CODE> 
      <CODE>BZ_OK</CODE> 
         otherwise
</PRE>

<P>
Allowable next actions:

<PRE>
      none
</PRE>



<H3><A NAME="SEC21" HREF="manual_toc.html#TOC21"><CODE>bzWriteOpen</CODE></A></H3>

<PRE>
   BZFILE *bzWriteOpen ( int *bzerror, FILE *f, 
                         int blockSize100k, int verbosity,
                         int workFactor );
</PRE>

<P>
Prepare to write compressed data to file handle <CODE>f</CODE>.  
<CODE>f</CODE> should refer to
a file which has been opened for writing, and for which the error
indicator (<CODE>ferror(f)</CODE>)is not set.  

</P>
<P>
For the meaning of parameters <CODE>blockSize100k</CODE>,
<CODE>verbosity</CODE> and <CODE>workFactor</CODE>, see
<BR> <CODE>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>bzWrite</CODE>.

</P>
<P>
Possible assignments to <CODE>bzerror</CODE>:

<PRE>
      <CODE>BZ_PARAM_ERROR</CODE> 
         if <CODE>f</CODE> is <CODE>NULL</CODE> 
         or <CODE>blockSize100k &#60; 1</CODE> or <CODE>blockSize100k &#62; 9</CODE>
      <CODE>BZ_IO_ERROR</CODE> 
         if <CODE>ferror(f)</CODE> is nonzero
      <CODE>BZ_MEM_ERROR</CODE> 
         if insufficient memory is available
      <CODE>BZ_OK</CODE> 
         otherwise
</PRE>

<P>
Possible return values:

<PRE>
      Pointer to an abstract <CODE>BZFILE</CODE>  
         if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>   
      <CODE>NULL</CODE> 
         otherwise
</PRE>

<P>
Allowable next actions:

<PRE>
      <CODE>bzWrite</CODE> 
         if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE> 
         (you could go directly to <CODE>bzWriteClose</CODE>, but this would be pretty pointless)
      <CODE>bzWriteClose</CODE> 
         otherwise
</PRE>



<H3><A NAME="SEC22" HREF="manual_toc.html#TOC22"><CODE>bzWrite</CODE></A></H3>

<PRE>
   void bzWrite ( int *bzerror, BZFILE *b, void *buf, int len );
</PRE>

<P>
Absorbs <CODE>len</CODE> bytes from the buffer <CODE>buf</CODE>, eventually to be
compressed and written to the file.

</P>
<P>
Possible assignments to <CODE>bzerror</CODE>:

<PRE>
      <CODE>BZ_PARAM_ERROR</CODE> 
         if <CODE>b</CODE> is <CODE>NULL</CODE> or <CODE>buf</CODE> is <CODE>NULL</CODE> or <CODE>len &#60; 0</CODE>
      <CODE>BZ_SEQUENCE_ERROR</CODE> 
         if b was opened with <CODE>bzReadOpen</CODE>
      <CODE>BZ_IO_ERROR</CODE> 
         if there is an error writing the compressed file.
      <CODE>BZ_OK</CODE> 
         otherwise
</PRE>



<H3><A NAME="SEC23" HREF="manual_toc.html#TOC23"><CODE>bzWriteClose</CODE></A></H3>

<PRE>
   int bzWriteClose ( int *bzerror, BZFILE* f,
                      int abandon,
                      unsigned int* nbytes_in,
                      unsigned int* nbytes_out );
</PRE>

<P>
Compresses and flushes to the compressed file all data so far supplied
by <CODE>bzWrite</CODE>.  The logical end-of-stream markers are also written, so
subsequent calls to <CODE>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>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>.