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 Reasons:
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 re‐
87 lease. 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 re‐
101 quired 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 re‐
111 lease. 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], re‐
126 quiring only Adler1, Adler2, and Size2.
127 Warning:
129 This function is deprecated and will be removed in a future re‐
130 lease. 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 re‐
161 lease. 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 re‐
176 lease. 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 re‐
200 lease. 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 re‐
219 lease. 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 * default gives default compromise between speed and compres‐
304 sion
305 * none (0) gives no compression
307 * best_speed (1) gives best speed
309 * best_compression (9) gives best compression
311 deflateInit(Z, Level, Method, WindowBits, MemLevel, Strategy) ->
313 ok
314 Types:
316 Z = zstream()
318 Level = zlevel()
319 Method = zmethod()
320 WindowBits = zwindowbits()
321 MemLevel = zmemlevel()
322 Strategy = zstrategy()
323 Initiates a zlib stream for compression.
325 Level:
327 Compression level to use:
328 * default gives default compromise between speed and com‐
330 pression
331 * none (0) gives no compression
333 * best_speed (1) gives best speed
335 * best_compression (9) gives best compression
337 Method:
339 Compression method to use, currently the only supported
340 method is deflated.
341 WindowBits:
343 The base two logarithm of the window size (the size of the
344 history buffer). It is to be in the range 8 through 15.
345 Larger values result in better compression at the expense of
346 memory usage. Defaults to 15 if deflateInit/2 is used. A
347 negative WindowBits value suppresses the zlib header (and
348 checksum) from the stream. Notice that the zlib source men‐
349 tions this only as a undocumented feature.
350 Warning:
352 Due to a known bug in the underlying zlib library, WindowBits
353 values 8 and -8 do not work as expected. In zlib versions be‐
354 fore 1.2.9 values 8 and -8 are automatically changed to 9 and
355 -9. From zlib version 1.2.9 value -8 is rejected causing
356 zlib:deflateInit/6 to fail (8 is still changed to 9). It also
357 seem possible that future versions of zlib may fix this bug
358 and start accepting 8 and -8 as is.
359 Conclusion: Avoid values 8 and -8 unless you know your zlib
361 version supports them.
362 MemLevel:
365 Specifies how much memory is to be allocated for the inter‐
366 nal compression state: MemLevel=1 uses minimum memory but is
367 slow and reduces compression ratio; MemLevel=9 uses maximum
368 memory for optimal speed. Defaults to 8.
369 Strategy:
371 Tunes the compression algorithm. Use the following values:
372 * default for normal data
374 * filtered for data produced by a filter (or predictor)
376 * huffman_only to force Huffman encoding only (no string
378 match)
379 * rle to limit match distances to one (run-length encoding)
381 Filtered data consists mostly of small values with a some‐
383 what random distribution. In this case, the compression al‐
384 gorithm is tuned to compress them better. The effect of fil‐
385 tered is to force more Huffman coding and less string match‐
386 ing; it is somewhat intermediate between default and huff‐
387 man_only. rle is designed to be almost as fast as huff‐
388 man_only, but gives better compression for PNG image data.
389 Strategy affects only the compression ratio, but not the
391 correctness of the compressed output even if it is not set
392 appropriately.
393 deflateParams(Z, Level, Strategy) -> ok
395 Types:
397 Z = zstream()
399 Level = zlevel()
400 Strategy = zstrategy()
401 Dynamically updates the compression level and compression strat‐
403 egy. The interpretation of Level and Strategy is as in de‐
404 flateInit/6. This can be used to switch between compression and
405 straight copy of the input data, or to switch to a different
406 kind of input data requiring a different strategy. If the com‐
407 pression level is changed, the input available so far is com‐
408 pressed with the old level (and can be flushed); the new level
409 takes effect only at the next call of deflate/3.
410 Before the call of deflateParams, the stream state must be set
412 as for a call of deflate/3, as the currently available input may
413 have to be compressed and flushed.
414 deflateReset(Z) -> ok
416 Types:
418 Z = zstream()
420 Equivalent to deflateEnd/1 followed by deflateInit/1,2,6, but
422 does not free and reallocate all the internal compression state.
423 The stream keeps the same compression level and any other at‐
424 tributes.
425 deflateSetDictionary(Z, Dictionary) -> Adler32
427 Types:
429 Z = zstream()
431 Dictionary = iodata()
432 Adler32 = integer() >= 0
433 Initializes the compression dictionary from the specified byte
435 sequence without producing any compressed output.
436 This function must be called immediately after deflateInit/1,2,6
438 or deflateReset/1, before any call of deflate/3.
439 The compressor and decompressor must use the same dictionary
441 (see inflateSetDictionary/2).
442 The Adler checksum of the dictionary is returned.
444 getBufSize(Z) -> integer() >= 0
446 Types:
448 Z = zstream()
450 Gets the size of the intermediate buffer.
452 Warning:
454 This function is deprecated and will be removed in a future re‐
455 lease.
456 gunzip(Data) -> Decompressed
459 Types:
461 Data = iodata()
463 Decompressed = binary()
464 Uncompresses data with gz headers and checksum.
466 gzip(Data) -> Compressed
468 Types:
470 Data = iodata()
472 Compressed = binary()
473 Compresses data with gz headers and checksum.
475 inflate(Z, Data) -> Decompressed
477 Types:
479 Z = zstream()
481 Data = iodata()
482 Decompressed = iolist()
483 Equivalent to inflate(Z, Data, [])
485 inflate(Z, Data, Options) -> Decompressed
487 Types:
489 Z = zstream()
491 Data = iodata()
492 Options = [{exception_on_need_dict, boolean()}]
493 Decompressed =
494 iolist() |
495 {need_dictionary,
496 Adler32 :: integer() >= 0,
497 Output :: iolist()}
498 Decompresses as much data as possible. It can introduce some
500 output latency (reading input without producing any output).
501 Currently the only available option is {excep‐
503 tion_on_need_dict,boolean()} which controls whether the function
504 should throw an exception when a preset dictionary is required
505 for decompression. When set to false, a need_dictionary tuple
506 will be returned instead. See inflateSetDictionary/2 for de‐
507 tails.
508 Warning:
510 This option defaults to true for backwards compatibility but we
511 intend to remove the exception behavior in a future release. New
512 code that needs to handle dictionaries manually should always
513 specify {exception_on_need_dict,false}.
514 inflateChunk(Z) -> Decompressed | {more, Decompressed}
517 Types:
519 Z = zstream()
521 Decompressed = iolist()
522 Warning:
524 This function is deprecated and will be removed in a future re‐
525 lease. Use safeInflate/2 instead.
526 Reads the next chunk of uncompressed data, initialized by in‐
529 flateChunk/2.
530 This function is to be repeatedly called, while it returns
532 {more, Decompressed}.
533 inflateChunk(Z, Data) -> Decompressed | {more, Decompressed}
535 Types:
537 Z = zstream()
539 Data = iodata()
540 Decompressed = iolist()
541 Warning:
543 This function is deprecated and will be removed in a future re‐
544 lease. Use safeInflate/2 instead.
545 Like inflate/2, but decompresses no more data than will fit in
548 the buffer configured through setBufSize/2. Is is useful when
549 decompressing a stream with a high compression ratio, such that
550 a small amount of compressed input can expand up to 1000 times.
551 This function returns {more, Decompressed}, when there is more
553 output available, and inflateChunk/1 is to be used to read it.
554 This function can introduce some output latency (reading input
556 without producing any output).
557 An exception will be thrown if a preset dictionary is required
559 for further decompression. See inflateSetDictionary/2 for de‐
560 tails.
561 Example:
563 walk(Compressed, Handler) ->
565 Z = zlib:open(),
566 zlib:inflateInit(Z),
567 % Limit single uncompressed chunk size to 512kb
568 zlib:setBufSize(Z, 512 * 1024),
569 loop(Z, Handler, zlib:inflateChunk(Z, Compressed)),
570 zlib:inflateEnd(Z),
571 zlib:close(Z).
572 loop(Z, Handler, {more, Uncompressed}) ->
574 Handler(Uncompressed),
575 loop(Z, Handler, zlib:inflateChunk(Z));
576 loop(Z, Handler, Uncompressed) ->
577 Handler(Uncompressed).
578 inflateEnd(Z) -> ok
580 Types:
582 Z = zstream()
584 Ends the inflate session and cleans all data used. Notice that
586 this function throws a data_error exception if no end of stream
587 was found (meaning that not all data has been uncompressed).
588 inflateGetDictionary(Z) -> Dictionary
590 Types:
592 Z = zstream()
594 Dictionary = binary()
595 Returns the decompression dictionary currently in use by the
597 stream. This function must be called between inflateInit/1,2 and
598 inflateEnd.
599 Only supported if ERTS was compiled with zlib >= 1.2.8.
601 inflateInit(Z) -> ok
603 Types:
605 Z = zstream()
607 Initializes a zlib stream for decompression.
609 inflateInit(Z, WindowBits) -> ok
611 Types:
613 Z = zstream()
615 WindowBits = zwindowbits()
616 Initializes a decompression session on zlib stream.
618 WindowBits is the base two logarithm of the maximum window size
620 (the size of the history buffer). It is to be in the range 8
621 through 15. Default to 15 if inflateInit/1 is used.
622 If a compressed stream with a larger window size is specified as
624 input, inflate/2 throws the data_error exception.
625 A negative WindowBits value makes zlib ignore the zlib header
627 (and checksum) from the stream. Notice that the zlib source men‐
628 tions this only as a undocumented feature.
629 inflateReset(Z) -> ok
631 Types:
633 Z = zstream()
635 Equivalent to inflateEnd/1 followed by inflateInit/1, but does
637 not free and reallocate all the internal decompression state.
638 The stream will keep attributes that could have been set by in‐
639 flateInit/1,2.
640 inflateSetDictionary(Z, Dictionary) -> ok
642 Types:
644 Z = zstream()
646 Dictionary = iodata()
647 Initializes the decompression dictionary from the specified un‐
649 compressed byte sequence. This function must be called as a re‐
650 sponse to an inflate operation (eg. safeInflate/2) returning
651 {need_dictionary,Adler,Output} or in the case of deprecated
652 functions, throwing an {'EXIT',{{need_dictionary,Adler},_Stack‐
653 Trace}} exception.
654 The dictionary chosen by the compressor can be determined from
656 the Adler value returned or thrown by the call to the inflate
657 function. The compressor and decompressor must use the same dic‐
658 tionary (See deflateSetDictionary/2).
659 After setting the dictionary the inflate operation should be re‐
661 tried without new input.
662 Example:
664 deprecated_unpack(Z, Compressed, Dict) ->
666 case catch zlib:inflate(Z, Compressed) of
667 {'EXIT',{{need_dictionary,_DictID},_}} ->
668 ok = zlib:inflateSetDictionary(Z, Dict),
669 Uncompressed = zlib:inflate(Z, []);
670 Uncompressed ->
671 Uncompressed
672 end.
673 new_unpack(Z, Compressed, Dict) ->
675 case zlib:inflate(Z, Compressed, [{exception_on_need_dict, false}]) of
676 {need_dictionary, _DictId, Output} ->
677 ok = zlib:inflateSetDictionary(Z, Dict),
678 [Output | zlib:inflate(Z, [])];
679 Uncompressed ->
680 Uncompressed
681 end.
682 open() -> zstream()
684 Opens a zlib stream.
686 safeInflate(Z, Data) -> Result
688 Types:
690 Z = zstream()
692 Data = iodata()
693 Result =
694 {continue, Output :: iolist()} |
695 {finished, Output :: iolist()} |
696 {need_dictionary,
697 Adler32 :: integer() >= 0,
698 Output :: iolist()}
699 Like inflate/2, but returns once it has expanded beyond a small
701 implementation-defined threshold. It's useful when decompressing
702 untrusted input which could have been maliciously crafted to ex‐
703 pand until the system runs out of memory.
704 This function returns {continue | finished, Output}, where Out‐
706 put is the data that was decompressed in this call. New input
707 can be queued up on each call if desired, and the function will
708 return {finished, Output} once all queued data has been decom‐
709 pressed.
710 This function can introduce some output latency (reading input
712 without producing any output).
713 If a preset dictionary is required for further decompression,
715 this function returns a need_dictionary tuple. See inflateSet‐
716 Dictionary/2) for details.
717 Example:
719 walk(Compressed, Handler) ->
721 Z = zlib:open(),
722 zlib:inflateInit(Z),
723 loop(Z, Handler, zlib:safeInflate(Z, Compressed)),
724 zlib:inflateEnd(Z),
725 zlib:close(Z).
726 loop(Z, Handler, {continue, Output}) ->
728 Handler(Output),
729 loop(Z, Handler, zlib:safeInflate(Z, []));
730 loop(Z, Handler, {finished, Output}) ->
731 Handler(Output).
732 setBufSize(Z, Size) -> ok
734 Types:
736 Z = zstream()
738 Size = integer() >= 0
739 Sets the intermediate buffer size.
741 Warning:
743 This function is deprecated and will be removed in a future re‐
744 lease.
745 set_controlling_process(Z, Pid) -> ok
748 Types:
750 Z = zstream()
752 Pid = pid()
753 Changes the controlling process of Z to Pid, which must be a lo‐
755 cal process.
756 uncompress(Data) -> Decompressed
758 Types:
760 Data = iodata()
762 Decompressed = binary()
763 Uncompresses data with zlib headers and checksum.
765 unzip(Data) -> Decompressed
767 Types:
769 Data = iodata()
771 Decompressed = binary()
772 Uncompresses data without zlib headers and checksum.
774 zip(Data) -> Compressed
776 Types:
778 Data = iodata()
780 Compressed = binary()
781 Compresses data without zlib headers and checksum.
783Ericsson AB erts 12.1.5 zlib(3)