aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/zlib.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/zlib.xml')
-rw-r--r--erts/doc/src/zlib.xml606
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,&lt;&lt; &gt;&gt;,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,&lt;&lt; &gt;&gt;), 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>&lt;&lt;Bin1/binary,Bin2/binary&gt;&gt;</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,&lt;&lt; &gt;&gt;), 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>&lt;&lt;Bin1/binary,Bin2/binary&gt;&gt;</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>
+