1zlib(3)                    Erlang Module Definition                    zlib(3)
2
3
4

NAME

6       zlib - zlib compression interface.
7

DESCRIPTION

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
13       A typical (compress) usage is as follows:
14
15       Z = zlib:open(),
16       ok = zlib:deflateInit(Z,default),
17
18       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
28       In  all  functions  errors, {'EXIT',{Reason,Backtrace}}, can be thrown,
29       where Reason describes the error.
30
31       Typical Reasons:
32
33         badarg:
34           Bad argument.
35
36         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
40         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
45         data_error:
46           The data contains errors.
47
48         stream_error:
49           Inconsistent stream state.
50
51         {need_dictionary,Adler32}:
52           See inflate/2.
53

DATA TYPES

55       zstream() = reference()
56
57              A zlib stream, see open/0.
58
59       zlevel() =
60           none | default | best_compression | best_speed | 0..9
61
62       zflush() = none | sync | full | finish
63
64       zmemlevel() = 1..9
65
66       zmethod() = deflated
67
68       zstrategy() = default | filtered | huffman_only | rle
69
70       zwindowbits() = -15..-8 | 8..47
71
72              Normally in the range -15..-8 | 8..15.
73

EXPORTS

75       adler32(Z, Data) -> CheckSum
76
77              Types:
78
79                 Z = zstream()
80                 Data = iodata()
81                 CheckSum = integer() >= 0
82
83              Calculates the Adler-32 checksum for Data.
84
85          Warning:
86              This  function is deprecated and will be removed in a future re‐
87              lease. Use erlang:adler32/1 instead.
88
89
90       adler32(Z, PrevAdler, Data) -> CheckSum
91
92              Types:
93
94                 Z = zstream()
95                 PrevAdler = integer() >= 0
96                 Data = iodata()
97                 CheckSum = integer() >= 0
98
99              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
103              Example:
104
105              Crc = lists:foldl(fun(Data,Crc0) ->
106                                    zlib:adler32(Z, Crc0, Data),
107                                end, zlib:adler32(Z,<< >>), Datas)
108
109          Warning:
110              This function is deprecated and will be removed in a future  re‐
111              lease. Use erlang:adler32/2 instead.
112
113
114       adler32_combine(Z, Adler1, Adler2, Size2) -> Adler
115
116              Types:
117
118                 Z = zstream()
119                 Adler = Adler1 = Adler2 = Size2 = integer() >= 0
120
121              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
125              This  function  returns the Adler checksum of [Data1,Data2], re‐
126              quiring only Adler1, Adler2, and Size2.
127
128          Warning:
129              This function is deprecated and will be removed in a future  re‐
130              lease. Use erlang:adler32_combine/3 instead.
131
132
133       close(Z) -> ok
134
135              Types:
136
137                 Z = zstream()
138
139              Closes the stream referenced by Z.
140
141       compress(Data) -> Compressed
142
143              Types:
144
145                 Data = iodata()
146                 Compressed = binary()
147
148              Compresses data with zlib headers and checksum.
149
150       crc32(Z) -> CRC
151
152              Types:
153
154                 Z = zstream()
155                 CRC = integer() >= 0
156
157              Gets the current calculated CRC checksum.
158
159          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
163
164       crc32(Z, Data) -> CRC
165
166              Types:
167
168                 Z = zstream()
169                 Data = iodata()
170                 CRC = integer() >= 0
171
172              Calculates the CRC checksum for Data.
173
174          Warning:
175              This function is deprecated and will be removed in a future  re‐
176              lease. Use erlang:crc32/1 instead.
177
178
179       crc32(Z, PrevCRC, Data) -> CRC
180
181              Types:
182
183                 Z = zstream()
184                 PrevCRC = integer() >= 0
185                 Data = iodata()
186                 CRC = integer() >= 0
187
188              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
192              Example:
193
194              Crc = lists:foldl(fun(Data,Crc0) ->
195                                    zlib:crc32(Z, Crc0, Data),
196                                end, zlib:crc32(Z,<< >>), Datas)
197
198          Warning:
199              This  function is deprecated and will be removed in a future re‐
200              lease. Use erlang:crc32/2 instead.
201
202
203       crc32_combine(Z, CRC1, CRC2, Size2) -> CRC
204
205              Types:
206
207                 Z = zstream()
208                 CRC = CRC1 = CRC2 = Size2 = integer() >= 0
209
210              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
214              This function returns the CRC checksum of [Data1,Data2], requir‐
215              ing only CRC1, CRC2, and Size2.
216
217          Warning:
218              This  function is deprecated and will be removed in a future re‐
219              lease. Use erlang:crc32_combine/3 instead.
220
221
222       deflate(Z, Data) -> Compressed
223
224              Types:
225
226                 Z = zstream()
227                 Data = iodata()
228                 Compressed = iolist()
229
230              Same as deflate(Z, Data, none).
231
232       deflate(Z, Data, Flush) -> Compressed
233
234              Types:
235
236                 Z = zstream()
237                 Data = iodata()
238                 Flush = zflush()
239                 Compressed = iolist()
240
241              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
246              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
252              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
258              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
263              Flush can be set to finish immediately after deflateInit if  all
264              compression is to be done in one step.
265
266              Example:
267
268              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
274       deflateEnd(Z) -> ok
275
276              Types:
277
278                 Z = zstream()
279
280              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
284       deflateInit(Z) -> ok
285
286              Types:
287
288                 Z = zstream()
289
290              Same as zlib:deflateInit(Z, default).
291
292       deflateInit(Z, Level) -> ok
293
294              Types:
295
296                 Z = zstream()
297                 Level = zlevel()
298
299              Initializes a zlib stream for compression.
300
301              Level decides the compression level to be used:
302
303                * default  gives default compromise between speed and compres‐
304                  sion
305
306                * none (0) gives no compression
307
308                * best_speed (1) gives best speed
309
310                * best_compression (9) gives best compression
311
312       deflateInit(Z, Level, Method, WindowBits, MemLevel, Strategy) ->
313                      ok
314
315              Types:
316
317                 Z = zstream()
318                 Level = zlevel()
319                 Method = zmethod()
320                 WindowBits = zwindowbits()
321                 MemLevel = zmemlevel()
322                 Strategy = zstrategy()
323
324              Initiates a zlib stream for compression.
325
326                Level:
327                  Compression level to use:
328
329                  * default gives default compromise between  speed  and  com‐
330                    pression
331
332                  * none (0) gives no compression
333
334                  * best_speed (1) gives best speed
335
336                  * best_compression (9) gives best compression
337
338                Method:
339                  Compression  method  to  use,  currently  the only supported
340                  method is deflated.
341
342                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
351            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
360                Conclusion: Avoid values 8 and -8 unless you  know  your  zlib
361                version supports them.
362
363
364                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
370                Strategy:
371                  Tunes the compression algorithm. Use the following values:
372
373                  * default for normal data
374
375                  * filtered for data produced by a filter (or predictor)
376
377                  * huffman_only to force Huffman  encoding  only  (no  string
378                    match)
379
380                  * rle to limit match distances to one (run-length encoding)
381
382                  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
390                  Strategy  affects  only  the  compression ratio, but not the
391                  correctness of the compressed output even if it is  not  set
392                  appropriately.
393
394       deflateParams(Z, Level, Strategy) -> ok
395
396              Types:
397
398                 Z = zstream()
399                 Level = zlevel()
400                 Strategy = zstrategy()
401
402              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
411              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
415       deflateReset(Z) -> ok
416
417              Types:
418
419                 Z = zstream()
420
421              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
426       deflateSetDictionary(Z, Dictionary) -> Adler32
427
428              Types:
429
430                 Z = zstream()
431                 Dictionary = iodata()
432                 Adler32 = integer() >= 0
433
434              Initializes  the  compression dictionary from the specified byte
435              sequence without producing any compressed output.
436
437              This function must be called immediately after deflateInit/1,2,6
438              or deflateReset/1, before any call of deflate/3.
439
440              The  compressor  and  decompressor  must use the same dictionary
441              (see inflateSetDictionary/2).
442
443              The Adler checksum of the dictionary is returned.
444
445       getBufSize(Z) -> integer() >= 0
446
447              Types:
448
449                 Z = zstream()
450
451              Gets the size of the intermediate buffer.
452
453          Warning:
454              This function is deprecated and will be removed in a future  re‐
455              lease.
456
457
458       gunzip(Data) -> Decompressed
459
460              Types:
461
462                 Data = iodata()
463                 Decompressed = binary()
464
465              Uncompresses data with gz headers and checksum.
466
467       gzip(Data) -> Compressed
468
469              Types:
470
471                 Data = iodata()
472                 Compressed = binary()
473
474              Compresses data with gz headers and checksum.
475
476       inflate(Z, Data) -> Decompressed
477
478              Types:
479
480                 Z = zstream()
481                 Data = iodata()
482                 Decompressed = iolist()
483
484              Equivalent to inflate(Z, Data, [])
485
486       inflate(Z, Data, Options) -> Decompressed
487
488              Types:
489
490                 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
499              Decompresses  as  much  data  as possible. It can introduce some
500              output latency (reading input without producing any output).
501
502              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
509          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
515
516       inflateChunk(Z) -> Decompressed | {more, Decompressed}
517
518              Types:
519
520                 Z = zstream()
521                 Decompressed = iolist()
522
523          Warning:
524              This function is deprecated and will be removed in a future  re‐
525              lease. Use safeInflate/2 instead.
526
527
528              Reads  the  next  chunk of uncompressed data, initialized by in‐
529              flateChunk/2.
530
531              This function is to  be  repeatedly  called,  while  it  returns
532              {more, Decompressed}.
533
534       inflateChunk(Z, Data) -> Decompressed | {more, Decompressed}
535
536              Types:
537
538                 Z = zstream()
539                 Data = iodata()
540                 Decompressed = iolist()
541
542          Warning:
543              This  function is deprecated and will be removed in a future re‐
544              lease. Use safeInflate/2 instead.
545
546
547              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
552              This  function  returns {more, Decompressed}, when there is more
553              output available, and inflateChunk/1 is to be used to read it.
554
555              This function can introduce some output latency  (reading  input
556              without producing any output).
557
558              An  exception  will be thrown if a preset dictionary is required
559              for further decompression. See  inflateSetDictionary/2  for  de‐
560              tails.
561
562              Example:
563
564              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
573              loop(Z, Handler, {more, Uncompressed}) ->
574                  Handler(Uncompressed),
575                  loop(Z, Handler, zlib:inflateChunk(Z));
576              loop(Z, Handler, Uncompressed) ->
577                  Handler(Uncompressed).
578
579       inflateEnd(Z) -> ok
580
581              Types:
582
583                 Z = zstream()
584
585              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
589       inflateGetDictionary(Z) -> Dictionary
590
591              Types:
592
593                 Z = zstream()
594                 Dictionary = binary()
595
596              Returns  the  decompression  dictionary  currently in use by the
597              stream. This function must be called between inflateInit/1,2 and
598              inflateEnd.
599
600              Only supported if ERTS was compiled with zlib >= 1.2.8.
601
602       inflateInit(Z) -> ok
603
604              Types:
605
606                 Z = zstream()
607
608              Initializes a zlib stream for decompression.
609
610       inflateInit(Z, WindowBits) -> ok
611
612              Types:
613
614                 Z = zstream()
615                 WindowBits = zwindowbits()
616
617              Initializes a decompression session on zlib stream.
618
619              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
623              If a compressed stream with a larger window size is specified as
624              input, inflate/2 throws the data_error exception.
625
626              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
630       inflateReset(Z) -> ok
631
632              Types:
633
634                 Z = zstream()
635
636              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
641       inflateSetDictionary(Z, Dictionary) -> ok
642
643              Types:
644
645                 Z = zstream()
646                 Dictionary = iodata()
647
648              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
655              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
660              After setting the dictionary the inflate operation should be re‐
661              tried without new input.
662
663              Example:
664
665              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
674              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
683       open() -> zstream()
684
685              Opens a zlib stream.
686
687       safeInflate(Z, Data) -> Result
688
689              Types:
690
691                 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
700              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
705              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
711              This  function  can introduce some output latency (reading input
712              without producing any output).
713
714              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
718              Example:
719
720              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
727              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
733       setBufSize(Z, Size) -> ok
734
735              Types:
736
737                 Z = zstream()
738                 Size = integer() >= 0
739
740              Sets the intermediate buffer size.
741
742          Warning:
743              This function is deprecated and will be removed in a future  re‐
744              lease.
745
746
747       set_controlling_process(Z, Pid) -> ok
748
749              Types:
750
751                 Z = zstream()
752                 Pid = pid()
753
754              Changes the controlling process of Z to Pid, which must be a lo‐
755              cal process.
756
757       uncompress(Data) -> Decompressed
758
759              Types:
760
761                 Data = iodata()
762                 Decompressed = binary()
763
764              Uncompresses data with zlib headers and checksum.
765
766       unzip(Data) -> Decompressed
767
768              Types:
769
770                 Data = iodata()
771                 Decompressed = binary()
772
773              Uncompresses data without zlib headers and checksum.
774
775       zip(Data) -> Compressed
776
777              Types:
778
779                 Data = iodata()
780                 Compressed = binary()
781
782              Compresses data without zlib headers and checksum.
783
784
785
786Ericsson AB                      erts 12.3.2.1                         zlib(3)
Impressum