Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
zlib(3)			   Erlang Module Definition		       zlib(3)

NAME
       zlib - zlib compression interface.

DESCRIPTION
       This  module provides an	API for	the zlib library (www.zlib.net). It is
       used to compress	and decompress data. The data format is	 described  by
       RFC 1950, RFC 1951, and RFC 1952.

       A typical (compress) usage is as	follows:

       Z = zlib:open(),
       ok = zlib:deflateInit(Z,default),

       Compress	= fun(end_of_data, _Cont) -> [];
		     (Data, Cont) ->
			[zlib:deflate(Z, Data)|Cont(Read(),Cont)]
		  end,
       Compressed = Compress(Read(),Compress),
       Last = zlib:deflate(Z, [], finish),
       ok = zlib:deflateEnd(Z),
       zlib:close(Z),
       list_to_binary([Compressed|Last])

       In  all	functions  errors, {'EXIT',{Reason,Backtrace}},	can be thrown,
       where Reason describes the error.

       Typical Reasons:

	 badarg:
	   Bad argument.

	 not_initialized:
	   The stream hasn't been initialized,	eg.  if	 inflateInit/1	wasn't
	   called prior	to a call to inflate/2.

	 not_on_controlling_process:
	   The	stream	was  used  by  a  process that doesn't control it. Use
	   set_controlling_process/2 if	you need to transfer  a	 stream	 to  a
	   different process.

	 data_error:
	   The data contains errors.

	 stream_error:
	   Inconsistent	stream state.

	 {need_dictionary,Adler32}:
	   See inflate/2.

DATA TYPES
       zstream() = reference()

	      A	zlib stream, see open/0.

       zlevel()	=
	   none	| default | best_compression | best_speed | 0..9

       zflush()	= none | sync |	full | finish

       zmemlevel() = 1..9

       zmethod() = deflated

       zstrategy() = default | filtered	| huffman_only | rle

       zwindowbits() = -15..-8 | 8..47

	      Normally in the range -15..-8 | 8..15.

EXPORTS
       adler32(Z, Data)	-> CheckSum

	      Types:

		 Z = zstream()
		 Data =	iodata()
		 CheckSum = integer() >= 0

	      Calculates the Adler-32 checksum for Data.

	  Warning:
	      This  function is	deprecated and will be removed in a future re-
	      lease. Use erlang:adler32/1 instead.

       adler32(Z, PrevAdler, Data) -> CheckSum

	      Types:

		 Z = zstream()
		 PrevAdler = integer() >= 0
		 Data =	iodata()
		 CheckSum = integer() >= 0

	      Updates a	running	Adler-32 checksum for Data.  If	 Data  is  the
	      empty  binary or the empty iolist, this function returns the re-
	      quired initial value for the checksum.

	      Example:

	      Crc = lists:foldl(fun(Data,Crc0) ->
				    zlib:adler32(Z, Crc0, Data),
				end, zlib:adler32(Z,<< >>), Datas)

	  Warning:
	      This function is deprecated and will be removed in a future  re-
	      lease. Use erlang:adler32/2 instead.

       adler32_combine(Z, Adler1, Adler2, Size2) -> Adler

	      Types:

		 Z = zstream()
		 Adler = Adler1	= Adler2 = Size2 = integer() >=	0

	      Combines	two  Adler-32  checksums into one. For two binaries or
	      iolists, Data1 and Data2 with sizes of  Size1  and  Size2,  with
	      Adler-32 checksums Adler1	and Adler2.

	      This  function  returns the Adler	checksum of [Data1,Data2], re-
	      quiring only Adler1, Adler2, and Size2.

	  Warning:
	      This function is deprecated and will be removed in a future  re-
	      lease. Use erlang:adler32_combine/3 instead.

       close(Z)	-> ok

	      Types:

		 Z = zstream()

	      Closes the stream	referenced by Z.

       compress(Data) -> Compressed

	      Types:

		 Data =	iodata()
		 Compressed = binary()

	      Compresses data with zlib	headers	and checksum.

       crc32(Z)	-> CRC

	      Types:

		 Z = zstream()
		 CRC = integer() >= 0

	      Gets the current calculated CRC checksum.

	  Warning:
	      This  function is	deprecated and will be removed in a future re-
	      lease. Use erlang:crc32/1	on the uncompressed data instead.

       crc32(Z,	Data) -> CRC

	      Types:

		 Z = zstream()
		 Data =	iodata()
		 CRC = integer() >= 0

	      Calculates the CRC checksum for Data.

	  Warning:
	      This function is deprecated and will be removed in a future  re-
	      lease. Use erlang:crc32/1	instead.

       crc32(Z,	PrevCRC, Data) -> CRC

	      Types:

		 Z = zstream()
		 PrevCRC = integer() >=	0
		 Data =	iodata()
		 CRC = integer() >= 0

	      Updates  a  running  CRC checksum	for Data. If Data is the empty
	      binary or	the empty iolist, this function	returns	 the  required
	      initial value for	the CRC.

	      Example:

	      Crc = lists:foldl(fun(Data,Crc0) ->
				    zlib:crc32(Z, Crc0,	Data),
				end, zlib:crc32(Z,<< >>), Datas)

	  Warning:
	      This  function is	deprecated and will be removed in a future re-
	      lease. Use erlang:crc32/2	instead.

       crc32_combine(Z,	CRC1, CRC2, Size2) -> CRC

	      Types:

		 Z = zstream()
		 CRC = CRC1 = CRC2 = Size2 = integer() >= 0

	      Combines two  CRC	 checksums  into  one.	For  two  binaries  or
	      iolists, Data1 and Data2 with sizes of Size1 and Size2, with CRC
	      checksums	CRC1 and CRC2.

	      This function returns the	CRC checksum of	[Data1,Data2], requir-
	      ing only CRC1, CRC2, and Size2.

	  Warning:
	      This  function is	deprecated and will be removed in a future re-
	      lease. Use erlang:crc32_combine/3	instead.

       deflate(Z, Data)	-> Compressed

	      Types:

		 Z = zstream()
		 Data =	iodata()
		 Compressed = iolist()

	      Same as deflate(Z, Data, none).

       deflate(Z, Data,	Flush) -> Compressed

	      Types:

		 Z = zstream()
		 Data =	iodata()
		 Flush = zflush()
		 Compressed = iolist()

	      Compresses as much data as possible, and stops  when  the	 input
	      buffer  becomes  empty.  It  can	introduce  some	output latency
	      (reading input without producing any output) except when	forced
	      to flush.

	      If  Flush	 is  set to sync, all pending output is	flushed	to the
	      output buffer and	the output is aligned on a byte	 boundary,  so
	      that  the	 decompressor can get all input	data available so far.
	      Flushing can degrade  compression	 for  some  compression	 algo-
	      rithms; thus, use	it only	when necessary.

	      If Flush is set to full, all output is flushed as	with sync, and
	      the compression state is reset so	that decompression can restart
	      from  this point if previous compressed data has been damaged or
	      if random	access is desired. Using full too often	can  seriously
	      degrade the compression.

	      If  Flush	 is set	to finish, pending input is processed, pending
	      output is	flushed, and deflate/3 returns.	 Afterwards  the  only
	      possible	operations  on the stream are deflateReset/1 or	defla-
	      teEnd/1.

	      Flush can	be set to finish immediately after deflateInit if  all
	      compression is to	be done	in one step.

	      Example:

	      zlib:deflateInit(Z),
	      B1 = zlib:deflate(Z,Data),
	      B2 = zlib:deflate(Z,<< >>,finish),
	      zlib:deflateEnd(Z),
	      list_to_binary([B1,B2])

       deflateEnd(Z) ->	ok

	      Types:

		 Z = zstream()

	      Ends  the	 deflate session and cleans all	data used. Notice that
	      this function throws a data_error	exception if the last call  to
	      deflate/3	was not	called with Flush set to finish.

       deflateInit(Z) -> ok

	      Types:

		 Z = zstream()

	      Same as zlib:deflateInit(Z, default).

       deflateInit(Z, Level) ->	ok

	      Types:

		 Z = zstream()
		 Level = zlevel()

	      Initializes a zlib stream	for compression.

	      Level decides the	compression level to be	used:

		* default  gives default compromise between speed and compres-
		  sion

		* none (0) gives no compression

		* best_speed (1) gives best speed

		* best_compression (9) gives best compression

       deflateInit(Z, Level, Method, WindowBits, MemLevel, Strategy) ->
		      ok

	      Types:

		 Z = zstream()
		 Level = zlevel()
		 Method	= zmethod()
		 WindowBits = zwindowbits()
		 MemLevel = zmemlevel()
		 Strategy = zstrategy()

	      Initiates	a zlib stream for compression.

		Level:
		  Compression level to use:

		  * default gives default compromise between  speed  and  com-
		    pression

		  * none (0) gives no compression

		  * best_speed (1) gives best speed

		  * best_compression (9) gives best compression

		Method:
		  Compression  method  to  use,	 currently  the	only supported
		  method is deflated.

		WindowBits:
		  The base two logarithm of the	window size (the size  of  the
		  history  buffer).  It	 is  to	 be in the range 8 through 15.
		  Larger values	result in better compression at	the expense of
		  memory  usage.  Defaults  to	15 if deflateInit/2 is used. A
		  negative WindowBits value suppresses the  zlib  header  (and
		  checksum)  from the stream. Notice that the zlib source men-
		  tions	this only as a undocumented feature.

	    Warning:
		Due to a known bug in the underlying zlib library,  WindowBits
		values	8 and -8 do not	work as	expected. In zlib versions be-
		fore 1.2.9 values 8 and	-8 are automatically changed to	9  and
		-9.  From  zlib	 version  1.2.9	 value	-8 is rejected causing
		zlib:deflateInit/6 to fail (8 is still changed to 9). It  also
		seem  possible	that  future versions of zlib may fix this bug
		and start accepting 8 and -8 as	is.

		Conclusion: Avoid values 8 and -8 unless you  know  your  zlib
		version	supports them.

		MemLevel:
		  Specifies  how much memory is	to be allocated	for the	inter-
		  nal compression state: MemLevel=1 uses minimum memory	but is
		  slow	and reduces compression	ratio; MemLevel=9 uses maximum
		  memory for optimal speed. Defaults to	8.

		Strategy:
		  Tunes	the compression	algorithm. Use the following values:

		  * default for	normal data

		  * filtered for data produced by a filter (or predictor)

		  * huffman_only to force Huffman  encoding  only  (no	string
		    match)

		  * rle	to limit match distances to one	(run-length encoding)

		  Filtered  data  consists mostly of small values with a some-
		  what random distribution. In this case, the compression  al-
		  gorithm is tuned to compress them better. The	effect of fil-
		  tered	is to force more Huffman coding	and less string	match-
		  ing;	it  is somewhat	intermediate between default and huff-
		  man_only. rle	is designed to be  almost  as  fast  as	 huff-
		  man_only, but	gives better compression for PNG image data.

		  Strategy  affects  only  the	compression ratio, but not the
		  correctness of the compressed	output even if it is  not  set
		  appropriately.

       deflateParams(Z,	Level, Strategy) -> ok

	      Types:

		 Z = zstream()
		 Level = zlevel()
		 Strategy = zstrategy()

	      Dynamically updates the compression level	and compression	strat-
	      egy. The interpretation of Level	and  Strategy  is  as  in  de-
	      flateInit/6.  This can be	used to	switch between compression and
	      straight copy of the input data, or to  switch  to  a  different
	      kind  of	input data requiring a different strategy. If the com-
	      pression level is	changed, the input available so	 far  is  com-
	      pressed  with  the old level (and	can be flushed); the new level
	      takes effect only	at the next call of deflate/3.

	      Before the call of deflateParams,	the stream state must  be  set
	      as for a call of deflate/3, as the currently available input may
	      have to be compressed and	flushed.

       deflateReset(Z) -> ok

	      Types:

		 Z = zstream()

	      Equivalent to deflateEnd/1 followed  by  deflateInit/1,2,6,  but
	      does not free and	reallocate all the internal compression	state.
	      The stream keeps the same	compression level and  any  other  at-
	      tributes.

       deflateSetDictionary(Z, Dictionary) -> Adler32

	      Types:

		 Z = zstream()
		 Dictionary = iodata()
		 Adler32 = integer() >=	0

	      Initializes  the	compression dictionary from the	specified byte
	      sequence without producing any compressed	output.

	      This function must be called immediately after deflateInit/1,2,6
	      or deflateReset/1, before	any call of deflate/3.

	      The  compressor  and  decompressor  must use the same dictionary
	      (see inflateSetDictionary/2).

	      The Adler	checksum of the	dictionary is returned.

       getBufSize(Z) ->	integer() >= 0

	      Types:

		 Z = zstream()

	      Gets the size of the intermediate	buffer.

	  Warning:
	      This function is deprecated and will be removed in a future  re-
	      lease.

       gunzip(Data) -> Decompressed

	      Types:

		 Data =	iodata()
		 Decompressed =	binary()

	      Uncompresses data	with gz	headers	and checksum.

       gzip(Data) -> Compressed

	      Types:

		 Data =	iodata()
		 Compressed = binary()

	      Compresses data with gz headers and checksum.

       inflate(Z, Data)	-> Decompressed

	      Types:

		 Z = zstream()
		 Data =	iodata()
		 Decompressed =	iolist()

	      Equivalent to inflate(Z, Data, [])

       inflate(Z, Data,	Options) -> Decompressed

	      Types:

		 Z = zstream()
		 Data =	iodata()
		 Options = [{exception_on_need_dict, boolean()}]
		 Decompressed =
		     iolist() |
		     {need_dictionary,
		      Adler32 :: integer() >= 0,
		      Output ::	iolist()}

	      Decompresses  as	much  data  as possible. It can	introduce some
	      output latency (reading input without producing any output).

	      Currently	   the	  only	  available    option	 is    {excep-
	      tion_on_need_dict,boolean()} which controls whether the function
	      should throw an exception	when a preset dictionary  is  required
	      for  decompression.  When	 set to	false, a need_dictionary tuple
	      will be returned instead.	 See  inflateSetDictionary/2  for  de-
	      tails.

	  Warning:
	      This  option defaults to true for	backwards compatibility	but we
	      intend to	remove the exception behavior in a future release. New
	      code  that  needs	 to handle dictionaries	manually should	always
	      specify {exception_on_need_dict,false}.

       inflateChunk(Z) -> Decompressed | {more,	Decompressed}

	      Types:

		 Z = zstream()
		 Decompressed =	iolist()

	  Warning:
	      This function is deprecated and will be removed in a future  re-
	      lease. Use safeInflate/2 instead.

	      Reads  the  next	chunk of uncompressed data, initialized	by in-
	      flateChunk/2.

	      This function is to  be  repeatedly  called,  while  it  returns
	      {more, Decompressed}.

       inflateChunk(Z, Data) ->	Decompressed | {more, Decompressed}

	      Types:

		 Z = zstream()
		 Data =	iodata()
		 Decompressed =	iolist()

	  Warning:
	      This  function is	deprecated and will be removed in a future re-
	      lease. Use safeInflate/2 instead.

	      Like inflate/2, but decompresses no more data than will  fit  in
	      the  buffer  configured  through setBufSize/2. Is	is useful when
	      decompressing a stream with a high compression ratio, such  that
	      a	small amount of	compressed input can expand up to 1000 times.

	      This  function  returns {more, Decompressed}, when there is more
	      output available,	and inflateChunk/1 is to be used to read it.

	      This function can	introduce some output latency  (reading	 input
	      without producing	any output).

	      An  exception  will be thrown if a preset	dictionary is required
	      for further decompression. See  inflateSetDictionary/2  for  de-
	      tails.

	      Example:

	      walk(Compressed, Handler)	->
		  Z = zlib:open(),
		  zlib:inflateInit(Z),
		  % Limit single uncompressed chunk size to 512kb
		  zlib:setBufSize(Z, 512 * 1024),
		  loop(Z, Handler, zlib:inflateChunk(Z,	Compressed)),
		  zlib:inflateEnd(Z),
		  zlib:close(Z).

	      loop(Z, Handler, {more, Uncompressed}) ->
		  Handler(Uncompressed),
		  loop(Z, Handler, zlib:inflateChunk(Z));
	      loop(Z, Handler, Uncompressed) ->
		  Handler(Uncompressed).

       inflateEnd(Z) ->	ok

	      Types:

		 Z = zstream()

	      Ends  the	 inflate session and cleans all	data used. Notice that
	      this function throws a data_error	exception if no	end of	stream
	      was found	(meaning that not all data has been uncompressed).

       inflateGetDictionary(Z) -> Dictionary

	      Types:

		 Z = zstream()
		 Dictionary = binary()

	      Returns  the  decompression  dictionary  currently in use	by the
	      stream. This function must be called between inflateInit/1,2 and
	      inflateEnd.

	      Only supported if	ERTS was compiled with zlib >= 1.2.8.

       inflateInit(Z) -> ok

	      Types:

		 Z = zstream()

	      Initializes a zlib stream	for decompression.

       inflateInit(Z, WindowBits) -> ok

	      Types:

		 Z = zstream()
		 WindowBits = zwindowbits()

	      Initializes a decompression session on zlib stream.

	      WindowBits  is the base two logarithm of the maximum window size
	      (the size	of the history buffer).	It is to be  in	 the  range  8
	      through 15. Default to 15	if inflateInit/1 is used.

	      If a compressed stream with a larger window size is specified as
	      input, inflate/2 throws the data_error exception.

	      A	negative WindowBits value makes	zlib ignore  the  zlib	header
	      (and checksum) from the stream. Notice that the zlib source men-
	      tions this only as a undocumented	feature.

       inflateReset(Z) -> ok

	      Types:

		 Z = zstream()

	      Equivalent to inflateEnd/1 followed by inflateInit/1,  but  does
	      not  free	 and  reallocate all the internal decompression	state.
	      The stream will keep attributes that could have been set by  in-
	      flateInit/1,2.

       inflateSetDictionary(Z, Dictionary) -> ok

	      Types:

		 Z = zstream()
		 Dictionary = iodata()

	      Initializes  the decompression dictionary	from the specified un-
	      compressed byte sequence.	This function must be called as	a  re-
	      sponse  to  an  inflate  operation (eg. safeInflate/2) returning
	      {need_dictionary,Adler,Output} or	 in  the  case	of  deprecated
	      functions,  throwing an {'EXIT',{{need_dictionary,Adler},_Stack-
	      Trace}} exception.

	      The dictionary chosen by the compressor can be  determined  from
	      the  Adler  value	 returned or thrown by the call	to the inflate
	      function.	The compressor and decompressor	must use the same dic-
	      tionary (See deflateSetDictionary/2).

	      After setting the	dictionary the inflate operation should	be re-
	      tried without new	input.

	      Example:

	      deprecated_unpack(Z, Compressed, Dict) ->
		   case	catch zlib:inflate(Z, Compressed) of
			{'EXIT',{{need_dictionary,_DictID},_}} ->
			       ok = zlib:inflateSetDictionary(Z, Dict),
			       Uncompressed = zlib:inflate(Z, []);
			Uncompressed ->
			       Uncompressed
		   end.

	      new_unpack(Z, Compressed,	Dict) ->
		  case zlib:inflate(Z, Compressed, [{exception_on_need_dict, false}]) of
		      {need_dictionary,	_DictId, Output} ->
			  ok = zlib:inflateSetDictionary(Z, Dict),
			  [Output | zlib:inflate(Z, [])];
		      Uncompressed ->
			  Uncompressed
		  end.

       open() -> zstream()

	      Opens a zlib stream.

       safeInflate(Z, Data) -> Result

	      Types:

		 Z = zstream()
		 Data =	iodata()
		 Result	=
		     {continue,	Output :: iolist()} |
		     {finished,	Output :: iolist()} |
		     {need_dictionary,
		      Adler32 :: integer() >= 0,
		      Output ::	iolist()}

	      Like inflate/2, but returns once it has expanded beyond a	 small
	      implementation-defined threshold.	It's useful when decompressing
	      untrusted	input which could have been maliciously	crafted	to ex-
	      pand until the system runs out of	memory.

	      This  function returns {continue | finished, Output}, where Out-
	      put is the data that was decompressed in this  call.  New	 input
	      can  be queued up	on each	call if	desired, and the function will
	      return {finished,	Output}	once all queued	data has  been	decom-
	      pressed.

	      This  function  can introduce some output	latency	(reading input
	      without producing	any output).

	      If a preset dictionary is	required  for  further	decompression,
	      this  function  returns a	need_dictionary	tuple. See inflateSet-
	      Dictionary/2) for	details.

	      Example:

	      walk(Compressed, Handler)	->
		  Z = zlib:open(),
		  zlib:inflateInit(Z),
		  loop(Z, Handler, zlib:safeInflate(Z, Compressed)),
		  zlib:inflateEnd(Z),
		  zlib:close(Z).

	      loop(Z, Handler, {continue, Output}) ->
		  Handler(Output),
		  loop(Z, Handler, zlib:safeInflate(Z, []));
	      loop(Z, Handler, {finished, Output}) ->
		  Handler(Output).

       setBufSize(Z, Size) -> ok

	      Types:

		 Z = zstream()
		 Size =	integer() >= 0

	      Sets the intermediate buffer size.

	  Warning:
	      This function is deprecated and will be removed in a future  re-
	      lease.

       set_controlling_process(Z, Pid) -> ok

	      Types:

		 Z = zstream()
		 Pid = pid()

	      Changes the controlling process of Z to Pid, which must be a lo-
	      cal process.

       uncompress(Data)	-> Decompressed

	      Types:

		 Data =	iodata()
		 Decompressed =	binary()

	      Uncompresses data	with zlib headers and checksum.

       unzip(Data) -> Decompressed

	      Types:

		 Data =	iodata()
		 Decompressed =	binary()

	      Uncompresses data	without	zlib headers and checksum.

       zip(Data) -> Compressed

	      Types:

		 Data =	iodata()
		 Compressed = binary()

	      Compresses data without zlib headers and checksum.

Ericsson AB			   erts	12.2			       zlib(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zlib&sektion=3&manpath=FreeBSD+Ports+13.1>

home | help