📄 manual_3.html
字号:
<HTML><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><!-- Created on January, 5 2002 by texi2html 1.64 --><!-- Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author) Karl Berry <karl@freefriends.org> Olaf Bachmann <obachman@mathematik.uni-kl.de> and many others.Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>Send bugs and suggestions to <texi2html@mathematik.uni-kl.de> --><HEAD><TITLE>Untitled Document: 3. Programming with <CODE>libbzip2</CODE></TITLE><META NAME="description" CONTENT="Untitled Document: 3. Programming with <CODE>libbzip2</CODE>"><META NAME="keywords" CONTENT="Untitled Document: 3. Programming with <CODE>libbzip2</CODE>"><META NAME="resource-type" CONTENT="document"><META NAME="distribution" CONTENT="global"><META NAME="Generator" CONTENT="texi2html 1.64"></HEAD><BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000"><A NAME="SEC12"></A><TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0><TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_2.html#SEC11"> < </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC13"> > </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD></TR></TABLE><H1> 3. Programming with <CODE>libbzip2</CODE> </H1><!--docid::SEC12::--><P>This chapter describes the programming interface to <CODE>libbzip2</CODE>.</P><P>For general background information, particularly about memoryuse and performance aspects, you'd be well advised to read Chapter 2as well.</P><P><HR SIZE="6"><A NAME="SEC13"></A><TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0><TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC12"> < </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC14"> > </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD></TR></TABLE><H2> 3.1 Top-level structure </H2><!--docid::SEC13::--><P><CODE>libbzip2</CODE> is a flexible library for compressing and decompressingdata in the <CODE>bzip2</CODE> data format. Although packaged as a singleentity, it helps to regard the library as three separate parts: the lowlevel interface, and the high level interface, and some utilityfunctions.</P><P>The structure of <CODE>libbzip2</CODE>'s interfaces is similar tothat of Jean-loup Gailly's and Mark Adler's excellent <CODE>zlib</CODE> library.</P><P>All externally visible symbols have names beginning <CODE>BZ2_</CODE>.This is new in version 1.0. The intention is to minimise pollutionof the namespaces of library clients.</P><P><HR SIZE="6"><A NAME="SEC14"></A><TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0><TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC13"> < </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC15"> > </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD></TR></TABLE><H3> 3.1.1 Low-level summary </H3><!--docid::SEC14::--><P>This interface provides services for compressing and decompressingdata in memory. There's no provision for dealing with files, streamsor any other I/O mechanisms, just straight memory-to-memory work.In fact, this part of the library can be compiled without inclusionof <CODE>stdio.h</CODE>, which may be helpful for embedded applications.</P><P>The low-level part of the library has no global variables andis therefore thread-safe.</P><P>Six routines make up the low level interface: <CODE>BZ2_bzCompressInit</CODE>, <CODE>BZ2_bzCompress</CODE>, and <BR> <CODE>BZ2_bzCompressEnd</CODE>for compression,and a corresponding trio <CODE>BZ2_bzDecompressInit</CODE>, <BR> <CODE>BZ2_bzDecompress</CODE>and <CODE>BZ2_bzDecompressEnd</CODE> for decompression. The <CODE>*Init</CODE> functions allocatememory for compression/decompression and do otherinitialisations, whilst the <CODE>*End</CODE> functions close down operationsand release memory.</P><P>The real work is done by <CODE>BZ2_bzCompress</CODE> and <CODE>BZ2_bzDecompress</CODE>. These compress and decompress data from a user-supplied input bufferto a user-supplied output buffer. These buffers can be any size;arbitrary quantities of data are handled by making repeated callsto these functions. This is a flexible mechanism allowing a consumer-pull style of activity, or producer-push, or a mixture ofboth.</P><P><HR SIZE="6"><A NAME="SEC15"></A><TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0><TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC14"> < </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC16"> > </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD></TR></TABLE><H3> 3.1.2 High-level summary </H3><!--docid::SEC15::--><P>This interface provides some handy wrappers around the low-levelinterface to facilitate reading and writing <CODE>bzip2</CODE> formatfiles (<CODE>.bz2</CODE> files). The routines provide hooks to facilitatereading files in which the <CODE>bzip2</CODE> data stream is embedded within some larger-scale file structure, or where there aremultiple <CODE>bzip2</CODE> data streams concatenated end-to-end.</P><P>For reading files, <CODE>BZ2_bzReadOpen</CODE>, <CODE>BZ2_bzRead</CODE>,<CODE>BZ2_bzReadClose</CODE> and <BR> <CODE>BZ2_bzReadGetUnused</CODE> are supplied. Forwriting files, <CODE>BZ2_bzWriteOpen</CODE>, <CODE>BZ2_bzWrite</CODE> and<CODE>BZ2_bzWriteFinish</CODE> are available.</P><P>As with the low-level library, no global variables are usedso the library is per se thread-safe. However, if I/O errorsoccur whilst reading or writing the underlying compressed files,you may have to consult <CODE>errno</CODE> to determine the cause ofthe error. In that case, you'd need a C library which correctlysupports <CODE>errno</CODE> in a multithreaded environment.</P><P>To make the library a little simpler and more portable,<CODE>BZ2_bzReadOpen</CODE> and <CODE>BZ2_bzWriteOpen</CODE> require you to pass them filehandles (<CODE>FILE*</CODE>s) which have previously been opened for reading orwriting respectively. That avoids portability problems associated withfile operations and file attributes, whilst not being much of animposition on the programmer.</P><P><HR SIZE="6"><A NAME="SEC16"></A><TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0><TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC15"> < </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC17"> > </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD></TR></TABLE><H3> 3.1.3 Utility functions summary </H3><!--docid::SEC16::-->For very simple needs, <CODE>BZ2_bzBuffToBuffCompress</CODE> and<CODE>BZ2_bzBuffToBuffDecompress</CODE> are provided. These compressdata in memory from one buffer to another buffer in a singlefunction call. You should assess whether these functionsfulfill your memory-to-memory compression/decompressionrequirements before investing effort in understanding the moregeneral but more complex low-level interface.<P>Yoshioka Tsuneo (<CODE>QWF00133@niftyserve.or.jp</CODE> /<CODE>tsuneo-y@is.aist-nara.ac.jp</CODE>) has contributed some functions togive better <CODE>zlib</CODE> compatibility. These functions are<CODE>BZ2_bzopen</CODE>, <CODE>BZ2_bzread</CODE>, <CODE>BZ2_bzwrite</CODE>, <CODE>BZ2_bzflush</CODE>,<CODE>BZ2_bzclose</CODE>,<CODE>BZ2_bzerror</CODE> and <CODE>BZ2_bzlibVersion</CODE>. You may find these functionsmore convenient for simple file reading and writing, than those in thehigh-level interface. These functions are not (yet) officially part ofthe library, and are minimally documented here. If they break, youget to keep all the pieces. I hope to document them properly when timepermits.</P><P>Yoshioka also contributed modifications to allow the library to bebuilt as a Windows DLL.</P><P><HR SIZE="6"><A NAME="SEC17"></A><TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0><TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC16"> < </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_3.html#SEC18"> > </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[ << ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top"> Up </A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[ >> ]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual.html#SEC_Top">Top</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD></TR></TABLE><H2> 3.2 Error handling </H2><!--docid::SEC17::--><P>The library is designed to recover cleanly in all situations, includingthe worst-case situation of decompressing random data. I'm not 100% sure that it can always do this, so you might want to adda signal handler to catch segmentation violations during decompressionif you are feeling especially paranoid. I would be interested inhearing more about the robustness of the library to corruptedcompressed data.</P><P>Version 1.0 is much more robust in this respect than0.9.0 or 0.9.5. Investigations with Checker (a tool for detecting problems with memory management, similar to Purify)indicate that, at least for the few files I tested, all single-biterrors in the decompressed data are caught properly, with nosegmentation faults, no reads of uninitialised data and no out of range reads or writes. So it's certainly much improved,although I wouldn't claim it to be totally bombproof.</P><P>The file <CODE>bzlib.h</CODE> contains all definitions needed to use⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -