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() = term()
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()
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()
96 Data = iodata()
97 CheckSum = integer()
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()
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()
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()
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()
185 Data = iodata()
186 CRC = integer()
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()
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()
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, Adler32 :: integer(), Output ::
490 iolist()}
491 Decompresses as much data as possible. It can introduce some
493 output latency (reading input without producing any output).
494 Currently the only available option is {excep‐
496 tion_on_need_dict,boolean()} which controls whether the function
497 should throw an exception when a preset dictionary is required
498 for decompression. When set to false, a need_dictionary tuple
499 will be returned instead. See inflateSetDictionary/2 for
500 details.
501 Warning:
503 This option defaults to true for backwards compatibility but we
504 intend to remove the exception behavior in a future release. New
505 code that needs to handle dictionaries manually should always
506 specify {exception_on_need_dict,false}.
507 inflateChunk(Z) -> Decompressed | {more, Decompressed}
510 Types:
512 Z = zstream()
514 Decompressed = iolist()
515 Warning:
517 This function is deprecated and will be removed in a future
518 release. Use safeInflate/2 instead.
519 Reads the next chunk of uncompressed data, initialized by
522 inflateChunk/2.
523 This function is to be repeatedly called, while it returns
525 {more, Decompressed}.
526 inflateChunk(Z, Data) -> Decompressed | {more, Decompressed}
528 Types:
530 Z = zstream()
532 Data = iodata()
533 Decompressed = iolist()
534 Warning:
536 This function is deprecated and will be removed in a future
537 release. Use safeInflate/2 instead.
538 Like inflate/2, but decompresses no more data than will fit in
541 the buffer configured through setBufSize/2. Is is useful when
542 decompressing a stream with a high compression ratio, such that
543 a small amount of compressed input can expand up to 1000 times.
544 This function returns {more, Decompressed}, when there is more
546 output available, and inflateChunk/1 is to be used to read it.
547 This function can introduce some output latency (reading input
549 without producing any output).
550 An exception will be thrown if a preset dictionary is required
552 for further decompression. See inflateSetDictionary/2 for
553 details.
554 Example:
556 walk(Compressed, Handler) ->
558 Z = zlib:open(),
559 zlib:inflateInit(Z),
560 % Limit single uncompressed chunk size to 512kb
561 zlib:setBufSize(Z, 512 * 1024),
562 loop(Z, Handler, zlib:inflateChunk(Z, Compressed)),
563 zlib:inflateEnd(Z),
564 zlib:close(Z).
565 loop(Z, Handler, {more, Uncompressed}) ->
567 Handler(Uncompressed),
568 loop(Z, Handler, zlib:inflateChunk(Z));
569 loop(Z, Handler, Uncompressed) ->
570 Handler(Uncompressed).
571 inflateEnd(Z) -> ok
573 Types:
575 Z = zstream()
577 Ends the inflate session and cleans all data used. Notice that
579 this function throws a data_error exception if no end of stream
580 was found (meaning that not all data has been uncompressed).
581 inflateGetDictionary(Z) -> Dictionary
583 Types:
585 Z = zstream()
587 Dictionary = binary()
588 Returns the decompression dictionary currently in use by the
590 stream. This function must be called between inflateInit/1,2 and
591 inflateEnd.
592 Only supported if ERTS was compiled with zlib >= 1.2.8.
594 inflateInit(Z) -> ok
596 Types:
598 Z = zstream()
600 Initializes a zlib stream for decompression.
602 inflateInit(Z, WindowBits) -> ok
604 Types:
606 Z = zstream()
608 WindowBits = zwindowbits()
609 Initializes a decompression session on zlib stream.
611 WindowBits is the base two logarithm of the maximum window size
613 (the size of the history buffer). It is to be in the range 8
614 through 15. Default to 15 if inflateInit/1 is used.
615 If a compressed stream with a larger window size is specified as
617 input, inflate/2 throws the data_error exception.
618 A negative WindowBits value makes zlib ignore the zlib header
620 (and checksum) from the stream. Notice that the zlib source men‐
621 tions this only as a undocumented feature.
622 inflateReset(Z) -> ok
624 Types:
626 Z = zstream()
628 Equivalent to inflateEnd/1 followed by inflateInit/1, but does
630 not free and reallocate all the internal decompression state.
631 The stream will keep attributes that could have been set by
632 inflateInit/1,2.
633 inflateSetDictionary(Z, Dictionary) -> ok
635 Types:
637 Z = zstream()
639 Dictionary = iodata()
640 Initializes the decompression dictionary from the specified
642 uncompressed byte sequence. This function must be called as a
643 response to an inflate operation (eg. safeInflate/2) returning
644 {need_dictionary,Adler,Output} or in the case of deprecated
645 functions, throwing an {'EXIT',{{need_dictionary,Adler},_Stack‐
646 Trace}} exception.
647 The dictionary chosen by the compressor can be determined from
649 the Adler value returned or thrown by the call to the inflate
650 function. The compressor and decompressor must use the same dic‐
651 tionary (See deflateSetDictionary/2).
652 After setting the dictionary the inflate operation should be
654 retried without new input.
655 Example:
657 deprecated_unpack(Z, Compressed, Dict) ->
659 case catch zlib:inflate(Z, Compressed) of
660 {'EXIT',{{need_dictionary,_DictID},_}} ->
661 ok = zlib:inflateSetDictionary(Z, Dict),
662 Uncompressed = zlib:inflate(Z, []);
663 Uncompressed ->
664 Uncompressed
665 end.
666 new_unpack(Z, Compressed, Dict) ->
668 case zlib:inflate(Z, Compressed, [{exception_on_need_dict, false}]) of
669 {need_dictionary, _DictId, Output} ->
670 ok = zlib:inflateSetDictionary(Z, Dict),
671 [Output | zlib:inflate(Z, [])];
672 Uncompressed ->
673 Uncompressed
674 end.
675 open() -> zstream()
677 Opens a zlib stream.
679 safeInflate(Z, Data) -> Result
681 Types:
683 Z = zstream()
685 Data = iodata()
686 Result =
687 {continue, Output :: iolist()} |
688 {finished, Output :: iolist()} |
689 {need_dictionary, Adler32 :: integer(), Output ::
690 iolist()}
691 Like inflate/2, but returns once it has expanded beyond a small
693 implementation-defined threshold. It's useful when decompressing
694 untrusted input which could have been maliciously crafted to
695 expand until the system runs out of memory.
696 This function returns {continue | finished, Output}, where Out‐
698 put is the data that was decompressed in this call. New input
699 can be queued up on each call if desired, and the function will
700 return {finished, Output} once all queued data has been decom‐
701 pressed.
702 This function can introduce some output latency (reading input
704 without producing any output).
705 If a preset dictionary is required for further decompression,
707 this function returns a need_dictionary tuple. See inflateSet‐
708 Dictionary/2) for details.
709 Example:
711 walk(Compressed, Handler) ->
713 Z = zlib:open(),
714 zlib:inflateInit(Z),
715 loop(Z, Handler, zlib:safeInflate(Z, Compressed)),
716 zlib:inflateEnd(Z),
717 zlib:close(Z).
718 loop(Z, Handler, {continue, Output}) ->
720 Handler(Output),
721 loop(Z, Handler, zlib:safeInflate(Z, []));
722 loop(Z, Handler, {finished, Output}) ->
723 Handler(Output).
724 setBufSize(Z, Size) -> ok
726 Types:
728 Z = zstream()
730 Size = integer() >= 0
731 Sets the intermediate buffer size.
733 Warning:
735 This function is deprecated and will be removed in a future
736 release.
737 set_controlling_process(Z, Pid) -> ok
740 Types:
742 Z = zstream()
744 Pid = pid()
745 Changes the controlling process of Z to Pid, which must be a
747 local process.
748 uncompress(Data) -> Decompressed
750 Types:
752 Data = iodata()
754 Decompressed = binary()
755 Uncompresses data with zlib headers and checksum.
757 unzip(Data) -> Decompressed
759 Types:
761 Data = iodata()
763 Decompressed = binary()
764 Uncompresses data without zlib headers and checksum.
766 zip(Data) -> Compressed
768 Types:
770 Data = iodata()
772 Compressed = binary()
773 Compresses data without zlib headers and checksum.
775Ericsson AB erts 9.3.3.10 zlib(3)