From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- erts/doc/src/zlib.xml | 606 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 606 insertions(+) create mode 100644 erts/doc/src/zlib.xml (limited to 'erts/doc/src/zlib.xml') 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 @@ + + + + +
+ + 20052009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + zlib + + + + + zlib.xml +
+ zlib + Zlib Compression interface. + +

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.

+

A typical (compress) usage looks like:

+ 
+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])
+

In all functions errors, {'EXIT',{Reason,Backtrace}}, + might be thrown, where Reason describes the + error. Typical reasons are:

+ + badarg + +

Bad argument

+ + data_error + +

The data contains errors

+ + stream_error + +

Inconsistent stream state

+ + einval + +

Bad value or wrong function called

+ + {need_dictionary,Adler32} + +

See inflate/2

+ + + + +
+ DATA TYPES + +iodata = iolist() | binary() + +iolist = [char() | binary() | iolist()] + a binary is allowed as the tail of the list + +zstream = a zlib stream, see open/0 +
+ + + open() -> Z + Open a stream and return a stream reference + + Z = zstream() + + +

Open a zlib stream.

+ + + + close(Z) -> ok + Close a stream + + Z = zstream() + + +

Closes the stream referenced by Z.

+ + + + deflateInit(Z) -> ok + Initialize a session for compression + + Z = zstream() + + +

Same as zlib:deflateInit(Z, default).

+ + + + deflateInit(Z, Level) -> ok + Initialize a session for compression + + Z = zstream() + Level = none | default | best_speed | best_compression | 0..9 + + +

Initialize a zlib stream for compression.

+

Level decides the compression level to be used, 0 + (none), gives no compression at all, 1 + (best_speed) gives best speed and 9 + (best_compression) gives best compression.

+ + + + deflateInit(Z, Level, Method, WindowBits, MemLevel, Strategy) -> ok + Initialize a session for compression + + Z = zstream() + Level = none | default | best_speed | best_compression | 0..9 + Method = deflated + WindowBits = 9..15|-9..-15 + MemLevel = 1..9 + Strategy = default|filtered|huffman_only + + +

Initiates a zlib stream for compression.

+

The Level parameter decides the compression level to be + used, 0 (none), gives no compression at all, 1 + (best_speed) gives best speed and 9 + (best_compression) gives best compression.

+

The Method parameter decides which compression method to use, + currently the only supported method is deflated.

+

The WindowBits 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 + deflateInit/2. A negative WindowBits + value suppresses the zlib header (and checksum) from the + stream. Note that the zlib source mentions this only as a + undocumented feature.

+

The MemLevel parameter specifies how much memory + should be allocated for the internal compression + state. MemLevel=1 uses minimum memory but is slow and + reduces compression ratio; MemLevel=9 uses maximum + memory for optimal speed. The default value is 8.

+

The Strategy parameter is used to tune the + compression algorithm. Use the value default for + normal data, filtered for data produced by a filter + (or predictor), or huffman_only 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 + filteredis to force more Huffman coding and less + string matching; it is somewhat intermediate between + default and huffman_only. The Strategy + parameter only affects the compression ratio but not the + correctness of the compressed output even if it is not set + appropriately.

+ + + + deflate(Z, Data) -> Compressed + Compress data + + Z = zstream() + Data = iodata() + Compressed = iolist() + + +

Same as deflate(Z, Data, none).

+ + + + deflate(Z, Data, Flush) -> + Compress data + + Z = zstream() + Data = iodata() + Flush = none | sync | full | finish + Compressed = iolist() + + +

deflate/3 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.

+

If the parameter Flush is set to sync, 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.

+

If Flush is set to full, all output is flushed as with + sync, 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 full too often can seriously degrade + the compression.

+

If the parameter Flush is set to finish, + pending input is processed, pending output is flushed and + deflate/3 returns. Afterwards the only possible + operations on the stream are deflateReset/1 or deflateEnd/1.

+

Flush can be set to finish immediately after + deflateInit if all compression is to be done in one step.

+ 
+ 
+zlib:deflateInit(Z),
+B1 = zlib:deflate(Z,Data),
+B2 = zlib:deflate(Z,<< >>,finish),
+zlib:deflateEnd(Z),
+list_to_binary([B1,B2])
+ + + + deflateSetDictionary(Z, Dictionary) -> Adler32 + Initialize the compression dictionary + + Z = zstream() + Dictionary = binary() + Adler32 = integer() + + +

Initializes the compression dictionary from the given byte + sequence without producing any compressed output. This + function must be called immediately after + deflateInit/[1|2|6] or deflateReset/1, before + any call of deflate/3. The compressor and + decompressor must use exactly the same dictionary (see + inflateSetDictionary/2). The adler checksum of the + dictionary is returned.

+ + + + deflateReset(Z) -> ok + Reset the deflate session + + Z = zstream() + + +

This function is equivalent to deflateEnd/1 + followed by deflateInit/[1|2|6], but does not free + and reallocate all the internal compression state. The + stream will keep the same compression level and any other + attributes.

+ + + + deflateParams(Z, Level, Strategy) -> ok + Dynamicly update deflate parameters + + Z = zstream() + Level = none | default | best_speed | best_compression | 0..9 + Strategy = default|filtered|huffman_only + + +

Dynamically update the compression level and compression + strategy. The interpretation of Level and + Strategy is as in deflateInit/6. 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 deflate/3.

+

Before the call of deflateParams, the stream state must be set as for + a call of deflate/3, since the currently available input may have to + be compressed and flushed.

+ + + + deflateEnd(Z) -> ok + End deflate session + + Z = zstream() + + +

End the deflate session and cleans all data used. + Note that this function will throw an data_error + exception if the last call to + deflate/3 was not called with Flush set to + finish.

+ + + + inflateInit(Z) -> ok + Initialize a session for decompression + + Z = zstream() + + +

Initialize a zlib stream for decompression.

+ + + + inflateInit(Z, WindowBits) -> ok + Initialize a session for decompression + + Z = zstream() + WindowBits = 9..15|-9..-15 + + +

Initialize decompression session on zlib stream.

+

The WindowBits 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 inflateInit/1 is used. + If a compressed stream with a larger window size is + given as input, inflate() will throw the data_error + exception. A negative WindowBits value makes zlib ignore the + zlib header (and checksum) from the stream. Note that the zlib + source mentions this only as a undocumented feature.

+ + + + inflate(Z, Data) -> DeCompressed + Decompress data + + Z = zstream() + Data = iodata() + DeCompressed = iolist() + + +

inflate/2 decompresses as much data as possible. + It may some introduce some output latency (reading + input without producing any output).

+

If a preset dictionary is needed at this point (see + inflateSetDictionary below), inflate/2 throws a + {need_dictionary,Adler} exception where Adler is + the adler32 checksum of the dictionary chosen by the + compressor.

+ + + + inflateSetDictionary(Z, Dictionary) -> ok + Initialize the decompression dictionary + + Z = zstream() + Dictionary = binary() + + +

Initializes the decompression dictionary from the given + uncompressed byte sequence. This function must be called + immediately after a call of inflate/2 if this call + threw a {need_dictionary,Adler} exception. + The dictionary chosen by the + compressor can be determined from the Adler value thrown + by the call to inflate/2. The compressor and decompressor + must use exactly the same dictionary (see deflateSetDictionary/2).

+

Example:

+ 
+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.
+ + + + inflateReset(Z) -> ok + >Reset the inflate session + + Z = zstream() + + +

This function is equivalent to inflateEnd/1 followed + by inflateInit/1, but does not free and reallocate all + the internal decompression state. The stream will keep + attributes that may have been set by inflateInit/[1|2].

+ + + + inflateEnd(Z) -> ok + End inflate session + + Z = zstream() + + +

End the inflate session and cleans all data used. Note + that this function will throw a data_error exception + if no end of stream was found (meaning that not all data + has been uncompressed).

+ + + + setBufSize(Z, Size) -> ok + Set buffer size + + Z = zstream() + Size = integer() + + +

Sets the intermediate buffer size.

+ + + + getBufSize(Z) -> Size + Get buffer size + + Z = zstream() + Size = integer() + + +

Get the size of intermediate buffer.

+ + + + crc32(Z) -> CRC + Get current CRC + + Z = zstream() + CRC = integer() + + +

Get the current calculated CRC checksum.

+ + + + crc32(Z, Binary) -> CRC + Calculate CRC + + Z = zstream() + Binary = binary() + CRC = integer() + + +

Calculate the CRC checksum for Binary.

+ + + + crc32(Z, PrevCRC, Binary) -> CRC + Calculate CRC + + Z = zstream() + PrevCRC = integer() + Binary = binary() + CRC = integer() + + +

Update a running CRC checksum for Binary. + If Binary is the empty binary, this function returns + the required initial value for the crc.

+ 
+Crc = lists:foldl(fun(Bin,Crc0) ->  
+\011              zlib:crc32(Z, Crc0, Bin),
+\011          end, zlib:crc32(Z,<< >>), Bins)
+ + + + crc32_combine(Z, CRC1, CRC2, Size2) -> CRC + Combine two CRC's + + Z = zstream() + CRC = integer() + CRC1 = integer() + CRC2 = integer() + Size2 = integer() + + +

Combine two CRC checksums into one. For two binaries, + Bin1 and Bin2 with sizes of Size1 and + Size2, with CRC checksums CRC1 and + CRC2. crc32_combine/4 returns the CRC + checksum of <<Bin1/binary,Bin2/binary>>, requiring + only CRC1, CRC2, and Size2. +

+ + + + adler32(Z, Binary) -> Checksum + Calculate the adler checksum + + Z = zstream() + Binary = binary() + Checksum = integer() + + +

Calculate the Adler-32 checksum for Binary.

+ + + + adler32(Z, PrevAdler, Binary) -> Checksum + Calculate the adler checksum + + Z = zstream() + PrevAdler = integer() + Binary = binary() + Checksum = integer() + + +

Update a running Adler-32 checksum for Binary. + If Binary is the empty binary, this function returns + the required initial value for the checksum.

+ 
+Crc = lists:foldl(fun(Bin,Crc0) ->  
+\011              zlib:adler32(Z, Crc0, Bin),
+\011          end, zlib:adler32(Z,<< >>), Bins)
+ + + + adler32_combine(Z, Adler1, Adler2, Size2) -> Adler + Combine two Adler-32 checksums + + Z = zstream() + Adler = integer() + Adler1 = integer() + Adler2 = integer() + Size2 = integer() + + +

Combine two Adler-32 checksums into one. For two binaries, + Bin1 and Bin2 with sizes of Size1 and + Size2, with Adler-32 checksums Adler1 and + Adler2. adler32_combine/4 returns the Adler + checksum of <<Bin1/binary,Bin2/binary>>, requiring + only Adler1, Adler2, and Size2. +

+ + + + compress(Binary) -> Compressed + Compress a binary with standard zlib functionality + + Binary = Compressed = binary() + + +

Compress a binary (with zlib headers and checksum).

+ + + + uncompress(Binary) -> Decompressed + Uncompress a binary with standard zlib functionality + + Binary = Decompressed = binary() + + +

Uncompress a binary (with zlib headers and checksum).

+ + + + zip(Binary) -> Compressed + Compress a binary without the zlib headers + + Binary = Compressed = binary() + + +

Compress a binary (without zlib headers and checksum).

+ + + + unzip(Binary) -> Decompressed + Uncompress a binary without the zlib headers + + Binary = Decompressed = binary() + + +

Uncompress a binary (without zlib headers and checksum).

+ + + + gzip(Data) -> Compressed + Compress a binary with gz header + + Binary = Compressed = binary() + + +

Compress a binary (with gz headers and checksum).

+ + + + gunzip(Bin) -> Decompressed + Uncompress a binary with gz header + + Binary = Decompressed = binary() + + +

Uncompress a binary (with gz headers and checksum).

+ + + + + -- cgit v1.2.3