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 Reasonss:
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                * 0 (none), gives no compression
304
305                * 1 (best_speed) gives best speed
306
307                * 9 (best_compression) gives best compression
308
309       deflateInit(Z, Level, Method, WindowBits, MemLevel, Strategy) ->
310                      ok
311
312              Types:
313
314                 Z = zstream()
315                 Level = zlevel()
316                 Method = zmethod()
317                 WindowBits = zwindowbits()
318                 MemLevel = zmemlevel()
319                 Strategy = zstrategy()
320
321              Initiates a zlib stream for compression.
322
323                Level:
324                  Compression level to use:
325
326                  * 0 (none), gives no compression
327
328                  * 1 (best_speed) gives best speed
329
330                  * 9 (best_compression) gives best compression
331
332                Method:
333                  Compression  method  to  use,  currently  the only supported
334                  method is deflated.
335
336                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
345            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 be‐
348                fore 1.2.9 values 8 and -8 are automatically changed to 9  and
349                -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
354                Conclusion: Avoid values 8 and -8 unless you  know  your  zlib
355                version supports them.
356
357
358                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
364                Strategy:
365                  Tunes the compression algorithm. Use the following values:
366
367                  * default for normal data
368
369                  * filtered for data produced by a filter (or predictor)
370
371                  * huffman_only to force Huffman  encoding  only  (no  string
372                    match)
373
374                  * rle to limit match distances to one (run-length encoding)
375
376                  Filtered  data  consists mostly of small values with a some‐
377                  what random distribution. In this case, the compression  al‐
378                  gorithm is tuned to compress them better. The effect of fil‐
379                  tered is to force more Huffman coding and less string match‐
380                  ing;  it  is somewhat intermediate between default and huff‐
381                  man_only. rle is designed to be  almost  as  fast  as  huff‐
382                  man_only, but gives better compression for PNG image data.
383
384                  Strategy  affects  only  the  compression ratio, but not the
385                  correctness of the compressed output even if it is  not  set
386                  appropriately.
387
388       deflateParams(Z, Level, Strategy) -> ok
389
390              Types:
391
392                 Z = zstream()
393                 Level = zlevel()
394                 Strategy = zstrategy()
395
396              Dynamically updates the compression level and compression strat‐
397              egy. The interpretation of Level  and  Strategy  is  as  in  de‐
398              flateInit/6.  This can be used to switch between compression and
399              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
405              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
409       deflateReset(Z) -> ok
410
411              Types:
412
413                 Z = zstream()
414
415              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  at‐
418              tributes.
419
420       deflateSetDictionary(Z, Dictionary) -> Adler32
421
422              Types:
423
424                 Z = zstream()
425                 Dictionary = iodata()
426                 Adler32 = integer() >= 0
427
428              Initializes  the  compression dictionary from the specified byte
429              sequence without producing any compressed output.
430
431              This function must be called immediately after deflateInit/1,2,6
432              or deflateReset/1, before any call of deflate/3.
433
434              The  compressor  and  decompressor  must use the same dictionary
435              (see inflateSetDictionary/2).
436
437              The Adler checksum of the dictionary is returned.
438
439       getBufSize(Z) -> integer() >= 0
440
441              Types:
442
443                 Z = zstream()
444
445              Gets the size of the intermediate buffer.
446
447          Warning:
448              This function is deprecated and will be removed in a future  re‐
449              lease.
450
451
452       gunzip(Data) -> Decompressed
453
454              Types:
455
456                 Data = iodata()
457                 Decompressed = binary()
458
459              Uncompresses data with gz headers and checksum.
460
461       gzip(Data) -> Compressed
462
463              Types:
464
465                 Data = iodata()
466                 Compressed = binary()
467
468              Compresses data with gz headers and checksum.
469
470       inflate(Z, Data) -> Decompressed
471
472              Types:
473
474                 Z = zstream()
475                 Data = iodata()
476                 Decompressed = iolist()
477
478              Equivalent to inflate(Z, Data, [])
479
480       inflate(Z, Data, Options) -> Decompressed
481
482              Types:
483
484                 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
493              Decompresses  as  much  data  as possible. It can introduce some
494              output latency (reading input without producing any output).
495
496              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  de‐
501              tails.
502
503          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
509
510       inflateChunk(Z) -> Decompressed | {more, Decompressed}
511
512              Types:
513
514                 Z = zstream()
515                 Decompressed = iolist()
516
517          Warning:
518              This function is deprecated and will be removed in a future  re‐
519              lease. Use safeInflate/2 instead.
520
521
522              Reads  the  next  chunk of uncompressed data, initialized by in‐
523              flateChunk/2.
524
525              This function is to  be  repeatedly  called,  while  it  returns
526              {more, Decompressed}.
527
528       inflateChunk(Z, Data) -> Decompressed | {more, Decompressed}
529
530              Types:
531
532                 Z = zstream()
533                 Data = iodata()
534                 Decompressed = iolist()
535
536          Warning:
537              This  function is deprecated and will be removed in a future re‐
538              lease. Use safeInflate/2 instead.
539
540
541              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
546              This  function  returns {more, Decompressed}, when there is more
547              output available, and inflateChunk/1 is to be used to read it.
548
549              This function can introduce some output latency  (reading  input
550              without producing any output).
551
552              An  exception  will be thrown if a preset dictionary is required
553              for further decompression. See  inflateSetDictionary/2  for  de‐
554              tails.
555
556              Example:
557
558              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
567              loop(Z, Handler, {more, Uncompressed}) ->
568                  Handler(Uncompressed),
569                  loop(Z, Handler, zlib:inflateChunk(Z));
570              loop(Z, Handler, Uncompressed) ->
571                  Handler(Uncompressed).
572
573       inflateEnd(Z) -> ok
574
575              Types:
576
577                 Z = zstream()
578
579              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
583       inflateGetDictionary(Z) -> Dictionary
584
585              Types:
586
587                 Z = zstream()
588                 Dictionary = binary()
589
590              Returns  the  decompression  dictionary  currently in use by the
591              stream. This function must be called between inflateInit/1,2 and
592              inflateEnd.
593
594              Only supported if ERTS was compiled with zlib >= 1.2.8.
595
596       inflateInit(Z) -> ok
597
598              Types:
599
600                 Z = zstream()
601
602              Initializes a zlib stream for decompression.
603
604       inflateInit(Z, WindowBits) -> ok
605
606              Types:
607
608                 Z = zstream()
609                 WindowBits = zwindowbits()
610
611              Initializes a decompression session on zlib stream.
612
613              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
617              If a compressed stream with a larger window size is specified as
618              input, inflate/2 throws the data_error exception.
619
620              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
624       inflateReset(Z) -> ok
625
626              Types:
627
628                 Z = zstream()
629
630              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  in‐
633              flateInit/1,2.
634
635       inflateSetDictionary(Z, Dictionary) -> ok
636
637              Types:
638
639                 Z = zstream()
640                 Dictionary = iodata()
641
642              Initializes  the decompression dictionary from the specified un‐
643              compressed byte sequence. This function must be called as a  re‐
644              sponse  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
649              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
654              After setting the dictionary the inflate operation should be re‐
655              tried without new input.
656
657              Example:
658
659              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
668              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
677       open() -> zstream()
678
679              Opens a zlib stream.
680
681       safeInflate(Z, Data) -> Result
682
683              Types:
684
685                 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
694              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 ex‐
697              pand until the system runs out of memory.
698
699              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
705              This  function  can introduce some output latency (reading input
706              without producing any output).
707
708              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
712              Example:
713
714              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
721              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
727       setBufSize(Z, Size) -> ok
728
729              Types:
730
731                 Z = zstream()
732                 Size = integer() >= 0
733
734              Sets the intermediate buffer size.
735
736          Warning:
737              This function is deprecated and will be removed in a future  re‐
738              lease.
739
740
741       set_controlling_process(Z, Pid) -> ok
742
743              Types:
744
745                 Z = zstream()
746                 Pid = pid()
747
748              Changes the controlling process of Z to Pid, which must be a lo‐
749              cal process.
750
751       uncompress(Data) -> Decompressed
752
753              Types:
754
755                 Data = iodata()
756                 Decompressed = binary()
757
758              Uncompresses data with zlib headers and checksum.
759
760       unzip(Data) -> Decompressed
761
762              Types:
763
764                 Data = iodata()
765                 Decompressed = binary()
766
767              Uncompresses data without zlib headers and checksum.
768
769       zip(Data) -> Compressed
770
771              Types:
772
773                 Data = iodata()
774                 Compressed = binary()
775
776              Compresses data without zlib headers and checksum.
777
778
779
780Ericsson AB                      erts 11.2.2.2                         zlib(3)
Impressum