manual.texi

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

and @code{bzWriteOpen} for attempts to use a file for which the
error indicator (viz, @code{ferror(f)}) is set.
On receipt of @code{BZ_IO_ERROR}, the caller should consult
@code{errno} and/or @code{perror} to acquire operating-system
specific information about the problem.
@item BZ_UNEXPECTED_EOF
Returned by @code{bzRead} when the compressed file finishes
before the logical end of stream is detected.
@item BZ_OUTBUFF_FULL
Returned by @code{bzBuffToBuffCompress} and
@code{bzBuffToBuffDecompress} to indicate that the output data
will not fit into the output buffer provided.
@end table



@section Low-level interface

@subsection @code{bzCompressInit}
@example
typedef 
   struct @{
      char *next_in;
      unsigned int avail_in;
      unsigned int total_in;

      char *next_out;
      unsigned int avail_out;
      unsigned int total_out;

      void *state;

      void *(*bzalloc)(void *,int,int);
      void (*bzfree)(void *,void *);
      void *opaque;
   @} 
   bz_stream;

int bzCompressInit ( bz_stream *strm, 
                     int blockSize100k, 
                     int verbosity,
                     int workFactor );

@end example

Prepares for compression.  The @code{bz_stream} structure
holds all data pertaining to the compression activity.  
A @code{bz_stream} structure should be allocated and initialised
prior to the call.
The fields of @code{bz_stream}
comprise the entirety of the user-visible data.  @code{state}
is a pointer to the private data structures required for compression.

Custom memory allocators are supported, via fields @code{bzalloc}, 
@code{bzfree},
and @code{opaque}.  The value 
@code{opaque} is passed to as the first argument to
all calls to @code{bzalloc} and @code{bzfree}, but is 
otherwise ignored by the library.
The call @code{bzalloc ( opaque, n, m )} is expected to return a 
pointer @code{p} to
@code{n * m} bytes of memory, and @code{bzfree ( opaque, p )} 
should free
that memory.

If you don't want to use a custom memory allocator, set @code{bzalloc}, 
@code{bzfree} and
@code{opaque} to @code{NULL}, 
and the library will then use the standard @code{malloc}/@code{free}
routines.

Before calling @code{bzCompressInit}, fields @code{bzalloc}, 
@code{bzfree} and @code{opaque} should
be filled appropriately, as just described.  Upon return, the internal
state will have been allocated and initialised, and @code{total_in} and 
@code{total_out} will have been set to zero.  
These last two 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.

Parameter @code{blockSize100k} 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.

Parameter @code{verbosity} 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}, no such output will appear for any verbosity
setting.

Parameter @code{workFactor} controls how the compression phase behaves
when presented with worst case, highly repetitive, input data.
If compression runs into difficulties caused by repetitive data,
some pseudo-random variations are inserted into the block, and
compression is restarted.  Lower values of @code{workFactor}
reduce the tolerance of compression to repetitive data.
You should set this parameter carefully; too low, and 
compression ratio suffers, 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.

Allowable values range from 0 to 250 inclusive.  0 is a special
case, equivalent to using the default value of 30.

Note that the randomisation process is entirely transparent.  
If the library decides to randomise and restart compression on a
block, it does so without comment.  Randomised blocks are
automatically de-randomised during decompression, so data
integrity is never compromised.

Possible return values:
@display
      @code{BZ_PARAM_ERROR} 
         if @code{strm} is @code{NULL} 
         or @code{blockSize} < 1 or @code{blockSize} > 9
         or @code{verbosity} < 0 or @code{verbosity} > 4
         or @code{workFactor} < 0 or @code{workFactor} > 250
      @code{BZ_MEM_ERROR} 
         if not enough memory is available
      @code{BZ_OK} 
         otherwise
@end display
Allowable next actions:
@display
      @code{bzCompress} 
         if @code{BZ_OK} is returned
      no specific action needed in case of error
@end display

@subsection @code{bzCompress}
@example
   int bzCompress ( bz_stream *strm, int action );
@end example
Provides more input and/or output buffer space for the library.  The
caller maintains input and output buffers, and calls @code{bzCompress} to
transfer data between them.

Before each call to @code{bzCompress}, @code{next_in} should point at
the data to be compressed, and @code{avail_in} should indicate how many
bytes the library may read.  @code{bzCompress} updates @code{next_in},
@code{avail_in} and @code{total_in} to reflect the number of bytes it
has read.

Similarly, @code{next_out} should point to a buffer in which the
compressed data is to be placed, with @code{avail_out} indicating how
much output space is available.  @code{bzCompress} updates
@code{next_out}, @code{avail_out} and @code{total_out} to reflect the
number of bytes output.

You may provide and remove as little or as much data as you like on each
call of @code{bzCompress}.  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.

A second purpose of @code{bzCompress} is to request a change of mode of the
compressed stream.  

Conceptually, a compressed stream can be in one of four states: IDLE,
RUNNING, FLUSHING and FINISHING.  Before initialisation
(@code{bzCompressInit}) and after termination (@code{bzCompressEnd}), a
stream is regarded as IDLE.

Upon initialisation (@code{bzCompressInit}), the stream is placed in the
RUNNING state.  Subsequent calls to @code{bzCompress} should pass
@code{BZ_RUN} as the requested action; other actions are illegal and
will result in @code{BZ_SEQUENCE_ERROR}.

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{bzCompress} will no longer attempt to read data from
@code{next_in}, but it will want to write data to @code{next_out}.
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{bzCompress}.

Instead, the calling program passes @code{BZ_FINISH} as an action to
@code{bzCompress}.  This changes the stream's state to FINISHING.  Any
remaining input (ie, @code{next_in[0 .. avail_in-1]}) is compressed and
transferred to the output buffer.  To do this, @code{bzCompress} must be
called repeatedly until all the output has been consumed.  At that
point, @code{bzCompress} returns @code{BZ_STREAM_END}, and the stream's
state is set back to IDLE.  @code{bzCompressEnd} should then be
called.

Just to make sure the calling program does not cheat, the library makes
a note of @code{avail_in} at the time of the first call to
@code{bzCompress} which has @code{BZ_FINISH} 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} over
subsequent calls to @code{bzCompress}, 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}.  This indicates a
programming mistake which should be corrected.

Instead of asking to finish, the calling program may ask
@code{bzCompress} 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{bzCompress} with an action of
@code{BZ_FLUSH}, remove output data, and persist with the
@code{BZ_FLUSH} action until the value @code{BZ_RUN} is returned.  As
with finishing, @code{bzCompress} detects any attempt to provide more
input data once the flush has begun.

Once the flush is complete, the stream returns to the normal RUNNING
state.

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{bzCompress}.
@display
IDLE/@code{any}           
      Illegal.  IDLE state only exists after @code{bzCompressEnd} or
      before @code{bzCompressInit}.
      Return value = @code{BZ_SEQUENCE_ERROR}

RUNNING/@code{BZ_RUN}     
      Compress from @code{next_in} to @code{next_out} as much as possible.
      Next state = RUNNING
      Return value = @code{BZ_RUN_OK}

RUNNING/@code{BZ_FLUSH}   
      Remember current value of @code{next_in}.  Compress from @code{next_in}
      to @code{next_out} as much as possible, but do not accept any more input.  
      Next state = FLUSHING
      Return value = @code{BZ_FLUSH_OK}

RUNNING/@code{BZ_FINISH}  
      Remember current value of @code{next_in}.  Compress from @code{next_in}
      to @code{next_out} as much as possible, but do not accept any more input.
      Next state = FINISHING
      Return value = @code{BZ_FINISH_OK}

FLUSHING/@code{BZ_FLUSH}  
      Compress from @code{next_in} to @code{next_out} 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}
      else
         Next state = FLUSHING; Return value = @code{BZ_FLUSH_OK}

FLUSHING/other     
      Illegal.
      Return value = @code{BZ_SEQUENCE_ERROR}

FINISHING/@code{BZ_FINISH}  
      Compress from @code{next_in} to @code{next_out} 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}
      else
         Next state = FINISHING; Return value = @code{BZ_FINISHING}

FINISHING/other
      Illegal.
      Return value = @code{BZ_SEQUENCE_ERROR}
@end display

That still looks complicated?  Well, fair enough.  The usual sequence
of calls for compressing a load of data is:
@itemize @bullet
@item Get started with @code{bzCompressInit}.
@item Shovel data in and shlurp out its compressed form using zero or more
calls of @code{bzCompress} with action = @code{BZ_RUN}.
@item Finish up.  
Repeatedly call @code{bzCompress} with action = @code{BZ_FINISH}, 
copying out the compressed output, until @code{BZ_STREAM_END} is returned.
@item Close up and go home.  Call @code{bzCompressEnd}.
@end itemize
If the data you want to compress fits into your input buffer all
at once, you can skip the calls of @code{bzCompress ( ..., BZ_RUN )} and 
just do the @code{bzCompress ( ..., BZ_FINISH )} calls.

All required memory is allocated by @code{bzCompressInit}.  The
compression library can accept any data at all (obviously).  So you
shouldn't get any error return values from the @code{bzCompress} calls.
If you do, they will be @code{BZ_SEQUENCE_ERROR}, and indicate a bug in
your programming.

Trivial other possible return values:
@display
      @code{BZ_PARAM_ERROR}   
         if @code{strm} is @code{NULL}, or @code{strm->s} is @code{NULL}
@end display

@subsection @code{bzCompressEnd}
@example
int bzCompressEnd ( bz_stream *strm );
@end example
Releases all memory associated with a compression stream.

Possible return values:
@display
   @code{BZ_PARAM_ERROR}    if @code{strm} is @code{NULL} or @code{strm->s} is @code{NULL}
   @code{BZ_OK}    otherwise
@end display


@subsection @code{bzDecompressInit}
@example
int bzDecompressInit ( bz_stream *strm, int verbosity, int small );
@end example
Prepares for decompression.  As with @code{bzCompressInit}, a
@code{bz_stream} record should be allocated and initialised before the
call.  Fields @code{bzalloc}, @code{bzfree} and @code{opaque} should be
set if a custom memory allocator is required, or made @code{NULL} for
the normal @code{malloc}/@code{free} routines.  Upon return, the internal
state will have been initialised, and @code{total_in} and
@code{total_out} will be zero.

For the meaning of parameter @code{verbosity}, see @code{bzCompressInit}.

If @code{small} 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.

Note that the amount of memory needed to decompress
a stream cannot be determined until the stream's header has been read,