diff options
Diffstat (limited to 'erts/doc/src/zlib.xml')
| -rw-r--r-- | erts/doc/src/zlib.xml | 606 |
1 files changed, 606 insertions, 0 deletions
diff --git a/erts/doc/src/zlib.xml b/erts/doc/src/zlib.xml new file mode 100644 index 0000000000..9f39ac657a --- /dev/null +++ b/erts/doc/src/zlib.xml @@ -0,0 +1,606 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2005</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>zlib</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>zlib.xml</file> + </header> + <module>zlib</module> + <modulesummary>Zlib Compression interface.</modulesummary> + <description> + <p>The zlib module provides an API for the zlib library + (http://www.zlib.org). + It is used to compress and decompress data. The + data format is described by RFCs 1950 to 1952.</p> + <p>A typical (compress) usage looks like:</p> + <pre> +Z = zlib:open(), +ok = zlib:deflateInit(Z,default), + +Compress = fun(end_of_data, _Cont) -> []; + (Data, Cont) -> + [zlib:deflate(Z, Data)|Cont(Read(),Cont)] + end, +Compressed = Compress(Read(),Compress), +Last = zlib:deflate(Z, [], finish), +ok = zlib:deflateEnd(Z), +zlib:close(Z), +list_to_binary([Compressed|Last])</pre> + <p>In all functions errors, <c>{'EXIT',{Reason,Backtrace}}</c>, + might be thrown, where <c>Reason</c> describes the + error. Typical reasons are:</p> + <taglist> + <tag><c>badarg</c></tag> + <item> + <p>Bad argument</p> + </item> + <tag><c>data_error</c></tag> + <item> + <p>The data contains errors</p> + </item> + <tag><c>stream_error</c></tag> + <item> + <p>Inconsistent stream state</p> + </item> + <tag><c>einval</c></tag> + <item> + <p>Bad value or wrong function called</p> + </item> + <tag><c>{need_dictionary,Adler32}</c></tag> + <item> + <p>See <c>inflate/2</c></p> + </item> + </taglist> + </description> + + <section> + <title>DATA TYPES</title> + <code type="none"> +iodata = iolist() | binary() + +iolist = [char() | binary() | iolist()] + a binary is allowed as the tail of the list + +zstream = a zlib stream, see open/0</code> + </section> + <funcs> + <func> + <name>open() -> Z </name> + <fsummary>Open a stream and return a stream reference</fsummary> + <type> + <v>Z = zstream()</v> + </type> + <desc> + <p>Open a zlib stream.</p> + </desc> + </func> + <func> + <name>close(Z) -> ok</name> + <fsummary>Close a stream</fsummary> + <type> + <v>Z = zstream()</v> + </type> + <desc> + <p>Closes the stream referenced by <c>Z</c>.</p> + </desc> + </func> + <func> + <name>deflateInit(Z) -> ok</name> + <fsummary>Initialize a session for compression</fsummary> + <type> + <v>Z = zstream()</v> + </type> + <desc> + <p>Same as <c>zlib:deflateInit(Z, default)</c>.</p> + </desc> + </func> + <func> + <name>deflateInit(Z, Level) -> ok</name> + <fsummary>Initialize a session for compression</fsummary> + <type> + <v>Z = zstream()</v> + <v>Level = none | default | best_speed | best_compression | 0..9</v> + </type> + <desc> + <p>Initialize a zlib stream for compression.</p> + <p><c>Level</c> decides the compression level to be used, 0 + (<c>none</c>), gives no compression at all, 1 + (<c>best_speed</c>) gives best speed and 9 + (<c>best_compression</c>) gives best compression.</p> + </desc> + </func> + <func> + <name>deflateInit(Z, Level, Method, WindowBits, MemLevel, Strategy) -> ok</name> + <fsummary>Initialize a session for compression</fsummary> + <type> + <v>Z = zstream()</v> + <v>Level = none | default | best_speed | best_compression | 0..9</v> + <v>Method = deflated</v> + <v>WindowBits = 9..15|-9..-15</v> + <v>MemLevel = 1..9</v> + <v>Strategy = default|filtered|huffman_only</v> + </type> + <desc> + <p>Initiates a zlib stream for compression.</p> + <p>The <c>Level</c> parameter decides the compression level to be + used, 0 (<c>none</c>), gives no compression at all, 1 + (<c>best_speed</c>) gives best speed and 9 + (<c>best_compression</c>) gives best compression.</p> + <p>The <c>Method</c> parameter decides which compression method to use, + currently the only supported method is <c>deflated</c>.</p> + <p>The <c>WindowBits</c> parameter is the base two logarithm + of the window size (the size of the history buffer). It + should be in the range 9 through 15. Larger values + of this parameter result in better compression at the + expense of memory usage. The default value is 15 if + <c>deflateInit/2</c>. A negative <c>WindowBits</c> + value suppresses the zlib header (and checksum) from the + stream. Note that the zlib source mentions this only as a + undocumented feature.</p> + <p>The <c>MemLevel</c> parameter specifies how much memory + should be allocated for the internal compression + state. <c>MemLevel</c>=1 uses minimum memory but is slow and + reduces compression ratio; <c>MemLevel</c>=9 uses maximum + memory for optimal speed. The default value is 8.</p> + <p>The <c>Strategy</c> parameter is used to tune the + compression algorithm. Use the value <c>default</c> for + normal data, <c>filtered</c> for data produced by a filter + (or predictor), or <c>huffman_only</c> to force Huffman + encoding only (no string match). Filtered data consists + mostly of small values with a somewhat random + distribution. In this case, the compression algorithm is + tuned to compress them better. The effect of + <c>filtered</c>is to force more Huffman coding and less + string matching; it is somewhat intermediate between + <c>default</c> and <c>huffman_only</c>. The <c>Strategy</c> + parameter only affects the compression ratio but not the + correctness of the compressed output even if it is not set + appropriately.</p> + </desc> + </func> + <func> + <name>deflate(Z, Data) -> Compressed</name> + <fsummary>Compress data</fsummary> + <type> + <v>Z = zstream()</v> + <v>Data = iodata()</v> + <v>Compressed = iolist()</v> + </type> + <desc> + <p>Same as <c>deflate(Z, Data, none)</c>.</p> + </desc> + </func> + <func> + <name>deflate(Z, Data, Flush) -> </name> + <fsummary>Compress data</fsummary> + <type> + <v>Z = zstream()</v> + <v>Data = iodata()</v> + <v>Flush = none | sync | full | finish</v> + <v>Compressed = iolist()</v> + </type> + <desc> + <p><c>deflate/3</c> compresses as much data as possible, and + stops when the input buffer becomes empty. It may introduce + some output latency (reading input without producing any + output) except when forced to flush.</p> + <p>If the parameter <c>Flush</c> is set to <c>sync</c>, all + pending output is flushed to the output buffer and the + output is aligned on a byte boundary, so that the + decompressor can get all input data available so far. + Flushing may degrade compression for some compression algorithms and so + it should be used only when necessary.</p> + <p>If <c>Flush</c> is set to <c>full</c>, all output is flushed as with + <c>sync</c>, and the compression state is reset so that decompression can + restart from this point if previous compressed data has been damaged or if + random access is desired. Using <c>full</c> too often can seriously degrade + the compression.</p> + <p>If the parameter <c>Flush</c> is set to <c>finish</c>, + pending input is processed, pending output is flushed and + <c>deflate/3</c> returns. Afterwards the only possible + operations on the stream are <c>deflateReset/1</c> or <c>deflateEnd/1</c>.</p> + <p><c>Flush</c> can be set to <c>finish</c> immediately after + <c>deflateInit</c> if all compression is to be done in one step.</p> + <pre> + +zlib:deflateInit(Z), +B1 = zlib:deflate(Z,Data), +B2 = zlib:deflate(Z,<< >>,finish), +zlib:deflateEnd(Z), +list_to_binary([B1,B2])</pre> + </desc> + </func> + <func> + <name>deflateSetDictionary(Z, Dictionary) -> Adler32</name> + <fsummary>Initialize the compression dictionary</fsummary> + <type> + <v>Z = zstream()</v> + <v>Dictionary = binary()</v> + <v>Adler32 = integer()</v> + </type> + <desc> + <p>Initializes the compression dictionary from the given byte + sequence without producing any compressed output. This + function must be called immediately after + <c>deflateInit/[1|2|6]</c> or <c>deflateReset/1</c>, before + any call of <c>deflate/3</c>. The compressor and + decompressor must use exactly the same dictionary (see + <c>inflateSetDictionary/2</c>). The adler checksum of the + dictionary is returned.</p> + </desc> + </func> + <func> + <name>deflateReset(Z) -> ok</name> + <fsummary>Reset the deflate session</fsummary> + <type> + <v>Z = zstream()</v> + </type> + <desc> + <p>This function is equivalent to <c>deflateEnd/1</c> + followed by <c>deflateInit/[1|2|6]</c>, but does not free + and reallocate all the internal compression state. The + stream will keep the same compression level and any other + attributes.</p> + </desc> + </func> + <func> + <name>deflateParams(Z, Level, Strategy) -> ok </name> + <fsummary>Dynamicly update deflate parameters</fsummary> + <type> + <v>Z = zstream()</v> + <v>Level = none | default | best_speed | best_compression | 0..9</v> + <v>Strategy = default|filtered|huffman_only</v> + </type> + <desc> + <p>Dynamically update the compression level and compression + strategy. The interpretation of <c>Level</c> and + <c>Strategy</c> is as in <c>deflateInit/6</c>. This can be + used to switch between compression and straight copy of the + input data, or to switch to a different kind of input data + requiring a different strategy. If the compression level is + changed, the input available so far is compressed with the + old level (and may be flushed); the new level will take + effect only at the next call of <c>deflate/3</c>.</p> + <p>Before the call of deflateParams, the stream state must be set as for + a call of <c>deflate/3</c>, since the currently available input may have to + be compressed and flushed.</p> + </desc> + </func> + <func> + <name>deflateEnd(Z) -> ok</name> + <fsummary>End deflate session</fsummary> + <type> + <v>Z = zstream()</v> + </type> + <desc> + <p>End the deflate session and cleans all data used. + Note that this function will throw an <c>data_error</c> + exception if the last call to + <c>deflate/3</c> was not called with <c>Flush</c> set to + <c>finish</c>.</p> + </desc> + </func> + <func> + <name>inflateInit(Z) -> ok </name> + <fsummary>Initialize a session for decompression</fsummary> + <type> + <v>Z = zstream()</v> + </type> + <desc> + <p>Initialize a zlib stream for decompression.</p> + </desc> + </func> + <func> + <name>inflateInit(Z, WindowBits) -> ok </name> + <fsummary>Initialize a session for decompression</fsummary> + <type> + <v>Z = zstream()</v> + <v>WindowBits = 9..15|-9..-15</v> + </type> + <desc> + <p>Initialize decompression session on zlib stream.</p> + <p>The <c>WindowBits</c> parameter is the base two logarithm + of the maximum window size (the size of the history buffer). + It should be in the range 9 through 15. + The default value is 15 if <c>inflateInit/1</c> is used. + If a compressed stream with a larger window size is + given as input, inflate() will throw the <c>data_error</c> + exception. A negative <c>WindowBits</c> value makes zlib ignore the + zlib header (and checksum) from the stream. Note that the zlib + source mentions this only as a undocumented feature.</p> + </desc> + </func> + <func> + <name>inflate(Z, Data) -> DeCompressed </name> + <fsummary>Decompress data</fsummary> + <type> + <v>Z = zstream()</v> + <v>Data = iodata()</v> + <v>DeCompressed = iolist()</v> + </type> + <desc> + <p><c>inflate/2</c> decompresses as much data as possible. + It may some introduce some output latency (reading + input without producing any output).</p> + <p>If a preset dictionary is needed at this point (see + <c>inflateSetDictionary</c> below), <c>inflate/2</c> throws a + <c>{need_dictionary,Adler}</c> exception where <c>Adler</c> is + the adler32 checksum of the dictionary chosen by the + compressor.</p> + </desc> + </func> + <func> + <name>inflateSetDictionary(Z, Dictionary) -> ok</name> + <fsummary>Initialize the decompression dictionary</fsummary> + <type> + <v>Z = zstream()</v> + <v>Dictionary = binary()</v> + </type> + <desc> + <p>Initializes the decompression dictionary from the given + uncompressed byte sequence. This function must be called + immediately after a call of <c>inflate/2</c> if this call + threw a <c>{need_dictionary,Adler}</c> exception. + The dictionary chosen by the + compressor can be determined from the Adler value thrown + by the call to <c>inflate/2</c>. The compressor and decompressor + must use exactly the same dictionary (see <c>deflateSetDictionary/2</c>).</p> + <p>Example:</p> + <pre> +unpack(Z, Compressed, Dict) -> + case catch zlib:inflate(Z, Compressed) of +\011 {'EXIT',{{need_dictionary,DictID},_}} -> + \011 zlib:inflateSetDictionary(Z, Dict), +\011 Uncompressed = zlib:inflate(Z, []); +\011 Uncompressed -> +\011 Uncompressed + end.</pre> + </desc> + </func> + <func> + <name>inflateReset(Z) -> ok</name> + <fsummary>>Reset the inflate session</fsummary> + <type> + <v>Z = zstream()</v> + </type> + <desc> + <p>This function is equivalent to <c>inflateEnd/1</c> followed + by <c>inflateInit/1</c>, but does not free and reallocate all + the internal decompression state. The stream will keep + attributes that may have been set by <c>inflateInit/[1|2]</c>.</p> + </desc> + </func> + <func> + <name>inflateEnd(Z) -> ok</name> + <fsummary>End inflate session</fsummary> + <type> + <v>Z = zstream()</v> + </type> + <desc> + <p>End the inflate session and cleans all data used. Note + that this function will throw a <c>data_error</c> exception + if no end of stream was found (meaning that not all data + has been uncompressed).</p> + </desc> + </func> + <func> + <name>setBufSize(Z, Size) -> ok</name> + <fsummary>Set buffer size</fsummary> + <type> + <v>Z = zstream()</v> + <v>Size = integer()</v> + </type> + <desc> + <p>Sets the intermediate buffer size.</p> + </desc> + </func> + <func> + <name>getBufSize(Z) -> Size</name> + <fsummary>Get buffer size</fsummary> + <type> + <v>Z = zstream()</v> + <v>Size = integer()</v> + </type> + <desc> + <p>Get the size of intermediate buffer.</p> + </desc> + </func> + <func> + <name>crc32(Z) -> CRC</name> + <fsummary>Get current CRC</fsummary> + <type> + <v>Z = zstream()</v> + <v>CRC = integer()</v> + </type> + <desc> + <p>Get the current calculated CRC checksum.</p> + </desc> + </func> + <func> + <name>crc32(Z, Binary) -> CRC</name> + <fsummary>Calculate CRC</fsummary> + <type> + <v>Z = zstream()</v> + <v>Binary = binary()</v> + <v>CRC = integer()</v> + </type> + <desc> + <p>Calculate the CRC checksum for <c>Binary</c>.</p> + </desc> + </func> + <func> + <name>crc32(Z, PrevCRC, Binary) -> CRC </name> + <fsummary>Calculate CRC</fsummary> + <type> + <v>Z = zstream()</v> + <v>PrevCRC = integer()</v> + <v>Binary = binary()</v> + <v>CRC = integer()</v> + </type> + <desc> + <p>Update a running CRC checksum for <c>Binary</c>. + If <c>Binary</c> is the empty binary, this function returns + the required initial value for the crc.</p> + <pre> +Crc = lists:foldl(fun(Bin,Crc0) -> +\011 zlib:crc32(Z, Crc0, Bin), +\011 end, zlib:crc32(Z,<< >>), Bins)</pre> + </desc> + </func> + <func> + <name>crc32_combine(Z, CRC1, CRC2, Size2) -> CRC </name> + <fsummary>Combine two CRC's</fsummary> + <type> + <v>Z = zstream()</v> + <v>CRC = integer()</v> + <v>CRC1 = integer()</v> + <v>CRC2 = integer()</v> + <v>Size2 = integer()</v> + </type> + <desc> + <p>Combine two CRC checksums into one. For two binaries, + <c>Bin1</c> and <c>Bin2</c> with sizes of <c>Size1</c> and + <c>Size2</c>, with CRC checksums <c>CRC1</c> and + <c>CRC2</c>. <c>crc32_combine/4</c> returns the <c>CRC</c> + checksum of <c><<Bin1/binary,Bin2/binary>></c>, requiring + only <c>CRC1</c>, <c>CRC2</c>, and <c>Size2</c>. + </p> + </desc> + </func> + <func> + <name>adler32(Z, Binary) -> Checksum</name> + <fsummary>Calculate the adler checksum</fsummary> + <type> + <v>Z = zstream()</v> + <v>Binary = binary()</v> + <v>Checksum = integer()</v> + </type> + <desc> + <p>Calculate the Adler-32 checksum for <c>Binary</c>.</p> + </desc> + </func> + <func> + <name>adler32(Z, PrevAdler, Binary) -> Checksum</name> + <fsummary>Calculate the adler checksum</fsummary> + <type> + <v>Z = zstream()</v> + <v>PrevAdler = integer()</v> + <v>Binary = binary()</v> + <v>Checksum = integer()</v> + </type> + <desc> + <p>Update a running Adler-32 checksum for <c>Binary</c>. + If <c>Binary</c> is the empty binary, this function returns + the required initial value for the checksum.</p> + <pre> +Crc = lists:foldl(fun(Bin,Crc0) -> +\011 zlib:adler32(Z, Crc0, Bin), +\011 end, zlib:adler32(Z,<< >>), Bins)</pre> + </desc> + </func> + <func> + <name>adler32_combine(Z, Adler1, Adler2, Size2) -> Adler </name> + <fsummary>Combine two Adler-32 checksums</fsummary> + <type> + <v>Z = zstream()</v> + <v>Adler = integer()</v> + <v>Adler1 = integer()</v> + <v>Adler2 = integer()</v> + <v>Size2 = integer()</v> + </type> + <desc> + <p>Combine two Adler-32 checksums into one. For two binaries, + <c>Bin1</c> and <c>Bin2</c> with sizes of <c>Size1</c> and + <c>Size2</c>, with Adler-32 checksums <c>Adler1</c> and + <c>Adler2</c>. <c>adler32_combine/4</c> returns the <c>Adler</c> + checksum of <c><<Bin1/binary,Bin2/binary>></c>, requiring + only <c>Adler1</c>, <c>Adler2</c>, and <c>Size2</c>. + </p> + </desc> + </func> + <func> + <name>compress(Binary) -> Compressed </name> + <fsummary>Compress a binary with standard zlib functionality</fsummary> + <type> + <v>Binary = Compressed = binary()</v> + </type> + <desc> + <p>Compress a binary (with zlib headers and checksum).</p> + </desc> + </func> + <func> + <name>uncompress(Binary) -> Decompressed</name> + <fsummary>Uncompress a binary with standard zlib functionality</fsummary> + <type> + <v>Binary = Decompressed = binary()</v> + </type> + <desc> + <p>Uncompress a binary (with zlib headers and checksum).</p> + </desc> + </func> + <func> + <name>zip(Binary) -> Compressed</name> + <fsummary>Compress a binary without the zlib headers</fsummary> + <type> + <v>Binary = Compressed = binary()</v> + </type> + <desc> + <p>Compress a binary (without zlib headers and checksum).</p> + </desc> + </func> + <func> + <name>unzip(Binary) -> Decompressed</name> + <fsummary>Uncompress a binary without the zlib headers</fsummary> + <type> + <v>Binary = Decompressed = binary()</v> + </type> + <desc> + <p>Uncompress a binary (without zlib headers and checksum).</p> + </desc> + </func> + <func> + <name>gzip(Data) -> Compressed</name> + <fsummary>Compress a binary with gz header</fsummary> + <type> + <v>Binary = Compressed = binary()</v> + </type> + <desc> + <p>Compress a binary (with gz headers and checksum).</p> + </desc> + </func> + <func> + <name>gunzip(Bin) -> Decompressed</name> + <fsummary>Uncompress a binary with gz header</fsummary> + <type> + <v>Binary = Decompressed = binary()</v> + </type> + <desc> + <p>Uncompress a binary (with gz headers and checksum).</p> + </desc> + </func> + </funcs> +</erlref> + |