Unix/Linux Go Back    


Linux 2.6 - man page for zlib (linux section 3erl)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


zlib(3erl)			     Erlang Module Definition			       zlib(3erl)

NAME
       zlib - Zlib Compression interface.

DESCRIPTION
       The  zlib module provides an API for the zlib library (http://www.zlib.org). It is used to
       compress and decompress data. The data format is described by RFCs 1950 to 1952.

       A typical (compress) usage looks like:

       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}}  ,	might  be  thrown,  where  Reason
       describes the error. Typical reasons are:

	 badarg :
	   Bad argument

	 data_error :
	   The data contains errors

	 stream_error :
	   Inconsistent stream state

	 einval :
	   Bad value or wrong function called

	 {need_dictionary,Adler32} :
	   See inflate/2

DATA TYPES
       iodata = iolist() | binary()

       iolist = [char() | binary() | iolist()]
	 a binary is allowed as the tail of the list

       zstream = a zlib stream, see open/0

EXPORTS
       open() -> Z

	      Types  Z = zstream()

	      Open a zlib stream.

       close(Z) -> ok

	      Types  Z = zstream()

	      Closes the stream referenced by Z .

       deflateInit(Z) -> ok

	      Types  Z = zstream()

	      Same as zlib:deflateInit(Z, default) .

       deflateInit(Z, Level) -> ok

	      Types  Z = zstream()
		     Level = none | default | best_speed | best_compression | 0..9

	      Initialize a zlib stream for compression.

	      Level decides the compression level to be used, 0 ( none ), gives no compression at
	      all, 1 ( best_speed ) gives best speed and 9 ( best_compression ) gives  best  com-
	      pression.

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

	      Types  Z = zstream()
		     Level = none | default | best_speed | best_compression | 0..9
		     Method = deflated
		     WindowBits = 9..15|-9..-15
		     MemLevel = 1..9
		     Strategy = default|filtered|huffman_only

	      Initiates a zlib stream for compression.

	      The  Level parameter decides the compression level to be used, 0 ( none ), gives no
	      compression at all, 1 ( best_speed ) gives best speed and 9  (  best_compression	)
	      gives best compression.

	      The  Method  parameter  decides which compression method to use, currently the only
	      supported method is deflated .

	      The WindowBits parameter is the base two logarithm of the window size (the size  of
	      the  history buffer). It should be in the range 9 through 15. Larger values of this
	      parameter result in better compression at the expense of memory usage. The  default
	      value  is  15  if  deflateInit/2	. A negative WindowBits value suppresses the zlib
	      header (and checksum) from the stream. Note that the zlib source mentions this only
	      as a undocumented feature.

	      The MemLevel parameter specifies how much memory should be allocated for the inter-
	      nal compression state. MemLevel =1 uses minimum memory but is slow and reduces com-
	      pression	ratio;	MemLevel  =9  uses  maximum memory for optimal speed. The default
	      value is 8.

	      The Strategy parameter is used to tune the compression  algorithm.  Use  the  value
	      default  for normal data, filtered for data produced by a filter (or predictor), or
	      huffman_only to force Huffman encoding only (no string match). Filtered  data  con-
	      sists mostly of small values with a somewhat random distribution. In this case, the
	      compression algorithm is tuned to compress them better. The effect of  filtered  is
	      to  force more Huffman coding and less string matching; it is somewhat intermediate
	      between default and huffman_only . The Strategy parameter only affects the compres-
	      sion  ratio  but not the correctness of the compressed output even if it is not set
	      appropriately.

       deflate(Z, Data) -> Compressed

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

	      Same as deflate(Z, Data, none) .

       deflate(Z, Data, Flush) ->

	      Types  Z = zstream()
		     Data = iodata()
		     Flush = none | sync | full | finish
		     Compressed = iolist()

	      deflate/3 compresses as much data as possible, and  stops  when  the  input  buffer
	      becomes  empty. It may introduce some output latency (reading input without produc-
	      ing any output) except when forced to flush.

	      If the parameter 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 may degrade compression for some com-
	      pression algorithms and so it should be used 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  com-
	      pressed  data has been damaged or if random access is desired. Using full too often
	      can seriously degrade the compression.

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

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

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

       deflateSetDictionary(Z, Dictionary) -> Adler32

	      Types  Z = zstream()
		     Dictionary = binary()
		     Adler32 = integer()

	      Initializes the compression dictionary from the given byte sequence without produc-
	      ing  any	compressed  output.  This  function  must  be  called  immediately  after
	      deflateInit/[1|2|6] or deflateReset/1 , before any call of deflate/3 . The compres-
	      sor and decompressor must use  exactly  the  same  dictionary  (see  inflateSetDic-
	      tionary/2 ). The adler checksum of the dictionary is returned.

       deflateReset(Z) -> ok

	      Types  Z = zstream()

	      This  function  is equivalent to deflateEnd/1 followed by deflateInit/[1|2|6] , but
	      does not free and reallocate all the internal compression state.	The  stream  will
	      keep the same compression level and any other attributes.

       deflateParams(Z, Level, Strategy) -> ok

	      Types  Z = zstream()
		     Level = none | default | best_speed | best_compression | 0..9
		     Strategy = default|filtered|huffman_only

	      Dynamically  update the compression level and compression strategy. The interpreta-
	      tion of Level and Strategy is as in deflateInit/6 . This	can  be  used  to  switch
	      between  compression and straight copy of the input data, or to switch to a differ-
	      ent kind of input data requiring a different strategy. If the compression level  is
	      changed,	the  input  available so far is compressed with the old level (and may be
	      flushed); the new level will take 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  ,  since  the	currently  available  input may have to be compressed and
	      flushed.

       deflateEnd(Z) -> ok

	      Types  Z = zstream()

	      End the deflate session and cleans all data used.  Note  that  this  function  will
	      throw  an  data_error  exception	if the last call to deflate/3 was not called with
	      Flush set to finish .

       inflateInit(Z) -> ok

	      Types  Z = zstream()

	      Initialize a zlib stream for decompression.

       inflateInit(Z, WindowBits) -> ok

	      Types  Z = zstream()
		     WindowBits = 9..15|-9..-15

	      Initialize decompression session on zlib stream.

	      The WindowBits parameter is the base two logarithm of the maximum window size  (the
	      size  of	the  history buffer). It should be in the range 9 through 15. The default
	      value is 15 if inflateInit/1 is used. If a compressed stream with a  larger  window
	      size  is	given as input, inflate() will throw the data_error exception. A negative
	      WindowBits value makes zlib ignore the zlib header (and checksum) from the  stream.
	      Note that the zlib source mentions this only as a undocumented feature.

       inflate(Z, Data) -> DeCompressed

	      Types  Z = zstream()
		     Data = iodata()
		     DeCompressed = iolist()

	      inflate/2  decompresses as much data as possible. It may some introduce some output
	      latency (reading input without producing any output).

	      If a preset dictionary is needed at this point  (see  inflateSetDictionary  below),
	      inflate/2  throws  a  {need_dictionary,Adler}  exception where Adler is the adler32
	      checksum of the dictionary chosen by the compressor.

       inflateSetDictionary(Z, Dictionary) -> ok

	      Types  Z = zstream()
		     Dictionary = binary()

	      Initializes the decompression dictionary from the given uncompressed byte sequence.
	      This  function  must  be	called immediately after a call of inflate/2 if this call
	      threw a {need_dictionary,Adler} exception. The dictionary chosen by the  compressor
	      can  be  determined from the Adler value thrown by the call to inflate/2 . The com-
	      pressor and decompressor must use exactly the same dictionary  (see  deflateSetDic-
	      tionary/2 ).

	      Example:

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

       inflateReset(Z) -> ok

	      Types  Z = zstream()

	      This  function  is  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 may have been set by inflateInit/[1|2] .

       inflateEnd(Z) -> ok

	      Types  Z = zstream()

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

       setBufSize(Z, Size) -> ok

	      Types  Z = zstream()
		     Size = integer()

	      Sets the intermediate buffer size.

       getBufSize(Z) -> Size

	      Types  Z = zstream()
		     Size = integer()

	      Get the size of intermediate buffer.

       crc32(Z) -> CRC

	      Types  Z = zstream()
		     CRC = integer()

	      Get the current calculated CRC checksum.

       crc32(Z, Binary) -> CRC

	      Types  Z = zstream()
		     Binary = binary()
		     CRC = integer()

	      Calculate the CRC checksum for Binary .

       crc32(Z, PrevCRC, Binary) -> CRC

	      Types  Z = zstream()
		     PrevCRC = integer()
		     Binary = binary()
		     CRC = integer()

	      Update  a  running  CRC  checksum  for Binary . If Binary is the empty binary, this
	      function returns the required initial value for the crc.

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

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

	      Types  Z = zstream()
		     CRC = integer()
		     CRC1 = integer()
		     CRC2 = integer()
		     Size2 = integer()

	      Combine two CRC checksums into one. For two binaries, Bin1 and Bin2 with	sizes  of
	      Size1  and  Size2  , with CRC checksums CRC1 and CRC2 . crc32_combine/4 returns the
	      CRC checksum of <<Bin1/binary,Bin2/binary>> , requiring only  CRC1  ,  CRC2  ,  and
	      Size2 .

       adler32(Z, Binary) -> Checksum

	      Types  Z = zstream()
		     Binary = binary()
		     Checksum = integer()

	      Calculate the Adler-32 checksum for Binary .

       adler32(Z, PrevAdler, Binary) -> Checksum

	      Types  Z = zstream()
		     PrevAdler = integer()
		     Binary = binary()
		     Checksum = integer()

	      Update a running Adler-32 checksum for Binary . If Binary is the empty binary, this
	      function returns the required initial value for the checksum.

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

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

	      Types  Z = zstream()
		     Adler = integer()
		     Adler1 = integer()
		     Adler2 = integer()
		     Size2 = integer()

	      Combine two Adler-32 checksums into one. For two binaries, Bin1 and Bin2 with sizes
	      of  Size1 and Size2 , with Adler-32 checksums Adler1 and Adler2 . adler32_combine/4
	      returns the Adler checksum of <<Bin1/binary,Bin2/binary>> , requiring only Adler1 ,
	      Adler2 , and Size2 .

       compress(Binary) -> Compressed

	      Types  Binary = Compressed = binary()

	      Compress a binary (with zlib headers and checksum).

       uncompress(Binary) -> Decompressed

	      Types  Binary = Decompressed = binary()

	      Uncompress a binary (with zlib headers and checksum).

       zip(Binary) -> Compressed

	      Types  Binary = Compressed = binary()

	      Compress a binary (without zlib headers and checksum).

       unzip(Binary) -> Decompressed

	      Types  Binary = Decompressed = binary()

	      Uncompress a binary (without zlib headers and checksum).

       gzip(Data) -> Compressed

	      Types  Binary = Compressed = binary()

	      Compress a binary (with gz headers and checksum).

       gunzip(Bin) -> Decompressed

	      Types  Binary = Decompressed = binary()

	      Uncompress a binary (with gz headers and checksum).

Ericsson AB				    erts 5.8.3				       zlib(3erl)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:21 PM.