1856 lines
92 KiB
HTML
1856 lines
92 KiB
HTML
<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>
|