zlib 114 Manual.docx

zlib 114 Manual.docx

《zlib 114 Manual.docx》由会员分享，可在线阅读，更多相关《zlib 114 Manual.docx（22页珍藏版）》请在冰豆网上搜索。

zlib114Manual

zlib1.1.4Manual

Contents

I.Prologue

II.Introduction

III.Utilityfunctions

IV.Basicfunctions

V.Advancedfunctions

VI.Constants

VII.structz_stream_s

VIII.Checksumfunctions

IX.Misc

Prologue

'zlib'generalpurposecompressionlibraryversion1.1.4,March11th,2002

Copyright（C）1995-2002Jean-loupGaillyandMarkAdler

Thissoftwareisprovided'as-is',withoutanyexpressorimpliedwarranty.Innoeventwilltheauthorsbeheldliableforanydamagesarisingfromtheuseofthissoftware.

Permissionisgrantedtoanyonetousethissoftwareforanypurpose,includingcommercialapplications,andtoalteritandredistributeitfreely,subjecttothefollowingrestrictions:

1.Theoriginofthissoftwaremustnotbemisrepresented;youmustnotclaimthatyouwrotetheoriginalsoftware.Ifyouusethissoftwareinaproduct,anacknowledgmentintheproductdocumentationwouldbeappreciatedbutisnotrequired.

2.Alteredsourceversionsmustbeplainlymarkedassuch,andmustnotbemisrepresentedasbeingtheoriginalsoftware.

3.Thisnoticemaynotberemovedoralteredfromanysourcedistribution.

Jean-loupGailly

jloup@gzip.org

MarkAdler

madler@alumni.caltech.edu

ThedataformatusedbythezliblibraryisdescribedbyRFCs（RequestforComments）1950to1952inthefilesftp:

//（zlibformat）,rfc1951.txt（deflateformat）andrfc1952.txt（gzipformat）.

Thismanualisconvertedfromzlib.hbypiaip

Visitfortheofficialzlibwebpage.

Introduction

The'zlib'compressionlibraryprovidesin-memorycompressionanddecompressionfunctions,includingintegritychecksoftheuncompresseddata.Thisversionofthelibrarysupportsonlyonecompressionmethod（deflation）butotheralgorithmswillbeaddedlaterandwillhavethesamestreaminterface.

Compressioncanbedoneinasinglestepifthebuffersarelargeenough（forexampleifaninputfileismmap'ed）,orcanbedonebyrepeatedcallsofthecompressionfunction.Inthelattercase,theapplicationmustprovidemoreinputand/orconsumetheoutput（providingmoreoutputspace）beforeeachcall.

Thelibraryalsosupportsreadingandwritingfilesingzip（.gz）formatwithaninterfacesimilartothatofstdio.

Thelibrarydoesnotinstallanysignalhandler.Thedecodercheckstheconsistencyofthecompresseddata,sothelibraryshouldnevercrashevenincaseofcorruptedinput.

Utilityfunctions

Thefollowingutilityfunctionsareimplementedontopofthebasicstream-orientedfunctions.Tosimplifytheinterface,somedefaultoptionsareassumed（compressionlevelandmemoryusage,standardmemoryallocationfunctions）.Thesourcecodeoftheseutilityfunctionscaneasilybemodifiedifyouneedspecialoptions.

Functionlist

∙intcompress（Bytef*dest,uLongf*destLen,constBytef*source,uLongsourceLen）;

∙intcompress2（Bytef*dest,uLongf*destLen,constBytef*source,uLongsourceLen,intlevel）;

∙intuncompress（Bytef*dest,uLongf*destLen,constBytef*source,uLongsourceLen）;

∙typedefvoidpgzFile;

∙gzFilegzopen（constchar*path,constchar*mode）;

∙gzFilegzdopen（intfd,constchar*mode）;

∙intgzsetparams（gzFilefile,intlevel,intstrategy）;

∙intgzread（gzFilefile,voidpbuf,unsignedlen）;

∙intgzwrite（gzFilefile,constvoidpbuf,unsignedlen）;

∙intVAgzprintf（gzFilefile,constchar*format,...）;

∙intgzputs（gzFilefile,constchar*s）;

∙char*gzgets（gzFilefile,char*buf,intlen）;

∙intgzputc（gzFilefile,intc）;

∙intgzgetc（gzFilefile）;

∙intgzflush（gzFilefile,intflush）;

∙z_off_tgzseek（gzFilefile,z_off_toffset,intwhence）;

∙z_off_tgztell（gzFilefile）;

∙intgzrewind（gzFilefile）;

∙intgzeof（gzFilefile）;

∙intgzclose（gzFilefile）;

∙constchar*gzerror（gzFilefile,int*errnum）;

Functiondescription

intcompress（Bytef*dest,uLongf*destLen,constBytef*source,uLongsourceLen）;

Compressesthesourcebufferintothedestinationbuffer.sourceLenisthebytelengthofthesourcebuffer.Uponentry,destLenisthetotalsizeofthedestinationbuffer,whichmustbeatleast0.1%largerthansourceLenplus12bytes.Uponexit,destLenistheactualsizeofthecompressedbuffer.

Thisfunctioncanbeusedtocompressawholefileatonceiftheinputfileismmap'ed.

compressreturnsZ_OKifsuccess,Z_MEM_ERRORiftherewasnotenoughmemory,Z_BUF_ERRORiftherewasnotenoughroomintheoutputbuffer.

intcompress2（Bytef*dest,uLongf*destLen,constBytef*source,uLongsourceLen,intlevel）;

Compressesthesourcebufferintothedestinationbuffer.ThelevelparameterhasthesamemeaningasindeflateInit.sourceLenisthebytelengthofthesourcebuffer.Uponentry,destLenisthetotalsizeofthedestinationbuffer,whichmustbeatleast0.1%largerthansourceLenplus12bytes.Uponexit,destLenistheactualsizeofthecompressedbuffer.

compress2returnsZ_OKifsuccess,Z_MEM_ERRORiftherewasnotenoughmemory,Z_BUF_ERRORiftherewasnotenoughroomintheoutputbuffer,Z_STREAM_ERRORifthelevelparameterisinvalid.

intuncompress（Bytef*dest,uLongf*destLen,constBytef*source,uLongsourceLen）;

Decompressesthesourcebufferintothedestinationbuffer.sourceLenisthebytelengthofthesourcebuffer.Uponentry,destLenisthetotalsizeofthedestinationbuffer,whichmustbelargeenoughtoholdtheentireuncompresseddata.（Thesizeoftheuncompresseddatamusthavebeensavedpreviouslybythecompressorandtransmittedtothedecompressorbysomemechanismoutsidethescopeofthiscompressionlibrary.）Uponexit,destLenistheactualsizeofthecompressedbuffer.

Thisfunctioncanbeusedtodecompressawholefileatonceiftheinputfileismmap'ed.

uncompressreturnsZ_OKifsuccess,Z_MEM_ERRORiftherewasnotenoughmemory,Z_BUF_ERRORiftherewasnotenoughroomintheoutputbuffer,orZ_DATA_ERRORiftheinputdatawascorrupted.

typedefvoidpgzFile;

gzFilegzopen（constchar*path,constchar*mode）;

Opensagzip（.gz）fileforreadingorwriting.Themodeparameterisasinfopen（"rb"or"wb"）butcanalsoincludeacompressionlevel（"wb9"）orastrategy:

'f'forfiltereddataasin"wb6f",'h'forHuffmanonlycompressionasin"wb1h".（SeethedescriptionofdeflateInit2formoreinformationaboutthestrategyparameter.）

gzopencanbeusedtoreadafilewhichisnotingzipformat;inthiscasegzreadwilldirectlyreadfromthefilewithoutdecompression.

gzopenreturnsNULLifthefilecouldnotbeopenedoriftherewasinsufficientmemorytoallocatethe（de）compressionstate;errnocanbecheckedtodistinguishthetwocases（iferrnoiszero,thezliberrorisZ_MEM_ERROR）.

gzFilegzdopen（intfd,constchar*mode）;

gzdopen（）associatesagzFilewiththefiledescriptorfd.Filedescriptorsareobtainedfromcallslikeopen,dup,creat,pipeorfileno（inthefilehasbeenpreviouslyopenedwithfopen）.Themodeparameterisasingzopen.

ThenextcallofgzcloseonthereturnedgzFilewillalsoclosethefiledescriptorfd,justlikefclose（fdopen（fd）,mode）closesthefiledescriptorfd.Ifyouwanttokeepfdopen,usegzdopen（dup（fd）,mode）.

gzdopenreturnsNULLiftherewasinsufficientmemorytoallocatethe（de）compressionstate.

intgzsetparams（gzFilefile,intlevel,intstrategy）;

Dynamicallyupdatethecompressionlevelorstrategy.SeethedescriptionofdeflateInit2forthemeaningoftheseparameters.

gzsetparamsreturnsZ_OKifsuccess,orZ_STREAM_ERRORifthefilewasnotopenedforwriting.

intgzread（gzFilefile,voidpbuf,unsignedlen）;

Readsthegivennumberofuncompressedbytesfromthecompressedfile.Iftheinputfilewasnotingzipformat,gzreadcopiesthegivennumberofbytesintothebuffer.

gzreadreturnsthenumberofuncompressedbytesactuallyread（0forendoffile,-1forerror）.

intgzwrite（gzFilefile,constvoidpbuf,unsignedlen）;

Writesthegivennumberofuncompressedbytesintothecompressedfile.gzwritereturnsthenumberofuncompressedbytesactuallywritten（0incaseoferror）.

intVAgzprintf（gzFilefile,constchar*format,...）;

Converts,formats,andwritestheargstothecompressedfileundercontroloftheformatstring,asinfprintf.gzprintfreturnsthenumberofuncompressedbytesactuallywritten（0incaseoferror）.

intgzputs（gzFilefile,constchar*s）;

Writesthegivennull-terminatedstringtothecompressedfile,excludingtheterminatingnullcharacter.

gzputsreturnsthenumberofcharacterswritten,or-1incaseoferror.

char*gzgets（gzFilefile,char*buf,intlen）;

Readsbytesfromthecompressedfileuntillen-1charactersareread,oranewlinecharacterisreadandtransferredtobuf,oranend-of-fileconditionisencountered.Thestringisthenterminatedwithanullcharacter.

gzgetsreturnsbuf,orZ_NULLincaseoferror.

intgzputc（gzFilefile,intc）;

Writesc,convertedtoanunsignedchar,intothecompressedfile.gzputcreturnsthevaluethatwaswritten,or-1incaseoferror.

intgzgetc（gzFilefile）;

Readsonebytefromthecompressedfile.gzgetcreturnsthisbyteor-1incaseofendoffileorerror.

intgzflush（gzFilefile,intflush）;

Flushesallpendingoutputintothecompressedfile.Theparameterflushisasinthedeflate（）function.Thereturnvalueisthezliberrornumber（seefunctiongzerrorbelow）.gzflushreturnsZ_OKiftheflushparameterisZ_FINISHandalloutputcouldbeflushed.

gzflushshouldbecalledonlywhenstrictlynecessarybecauseitcandegradecompression.

z_off_tgzseek（gzFilefile,z_off_toffset,intwhence）;

Setsthestartingpositionforthenextgzread