1zlib(3) Erlang Module Definition zlib(3)
2
6 zlib - zlib compression interface.
7
9 This module provides an API for the zlib library (www.zlib.net). It is
10 used to compress and decompress data. The data format is described by
11 RFC 1950, RFC 1951, and RFC 1952.
12 A typical (compress) usage is as follows:
14 Z = zlib:open(),
16 ok = zlib:deflateInit(Z,default),
17 Compress = fun(end_of_data, _Cont) -> [];
19 (Data, Cont) ->
20 [zlib:deflate(Z, Data)|Cont(Read(),Cont)]
21 end,
22 Compressed = Compress(Read(),Compress),
23 Last = zlib:deflate(Z, [], finish),
24 ok = zlib:deflateEnd(Z),
25 zlib:close(Z),
26 list_to_binary([Compressed|Last])
27 In all functions errors, {'EXIT',{Reason,Backtrace}}, can be thrown,
29 where Reason describes the error.
30 Typical Reasonss:
32 badarg:
34 Bad argument.
35 not_initialized:
37 The stream hasn't been initialized, eg. if inflateInit/1 wasn't
38 called prior to a call to inflate/2.
39 not_on_controlling_process:
41 The stream was used by a process that doesn't control it. Use
42 set_controlling_process/2 if you need to transfer a stream to a
43 different process.
44 data_error:
46 The data contains errors.
47 stream_error:
49 Inconsistent stream state.
50 {need_dictionary,Adler32}:
52 See inflate/2.
53
55 zstream() = reference()
56 A zlib stream, see open/0.
58 zlevel() =
60 none | default | best_compression | best_speed | 0..9
61 zflush() = none | sync | full | finish
63 zmemlevel() = 1..9
65 zmethod() = deflated
67 zstrategy() = default | filtered | huffman_only | rle
69 zwindowbits() = -15..-8 | 8..47
71 Normally in the range -15..-8 | 8..15.
73
75 adler32(Z, Data) -> CheckSum
76 Types:
78 Z = zstream()
80 Data = iodata()
81 CheckSum = integer() >= 0
82 Calculates the Adler-32 checksum for Data.
84 Warning:
86 This function is deprecated and will be removed in a future
87 release. Use erlang:adler32/1 instead.
88 adler32(Z, PrevAdler, Data) -> CheckSum
91 Types:
93 Z = zstream()
95 PrevAdler = integer() >= 0
96 Data = iodata()
97 CheckSum = integer() >= 0
98 Updates a running Adler-32 checksum for Data. If Data is the
100 empty binary or the empty iolist, this function returns the
101 required initial value for the checksum.
102 Example:
104 Crc = lists:foldl(fun(Data,Crc0) ->
106 zlib:adler32(Z, Crc0, Data),
107 end, zlib:adler32(Z,<< >>), Datas)
108 Warning:
110 This function is deprecated and will be removed in a future
111 release. Use erlang:adler32/2 instead.
112 adler32_combine(Z, Adler1, Adler2, Size2) -> Adler
115 Types:
117 Z = zstream()
119 Adler = Adler1 = Adler2 = Size2 = integer() >= 0
120 Combines two Adler-32 checksums into one. For two binaries or
122 iolists, Data1 and Data2 with sizes of Size1 and Size2, with
123 Adler-32 checksums Adler1 and Adler2.
124 This function returns the Adler checksum of [Data1,Data2],
126 requiring only Adler1, Adler2, and Size2.
127 Warning:
129 This function is deprecated and will be removed in a future
130 release. Use erlang:adler32_combine/3 instead.
131 close(Z) -> ok
134 Types:
136 Z = zstream()
138 Closes the stream referenced by Z.
140 compress(Data) -> Compressed
142 Types:
144 Data = iodata()
146 Compressed = binary()
147 Compresses data with zlib headers and checksum.
149 crc32(Z) -> CRC
151 Types:
153 Z = zstream()
155 CRC = integer() >= 0
156 Gets the current calculated CRC checksum.
158 Warning:
160 This function is deprecated and will be removed in a future
161 release. Use erlang:crc32/1 on the uncompressed data instead.
162 crc32(Z, Data) -> CRC
165 Types:
167 Z = zstream()
169 Data = iodata()
170 CRC = integer() >= 0
171 Calculates the CRC checksum for Data.
173 Warning:
175 This function is deprecated and will be removed in a future
176 release. Use erlang:crc32/1 instead.
177 crc32(Z, PrevCRC, Data) -> CRC
180 Types:
182 Z = zstream()
184 PrevCRC = integer() >= 0
185 Data = iodata()
186 CRC = integer() >= 0
187 Updates a running CRC checksum for Data. If Data is the empty
189 binary or the empty iolist, this function returns the required
190 initial value for the CRC.
191 Example:
193 Crc = lists:foldl(fun(Data,Crc0) ->
195 zlib:crc32(Z, Crc0, Data),
196 end, zlib:crc32(Z,<< >>), Datas)
197 Warning:
199 This function is deprecated and will be removed in a future
200 release. Use erlang:crc32/2 instead.
201 crc32_combine(Z, CRC1, CRC2, Size2) -> CRC
204 Types:
206 Z = zstream()
208 CRC = CRC1 = CRC2 = Size2 = integer() >= 0
209 Combines two CRC checksums into one. For two binaries or
211 iolists, Data1 and Data2 with sizes of Size1 and Size2, with CRC
212 checksums CRC1 and CRC2.
213 This function returns the CRC checksum of [Data1,Data2], requir‐
215 ing only CRC1, CRC2, and Size2.
216 Warning:
218 This function is deprecated and will be removed in a future
219 release. Use erlang:crc32_combine/3 instead.
220 deflate(Z, Data) -> Compressed
223 Types:
225 Z = zstream()
227 Data = iodata()
228 Compressed = iolist()
229 Same as deflate(Z, Data, none).
231 deflate(Z, Data, Flush) -> Compressed
233 Types:
235 Z = zstream()
237 Data = iodata()
238 Flush = zflush()
239 Compressed = iolist()
240 Compresses as much data as possible, and stops when the input
242 buffer becomes empty. It can introduce some output latency
243 (reading input without producing any output) except when forced
244 to flush.
245 If Flush is set to sync, all pending output is flushed to the
247 output buffer and the output is aligned on a byte boundary, so
248 that the decompressor can get all input data available so far.
249 Flushing can degrade compression for some compression algo‐
250 rithms; thus, use it only when necessary.
251 If Flush is set to full, all output is flushed as with sync, and
253 the compression state is reset so that decompression can restart
254 from this point if previous compressed data has been damaged or
255 if random access is desired. Using full too often can seriously
256 degrade the compression.
257 If Flush is set to finish, pending input is processed, pending
259 output is flushed, and deflate/3 returns. Afterwards the only
260 possible operations on the stream are deflateReset/1 or defla‐
261 teEnd/1.
262 Flush can be set to finish immediately after deflateInit if all
264 compression is to be done in one step.
265 Example:
267 zlib:deflateInit(Z),
269 B1 = zlib:deflate(Z,Data),
270 B2 = zlib:deflate(Z,<< >>,finish),
271 zlib:deflateEnd(Z),
272 list_to_binary([B1,B2])
273 deflateEnd(Z) -> ok
275 Types:
277 Z = zstream()
279 Ends the deflate session and cleans all data used. Notice that
281 this function throws a data_error exception if the last call to
282 deflate/3 was not called with Flush set to finish.
283 deflateInit(Z) -> ok
285 Types:
287 Z = zstream()
289 Same as zlib:deflateInit(Z, default).
291 deflateInit(Z, Level) -> ok
293 Types:
295 Z = zstream()
297 Level = zlevel()
298 Initializes a zlib stream for compression.
300 Level decides the compression level to be used:
302 * 0 (none), gives no compression
304 * 1 (best_speed) gives best speed
306 * 9 (best_compression) gives best compression
308 deflateInit(Z, Level, Method, WindowBits, MemLevel, Strategy) ->
310 ok
311 Types:
313 Z = zstream()
315 Level = zlevel()
316 Method = zmethod()
317 WindowBits = zwindowbits()
318 MemLevel = zmemlevel()
319 Strategy = zstrategy()
320 Initiates a zlib stream for compression.
322 Level:
324 Compression level to use:
325 * 0 (none), gives no compression
327 * 1 (best_speed) gives best speed
329 * 9 (best_compression) gives best compression
331 Method:
333 Compression method to use, currently the only supported
334 method is deflated.
335 WindowBits:
337 The base two logarithm of the window size (the size of the
338 history buffer). It is to be in the range 8 through 15.
339 Larger values result in better compression at the expense of
340 memory usage. Defaults to 15 if deflateInit/2 is used. A
341 negative WindowBits value suppresses the zlib header (and
342 checksum) from the stream. Notice that the zlib source men‐
343 tions this only as a undocumented feature.
344 Warning:
346 Due to a known bug in the underlying zlib library, WindowBits
347 values 8 and -8 do not work as expected. In zlib versions
348 before 1.2.9 values 8 and -8 are automatically changed to 9
349 and -9. From zlib version 1.2.9 value -8 is rejected causing
350 zlib:deflateInit/6 to fail (8 is still changed to 9). It also
351 seem possible that future versions of zlib may fix this bug
352 and start accepting 8 and -8 as is.
353 Conclusion: Avoid values 8 and -8 unless you know your zlib
355 version supports them.
356 MemLevel:
359 Specifies how much memory is to be allocated for the inter‐
360 nal compression state: MemLevel=1 uses minimum memory but is
361 slow and reduces compression ratio; MemLevel=9 uses maximum
362 memory for optimal speed. Defaults to 8.
363 Strategy:
365 Tunes the compression algorithm. Use the following values:
366 * default for normal data
368 * filtered for data produced by a filter (or predictor)
370 * huffman_only to force Huffman encoding only (no string
372 match)
373 * rle to limit match distances to one (run-length encoding)
375 Filtered data consists mostly of small values with a some‐
377 what random distribution. In this case, the compression
378 algorithm is tuned to compress them better. The effect of
379 filtered is to force more Huffman coding and less string
380 matching; it is somewhat intermediate between default and
381 huffman_only. rle is designed to be almost as fast as huff‐
382 man_only, but gives better compression for PNG image data.
383 Strategy affects only the compression ratio, but not the
385 correctness of the compressed output even if it is not set
386 appropriately.
387 deflateParams(Z, Level, Strategy) -> ok
389 Types:
391 Z = zstream()
393 Level = zlevel()
394 Strategy = zstrategy()
395 Dynamically updates the compression level and compression strat‐
397 egy. The interpretation of Level and Strategy is as in
398 deflateInit/6. This can be used to switch between compression
399 and straight copy of the input data, or to switch to a different
400 kind of input data requiring a different strategy. If the com‐
401 pression level is changed, the input available so far is com‐
402 pressed with the old level (and can be flushed); the new level
403 takes effect only at the next call of deflate/3.
404 Before the call of deflateParams, the stream state must be set
406 as for a call of deflate/3, as the currently available input may
407 have to be compressed and flushed.
408 deflateReset(Z) -> ok
410 Types:
412 Z = zstream()
414 Equivalent to deflateEnd/1 followed by deflateInit/1,2,6, but
416 does not free and reallocate all the internal compression state.
417 The stream keeps the same compression level and any other
418 attributes.
419 deflateSetDictionary(Z, Dictionary) -> Adler32
421 Types:
423 Z = zstream()
425 Dictionary = iodata()
426 Adler32 = integer() >= 0
427 Initializes the compression dictionary from the specified byte
429 sequence without producing any compressed output.
430 This function must be called immediately after deflateInit/1,2,6
432 or deflateReset/1, before any call of deflate/3.
433 The compressor and decompressor must use the same dictionary
435 (see inflateSetDictionary/2).
436 The Adler checksum of the dictionary is returned.
438 getBufSize(Z) -> integer() >= 0
440 Types:
442 Z = zstream()
444 Gets the size of the intermediate buffer.
446 Warning:
448 This function is deprecated and will be removed in a future
449 release.
450 gunzip(Data) -> Decompressed
453 Types:
455 Data = iodata()
457 Decompressed = binary()
458 Uncompresses data with gz headers and checksum.
460 gzip(Data) -> Compressed
462 Types:
464 Data = iodata()
466 Compressed = binary()
467 Compresses data with gz headers and checksum.
469 inflate(Z, Data) -> Decompressed
471 Types:
473 Z = zstream()
475 Data = iodata()
476 Decompressed = iolist()
477 Equivalent to inflate(Z, Data, [])
479 inflate(Z, Data, Options) -> Decompressed
481 Types:
483 Z = zstream()
485 Data = iodata()
486 Options = [{exception_on_need_dict, boolean()}]
487 Decompressed =
488 iolist() |
489 {need_dictionary,
490 Adler32 :: integer() >= 0,
491 Output :: iolist()}
492 Decompresses as much data as possible. It can introduce some
494 output latency (reading input without producing any output).
495 Currently the only available option is {excep‐
497 tion_on_need_dict,boolean()} which controls whether the function
498 should throw an exception when a preset dictionary is required
499 for decompression. When set to false, a need_dictionary tuple
500 will be returned instead. See inflateSetDictionary/2 for
501 details.
502 Warning:
504 This option defaults to true for backwards compatibility but we
505 intend to remove the exception behavior in a future release. New
506 code that needs to handle dictionaries manually should always
507 specify {exception_on_need_dict,false}.
508 inflateChunk(Z) -> Decompressed | {more, Decompressed}
511 Types:
513 Z = zstream()
515 Decompressed = iolist()
516 Warning:
518 This function is deprecated and will be removed in a future
519 release. Use safeInflate/2 instead.
520 Reads the next chunk of uncompressed data, initialized by
523 inflateChunk/2.
524 This function is to be repeatedly called, while it returns
526 {more, Decompressed}.
527 inflateChunk(Z, Data) -> Decompressed | {more, Decompressed}
529 Types:
531 Z = zstream()
533 Data = iodata()
534 Decompressed = iolist()
535 Warning:
537 This function is deprecated and will be removed in a future
538 release. Use safeInflate/2 instead.
539 Like inflate/2, but decompresses no more data than will fit in
542 the buffer configured through setBufSize/2. Is is useful when
543 decompressing a stream with a high compression ratio, such that
544 a small amount of compressed input can expand up to 1000 times.
545 This function returns {more, Decompressed}, when there is more
547 output available, and inflateChunk/1 is to be used to read it.
548 This function can introduce some output latency (reading input
550 without producing any output).
551 An exception will be thrown if a preset dictionary is required
553 for further decompression. See inflateSetDictionary/2 for
554 details.
555 Example:
557 walk(Compressed, Handler) ->
559 Z = zlib:open(),
560 zlib:inflateInit(Z),
561 % Limit single uncompressed chunk size to 512kb
562 zlib:setBufSize(Z, 512 * 1024),
563 loop(Z, Handler, zlib:inflateChunk(Z, Compressed)),
564 zlib:inflateEnd(Z),
565 zlib:close(Z).
566 loop(Z, Handler, {more, Uncompressed}) ->
568 Handler(Uncompressed),
569 loop(Z, Handler, zlib:inflateChunk(Z));
570 loop(Z, Handler, Uncompressed) ->
571 Handler(Uncompressed).
572 inflateEnd(Z) -> ok
574 Types:
576 Z = zstream()
578 Ends the inflate session and cleans all data used. Notice that
580 this function throws a data_error exception if no end of stream
581 was found (meaning that not all data has been uncompressed).
582 inflateGetDictionary(Z) -> Dictionary
584 Types:
586 Z = zstream()
588 Dictionary = binary()
589 Returns the decompression dictionary currently in use by the
591 stream. This function must be called between inflateInit/1,2 and
592 inflateEnd.
593 Only supported if ERTS was compiled with zlib >= 1.2.8.
595 inflateInit(Z) -> ok
597 Types:
599 Z = zstream()
601 Initializes a zlib stream for decompression.
603 inflateInit(Z, WindowBits) -> ok
605 Types:
607 Z = zstream()
609 WindowBits = zwindowbits()
610 Initializes a decompression session on zlib stream.
612 WindowBits is the base two logarithm of the maximum window size
614 (the size of the history buffer). It is to be in the range 8
615 through 15. Default to 15 if inflateInit/1 is used.
616 If a compressed stream with a larger window size is specified as
618 input, inflate/2 throws the data_error exception.
619 A negative WindowBits value makes zlib ignore the zlib header
621 (and checksum) from the stream. Notice that the zlib source men‐
622 tions this only as a undocumented feature.
623 inflateReset(Z) -> ok
625 Types:
627 Z = zstream()
629 Equivalent to inflateEnd/1 followed by inflateInit/1, but does
631 not free and reallocate all the internal decompression state.
632 The stream will keep attributes that could have been set by
633 inflateInit/1,2.
634 inflateSetDictionary(Z, Dictionary) -> ok
636 Types:
638 Z = zstream()
640 Dictionary = iodata()
641 Initializes the decompression dictionary from the specified
643 uncompressed byte sequence. This function must be called as a
644 response to an inflate operation (eg. safeInflate/2) returning
645 {need_dictionary,Adler,Output} or in the case of deprecated
646 functions, throwing an {'EXIT',{{need_dictionary,Adler},_Stack‐
647 Trace}} exception.
648 The dictionary chosen by the compressor can be determined from
650 the Adler value returned or thrown by the call to the inflate
651 function. The compressor and decompressor must use the same dic‐
652 tionary (See deflateSetDictionary/2).
653 After setting the dictionary the inflate operation should be
655 retried without new input.
656 Example:
658 deprecated_unpack(Z, Compressed, Dict) ->
660 case catch zlib:inflate(Z, Compressed) of
661 {'EXIT',{{need_dictionary,_DictID},_}} ->
662 ok = zlib:inflateSetDictionary(Z, Dict),
663 Uncompressed = zlib:inflate(Z, []);
664 Uncompressed ->
665 Uncompressed
666 end.
667 new_unpack(Z, Compressed, Dict) ->
669 case zlib:inflate(Z, Compressed, [{exception_on_need_dict, false}]) of
670 {need_dictionary, _DictId, Output} ->
671 ok = zlib:inflateSetDictionary(Z, Dict),
672 [Output | zlib:inflate(Z, [])];
673 Uncompressed ->
674 Uncompressed
675 end.
676 open() -> zstream()
678 Opens a zlib stream.
680 safeInflate(Z, Data) -> Result
682 Types:
684 Z = zstream()
686 Data = iodata()
687 Result =
688 {continue, Output :: iolist()} |
689 {finished, Output :: iolist()} |
690 {need_dictionary,
691 Adler32 :: integer() >= 0,
692 Output :: iolist()}
693 Like inflate/2, but returns once it has expanded beyond a small
695 implementation-defined threshold. It's useful when decompressing
696 untrusted input which could have been maliciously crafted to
697 expand until the system runs out of memory.
698 This function returns {continue | finished, Output}, where Out‐
700 put is the data that was decompressed in this call. New input
701 can be queued up on each call if desired, and the function will
702 return {finished, Output} once all queued data has been decom‐
703 pressed.
704 This function can introduce some output latency (reading input
706 without producing any output).
707 If a preset dictionary is required for further decompression,
709 this function returns a need_dictionary tuple. See inflateSet‐
710 Dictionary/2) for details.
711 Example:
713 walk(Compressed, Handler) ->
715 Z = zlib:open(),
716 zlib:inflateInit(Z),
717 loop(Z, Handler, zlib:safeInflate(Z, Compressed)),
718 zlib:inflateEnd(Z),
719 zlib:close(Z).
720 loop(Z, Handler, {continue, Output}) ->
722 Handler(Output),
723 loop(Z, Handler, zlib:safeInflate(Z, []));
724 loop(Z, Handler, {finished, Output}) ->
725 Handler(Output).
726 setBufSize(Z, Size) -> ok
728 Types:
730 Z = zstream()
732 Size = integer() >= 0
733 Sets the intermediate buffer size.
735 Warning:
737 This function is deprecated and will be removed in a future
738 release.
739 set_controlling_process(Z, Pid) -> ok
742 Types:
744 Z = zstream()
746 Pid = pid()
747 Changes the controlling process of Z to Pid, which must be a
749 local process.
750 uncompress(Data) -> Decompressed
752 Types:
754 Data = iodata()
756 Decompressed = binary()
757 Uncompresses data with zlib headers and checksum.
759 unzip(Data) -> Decompressed
761 Types:
763 Data = iodata()
765 Decompressed = binary()
766 Uncompresses data without zlib headers and checksum.
768 zip(Data) -> Compressed
770 Types:
772 Data = iodata()
774 Compressed = binary()
775 Compresses data without zlib headers and checksum.
777Ericsson AB erts 10.7.1 zlib(3)