Context Navigation

manual_3.html @ 17062

Visit:

Revision 17062, 92.4 KB checked in by ghudson, 23 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r17061, which included commits to RCS files with non-trunk default branches.

Line
1	<HTML>
2	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
3	<!-- Created on January, 5 2002 by texi2html 1.64 -->
4	<!--
5	Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
6	Karl Berry <karl@freefriends.org>
7	Olaf Bachmann <obachman@mathematik.uni-kl.de>
8	and many others.
9	Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
10	Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
11
12	-->
13	<HEAD>
14	<TITLE>Untitled Document: 3. Programming with <CODE>libbzip2</CODE></TITLE>
15
16	<META NAME="description" CONTENT="Untitled Document: 3. Programming with <CODE>libbzip2</CODE>">
17	<META NAME="keywords" CONTENT="Untitled Document: 3. Programming with <CODE>libbzip2</CODE>">
18	<META NAME="resource-type" CONTENT="document">
19	<META NAME="distribution" CONTENT="global">
20	<META NAME="Generator" CONTENT="texi2html 1.64">
21
22	</HEAD>
23
24	<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
25
26	<A NAME="SEC12"></A>
27	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
28	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_2.html#SEC11"> < </A>]</TD>
29	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC13"> > </A>]</TD>
30	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
31	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
32	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
33	<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>
34	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
35	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
36	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
37	</TR></TABLE>
38	<H1> 3. Programming with <CODE>libbzip2</CODE> </H1>
39	<!--docid::SEC12::-->
40	<P>
41
42	This chapter describes the programming interface to <CODE>libbzip2</CODE>.
43	</P><P>
44
45	For general background information, particularly about memory
46	use and performance aspects, you'd be well advised to read Chapter 2
47	as well.
48	</P><P>
49
50	<HR SIZE="6">
51	<A NAME="SEC13"></A>
52	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
53	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC12"> < </A>]</TD>
54	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC14"> > </A>]</TD>
55	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
56	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
57	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
58	<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>
59	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
60	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
61	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
62	</TR></TABLE>
63	<H2> 3.1 Top-level structure </H2>
64	<!--docid::SEC13::-->
65	<P>
66
67	<CODE>libbzip2</CODE> is a flexible library for compressing and decompressing
68	data in the <CODE>bzip2</CODE> data format. Although packaged as a single
69	entity, it helps to regard the library as three separate parts: the low
70	level interface, and the high level interface, and some utility
71	functions.
72	</P><P>
73
74	The structure of <CODE>libbzip2</CODE>'s interfaces is similar to
75	that of Jean-loup Gailly's and Mark Adler's excellent <CODE>zlib</CODE>
76	library.
77	</P><P>
78
79	All externally visible symbols have names beginning <CODE>BZ2_</CODE>.
80	This is new in version 1.0. The intention is to minimise pollution
81	of the namespaces of library clients.
82	</P><P>
83
84	<HR SIZE="6">
85	<A NAME="SEC14"></A>
86	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
87	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC13"> < </A>]</TD>
88	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC15"> > </A>]</TD>
89	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
90	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
91	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
92	<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>
93	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
94	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
95	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
96	</TR></TABLE>
97	<H3> 3.1.1 Low-level summary </H3>
98	<!--docid::SEC14::-->
99	<P>
100
101	This interface provides services for compressing and decompressing
102	data in memory. There's no provision for dealing with files, streams
103	or any other I/O mechanisms, just straight memory-to-memory work.
104	In fact, this part of the library can be compiled without inclusion
105	of <CODE>stdio.h</CODE>, which may be helpful for embedded applications.
106	</P><P>
107
108	The low-level part of the library has no global variables and
109	is therefore thread-safe.
110	</P><P>
111
112	Six routines make up the low level interface:
113	<CODE>BZ2_bzCompressInit</CODE>, <CODE>BZ2_bzCompress</CODE>, and <BR> <CODE>BZ2_bzCompressEnd</CODE>
114	for compression,
115	and a corresponding trio <CODE>BZ2_bzDecompressInit</CODE>, <BR> <CODE>BZ2_bzDecompress</CODE>
116	and <CODE>BZ2_bzDecompressEnd</CODE> for decompression.
117	The <CODE>*Init</CODE> functions allocate
118	memory for compression/decompression and do other
119	initialisations, whilst the <CODE>*End</CODE> functions close down operations
120	and release memory.
121	</P><P>
122
123	The real work is done by <CODE>BZ2_bzCompress</CODE> and <CODE>BZ2_bzDecompress</CODE>.
124	These compress and decompress data from a user-supplied input buffer
125	to a user-supplied output buffer. These buffers can be any size;
126	arbitrary quantities of data are handled by making repeated calls
127	to these functions. This is a flexible mechanism allowing a
128	consumer-pull style of activity, or producer-push, or a mixture of
129	both.
130	</P><P>
131
132	<HR SIZE="6">
133	<A NAME="SEC15"></A>
134	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
135	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC14"> < </A>]</TD>
136	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC16"> > </A>]</TD>
137	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
138	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
139	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
140	<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>
141	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
142	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
143	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
144	</TR></TABLE>
145	<H3> 3.1.2 High-level summary </H3>
146	<!--docid::SEC15::-->
147	<P>
148
149	This interface provides some handy wrappers around the low-level
150	interface to facilitate reading and writing <CODE>bzip2</CODE> format
151	files (<CODE>.bz2</CODE> files). The routines provide hooks to facilitate
152	reading files in which the <CODE>bzip2</CODE> data stream is embedded
153	within some larger-scale file structure, or where there are
154	multiple <CODE>bzip2</CODE> data streams concatenated end-to-end.
155	</P><P>
156
157	For reading files, <CODE>BZ2_bzReadOpen</CODE>, <CODE>BZ2_bzRead</CODE>,
158	<CODE>BZ2_bzReadClose</CODE> and <BR> <CODE>BZ2_bzReadGetUnused</CODE> are supplied. For
159	writing files, <CODE>BZ2_bzWriteOpen</CODE>, <CODE>BZ2_bzWrite</CODE> and
160	<CODE>BZ2_bzWriteFinish</CODE> are available.
161	</P><P>
162
163	As with the low-level library, no global variables are used
164	so the library is per se thread-safe. However, if I/O errors
165	occur whilst reading or writing the underlying compressed files,
166	you may have to consult <CODE>errno</CODE> to determine the cause of
167	the error. In that case, you'd need a C library which correctly
168	supports <CODE>errno</CODE> in a multithreaded environment.
169	</P><P>
170
171	To make the library a little simpler and more portable,
172	<CODE>BZ2_bzReadOpen</CODE> and <CODE>BZ2_bzWriteOpen</CODE> require you to pass them file
173	handles (<CODE>FILE*</CODE>s) which have previously been opened for reading or
174	writing respectively. That avoids portability problems associated with
175	file operations and file attributes, whilst not being much of an
176	imposition on the programmer.
177	</P><P>
178
179	<HR SIZE="6">
180	<A NAME="SEC16"></A>
181	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
182	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC15"> < </A>]</TD>
183	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC17"> > </A>]</TD>
184	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
185	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
186	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
187	<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>
188	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
189	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
190	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
191	</TR></TABLE>
192	<H3> 3.1.3 Utility functions summary </H3>
193	<!--docid::SEC16::-->
194	For very simple needs, <CODE>BZ2_bzBuffToBuffCompress</CODE> and
195	<CODE>BZ2_bzBuffToBuffDecompress</CODE> are provided. These compress
196	data in memory from one buffer to another buffer in a single
197	function call. You should assess whether these functions
198	fulfill your memory-to-memory compression/decompression
199	requirements before investing effort in understanding the more
200	general but more complex low-level interface.
201	<P>
202
203	Yoshioka Tsuneo (<CODE>QWF00133@niftyserve.or.jp</CODE> /
204	<CODE>tsuneo-y@is.aist-nara.ac.jp</CODE>) has contributed some functions to
205	give better <CODE>zlib</CODE> compatibility. These functions are
206	<CODE>BZ2_bzopen</CODE>, <CODE>BZ2_bzread</CODE>, <CODE>BZ2_bzwrite</CODE>, <CODE>BZ2_bzflush</CODE>,
207	<CODE>BZ2_bzclose</CODE>,
208	<CODE>BZ2_bzerror</CODE> and <CODE>BZ2_bzlibVersion</CODE>. You may find these functions
209	more convenient for simple file reading and writing, than those in the
210	high-level interface. These functions are not (yet) officially part of
211	the library, and are minimally documented here. If they break, you
212	get to keep all the pieces. I hope to document them properly when time
213	permits.
214	</P><P>
215
216	Yoshioka also contributed modifications to allow the library to be
217	built as a Windows DLL.
218	</P><P>
219
220	<HR SIZE="6">
221	<A NAME="SEC17"></A>
222	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
223	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC16"> < </A>]</TD>
224	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC18"> > </A>]</TD>
225	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
226	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
227	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
228	<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>
229	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
230	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
231	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
232	</TR></TABLE>
233	<H2> 3.2 Error handling </H2>
234	<!--docid::SEC17::-->
235	<P>
236
237	The library is designed to recover cleanly in all situations, including
238	the worst-case situation of decompressing random data. I'm not
239	100% sure that it can always do this, so you might want to add
240	a signal handler to catch segmentation violations during decompression
241	if you are feeling especially paranoid. I would be interested in
242	hearing more about the robustness of the library to corrupted
243	compressed data.
244	</P><P>
245
246	Version 1.0 is much more robust in this respect than
247	0.9.0 or 0.9.5. Investigations with Checker (a tool for
248	detecting problems with memory management, similar to Purify)
249	indicate that, at least for the few files I tested, all single-bit
250	errors in the decompressed data are caught properly, with no
251	segmentation faults, no reads of uninitialised data and no
252	out of range reads or writes. So it's certainly much improved,
253	although I wouldn't claim it to be totally bombproof.
254	</P><P>
255
256	The file <CODE>bzlib.h</CODE> contains all definitions needed to use
257	the library. In particular, you should definitely not include
258	<CODE>bzlib_private.h</CODE>.
259	</P><P>
260
261	In <CODE>bzlib.h</CODE>, the various return values are defined. The following
262	list is not intended as an exhaustive description of the circumstances
263	in which a given value may be returned -- those descriptions are given
264	later. Rather, it is intended to convey the rough meaning of each
265	return value. The first five actions are normal and not intended to
266	denote an error situation.
267	<DL COMPACT>
268	<DT><CODE>BZ_OK</CODE>
269	<DD>The requested action was completed successfully.
270	<DT><CODE>BZ_RUN_OK</CODE>
271	<DD><DT><CODE>BZ_FLUSH_OK</CODE>
272	<DD><DT><CODE>BZ_FINISH_OK</CODE>
273	<DD>In <CODE>BZ2_bzCompress</CODE>, the requested flush/finish/nothing-special action
274	was completed successfully.
275	<DT><CODE>BZ_STREAM_END</CODE>
276	<DD>Compression of data was completed, or the logical stream end was
277	detected during decompression.
278	</DL>
279	<P>
280
281	The following return values indicate an error of some kind.
282	<DL COMPACT>
283	<DT><CODE>BZ_CONFIG_ERROR</CODE>
284	<DD>Indicates that the library has been improperly compiled on your
285	platform -- a major configuration error. Specifically, it means
286	that <CODE>sizeof(char)</CODE>, <CODE>sizeof(short)</CODE> and <CODE>sizeof(int)</CODE>
287	are not 1, 2 and 4 respectively, as they should be. Note that the
288	library should still work properly on 64-bit platforms which follow
289	the LP64 programming model -- that is, where <CODE>sizeof(long)</CODE>
290	and <CODE>sizeof(void*)</CODE> are 8. Under LP64, <CODE>sizeof(int)</CODE> is
291	still 4, so <CODE>libbzip2</CODE>, which doesn't use the <CODE>long</CODE> type,
292	is OK.
293	<DT><CODE>BZ_SEQUENCE_ERROR</CODE>
294	<DD>When using the library, it is important to call the functions in the
295	correct sequence and with data structures (buffers etc) in the correct
296	states. <CODE>libbzip2</CODE> checks as much as it can to ensure this is
297	happening, and returns <CODE>BZ_SEQUENCE_ERROR</CODE> if not. Code which
298	complies precisely with the function semantics, as detailed below,
299	should never receive this value; such an event denotes buggy code
300	which you should investigate.
301	<DT><CODE>BZ_PARAM_ERROR</CODE>
302	<DD>Returned when a parameter to a function call is out of range
303	or otherwise manifestly incorrect. As with <CODE>BZ_SEQUENCE_ERROR</CODE>,
304	this denotes a bug in the client code. The distinction between
305	<CODE>BZ_PARAM_ERROR</CODE> and <CODE>BZ_SEQUENCE_ERROR</CODE> is a bit hazy, but still worth
306	making.
307	<DT><CODE>BZ_MEM_ERROR</CODE>
308	<DD>Returned when a request to allocate memory failed. Note that the
309	quantity of memory needed to decompress a stream cannot be determined
310	until the stream's header has been read. So <CODE>BZ2_bzDecompress</CODE> and
311	<CODE>BZ2_bzRead</CODE> may return <CODE>BZ_MEM_ERROR</CODE> even though some of
312	the compressed data has been read. The same is not true for
313	compression; once <CODE>BZ2_bzCompressInit</CODE> or <CODE>BZ2_bzWriteOpen</CODE> have
314	successfully completed, <CODE>BZ_MEM_ERROR</CODE> cannot occur.
315	<DT><CODE>BZ_DATA_ERROR</CODE>
316	<DD>Returned when a data integrity error is detected during decompression.
317	Most importantly, this means when stored and computed CRCs for the
318	data do not match. This value is also returned upon detection of any
319	other anomaly in the compressed data.
320	<DT><CODE>BZ_DATA_ERROR_MAGIC</CODE>
321	<DD>As a special case of <CODE>BZ_DATA_ERROR</CODE>, it is sometimes useful to
322	know when the compressed stream does not start with the correct
323	magic bytes (<CODE>'B' 'Z' 'h'</CODE>).
324	<DT><CODE>BZ_IO_ERROR</CODE>
325	<DD>Returned by <CODE>BZ2_bzRead</CODE> and <CODE>BZ2_bzWrite</CODE> when there is an error
326	reading or writing in the compressed file, and by <CODE>BZ2_bzReadOpen</CODE>
327	and <CODE>BZ2_bzWriteOpen</CODE> for attempts to use a file for which the
328	error indicator (viz, <CODE>ferror(f)</CODE>) is set.
329	On receipt of <CODE>BZ_IO_ERROR</CODE>, the caller should consult
330	<CODE>errno</CODE> and/or <CODE>perror</CODE> to acquire operating-system
331	specific information about the problem.
332	<DT><CODE>BZ_UNEXPECTED_EOF</CODE>
333	<DD>Returned by <CODE>BZ2_bzRead</CODE> when the compressed file finishes
334	before the logical end of stream is detected.
335	<DT><CODE>BZ_OUTBUFF_FULL</CODE>
336	<DD>Returned by <CODE>BZ2_bzBuffToBuffCompress</CODE> and
337	<CODE>BZ2_bzBuffToBuffDecompress</CODE> to indicate that the output data
338	will not fit into the output buffer provided.
339	</DL>
340	<P>
341
342	<HR SIZE="6">
343	<A NAME="SEC18"></A>
344	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
345	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC17"> < </A>]</TD>
346	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC19"> > </A>]</TD>
347	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
348	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
349	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
350	<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>
351	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
352	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
353	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
354	</TR></TABLE>
355	<H2> 3.3 Low-level interface </H2>
356	<!--docid::SEC18::-->
357	<P>
358
359	<HR SIZE="6">
360	<A NAME="SEC19"></A>
361	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
362	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC18"> < </A>]</TD>
363	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC20"> > </A>]</TD>
364	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
365	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
366	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
367	<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>
368	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
369	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
370	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
371	</TR></TABLE>
372	<H3> 3.3.1 <CODE>BZ2_bzCompressInit</CODE> </H3>
373	<!--docid::SEC19::-->
374	<TABLE><tr><td> </td><td class=example><pre>typedef
375	struct {
376	char *next_in;
377	unsigned int avail_in;
378	unsigned int total_in_lo32;
379	unsigned int total_in_hi32;
380
381	char *next_out;
382	unsigned int avail_out;
383	unsigned int total_out_lo32;
384	unsigned int total_out_hi32;
385
386	void *state;
387
388	void (bzalloc)(void *,int,int);
389	void (bzfree)(void ,void *);
390	void *opaque;
391	}
392	bz_stream;
393
394	int BZ2_bzCompressInit ( bz_stream *strm,
395	int blockSize100k,
396	int verbosity,
397	int workFactor );
398
399	</pre></td></tr></table><P>
400
401	Prepares for compression. The <CODE>bz_stream</CODE> structure
402	holds all data pertaining to the compression activity.
403	A <CODE>bz_stream</CODE> structure should be allocated and initialised
404	prior to the call.
405	The fields of <CODE>bz_stream</CODE>
406	comprise the entirety of the user-visible data. <CODE>state</CODE>
407	is a pointer to the private data structures required for compression.
408	</P><P>
409
410	Custom memory allocators are supported, via fields <CODE>bzalloc</CODE>,
411	<CODE>bzfree</CODE>,
412	and <CODE>opaque</CODE>. The value
413	<CODE>opaque</CODE> is passed to as the first argument to
414	all calls to <CODE>bzalloc</CODE> and <CODE>bzfree</CODE>, but is
415	otherwise ignored by the library.
416	The call <CODE>bzalloc ( opaque, n, m )</CODE> is expected to return a
417	pointer <CODE>p</CODE> to
418	<CODE>n * m</CODE> bytes of memory, and <CODE>bzfree ( opaque, p )</CODE>
419	should free
420	that memory.
421	</P><P>
422
423	If you don't want to use a custom memory allocator, set <CODE>bzalloc</CODE>,
424	<CODE>bzfree</CODE> and
425	<CODE>opaque</CODE> to <CODE>NULL</CODE>,
426	and the library will then use the standard <CODE>malloc</CODE>/<CODE>free</CODE>
427	routines.
428	</P><P>
429
430	Before calling <CODE>BZ2_bzCompressInit</CODE>, fields <CODE>bzalloc</CODE>,
431	<CODE>bzfree</CODE> and <CODE>opaque</CODE> should
432	be filled appropriately, as just described. Upon return, the internal
433	state will have been allocated and initialised, and <CODE>total_in_lo32</CODE>,
434	<CODE>total_in_hi32</CODE>, <CODE>total_out_lo32</CODE> and
435	<CODE>total_out_hi32</CODE> will have been set to zero.
436	These four fields are used by the library
437	to inform the caller of the total amount of data passed into and out of
438	the library, respectively. You should not try to change them.
439	As of version 1.0, 64-bit counts are maintained, even on 32-bit
440	platforms, using the <CODE>_hi32</CODE> fields to store the upper 32 bits
441	of the count. So, for example, the total amount of data in
442	is <CODE>(total_in_hi32 << 32) + total_in_lo32</CODE>.
443	</P><P>
444
445	Parameter <CODE>blockSize100k</CODE> specifies the block size to be used for
446	compression. It should be a value between 1 and 9 inclusive, and the
447	actual block size used is 100000 x this figure. 9 gives the best
448	compression but takes most memory.
449	</P><P>
450
451	Parameter <CODE>verbosity</CODE> should be set to a number between 0 and 4
452	inclusive. 0 is silent, and greater numbers give increasingly verbose
453	monitoring/debugging output. If the library has been compiled with
454	<CODE>-DBZ_NO_STDIO</CODE>, no such output will appear for any verbosity
455	setting.
456	</P><P>
457
458	Parameter <CODE>workFactor</CODE> controls how the compression phase behaves
459	when presented with worst case, highly repetitive, input data. If
460	compression runs into difficulties caused by repetitive data, the
461	library switches from the standard sorting algorithm to a fallback
462	algorithm. The fallback is slower than the standard algorithm by
463	perhaps a factor of three, but always behaves reasonably, no matter how
464	bad the input.
465	</P><P>
466
467	Lower values of <CODE>workFactor</CODE> reduce the amount of effort the
468	standard algorithm will expend before resorting to the fallback. You
469	should set this parameter carefully; too low, and many inputs will be
470	handled by the fallback algorithm and so compress rather slowly, too
471	high, and your average-to-worst case compression times can become very
472	large. The default value of 30 gives reasonable behaviour over a wide
473	range of circumstances.
474	</P><P>
475
476	Allowable values range from 0 to 250 inclusive. 0 is a special case,
477	equivalent to using the default value of 30.
478	</P><P>
479
480	Note that the compressed output generated is the same regardless of
481	whether or not the fallback algorithm is used.
482	</P><P>
483
484	Be aware also that this parameter may disappear entirely in future
485	versions of the library. In principle it should be possible to devise a
486	good way to automatically choose which algorithm to use. Such a
487	mechanism would render the parameter obsolete.
488	</P><P>
489
490	Possible return values:
491	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE>
492	if the library has been mis-compiled
493	<CODE>BZ_PARAM_ERROR</CODE>
494	if <CODE>strm</CODE> is <CODE>NULL</CODE>
495	or <CODE>blockSize</CODE> < 1 or <CODE>blockSize</CODE> > 9
496	or <CODE>verbosity</CODE> < 0 or <CODE>verbosity</CODE> > 4
497	or <CODE>workFactor</CODE> < 0 or <CODE>workFactor</CODE> > 250
498	<CODE>BZ_MEM_ERROR</CODE>
499	if not enough memory is available
500	<CODE>BZ_OK</CODE>
501	otherwise
502	</pre></td></tr></table>Allowable next actions:
503	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzCompress</CODE>
504	if <CODE>BZ_OK</CODE> is returned
505	no specific action needed in case of error
506	</pre></td></tr></table></P><P>
507
508	<HR SIZE="6">
509	<A NAME="SEC20"></A>
510	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
511	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC19"> < </A>]</TD>
512	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC21"> > </A>]</TD>
513	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
514	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
515	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
516	<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>
517	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
518	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
519	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
520	</TR></TABLE>
521	<H3> 3.3.2 <CODE>BZ2_bzCompress</CODE> </H3>
522	<!--docid::SEC20::-->
523	<TABLE><tr><td> </td><td class=example><pre> int BZ2_bzCompress ( bz_stream *strm, int action );
524	</pre></td></tr></table>Provides more input and/or output buffer space for the library. The
525	caller maintains input and output buffers, and calls <CODE>BZ2_bzCompress</CODE> to
526	transfer data between them.
527	<P>
528
529	Before each call to <CODE>BZ2_bzCompress</CODE>, <CODE>next_in</CODE> should point at
530	the data to be compressed, and <CODE>avail_in</CODE> should indicate how many
531	bytes the library may read. <CODE>BZ2_bzCompress</CODE> updates <CODE>next_in</CODE>,
532	<CODE>avail_in</CODE> and <CODE>total_in</CODE> to reflect the number of bytes it
533	has read.
534	</P><P>
535
536	Similarly, <CODE>next_out</CODE> should point to a buffer in which the
537	compressed data is to be placed, with <CODE>avail_out</CODE> indicating how
538	much output space is available. <CODE>BZ2_bzCompress</CODE> updates
539	<CODE>next_out</CODE>, <CODE>avail_out</CODE> and <CODE>total_out</CODE> to reflect the
540	number of bytes output.
541	</P><P>
542
543	You may provide and remove as little or as much data as you like on each
544	call of <CODE>BZ2_bzCompress</CODE>. In the limit, it is acceptable to supply and
545	remove data one byte at a time, although this would be terribly
546	inefficient. You should always ensure that at least one byte of output
547	space is available at each call.
548	</P><P>
549
550	A second purpose of <CODE>BZ2_bzCompress</CODE> is to request a change of mode of the
551	compressed stream.
552	</P><P>
553
554	Conceptually, a compressed stream can be in one of four states: IDLE,
555	RUNNING, FLUSHING and FINISHING. Before initialisation
556	(<CODE>BZ2_bzCompressInit</CODE>) and after termination (<CODE>BZ2_bzCompressEnd</CODE>), a
557	stream is regarded as IDLE.
558	</P><P>
559
560	Upon initialisation (<CODE>BZ2_bzCompressInit</CODE>), the stream is placed in the
561	RUNNING state. Subsequent calls to <CODE>BZ2_bzCompress</CODE> should pass
562	<CODE>BZ_RUN</CODE> as the requested action; other actions are illegal and
563	will result in <CODE>BZ_SEQUENCE_ERROR</CODE>.
564	</P><P>
565
566	At some point, the calling program will have provided all the input data
567	it wants to. It will then want to finish up -- in effect, asking the
568	library to process any data it might have buffered internally. In this
569	state, <CODE>BZ2_bzCompress</CODE> will no longer attempt to read data from
570	<CODE>next_in</CODE>, but it will want to write data to <CODE>next_out</CODE>.
571	Because the output buffer supplied by the user can be arbitrarily small,
572	the finishing-up operation cannot necessarily be done with a single call
573	of <CODE>BZ2_bzCompress</CODE>.
574	</P><P>
575
576	Instead, the calling program passes <CODE>BZ_FINISH</CODE> as an action to
577	<CODE>BZ2_bzCompress</CODE>. This changes the stream's state to FINISHING. Any
578	remaining input (ie, <CODE>next_in[0 .. avail_in-1]</CODE>) is compressed and
579	transferred to the output buffer. To do this, <CODE>BZ2_bzCompress</CODE> must be
580	called repeatedly until all the output has been consumed. At that
581	point, <CODE>BZ2_bzCompress</CODE> returns <CODE>BZ_STREAM_END</CODE>, and the stream's
582	state is set back to IDLE. <CODE>BZ2_bzCompressEnd</CODE> should then be
583	called.
584	</P><P>
585
586	Just to make sure the calling program does not cheat, the library makes
587	a note of <CODE>avail_in</CODE> at the time of the first call to
588	<CODE>BZ2_bzCompress</CODE> which has <CODE>BZ_FINISH</CODE> as an action (ie, at the
589	time the program has announced its intention to not supply any more
590	input). By comparing this value with that of <CODE>avail_in</CODE> over
591	subsequent calls to <CODE>BZ2_bzCompress</CODE>, the library can detect any
592	attempts to slip in more data to compress. Any calls for which this is
593	detected will return <CODE>BZ_SEQUENCE_ERROR</CODE>. This indicates a
594	programming mistake which should be corrected.
595	</P><P>
596
597	Instead of asking to finish, the calling program may ask
598	<CODE>BZ2_bzCompress</CODE> to take all the remaining input, compress it and
599	terminate the current (Burrows-Wheeler) compression block. This could
600	be useful for error control purposes. The mechanism is analogous to
601	that for finishing: call <CODE>BZ2_bzCompress</CODE> with an action of
602	<CODE>BZ_FLUSH</CODE>, remove output data, and persist with the
603	<CODE>BZ_FLUSH</CODE> action until the value <CODE>BZ_RUN</CODE> is returned. As
604	with finishing, <CODE>BZ2_bzCompress</CODE> detects any attempt to provide more
605	input data once the flush has begun.
606	</P><P>
607
608	Once the flush is complete, the stream returns to the normal RUNNING
609	state.
610	</P><P>
611
612	This all sounds pretty complex, but isn't really. Here's a table
613	which shows which actions are allowable in each state, what action
614	will be taken, what the next state is, and what the non-error return
615	values are. Note that you can't explicitly ask what state the
616	stream is in, but nor do you need to -- it can be inferred from the
617	values returned by <CODE>BZ2_bzCompress</CODE>.
618	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif">IDLE/<CODE>any</CODE>
619	Illegal. IDLE state only exists after <CODE>BZ2_bzCompressEnd</CODE> or
620	before <CODE>BZ2_bzCompressInit</CODE>.
621	Return value = <CODE>BZ_SEQUENCE_ERROR</CODE>
622
623	RUNNING/<CODE>BZ_RUN</CODE>
624	Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible.
625	Next state = RUNNING
626	Return value = <CODE>BZ_RUN_OK</CODE>
627
628	RUNNING/<CODE>BZ_FLUSH</CODE>
629	Remember current value of <CODE>next_in</CODE>. Compress from <CODE>next_in</CODE>
630	to <CODE>next_out</CODE> as much as possible, but do not accept any more input.
631	Next state = FLUSHING
632	Return value = <CODE>BZ_FLUSH_OK</CODE>
633
634	RUNNING/<CODE>BZ_FINISH</CODE>
635	Remember current value of <CODE>next_in</CODE>. Compress from <CODE>next_in</CODE>
636	to <CODE>next_out</CODE> as much as possible, but do not accept any more input.
637	Next state = FINISHING
638	Return value = <CODE>BZ_FINISH_OK</CODE>
639
640	FLUSHING/<CODE>BZ_FLUSH</CODE>
641	Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible,
642	but do not accept any more input.
643	If all the existing input has been used up and all compressed
644	output has been removed
645	Next state = RUNNING; Return value = <CODE>BZ_RUN_OK</CODE>
646	else
647	Next state = FLUSHING; Return value = <CODE>BZ_FLUSH_OK</CODE>
648
649	FLUSHING/other
650	Illegal.
651	Return value = <CODE>BZ_SEQUENCE_ERROR</CODE>
652
653	FINISHING/<CODE>BZ_FINISH</CODE>
654	Compress from <CODE>next_in</CODE> to <CODE>next_out</CODE> as much as possible,
655	but to not accept any more input.
656	If all the existing input has been used up and all compressed
657	output has been removed
658	Next state = IDLE; Return value = <CODE>BZ_STREAM_END</CODE>
659	else
660	Next state = FINISHING; Return value = <CODE>BZ_FINISHING</CODE>
661
662	FINISHING/other
663	Illegal.
664	Return value = <CODE>BZ_SEQUENCE_ERROR</CODE>
665	</pre></td></tr></table></P><P>
666
667	That still looks complicated? Well, fair enough. The usual sequence
668	of calls for compressing a load of data is:
669	<UL>
670	<LI>Get started with <CODE>BZ2_bzCompressInit</CODE>.
671	<LI>Shovel data in and shlurp out its compressed form using zero or more
672	calls of <CODE>BZ2_bzCompress</CODE> with action = <CODE>BZ_RUN</CODE>.
673	<LI>Finish up.
674	Repeatedly call <CODE>BZ2_bzCompress</CODE> with action = <CODE>BZ_FINISH</CODE>,
675	copying out the compressed output, until <CODE>BZ_STREAM_END</CODE> is returned.
676	<LI>Close up and go home. Call <CODE>BZ2_bzCompressEnd</CODE>.
677	</UL>
678	If the data you want to compress fits into your input buffer all
679	at once, you can skip the calls of <CODE>BZ2_bzCompress ( ..., BZ_RUN )</CODE> and
680	just do the <CODE>BZ2_bzCompress ( ..., BZ_FINISH )</CODE> calls.
681	<P>
682
683	All required memory is allocated by <CODE>BZ2_bzCompressInit</CODE>. The
684	compression library can accept any data at all (obviously). So you
685	shouldn't get any error return values from the <CODE>BZ2_bzCompress</CODE> calls.
686	If you do, they will be <CODE>BZ_SEQUENCE_ERROR</CODE>, and indicate a bug in
687	your programming.
688	</P><P>
689
690	Trivial other possible return values:
691	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_PARAM_ERROR</CODE>
692	if <CODE>strm</CODE> is <CODE>NULL</CODE>, or <CODE>strm->s</CODE> is <CODE>NULL</CODE>
693	</pre></td></tr></table></P><P>
694
695	<HR SIZE="6">
696	<A NAME="SEC21"></A>
697	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
698	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC20"> < </A>]</TD>
699	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC22"> > </A>]</TD>
700	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
701	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
702	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
703	<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>
704	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
705	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
706	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
707	</TR></TABLE>
708	<H3> 3.3.3 <CODE>BZ2_bzCompressEnd</CODE> </H3>
709	<!--docid::SEC21::-->
710	<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzCompressEnd ( bz_stream *strm );
711	</pre></td></tr></table>Releases all memory associated with a compression stream.
712	<P>
713
714	Possible return values:
715	<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>
716	<CODE>BZ_OK</CODE> otherwise
717	</pre></td></tr></table></P><P>
718
719	<HR SIZE="6">
720	<A NAME="SEC22"></A>
721	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
722	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC21"> < </A>]</TD>
723	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC23"> > </A>]</TD>
724	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
725	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
726	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
727	<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>
728	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
729	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
730	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
731	</TR></TABLE>
732	<H3> 3.3.4 <CODE>BZ2_bzDecompressInit</CODE> </H3>
733	<!--docid::SEC22::-->
734	<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzDecompressInit ( bz_stream *strm, int verbosity, int small );
735	</pre></td></tr></table>Prepares for decompression. As with <CODE>BZ2_bzCompressInit</CODE>, a
736	<CODE>bz_stream</CODE> record should be allocated and initialised before the
737	call. Fields <CODE>bzalloc</CODE>, <CODE>bzfree</CODE> and <CODE>opaque</CODE> should be
738	set if a custom memory allocator is required, or made <CODE>NULL</CODE> for
739	the normal <CODE>malloc</CODE>/<CODE>free</CODE> routines. Upon return, the internal
740	state will have been initialised, and <CODE>total_in</CODE> and
741	<CODE>total_out</CODE> will be zero.
742	<P>
743
744	For the meaning of parameter <CODE>verbosity</CODE>, see <CODE>BZ2_bzCompressInit</CODE>.
745	</P><P>
746
747	If <CODE>small</CODE> is nonzero, the library will use an alternative
748	decompression algorithm which uses less memory but at the cost of
749	decompressing more slowly (roughly speaking, half the speed, but the
750	maximum memory requirement drops to around 2300k). See Chapter 2 for
751	more information on memory management.
752	</P><P>
753
754	Note that the amount of memory needed to decompress
755	a stream cannot be determined until the stream's header has been read,
756	so even if <CODE>BZ2_bzDecompressInit</CODE> succeeds, a subsequent
757	<CODE>BZ2_bzDecompress</CODE> could fail with <CODE>BZ_MEM_ERROR</CODE>.
758	</P><P>
759
760	Possible return values:
761	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE>
762	if the library has been mis-compiled
763	<CODE>BZ_PARAM_ERROR</CODE>
764	if <CODE>(small != 0 && small != 1)</CODE>
765	or <CODE>(verbosity < 0 \|\| verbosity > 4)</CODE>
766	<CODE>BZ_MEM_ERROR</CODE>
767	if insufficient memory is available
768	</pre></td></tr></table></P><P>
769
770	Allowable next actions:
771	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzDecompress</CODE>
772	if <CODE>BZ_OK</CODE> was returned
773	no specific action required in case of error
774	</pre></td></tr></table></P><P>
775
776
777	</P><P>
778
779	<HR SIZE="6">
780	<A NAME="SEC23"></A>
781	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
782	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC22"> < </A>]</TD>
783	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC24"> > </A>]</TD>
784	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
785	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
786	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
787	<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>
788	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
789	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
790	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
791	</TR></TABLE>
792	<H3> 3.3.5 <CODE>BZ2_bzDecompress</CODE> </H3>
793	<!--docid::SEC23::-->
794	<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzDecompress ( bz_stream *strm );
795	</pre></td></tr></table>Provides more input and/out output buffer space for the library. The
796	caller maintains input and output buffers, and uses <CODE>BZ2_bzDecompress</CODE>
797	to transfer data between them.
798	<P>
799
800	Before each call to <CODE>BZ2_bzDecompress</CODE>, <CODE>next_in</CODE>
801	should point at the compressed data,
802	and <CODE>avail_in</CODE> should indicate how many bytes the library
803	may read. <CODE>BZ2_bzDecompress</CODE> updates <CODE>next_in</CODE>, <CODE>avail_in</CODE>
804	and <CODE>total_in</CODE>
805	to reflect the number of bytes it has read.
806	</P><P>
807
808	Similarly, <CODE>next_out</CODE> should point to a buffer in which the uncompressed
809	output is to be placed, with <CODE>avail_out</CODE> indicating how much output space
810	is available. <CODE>BZ2_bzCompress</CODE> updates <CODE>next_out</CODE>,
811	<CODE>avail_out</CODE> and <CODE>total_out</CODE> to reflect
812	the number of bytes output.
813	</P><P>
814
815	You may provide and remove as little or as much data as you like on
816	each call of <CODE>BZ2_bzDecompress</CODE>.
817	In the limit, it is acceptable to
818	supply and remove data one byte at a time, although this would be
819	terribly inefficient. You should always ensure that at least one
820	byte of output space is available at each call.
821	</P><P>
822
823	Use of <CODE>BZ2_bzDecompress</CODE> is simpler than <CODE>BZ2_bzCompress</CODE>.
824	</P><P>
825
826	You should provide input and remove output as described above, and
827	repeatedly call <CODE>BZ2_bzDecompress</CODE> until <CODE>BZ_STREAM_END</CODE> is
828	returned. Appearance of <CODE>BZ_STREAM_END</CODE> denotes that
829	<CODE>BZ2_bzDecompress</CODE> has detected the logical end of the compressed
830	stream. <CODE>BZ2_bzDecompress</CODE> will not produce <CODE>BZ_STREAM_END</CODE> until
831	all output data has been placed into the output buffer, so once
832	<CODE>BZ_STREAM_END</CODE> appears, you are guaranteed to have available all
833	the decompressed output, and <CODE>BZ2_bzDecompressEnd</CODE> can safely be
834	called.
835	</P><P>
836
837	If case of an error return value, you should call <CODE>BZ2_bzDecompressEnd</CODE>
838	to clean up and release memory.
839	</P><P>
840
841	Possible return values:
842	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_PARAM_ERROR</CODE>
843	if <CODE>strm</CODE> is <CODE>NULL</CODE> or <CODE>strm->s</CODE> is <CODE>NULL</CODE>
844	or <CODE>strm->avail_out < 1</CODE>
845	<CODE>BZ_DATA_ERROR</CODE>
846	if a data integrity error is detected in the compressed stream
847	<CODE>BZ_DATA_ERROR_MAGIC</CODE>
848	if the compressed stream doesn't begin with the right magic bytes
849	<CODE>BZ_MEM_ERROR</CODE>
850	if there wasn't enough memory available
851	<CODE>BZ_STREAM_END</CODE>
852	if the logical end of the data stream was detected and all
853	output in has been consumed, eg <CODE>s->avail_out > 0</CODE>
854	<CODE>BZ_OK</CODE>
855	otherwise
856	</pre></td></tr></table>Allowable next actions:
857	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzDecompress</CODE>
858	if <CODE>BZ_OK</CODE> was returned
859	<CODE>BZ2_bzDecompressEnd</CODE>
860	otherwise
861	</pre></td></tr></table></P><P>
862
863	<HR SIZE="6">
864	<A NAME="SEC24"></A>
865	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
866	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC23"> < </A>]</TD>
867	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC25"> > </A>]</TD>
868	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
869	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
870	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
871	<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>
872	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
873	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
874	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
875	</TR></TABLE>
876	<H3> 3.3.6 <CODE>BZ2_bzDecompressEnd</CODE> </H3>
877	<!--docid::SEC24::-->
878	<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzDecompressEnd ( bz_stream *strm );
879	</pre></td></tr></table>Releases all memory associated with a decompression stream.
880	<P>
881
882	Possible return values:
883	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_PARAM_ERROR</CODE>
884	if <CODE>strm</CODE> is <CODE>NULL</CODE> or <CODE>strm->s</CODE> is <CODE>NULL</CODE>
885	<CODE>BZ_OK</CODE>
886	otherwise
887	</pre></td></tr></table></P><P>
888
889	Allowable next actions:
890	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> None.
891	</pre></td></tr></table></P><P>
892
893	<HR SIZE="6">
894	<A NAME="SEC25"></A>
895	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
896	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC24"> < </A>]</TD>
897	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC26"> > </A>]</TD>
898	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
899	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
900	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
901	<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>
902	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
903	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
904	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
905	</TR></TABLE>
906	<H2> 3.4 High-level interface </H2>
907	<!--docid::SEC25::-->
908	<P>
909
910	This interface provides functions for reading and writing
911	<CODE>bzip2</CODE> format files. First, some general points.
912	</P><P>
913
914	<UL>
915	<LI>All of the functions take an <CODE>int*</CODE> first argument,
916	<CODE>bzerror</CODE>.
917	After each call, <CODE>bzerror</CODE> should be consulted first to determine
918	the outcome of the call. If <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>,
919	the call completed
920	successfully, and only then should the return value of the function
921	(if any) be consulted. If <CODE>bzerror</CODE> is <CODE>BZ_IO_ERROR</CODE>,
922	there was an error
923	reading/writing the underlying compressed file, and you should
924	then consult <CODE>errno</CODE>/<CODE>perror</CODE> to determine the
925	cause of the difficulty.
926	<CODE>bzerror</CODE> may also be set to various other values; precise details are
927	given on a per-function basis below.
928	<LI>If <CODE>bzerror</CODE> indicates an error
929	(ie, anything except <CODE>BZ_OK</CODE> and <CODE>BZ_STREAM_END</CODE>),
930	you should immediately call <CODE>BZ2_bzReadClose</CODE> (or <CODE>BZ2_bzWriteClose</CODE>,
931	depending on whether you are attempting to read or to write)
932	to free up all resources associated
933	with the stream. Once an error has been indicated, behaviour of all calls
934	except <CODE>BZ2_bzReadClose</CODE> (<CODE>BZ2_bzWriteClose</CODE>) is undefined.
935	The implication is that (1) <CODE>bzerror</CODE> should
936	be checked after each call, and (2) if <CODE>bzerror</CODE> indicates an error,
937	<CODE>BZ2_bzReadClose</CODE> (<CODE>BZ2_bzWriteClose</CODE>) should then be called to clean up.
938	<LI>The <CODE>FILE*</CODE> arguments passed to
939	<CODE>BZ2_bzReadOpen</CODE>/<CODE>BZ2_bzWriteOpen</CODE>
940	should be set to binary mode.
941	Most Unix systems will do this by default, but other platforms,
942	including Windows and Mac, will not. If you omit this, you may
943	encounter problems when moving code to new platforms.
944	<LI>Memory allocation requests are handled by
945	<CODE>malloc</CODE>/<CODE>free</CODE>.
946	At present
947	there is no facility for user-defined memory allocators in the file I/O
948	functions (could easily be added, though).
949	</UL>
950	<P>
951
952	<HR SIZE="6">
953	<A NAME="SEC26"></A>
954	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
955	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC25"> < </A>]</TD>
956	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC27"> > </A>]</TD>
957	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
958	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
959	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
960	<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>
961	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
962	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
963	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
964	</TR></TABLE>
965	<H3> 3.4.1 <CODE>BZ2_bzReadOpen</CODE> </H3>
966	<!--docid::SEC26::-->
967	<TABLE><tr><td> </td><td class=example><pre> typedef void BZFILE;
968
969	BZFILE BZ2_bzReadOpen ( int bzerror, FILE *f,
970	int small, int verbosity,
971	void *unused, int nUnused );
972	</pre></td></tr></table>Prepare to read compressed data from file handle <CODE>f</CODE>. <CODE>f</CODE>
973	should refer to a file which has been opened for reading, and for which
974	the error indicator (<CODE>ferror(f)</CODE>)is not set. If <CODE>small</CODE> is 1,
975	the library will try to decompress using less memory, at the expense of
976	speed.
977	<P>
978
979	For reasons explained below, <CODE>BZ2_bzRead</CODE> will decompress the
980	<CODE>nUnused</CODE> bytes starting at <CODE>unused</CODE>, before starting to read
981	from the file <CODE>f</CODE>. At most <CODE>BZ_MAX_UNUSED</CODE> bytes may be
982	supplied like this. If this facility is not required, you should pass
983	<CODE>NULL</CODE> and <CODE>0</CODE> for <CODE>unused</CODE> and n<CODE>Unused</CODE>
984	respectively.
985	</P><P>
986
987	For the meaning of parameters <CODE>small</CODE> and <CODE>verbosity</CODE>,
988	see <CODE>BZ2_bzDecompressInit</CODE>.
989	</P><P>
990
991	The amount of memory needed to decompress a file cannot be determined
992	until the file's header has been read. So it is possible that
993	<CODE>BZ2_bzReadOpen</CODE> returns <CODE>BZ_OK</CODE> but a subsequent call of
994	<CODE>BZ2_bzRead</CODE> will return <CODE>BZ_MEM_ERROR</CODE>.
995	</P><P>
996
997	Possible assignments to <CODE>bzerror</CODE>:
998	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE>
999	if the library has been mis-compiled
1000	<CODE>BZ_PARAM_ERROR</CODE>
1001	if <CODE>f</CODE> is <CODE>NULL</CODE>
1002	or <CODE>small</CODE> is neither <CODE>0</CODE> nor <CODE>1</CODE>
1003	or <CODE>(unused == NULL && nUnused != 0)</CODE>
1004	or <CODE>(unused != NULL && !(0 <= nUnused <= BZ_MAX_UNUSED))</CODE>
1005	<CODE>BZ_IO_ERROR</CODE>
1006	if <CODE>ferror(f)</CODE> is nonzero
1007	<CODE>BZ_MEM_ERROR</CODE>
1008	if insufficient memory is available
1009	<CODE>BZ_OK</CODE>
1010	otherwise.
1011	</pre></td></tr></table></P><P>
1012
1013	Possible return values:
1014	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> Pointer to an abstract <CODE>BZFILE</CODE>
1015	if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>
1016	<CODE>NULL</CODE>
1017	otherwise
1018	</pre></td></tr></table></P><P>
1019
1020	Allowable next actions:
1021	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzRead</CODE>
1022	if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>
1023	<CODE>BZ2_bzClose</CODE>
1024	otherwise
1025	</pre></td></tr></table></P><P>
1026
1027	<HR SIZE="6">
1028	<A NAME="SEC27"></A>
1029	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1030	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC26"> < </A>]</TD>
1031	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC28"> > </A>]</TD>
1032	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1033	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1034	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1035	<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>
1036	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1037	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1038	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1039	</TR></TABLE>
1040	<H3> 3.4.2 <CODE>BZ2_bzRead</CODE> </H3>
1041	<!--docid::SEC27::-->
1042	<TABLE><tr><td> </td><td class=example><pre> int BZ2_bzRead ( int bzerror, BZFILE b, void *buf, int len );
1043	</pre></td></tr></table>Reads up to <CODE>len</CODE> (uncompressed) bytes from the compressed file
1044	<CODE>b</CODE> into
1045	the buffer <CODE>buf</CODE>. If the read was successful,
1046	<CODE>bzerror</CODE> is set to <CODE>BZ_OK</CODE>
1047	and the number of bytes read is returned. If the logical end-of-stream
1048	was detected, <CODE>bzerror</CODE> will be set to <CODE>BZ_STREAM_END</CODE>,
1049	and the number
1050	of bytes read is returned. All other <CODE>bzerror</CODE> values denote an error.
1051	<P>
1052
1053	<CODE>BZ2_bzRead</CODE> will supply <CODE>len</CODE> bytes,
1054	unless the logical stream end is detected
1055	or an error occurs. Because of this, it is possible to detect the
1056	stream end by observing when the number of bytes returned is
1057	less than the number
1058	requested. Nevertheless, this is regarded as inadvisable; you should
1059	instead check <CODE>bzerror</CODE> after every call and watch out for
1060	<CODE>BZ_STREAM_END</CODE>.
1061	</P><P>
1062
1063	Internally, <CODE>BZ2_bzRead</CODE> copies data from the compressed file in chunks
1064	of size <CODE>BZ_MAX_UNUSED</CODE> bytes
1065	before decompressing it. If the file contains more bytes than strictly
1066	needed to reach the logical end-of-stream, <CODE>BZ2_bzRead</CODE> will almost certainly
1067	read some of the trailing data before signalling <CODE>BZ_SEQUENCE_END</CODE>.
1068	To collect the read but unused data once <CODE>BZ_SEQUENCE_END</CODE> has
1069	appeared, call <CODE>BZ2_bzReadGetUnused</CODE> immediately before <CODE>BZ2_bzReadClose</CODE>.
1070	</P><P>
1071
1072	Possible assignments to <CODE>bzerror</CODE>:
1073	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_PARAM_ERROR</CODE>
1074	if <CODE>b</CODE> is <CODE>NULL</CODE> or <CODE>buf</CODE> is <CODE>NULL</CODE> or <CODE>len < 0</CODE>
1075	<CODE>BZ_SEQUENCE_ERROR</CODE>
1076	if <CODE>b</CODE> was opened with <CODE>BZ2_bzWriteOpen</CODE>
1077	<CODE>BZ_IO_ERROR</CODE>
1078	if there is an error reading from the compressed file
1079	<CODE>BZ_UNEXPECTED_EOF</CODE>
1080	if the compressed file ended before the logical end-of-stream was detected
1081	<CODE>BZ_DATA_ERROR</CODE>
1082	if a data integrity error was detected in the compressed stream
1083	<CODE>BZ_DATA_ERROR_MAGIC</CODE>
1084	if the stream does not begin with the requisite header bytes (ie, is not
1085	a <CODE>bzip2</CODE> data file). This is really a special case of <CODE>BZ_DATA_ERROR</CODE>.
1086	<CODE>BZ_MEM_ERROR</CODE>
1087	if insufficient memory was available
1088	<CODE>BZ_STREAM_END</CODE>
1089	if the logical end of stream was detected.
1090	<CODE>BZ_OK</CODE>
1091	otherwise.
1092	</pre></td></tr></table></P><P>
1093
1094	Possible return values:
1095	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> number of bytes read
1096	if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE> or <CODE>BZ_STREAM_END</CODE>
1097	undefined
1098	otherwise
1099	</pre></td></tr></table></P><P>
1100
1101	Allowable next actions:
1102	<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>
1103	if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>
1104	collect data from <CODE>buf</CODE>, then <CODE>BZ2_bzReadClose</CODE> or <CODE>BZ2_bzReadGetUnused</CODE>
1105	if <CODE>bzerror</CODE> is <CODE>BZ_SEQUENCE_END</CODE>
1106	<CODE>BZ2_bzReadClose</CODE>
1107	otherwise
1108	</pre></td></tr></table></P><P>
1109
1110	<HR SIZE="6">
1111	<A NAME="SEC28"></A>
1112	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1113	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC27"> < </A>]</TD>
1114	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC29"> > </A>]</TD>
1115	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1116	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1117	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1118	<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>
1119	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1120	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1121	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1122	</TR></TABLE>
1123	<H3> 3.4.3 <CODE>BZ2_bzReadGetUnused</CODE> </H3>
1124	<!--docid::SEC28::-->
1125	<TABLE><tr><td> </td><td class=example><pre> void BZ2_bzReadGetUnused ( int* bzerror, BZFILE *b,
1126	void** unused, int* nUnused );
1127	</pre></td></tr></table>Returns data which was read from the compressed file but was not needed
1128	to get to the logical end-of-stream. <CODE>*unused</CODE> is set to the address
1129	of the data, and <CODE>nUnused</CODE> to the number of bytes. <CODE>nUnused</CODE> will
1130	be set to a value between <CODE>0</CODE> and <CODE>BZ_MAX_UNUSED</CODE> inclusive.
1131	<P>
1132
1133	This function may only be called once <CODE>BZ2_bzRead</CODE> has signalled
1134	<CODE>BZ_STREAM_END</CODE> but before <CODE>BZ2_bzReadClose</CODE>.
1135	</P><P>
1136
1137	Possible assignments to <CODE>bzerror</CODE>:
1138	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_PARAM_ERROR</CODE>
1139	if <CODE>b</CODE> is <CODE>NULL</CODE>
1140	or <CODE>unused</CODE> is <CODE>NULL</CODE> or <CODE>nUnused</CODE> is <CODE>NULL</CODE>
1141	<CODE>BZ_SEQUENCE_ERROR</CODE>
1142	if <CODE>BZ_STREAM_END</CODE> has not been signalled
1143	or if <CODE>b</CODE> was opened with <CODE>BZ2_bzWriteOpen</CODE>
1144	<CODE>BZ_OK</CODE>
1145	otherwise
1146	</pre></td></tr></table></P><P>
1147
1148	Allowable next actions:
1149	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzReadClose</CODE>
1150	</pre></td></tr></table></P><P>
1151
1152	<HR SIZE="6">
1153	<A NAME="SEC29"></A>
1154	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1155	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC28"> < </A>]</TD>
1156	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC30"> > </A>]</TD>
1157	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1158	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1159	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1160	<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>
1161	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1162	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1163	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1164	</TR></TABLE>
1165	<H3> 3.4.4 <CODE>BZ2_bzReadClose</CODE> </H3>
1166	<!--docid::SEC29::-->
1167	<TABLE><tr><td> </td><td class=example><pre> void BZ2_bzReadClose ( int bzerror, BZFILE b );
1168	</pre></td></tr></table>Releases all memory pertaining to the compressed file <CODE>b</CODE>.
1169	<CODE>BZ2_bzReadClose</CODE> does not call <CODE>fclose</CODE> on the underlying file
1170	handle, so you should do that yourself if appropriate.
1171	<CODE>BZ2_bzReadClose</CODE> should be called to clean up after all error
1172	situations.
1173	<P>
1174
1175	Possible assignments to <CODE>bzerror</CODE>:
1176	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_SEQUENCE_ERROR</CODE>
1177	if <CODE>b</CODE> was opened with <CODE>BZ2_bzOpenWrite</CODE>
1178	<CODE>BZ_OK</CODE>
1179	otherwise
1180	</pre></td></tr></table></P><P>
1181
1182	Allowable next actions:
1183	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> none
1184	</pre></td></tr></table></P><P>
1185
1186	<HR SIZE="6">
1187	<A NAME="SEC30"></A>
1188	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1189	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC29"> < </A>]</TD>
1190	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC31"> > </A>]</TD>
1191	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1192	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1193	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1194	<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>
1195	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1196	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1197	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1198	</TR></TABLE>
1199	<H3> 3.4.5 <CODE>BZ2_bzWriteOpen</CODE> </H3>
1200	<!--docid::SEC30::-->
1201	<TABLE><tr><td> </td><td class=example><pre> BZFILE BZ2_bzWriteOpen ( int bzerror, FILE *f,
1202	int blockSize100k, int verbosity,
1203	int workFactor );
1204	</pre></td></tr></table>Prepare to write compressed data to file handle <CODE>f</CODE>.
1205	<CODE>f</CODE> should refer to
1206	a file which has been opened for writing, and for which the error
1207	indicator (<CODE>ferror(f)</CODE>)is not set.
1208	<P>
1209
1210	For the meaning of parameters <CODE>blockSize100k</CODE>,
1211	<CODE>verbosity</CODE> and <CODE>workFactor</CODE>, see
1212	<BR> <CODE>BZ2_bzCompressInit</CODE>.
1213	</P><P>
1214
1215	All required memory is allocated at this stage, so if the call
1216	completes successfully, <CODE>BZ_MEM_ERROR</CODE> cannot be signalled by a
1217	subsequent call to <CODE>BZ2_bzWrite</CODE>.
1218	</P><P>
1219
1220	Possible assignments to <CODE>bzerror</CODE>:
1221	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE>
1222	if the library has been mis-compiled
1223	<CODE>BZ_PARAM_ERROR</CODE>
1224	if <CODE>f</CODE> is <CODE>NULL</CODE>
1225	or <CODE>blockSize100k < 1</CODE> or <CODE>blockSize100k > 9</CODE>
1226	<CODE>BZ_IO_ERROR</CODE>
1227	if <CODE>ferror(f)</CODE> is nonzero
1228	<CODE>BZ_MEM_ERROR</CODE>
1229	if insufficient memory is available
1230	<CODE>BZ_OK</CODE>
1231	otherwise
1232	</pre></td></tr></table></P><P>
1233
1234	Possible return values:
1235	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> Pointer to an abstract <CODE>BZFILE</CODE>
1236	if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>
1237	<CODE>NULL</CODE>
1238	otherwise
1239	</pre></td></tr></table></P><P>
1240
1241	Allowable next actions:
1242	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ2_bzWrite</CODE>
1243	if <CODE>bzerror</CODE> is <CODE>BZ_OK</CODE>
1244	(you could go directly to <CODE>BZ2_bzWriteClose</CODE>, but this would be pretty pointless)
1245	<CODE>BZ2_bzWriteClose</CODE>
1246	otherwise
1247	</pre></td></tr></table></P><P>
1248
1249	<HR SIZE="6">
1250	<A NAME="SEC31"></A>
1251	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1252	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC30"> < </A>]</TD>
1253	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC32"> > </A>]</TD>
1254	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1255	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1256	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1257	<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>
1258	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1259	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1260	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1261	</TR></TABLE>
1262	<H3> 3.4.6 <CODE>BZ2_bzWrite</CODE> </H3>
1263	<!--docid::SEC31::-->
1264	<TABLE><tr><td> </td><td class=example><pre> void BZ2_bzWrite ( int bzerror, BZFILE b, void *buf, int len );
1265	</pre></td></tr></table>Absorbs <CODE>len</CODE> bytes from the buffer <CODE>buf</CODE>, eventually to be
1266	compressed and written to the file.
1267	<P>
1268
1269	Possible assignments to <CODE>bzerror</CODE>:
1270	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_PARAM_ERROR</CODE>
1271	if <CODE>b</CODE> is <CODE>NULL</CODE> or <CODE>buf</CODE> is <CODE>NULL</CODE> or <CODE>len < 0</CODE>
1272	<CODE>BZ_SEQUENCE_ERROR</CODE>
1273	if b was opened with <CODE>BZ2_bzReadOpen</CODE>
1274	<CODE>BZ_IO_ERROR</CODE>
1275	if there is an error writing the compressed file.
1276	<CODE>BZ_OK</CODE>
1277	otherwise
1278	</pre></td></tr></table></P><P>
1279
1280	<HR SIZE="6">
1281	<A NAME="SEC32"></A>
1282	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1283	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC31"> < </A>]</TD>
1284	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC33"> > </A>]</TD>
1285	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1286	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1287	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1288	<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>
1289	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1290	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1291	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1292	</TR></TABLE>
1293	<H3> 3.4.7 <CODE>BZ2_bzWriteClose</CODE> </H3>
1294	<!--docid::SEC32::-->
1295	<TABLE><tr><td> </td><td class=example><pre> void BZ2_bzWriteClose ( int bzerror, BZFILE f,
1296	int abandon,
1297	unsigned int* nbytes_in,
1298	unsigned int* nbytes_out );
1299
1300	void BZ2_bzWriteClose64 ( int bzerror, BZFILE f,
1301	int abandon,
1302	unsigned int* nbytes_in_lo32,
1303	unsigned int* nbytes_in_hi32,
1304	unsigned int* nbytes_out_lo32,
1305	unsigned int* nbytes_out_hi32 );
1306	</pre></td></tr></table><P>
1307
1308	Compresses and flushes to the compressed file all data so far supplied
1309	by <CODE>BZ2_bzWrite</CODE>. The logical end-of-stream markers are also written, so
1310	subsequent calls to <CODE>BZ2_bzWrite</CODE> are illegal. All memory associated
1311	with the compressed file <CODE>b</CODE> is released.
1312	<CODE>fflush</CODE> is called on the
1313	compressed file, but it is not <CODE>fclose</CODE>'d.
1314	</P><P>
1315
1316	If <CODE>BZ2_bzWriteClose</CODE> is called to clean up after an error, the only
1317	action is to release the memory. The library records the error codes
1318	issued by previous calls, so this situation will be detected
1319	automatically. There is no attempt to complete the compression
1320	operation, nor to <CODE>fflush</CODE> the compressed file. You can force this
1321	behaviour to happen even in the case of no error, by passing a nonzero
1322	value to <CODE>abandon</CODE>.
1323	</P><P>
1324
1325	If <CODE>nbytes_in</CODE> is non-null, <CODE>*nbytes_in</CODE> will be set to be the
1326	total volume of uncompressed data handled. Similarly, <CODE>nbytes_out</CODE>
1327	will be set to the total volume of compressed data written. For
1328	compatibility with older versions of the library, <CODE>BZ2_bzWriteClose</CODE>
1329	only yields the lower 32 bits of these counts. Use
1330	<CODE>BZ2_bzWriteClose64</CODE> if you want the full 64 bit counts. These
1331	two functions are otherwise absolutely identical.
1332	</P><P>
1333
1334	Possible assignments to <CODE>bzerror</CODE>:
1335	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_SEQUENCE_ERROR</CODE>
1336	if <CODE>b</CODE> was opened with <CODE>BZ2_bzReadOpen</CODE>
1337	<CODE>BZ_IO_ERROR</CODE>
1338	if there is an error writing the compressed file
1339	<CODE>BZ_OK</CODE>
1340	otherwise
1341	</pre></td></tr></table></P><P>
1342
1343	<HR SIZE="6">
1344	<A NAME="SEC33"></A>
1345	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1346	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC32"> < </A>]</TD>
1347	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC34"> > </A>]</TD>
1348	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1349	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1350	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1351	<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>
1352	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1353	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1354	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1355	</TR></TABLE>
1356	<H3> 3.4.8 Handling embedded compressed data streams </H3>
1357	<!--docid::SEC33::-->
1358	<P>
1359
1360	The high-level library facilitates use of
1361	<CODE>bzip2</CODE> data streams which form some part of a surrounding, larger
1362	data stream.
1363	<UL>
1364	<LI>For writing, the library takes an open file handle, writes
1365	compressed data to it, <CODE>fflush</CODE>es it but does not <CODE>fclose</CODE> it.
1366	The calling application can write its own data before and after the
1367	compressed data stream, using that same file handle.
1368	<LI>Reading is more complex, and the facilities are not as general
1369	as they could be since generality is hard to reconcile with efficiency.
1370	<CODE>BZ2_bzRead</CODE> reads from the compressed file in blocks of size
1371	<CODE>BZ_MAX_UNUSED</CODE> bytes, and in doing so probably will overshoot
1372	the logical end of compressed stream.
1373	To recover this data once decompression has
1374	ended, call <CODE>BZ2_bzReadGetUnused</CODE> after the last call of <CODE>BZ2_bzRead</CODE>
1375	(the one returning <CODE>BZ_STREAM_END</CODE>) but before calling
1376	<CODE>BZ2_bzReadClose</CODE>.
1377	</UL>
1378	<P>
1379
1380	This mechanism makes it easy to decompress multiple <CODE>bzip2</CODE>
1381	streams placed end-to-end. As the end of one stream, when <CODE>BZ2_bzRead</CODE>
1382	returns <CODE>BZ_STREAM_END</CODE>, call <CODE>BZ2_bzReadGetUnused</CODE> to collect the
1383	unused data (copy it into your own buffer somewhere).
1384	That data forms the start of the next compressed stream.
1385	To start uncompressing that next stream, call <CODE>BZ2_bzReadOpen</CODE> again,
1386	feeding in the unused data via the <CODE>unused</CODE>/<CODE>nUnused</CODE>
1387	parameters.
1388	Keep doing this until <CODE>BZ_STREAM_END</CODE> return coincides with the
1389	physical end of file (<CODE>feof(f)</CODE>). In this situation
1390	<CODE>BZ2_bzReadGetUnused</CODE>
1391	will of course return no data.
1392	</P><P>
1393
1394	This should give some feel for how the high-level interface can be used.
1395	If you require extra flexibility, you'll have to bite the bullet and get
1396	to grips with the low-level interface.
1397	</P><P>
1398
1399	<HR SIZE="6">
1400	<A NAME="SEC34"></A>
1401	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1402	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC33"> < </A>]</TD>
1403	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC35"> > </A>]</TD>
1404	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1405	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1406	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1407	<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>
1408	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1409	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1410	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1411	</TR></TABLE>
1412	<H3> 3.4.9 Standard file-reading/writing code </H3>
1413	<!--docid::SEC34::-->
1414	Here's how you'd write data to a compressed file:
1415	<TABLE><tr><td> </td><td class=example><pre>FILE* f;
1416	BZFILE* b;
1417	int nBuf;
1418	char buf[ /* whatever size you like */ ];
1419	int bzerror;
1420	int nWritten;
1421
1422	f = fopen ( "myfile.bz2", "w" );
1423	if (!f) {
1424	/* handle error */
1425	}
1426	b = BZ2_bzWriteOpen ( &bzerror, f, 9 );
1427	if (bzerror != BZ_OK) {
1428	BZ2_bzWriteClose ( b );
1429	/* handle error */
1430	}
1431
1432	while ( /* condition */ ) {
1433	/* get data to write into buf, and set nBuf appropriately */
1434	nWritten = BZ2_bzWrite ( &bzerror, b, buf, nBuf );
1435	if (bzerror == BZ_IO_ERROR) {
1436	BZ2_bzWriteClose ( &bzerror, b );
1437	/* handle error */
1438	}
1439	}
1440
1441	BZ2_bzWriteClose ( &bzerror, b );
1442	if (bzerror == BZ_IO_ERROR) {
1443	/* handle error */
1444	}
1445	</pre></td></tr></table>And to read from a compressed file:
1446	<TABLE><tr><td> </td><td class=example><pre>FILE* f;
1447	BZFILE* b;
1448	int nBuf;
1449	char buf[ /* whatever size you like */ ];
1450	int bzerror;
1451	int nWritten;
1452
1453	f = fopen ( "myfile.bz2", "r" );
1454	if (!f) {
1455	/* handle error */
1456	}
1457	b = BZ2_bzReadOpen ( &bzerror, f, 0, NULL, 0 );
1458	if (bzerror != BZ_OK) {
1459	BZ2_bzReadClose ( &bzerror, b );
1460	/* handle error */
1461	}
1462
1463	bzerror = BZ_OK;
1464	while (bzerror == BZ_OK && /* arbitrary other conditions */) {
1465	nBuf = BZ2_bzRead ( &bzerror, b, buf, /* size of buf */ );
1466	if (bzerror == BZ_OK) {
1467	/* do something with buf[0 .. nBuf-1] */
1468	}
1469	}
1470	if (bzerror != BZ_STREAM_END) {
1471	BZ2_bzReadClose ( &bzerror, b );
1472	/* handle error */
1473	} else {
1474	BZ2_bzReadClose ( &bzerror );
1475	}
1476	</pre></td></tr></table><P>
1477
1478	<HR SIZE="6">
1479	<A NAME="SEC35"></A>
1480	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1481	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC34"> < </A>]</TD>
1482	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC36"> > </A>]</TD>
1483	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1484	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1485	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1486	<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>
1487	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1488	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1489	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1490	</TR></TABLE>
1491	<H2> 3.5 Utility functions </H2>
1492	<!--docid::SEC35::-->
1493	<HR SIZE="6">
1494	<A NAME="SEC36"></A>
1495	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1496	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC35"> < </A>]</TD>
1497	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC37"> > </A>]</TD>
1498	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1499	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1500	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1501	<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>
1502	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1503	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1504	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1505	</TR></TABLE>
1506	<H3> 3.5.1 <CODE>BZ2_bzBuffToBuffCompress</CODE> </H3>
1507	<!--docid::SEC36::-->
1508	<TABLE><tr><td> </td><td class=example><pre> int BZ2_bzBuffToBuffCompress( char* dest,
1509	unsigned int* destLen,
1510	char* source,
1511	unsigned int sourceLen,
1512	int blockSize100k,
1513	int verbosity,
1514	int workFactor );
1515	</pre></td></tr></table>Attempts to compress the data in <CODE>source[0 .. sourceLen-1]</CODE>
1516	into the destination buffer, <CODE>dest[0 .. *destLen-1]</CODE>.
1517	If the destination buffer is big enough, <CODE>*destLen</CODE> is
1518	set to the size of the compressed data, and <CODE>BZ_OK</CODE> is
1519	returned. If the compressed data won't fit, <CODE>*destLen</CODE>
1520	is unchanged, and <CODE>BZ_OUTBUFF_FULL</CODE> is returned.
1521	<P>
1522
1523	Compression in this manner is a one-shot event, done with a single call
1524	to this function. The resulting compressed data is a complete
1525	<CODE>bzip2</CODE> format data stream. There is no mechanism for making
1526	additional calls to provide extra input data. If you want that kind of
1527	mechanism, use the low-level interface.
1528	</P><P>
1529
1530	For the meaning of parameters <CODE>blockSize100k</CODE>, <CODE>verbosity</CODE>
1531	and <CODE>workFactor</CODE>, <BR> see <CODE>BZ2_bzCompressInit</CODE>.
1532	</P><P>
1533
1534	To guarantee that the compressed data will fit in its buffer, allocate
1535	an output buffer of size 1% larger than the uncompressed data, plus
1536	six hundred extra bytes.
1537	</P><P>
1538
1539	<CODE>BZ2_bzBuffToBuffDecompress</CODE> will not write data at or
1540	beyond <CODE>dest[*destLen]</CODE>, even in case of buffer overflow.
1541	</P><P>
1542
1543	Possible return values:
1544	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE>
1545	if the library has been mis-compiled
1546	<CODE>BZ_PARAM_ERROR</CODE>
1547	if <CODE>dest</CODE> is <CODE>NULL</CODE> or <CODE>destLen</CODE> is <CODE>NULL</CODE>
1548	or <CODE>blockSize100k < 1</CODE> or <CODE>blockSize100k > 9</CODE>
1549	or <CODE>verbosity < 0</CODE> or <CODE>verbosity > 4</CODE>
1550	or <CODE>workFactor < 0</CODE> or <CODE>workFactor > 250</CODE>
1551	<CODE>BZ_MEM_ERROR</CODE>
1552	if insufficient memory is available
1553	<CODE>BZ_OUTBUFF_FULL</CODE>
1554	if the size of the compressed data exceeds <CODE>*destLen</CODE>
1555	<CODE>BZ_OK</CODE>
1556	otherwise
1557	</pre></td></tr></table></P><P>
1558
1559	<HR SIZE="6">
1560	<A NAME="SEC37"></A>
1561	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1562	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC36"> < </A>]</TD>
1563	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC38"> > </A>]</TD>
1564	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1565	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1566	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1567	<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>
1568	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1569	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1570	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1571	</TR></TABLE>
1572	<H3> 3.5.2 <CODE>BZ2_bzBuffToBuffDecompress</CODE> </H3>
1573	<!--docid::SEC37::-->
1574	<TABLE><tr><td> </td><td class=example><pre> int BZ2_bzBuffToBuffDecompress ( char* dest,
1575	unsigned int* destLen,
1576	char* source,
1577	unsigned int sourceLen,
1578	int small,
1579	int verbosity );
1580	</pre></td></tr></table>Attempts to decompress the data in <CODE>source[0 .. sourceLen-1]</CODE>
1581	into the destination buffer, <CODE>dest[0 .. *destLen-1]</CODE>.
1582	If the destination buffer is big enough, <CODE>*destLen</CODE> is
1583	set to the size of the uncompressed data, and <CODE>BZ_OK</CODE> is
1584	returned. If the compressed data won't fit, <CODE>*destLen</CODE>
1585	is unchanged, and <CODE>BZ_OUTBUFF_FULL</CODE> is returned.
1586	<P>
1587
1588	<CODE>source</CODE> is assumed to hold a complete <CODE>bzip2</CODE> format
1589	data stream. <BR> <CODE>BZ2_bzBuffToBuffDecompress</CODE> tries to decompress
1590	the entirety of the stream into the output buffer.
1591	</P><P>
1592
1593	For the meaning of parameters <CODE>small</CODE> and <CODE>verbosity</CODE>,
1594	see <CODE>BZ2_bzDecompressInit</CODE>.
1595	</P><P>
1596
1597	Because the compression ratio of the compressed data cannot be known in
1598	advance, there is no easy way to guarantee that the output buffer will
1599	be big enough. You may of course make arrangements in your code to
1600	record the size of the uncompressed data, but such a mechanism is beyond
1601	the scope of this library.
1602	</P><P>
1603
1604	<CODE>BZ2_bzBuffToBuffDecompress</CODE> will not write data at or
1605	beyond <CODE>dest[*destLen]</CODE>, even in case of buffer overflow.
1606	</P><P>
1607
1608	Possible return values:
1609	<TABLE><tr><td> </td><td class=display><pre style="font-family: serif"> <CODE>BZ_CONFIG_ERROR</CODE>
1610	if the library has been mis-compiled
1611	<CODE>BZ_PARAM_ERROR</CODE>
1612	if <CODE>dest</CODE> is <CODE>NULL</CODE> or <CODE>destLen</CODE> is <CODE>NULL</CODE>
1613	or <CODE>small != 0 && small != 1</CODE>
1614	or <CODE>verbosity < 0</CODE> or <CODE>verbosity > 4</CODE>
1615	<CODE>BZ_MEM_ERROR</CODE>
1616	if insufficient memory is available
1617	<CODE>BZ_OUTBUFF_FULL</CODE>
1618	if the size of the compressed data exceeds <CODE>*destLen</CODE>
1619	<CODE>BZ_DATA_ERROR</CODE>
1620	if a data integrity error was detected in the compressed data
1621	<CODE>BZ_DATA_ERROR_MAGIC</CODE>
1622	if the compressed data doesn't begin with the right magic bytes
1623	<CODE>BZ_UNEXPECTED_EOF</CODE>
1624	if the compressed data ends unexpectedly
1625	<CODE>BZ_OK</CODE>
1626	otherwise
1627	</pre></td></tr></table></P><P>
1628
1629	<HR SIZE="6">
1630	<A NAME="SEC38"></A>
1631	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1632	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC37"> < </A>]</TD>
1633	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC39"> > </A>]</TD>
1634	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1635	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1636	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1637	<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>
1638	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1639	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1640	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1641	</TR></TABLE>
1642	<H2> 3.6 <CODE>zlib</CODE> compatibility functions </H2>
1643	<!--docid::SEC38::-->
1644	Yoshioka Tsuneo has contributed some functions to
1645	give better <CODE>zlib</CODE> compatibility. These functions are
1646	<CODE>BZ2_bzopen</CODE>, <CODE>BZ2_bzread</CODE>, <CODE>BZ2_bzwrite</CODE>, <CODE>BZ2_bzflush</CODE>,
1647	<CODE>BZ2_bzclose</CODE>,
1648	<CODE>BZ2_bzerror</CODE> and <CODE>BZ2_bzlibVersion</CODE>.
1649	These functions are not (yet) officially part of
1650	the library. If they break, you get to keep all the pieces.
1651	Nevertheless, I think they work ok.
1652	<TABLE><tr><td> </td><td class=example><pre>typedef void BZFILE;
1653
1654	const char * BZ2_bzlibVersion ( void );
1655	</pre></td></tr></table>Returns a string indicating the library version.
1656	<TABLE><tr><td> </td><td class=example><pre>BZFILE * BZ2_bzopen ( const char path, const char mode );
1657	BZFILE * BZ2_bzdopen ( int fd, const char *mode );
1658	</pre></td></tr></table>Opens a <CODE>.bz2</CODE> file for reading or writing, using either its name
1659	or a pre-existing file descriptor.
1660	Analogous to <CODE>fopen</CODE> and <CODE>fdopen</CODE>.
1661	<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzread ( BZFILE* b, void* buf, int len );
1662	int BZ2_bzwrite ( BZFILE* b, void* buf, int len );
1663	</pre></td></tr></table>Reads/writes data from/to a previously opened <CODE>BZFILE</CODE>.
1664	Analogous to <CODE>fread</CODE> and <CODE>fwrite</CODE>.
1665	<TABLE><tr><td> </td><td class=example><pre>int BZ2_bzflush ( BZFILE* b );
1666	void BZ2_bzclose ( BZFILE* b );
1667	</pre></td></tr></table>Flushes/closes a <CODE>BZFILE</CODE>. <CODE>BZ2_bzflush</CODE> doesn't actually do
1668	anything. Analogous to <CODE>fflush</CODE> and <CODE>fclose</CODE>.
1669	<P>
1670
1671	<TABLE><tr><td> </td><td class=example><pre>const char * BZ2_bzerror ( BZFILE b, int errnum )
1672	</pre></td></tr></table>Returns a string describing the more recent error status of
1673	<CODE>b</CODE>, and also sets <CODE>*errnum</CODE> to its numerical value.
1674	</P><P>
1675
1676	<HR SIZE="6">
1677	<A NAME="SEC39"></A>
1678	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1679	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC38"> < </A>]</TD>
1680	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC40"> > </A>]</TD>
1681	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1682	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1683	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1684	<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>
1685	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1686	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1687	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1688	</TR></TABLE>
1689	<H2> 3.7 Using the library in a <CODE>stdio</CODE>-free environment </H2>
1690	<!--docid::SEC39::-->
1691	<P>
1692
1693	<HR SIZE="6">
1694	<A NAME="SEC40"></A>
1695	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1696	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC39"> < </A>]</TD>
1697	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC41"> > </A>]</TD>
1698	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1699	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1700	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1701	<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>
1702	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1703	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1704	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1705	</TR></TABLE>
1706	<H3> 3.7.1 Getting rid of <CODE>stdio</CODE> </H3>
1707	<!--docid::SEC40::-->
1708	<P>
1709
1710	In a deeply embedded application, you might want to use just
1711	the memory-to-memory functions. You can do this conveniently
1712	by compiling the library with preprocessor symbol <CODE>BZ_NO_STDIO</CODE>
1713	defined. Doing this gives you a library containing only the following
1714	eight functions:
1715	</P><P>
1716
1717	<CODE>BZ2_bzCompressInit</CODE>, <CODE>BZ2_bzCompress</CODE>, <CODE>BZ2_bzCompressEnd</CODE> <BR>
1718	<CODE>BZ2_bzDecompressInit</CODE>, <CODE>BZ2_bzDecompress</CODE>, <CODE>BZ2_bzDecompressEnd</CODE> <BR>
1719	<CODE>BZ2_bzBuffToBuffCompress</CODE>, <CODE>BZ2_bzBuffToBuffDecompress</CODE>
1720	</P><P>
1721
1722	When compiled like this, all functions will ignore <CODE>verbosity</CODE>
1723	settings.
1724	</P><P>
1725
1726	<HR SIZE="6">
1727	<A NAME="SEC41"></A>
1728	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1729	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC40"> < </A>]</TD>
1730	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC42"> > </A>]</TD>
1731	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1732	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1733	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1734	<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>
1735	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1736	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1737	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1738	</TR></TABLE>
1739	<H3> 3.7.2 Critical error handling </H3>
1740	<!--docid::SEC41::-->
1741	<CODE>libbzip2</CODE> contains a number of internal assertion checks which
1742	should, needless to say, never be activated. Nevertheless, if an
1743	assertion should fail, behaviour depends on whether or not the library
1744	was compiled with <CODE>BZ_NO_STDIO</CODE> set.
1745	<P>
1746
1747	For a normal compile, an assertion failure yields the message
1748	<TABLE><tr><td> </td><td class=example><pre> bzip2/libbzip2: internal error number N.
1749	This is a bug in bzip2/libbzip2, 1.0.2, 30-Dec-2001.
1750	Please report it to me at: jseward@acm.org. If this happened
1751	when you were using some program which uses libbzip2 as a
1752	component, you should also report this bug to the author(s)
1753	of that program. Please make an effort to report this bug;
1754	timely and accurate bug reports eventually lead to higher
1755	quality software. Thanks. Julian Seward, 30 December 2001.
1756	</pre></td></tr></table>where <CODE>N</CODE> is some error code number. If <CODE>N == 1007</CODE>, it also
1757	prints some extra text advising the reader that unreliable memory is
1758	often associated with internal error 1007. (This is a
1759	frequently-observed-phenomenon with versions 1.0.0/1.0.1).
1760	</P><P>
1761
1762	<CODE>exit(3)</CODE> is then called.
1763	</P><P>
1764
1765	For a <CODE>stdio</CODE>-free library, assertion failures result
1766	in a call to a function declared as:
1767	<TABLE><tr><td> </td><td class=example><pre> extern void bz_internal_error ( int errcode );
1768	</pre></td></tr></table>The relevant code is passed as a parameter. You should supply
1769	such a function.
1770	</P><P>
1771
1772	In either case, once an assertion failure has occurred, any
1773	<CODE>bz_stream</CODE> records involved can be regarded as invalid.
1774	You should not attempt to resume normal operation with them.
1775	</P><P>
1776
1777	You may, of course, change critical error handling to suit
1778	your needs. As I said above, critical errors indicate bugs
1779	in the library and should not occur. All "normal" error
1780	situations are indicated via error return codes from functions,
1781	and can be recovered from.
1782	</P><P>
1783
1784	<HR SIZE="6">
1785	<A NAME="SEC42"></A>
1786	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1787	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC41"> < </A>]</TD>
1788	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_4.html#SEC43"> > </A>]</TD>
1789	<TD VALIGN="MIDDLE" ALIGN="LEFT">   <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1790	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD>
1791	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1792	<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>
1793	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1794	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1795	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1796	</TR></TABLE>
1797	<H2> 3.8 Making a Windows DLL </H2>
1798	<!--docid::SEC42::-->
1799	Everything related to Windows has been contributed by Yoshioka Tsuneo
1800	<BR> (<CODE>QWF00133@niftyserve.or.jp</CODE> /
1801	<CODE>tsuneo-y@is.aist-nara.ac.jp</CODE>), so you should send your queries to
1802	him (but perhaps Cc: me, <CODE>jseward@acm.org</CODE>).
1803	<P>
1804
1805	My vague understanding of what to do is: using Visual C++ 5.0,
1806	open the project file <CODE>libbz2.dsp</CODE>, and build. That's all.
1807	</P><P>
1808
1809	If you can't
1810	open the project file for some reason, make a new one, naming these files:
1811	<CODE>blocksort.c</CODE>, <CODE>bzlib.c</CODE>, <CODE>compress.c</CODE>,
1812	<CODE>crctable.c</CODE>, <CODE>decompress.c</CODE>, <CODE>huffman.c</CODE>, <BR>
1813	<CODE>randtable.c</CODE> and <CODE>libbz2.def</CODE>. You will also need
1814	to name the header files <CODE>bzlib.h</CODE> and <CODE>bzlib_private.h</CODE>.
1815	</P><P>
1816
1817	If you don't use VC++, you may need to define the proprocessor symbol
1818	<CODE>_WIN32</CODE>.
1819	</P><P>
1820
1821	Finally, <CODE>dlltest.c</CODE> is a sample program using the DLL. It has a
1822	project file, <CODE>dlltest.dsp</CODE>.
1823	</P><P>
1824
1825	If you just want a makefile for Visual C, have a look at
1826	<CODE>makefile.msc</CODE>.
1827	</P><P>
1828
1829	Be aware that if you compile <CODE>bzip2</CODE> itself on Win32, you must set
1830	<CODE>BZ_UNIX</CODE> to 0 and <CODE>BZ_LCCWIN32</CODE> to 1, in the file
1831	<CODE>bzip2.c</CODE>, before compiling. Otherwise the resulting binary won't
1832	work correctly.
1833	</P><P>
1834
1835	I haven't tried any of this stuff myself, but it all looks plausible.
1836	</P><P>
1837
1838	<HR SIZE="6">
1839	<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
1840	<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD>
1841	<TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD>
1842	<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>
1843	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
1844	<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
1845	<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
1846	</TR></TABLE>
1847	<BR>
1848	<FONT SIZE="-1">
1849	This document was generated
1850	by <I>Julian Seward</I> on <I>January, 5 2002</I>
1851	using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
1852	"><I>texi2html</I></A>
1853
1854	</BODY>
1855	</HTML>

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: trunk/third/bzip2/manual_3.html @ 17062

Download in other formats: