TclZlib(3) Tcl Library Procedures TclZlib(3)______________________________________________________________________________NAME
Tcl_ZlibAdler32, Tcl_ZlibCRC32, Tcl_ZlibDeflate, Tcl_ZlibInflate,
Tcl_ZlibStreamAdler32, Tcl_ZlibStreamClose, Tcl_ZlibStreamEof,
Tcl_ZlibStreamGet, Tcl_ZlibStreamGetCommandName, Tcl_ZlibStreamInit,
Tcl_ZlibStreamPut - compression and decompression functions
SYNOPSIS
#include <tcl.h>
Tcl_Obj *
Tcl_ZlibDeflate(interp, format, dataObj, level, dictObj)
Tcl_Obj *
Tcl_ZlibInflate(interp, format, dataObj, dictObj)
unsigned int
Tcl_ZlibCRC32(initValue, bytes, length)
unsigned int
Tcl_ZlibAdler32(initValue, bytes, length)
int
Tcl_ZlibStreamInit(interp, mode, format, level, dictObj, zshandlePtr)
Tcl_Obj *
Tcl_ZlibStreamGetCommandName(zshandle)
int
Tcl_ZlibStreamEof(zshandle)
int
Tcl_ZlibStreamClose(zshandle)
int
Tcl_ZlibStreamAdler32(zshandle)
int
Tcl_ZlibStreamPut(zshandle, dataObj, flush)
int
Tcl_ZlibStreamGet(zshandle, dataObj, count)
ARGUMENTS
Tcl_Interp *interp (in) The interpreter to store
resulting compressed or
uncompressed data in. Also
where any error messages are
written.
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
compressed data. In addition,
for decompression only,
TCL_ZLIB_FORMAT_AUTO may also
be chosen which can automati‐
cally detect whether the com‐
pressed data was in zlib or
gzip format.
Tcl_Obj *dataObj (in/out) A byte-array object contain‐
ing the data to be compressed
or decompressed, or which is
set to the data extracted
from the stream when passed
to Tcl_ZlibStreamGet.
int level (in) What level of compression to
use. Should be a number from
0 to 9 or one of the follow‐
ing: TCL_ZLIB_COMPRESS_NONE
for no compression,
TCL_ZLIB_COMPRESS_FAST for
fast but inefficient compres‐
sion, TCL_ZLIB_COMPRESS_BEST
for slow but maximal compres‐
sion, or TCL_ZLIB_COM‐
PRESS_DEFAULT for the level
recommended 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
TCL_ZLIB_FORMAT_AUTO. If a
NULL is passed, a default
header will be used on com‐
pression and the header will
be ignored (apart from
integrity checks) on decom‐
pression.
unsigned int initValue (in) The initial value for the
checksum 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 check‐
sum 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
decompressing stream.
Tcl_ZlibStream *zshandlePtr (out) A pointer to a variable in
which to write the abstract
token for the stream upon
successful creation.
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 cur‐
rently 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 corrup‐
tion, or TCL_ZLIB_FINALIZE to
ensure that the stream is
finished and that any trailer
demanded 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.
_________________________________________________________________DESCRIPTION
These functions form the interface from the Tcl library to the Zlib
library by Jean-loup Gailly and Mark Adler.
Tcl_ZlibDeflate and Tcl_ZlibInflate compress and decompress data
respectively. Upon success, they leave the resulting compressed or
decompressed data in a byte-array object that is the Tcl interpreter's
result. Note that the dictObj parameter is only used when the format
parameter is TCL_ZLIB_FORMAT_GZIP or TCL_ZLIB_FORMAT_AUTO.
Tcl_ZlibAdler32 and Tcl_ZlibCRC32 compute checksums on arrays of bytes.
Typical usage is:
checksum = Tcl_ZlibCRC32(Tcl_ZlibCRC32(0,NULL,0), data, length);
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; Tcl_ZlibStreamGetCommandName returns the
name of that command given the stream token. 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 pro‐
cessing. Tcl_ZlibStreamAdler32 returns the checksum computed over the
uncompressed data, and Tcl_ZlibStreamEof returns whether the end of the
uncompressed data has been reached. Finally, Tcl_ZlibStreamClose will
clean up the stream and delete the associated command: using
Tcl_DeleteCommand on the stream's command is equivalent.
PORTABILITY NOTES
These functions will fail gracefully if Tcl is not linked with the zlib
library.
SEE ALSOTcl_NewByteArrayObj(3), zlib(n)KEYWORDS
compress, decompress, deflate, gzip, inflate
Tcl 8.6 TclZlib(3)
