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