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

FreeBSD Manual Pages


home | help
TclZlib(3)		    Tcl	Library	Procedures		    TclZlib(3)


       Tcl_ZlibAdler32,	  Tcl_ZlibCRC32,   Tcl_ZlibDeflate,   Tcl_ZlibInflate,
       Tcl_ZlibStreamChecksum,	   Tcl_ZlibStreamClose,	    Tcl_ZlibStreamEof,
       Tcl_ZlibStreamGet,   Tcl_ZlibStreamGetCommandName,  Tcl_ZlibStreamInit,
       Tcl_ZlibStreamPut - compression and decompression functions

       #include	<tcl.h>

       Tcl_ZlibDeflate(interp, format, dataObj,	level, dictObj)

       Tcl_ZlibInflate(interp, format, dataObj,	dictObj)

       unsigned	int
       Tcl_ZlibCRC32(initValue,	bytes, length)

       unsigned	int
       Tcl_ZlibAdler32(initValue, bytes, length)

       Tcl_ZlibStreamInit(interp, mode,	format,	level, dictObj,	zshandlePtr)

       Tcl_Obj *





       Tcl_ZlibStreamPut(zshandle, dataObj, flush)

       Tcl_ZlibStreamGet(zshandle, dataObj, count)

       Tcl_ZlibStreamSetCompressionDictionary(zshandle,	compDict)

       Tcl_Interp *interp (in)		     The interpreter to	store  result-
					     ing  compressed  or  uncompressed
					     data in.  Also  where  any	 error
					     messages	 are	written.   For
					     Tcl_ZlibStreamInit, this  can  be
					     NULL  to  create a	stream that is
					     not bound to a command.

       int format (in)			     What format of compressed data to
					     work   with.   Must   be  one  of
					     TCL_ZLIB_FORMAT_ZLIB  for	 zlib-
					     format data, TCL_ZLIB_FORMAT_GZIP
					     for    gzip-format	   data,    or
					     TCL_ZLIB_FORMAT_RAW  for raw com-
					     pressed data.  In	addition,  for
					     decompression only, TCL_ZLIB_FOR-
					     MAT_AUTO may also be chosen which
					     can  automatically	detect whether
					     the compressed data was  in  zlib
					     or	gzip format.

       Tcl_Obj *dataObj	(in/out)	     A byte-array value	containing the
					     data to be	compressed  or	decom-
					     pressed, or to which the data ex-
					     tracted from the  stream  is  ap-
					     pended  when  passed to Tcl_Zlib-

       int level (in)			     What level	of compression to use.
					     Should be a number	from 0 to 9 or
					     one     of	    the	    following:
					     TCL_ZLIB_COMPRESS_NONE   for   no
					     compression,	 TCL_ZLIB_COM-
					     PRESS_FAST	 for  fast but ineffi-
					     cient compression,	 TCL_ZLIB_COM-
					     PRESS_BEST	 for  slow but maximal
					     compression,   or	 TCL_ZLIB_COM-
					     PRESS_DEFAULT  for	the level rec-
					     ommended by the zlib library.

       Tcl_Obj *dictObj	(in/out)	     A dictionary  that	 contains,  or
					     which will	be updated to contain,
					     a description of the gzip	header
					     associated	 with  the  compressed
					     data. Only	useful when the	format
					     is	    TCL_ZLIB_FORMAT_GZIP    or
					     is	 passed, a default header will
					     be	used on	 compression  and  the
					     header  will  be  ignored	(apart
					     from integrity checks) on	decom-
					     pression.	See  the  section GZIP
					     OPTIONS  DICTIONARY  for  details
					     about  the	 contents of this dic-

       unsigned	int initValue (in)	     The initial value for the	check-
					     sum algorithm.

       unsigned	char *bytes (in)	     An	 array	of  bytes  to  run the
					     checksum algorithm	over, or  NULL
					     to	 get  the  recommended initial
					     value for the checksum algorithm.

       int length (in)			     The number	of bytes in the	array.

       int mode	(in)			     What mode to operate  the	stream
					     in.      Should	 be	either
					     TCL_ZLIB_STREAM_DEFLATE   for   a
					     compressing       stream	    or
					     TCL_ZLIB_STREAM_INFLATE for a de-
					     compressing stream.

       Tcl_ZlibStream *zshandlePtr (out)     A	pointer	to a variable in which
					     to	write the abstract  token  for
					     the  stream  upon successful cre-

       Tcl_ZlibStream zshandle (in)	     The abstract token	for the	stream
					     to	operate	on.

       int flush (in)			     Whether  and  how	to  flush  the
					     stream after writing the data  to
					     it.     Must     be    one	   of:
					     TCL_ZLIB_NO_FLUSH if no  flushing
					     is	 to be done, TCL_ZLIB_FLUSH if
					     the  currently  compressed	  data
					     must be made available for	access
					     using	    Tcl_ZlibStreamGet,
					     TCL_ZLIB_FULLFLUSH	 if the	stream
					     must be put into  a  state	 where
					     the decompressor can recover from
					     on	corruption, or TCL_ZLIB_FINAL-
					     IZE  to ensure that the stream is
					     finished and that any trailer de-
					     manded by the format is written.

       int count (in)			     The  maximum  number  of bytes to
					     get from the stream, or -1	to get
					     all   remaining  bytes  from  the
					     stream's buffers.

       Tcl_Obj *compDict (in)		     A byte array value	 that  is  the
					     compression   dictionary  to  use
					     with the stream.  Note that  this
					     is	 not  a	Tcl dictionary,	and it
					     is	 recommended  that  this  only
					     ever  be  used  with streams that
					     were created  with	 their	format
					     set  to  TCL_ZLIB_FORMAT_ZLIB be-
					     cause the other formats  have  no
					     mechanism	to  indicate whether a
					     compression    dictionary	   was
					     present other than	to fail	on de-

       These functions form the	interface from the Tcl library to the Zlib li-
       brary by	Jean-loup Gailly and Mark Adler.

       Tcl_ZlibDeflate	and  Tcl_ZlibInflate  respectively compress and	decom-
       press the data contained	in the dataObj argument, according to the for-
       mat  and,  for compression, level arguments. The	dictionary in the dic-
       tObj parameter is used to convey	additional  header  information	 about
       the compressed data when	the compression	format supports	it; currently,
       the dictionary is only used when	the format parameter is	 TCL_ZLIB_FOR-
       MAT_GZIP	 or  TCL_ZLIB_FORMAT_AUTO.  For	details	of the contents	of the
       dictionary, see the GZIP	OPTIONS	DICTIONARY section  below.  Upon  suc-
       cess,  both  functions  leave  the resulting compressed or decompressed
       data in a byte-array value that is the Tcl  interpreter's  result;  the
       returned	value is a standard Tcl	result code.

       Tcl_ZlibAdler32 and Tcl_ZlibCRC32 compute checksums on arrays of	bytes,
       returning the computed checksum.	Checksums are computed	incrementally,
       allowing	 data  to  be processed	one block at a time, but this requires
       the caller to maintain the current checksum and pass it in as the init-
       Value  parameter;  the initial value to use for this can	be obtained by
       using NULL for the bytes	parameter instead of a pointer to the array of
       bytes  to  compute the checksum over. Thus, typical usage in the	single
       data block case is like this:

	      checksum = Tcl_ZlibCRC32(Tcl_ZlibCRC32(0,NULL,0),	data, length);

       Note that the Adler-32 algorithm	is not a real checksum,	but instead is
       a related type of hash that works best on longer	data.

       Tcl_ZlibStreamInit  creates  a compressing or decompressing stream that
       is linked to a Tcl command, according to	its arguments, and provides an
       abstract	 token	for  the  stream and returns a normal Tcl result code;
       Tcl_ZlibStreamGetCommandName returns the	name of	that command given the
       stream token, or	NULL if	the stream has no command. Streams are not de-
       signed to be thread-safe; each stream should only ever be used from the
       thread  that  created  it. When working with gzip streams, a dictionary
       (fields as given	in the GZIP OPTIONS DICTIONARY section below)  can  be
       given via the dictObj parameter that on compression allows control over
       the generated headers, and on decompression allows discovery of the ex-
       isting  headers.	 Note that the dictionary will be written to on	decom-
       pression	once sufficient	data has been read to have a complete  header.
       This  means that	the dictionary must be an unshared value in that case;
       a blank value created with Tcl_NewObj is	suggested.

       Once a stream has been constructed, Tcl_ZlibStreamPut is	 used  to  add
       data  to	the stream and Tcl_ZlibStreamGet is used to retrieve data from
       the stream after	processing. Both return	normal Tcl  result  codes  and
       leave an	error message in the result of the interpreter that the	stream
       is registered with in the error case (if	such a registration  has  been
       performed).  With Tcl_ZlibStreamPut, the	data buffer value passed to it
       should not be modified afterwards.  With	 Tcl_ZlibStreamGet,  the  data
       buffer  value passed to it will have the	data bytes appended to it. In-
       ternally	to the stream, data is kept compressed so as to	 minimize  the
       cost of buffer space.

       Tcl_ZlibStreamChecksum  returns	the  checksum computed over the	uncom-
       pressed data according to the format, and Tcl_ZlibStreamEof  returns  a
       boolean	value  indicating whether the end of the uncompressed data has
       been reached.

       Tcl_ZlibStreamSetCompressionDictionary is used to control the  compres-
       sion dictionary used with the stream, a compression dictionary being an
       array of	bytes (such as might be	created	with Tcl_NewByteArrayObj) that
       is  used	to initialize the compression engine rather than leaving it to
       create it on the	fly from the data being	compressed. Setting a compres-
       sion dictionary allows for more efficient compression in	the case where
       the start of the	data is	highly regular,	but it does require  both  the
       compressor and the decompressor to agreee on the	value to use. Compres-
       sion dictionaries are only fully	supported  for	zlib-format  data;  on
       compression, they must be set before any	data is	sent in	with Tcl_Zlib-
       StreamPut, and on decompression	they  should  be  set  when  Tcl_Zlib-
       StreamGet  produces an error with its -errorcode	set to "ZLIB NEED_DICT
       code"; the code will be the Adler-32 checksum (see Tcl_ZlibAdler32)  of
       the  compression	 dictionary  sought.  (Note that this is only true for
       zlib-format streams; gzip streams ignore	 compression  dictionaries  as
       the format specification	doesn't	permit them, and raw streams just pro-
       duce a data error if the	compression dictionary is  missing  or	incor-

       If you wish to clear a stream and reuse it for a	new compression	or de-
       compression action, Tcl_ZlibStreamReset will do this and	return a  nor-
       mal  Tcl	 result	 code  to  indicate  whether it	was successful;	if the
       stream is registered with an interpreter, an error message will be left
       in  the	interpreter  result when this function returns TCL_ERROR.  Fi-
       nally, Tcl_ZlibStreamClose will clean up	the stream and delete the  as-
       sociated	 command:  using  Tcl_DeleteCommand on the stream's command is
       equivalent (when	such a command exists).

       The dictObj parameter to	Tcl_ZlibDeflate, Tcl_ZlibInflate and Tcl_Zlib-
       StreamInit  is  used to pass a dictionary of options about that is used
       to describe the gzip header in the compressed data. When	creating  com-
       pressed data, the dictionary is read and	when unpacking compressed data
       the dictionary is written (in which case	the dictObj parameter must re-
       fer to an unshared dictionary value).

       The  following fields in	the dictionary value are understood. All other
       fields are ignored. No field is required	when  creating	a  gzip-format

	      This  holds  the comment field of	the header, if present.	If ab-
	      sent, no comment was supplied (on	decompression) or will be cre-
	      ated (on compression).

       crc    A	 boolean  value	describing whether a CRC of the	header is com-
	      puted. Note that the gzip	program	does not use or	allow a	CRC on
	      the header.

	      The  name	 of  the  file	that  held the uncompressed data. This
	      should not contain any directory separators, and should be sani-
	      tized before use on decompression	with file tail.

       os     The operating system type	code field from	the header (if not the
	      "unknown"	value).	See RFC	1952 for the meaning of	 these	codes.
	      On  compression, if this is absent then the field	will be	set to
	      the "unknown" value.

       size   The size of the uncompressed data. This is ignored  on  compres-
	      sion;  the  size of the data compressed depends on how much data
	      is supplied to the compression engine.

       time   The time field from the header if	non-zero, expected to  be  the
	      time  that  the  file  named by the filename field was modified.
	      Suitable for use with clock format. On creation, the right value
	      to use is	that from clock	seconds	or file	mtime.

       type   The  type	 of  the  uncompressed data (either binary or text) if

       These functions will fail gracefully if Tcl is not linked with the zlib

       Tcl_NewByteArrayObj(3), zlib(n)

       compress, decompress, deflate, gzip, inflate

Tcl				      8.6			    TclZlib(3)


Want to link to this manual page? Use this URL:

home | help