Provided by: tcl8.6-doc_8.6.14+dfsg-1build1_all 
NAME
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
SYNOPSIS
#include <tcl.h>
int
Tcl_ZlibDeflate(interp, format, dataObj, level, dictObj)
int
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_ZlibStreamReset(zshandle)
int
Tcl_ZlibStreamChecksum(zshandle)
int
Tcl_ZlibStreamPut(zshandle, dataObj, flush)
int
Tcl_ZlibStreamGet(zshandle, dataObj, count)
Tcl_ZlibStreamSetCompressionDictionary(zshandle, compDict)
ARGUMENTS
Tcl_Interp *interp (in) The interpreter to store resulting 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 compressed data. In
addition, for decompression only,
TCL_ZLIB_FORMAT_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 decompressed, or to which the data
extracted from the stream is appended 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 following:
TCL_ZLIB_COMPRESS_NONE for no compression,
TCL_ZLIB_COMPRESS_FAST for fast but inefficient
compression, TCL_ZLIB_COMPRESS_BEST for slow but
maximal compression, or TCL_ZLIB_COMPRESS_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 compression and the header
will be ignored (apart from integrity checks) on
decompression. See the section GZIP OPTIONS
DICTIONARY for details about the contents of this
dictionary.
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 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 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
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_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.
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 because the other formats have
no mechanism to indicate whether a compression
dictionary was present other than to fail on
decompression.
_________________________________________________________________________________________________
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 respectively compress and decompress the data
contained in the dataObj argument, according to the format and, for compression, level
arguments. The dictionary in the dictObj 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_FORMAT_GZIP or
TCL_ZLIB_FORMAT_AUTO. For details of the contents of the dictionary, see the GZIP OPTIONS
DICTIONARY section below. Upon success, 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 initValue 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.
ZLIB STREAMS
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
designed 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 existing headers. Note that the dictionary will be written to on
decompression 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. Internally to the stream, data is kept compressed so as to
minimize the cost of buffer space.
Tcl_ZlibStreamChecksum returns the checksum computed over the uncompressed 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 compression 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
compression 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. Compression dictionaries are only fully
supported for zlib-format data; on compression, they must be set before any data is sent
in with Tcl_ZlibStreamPut, and on decompression they should be set when Tcl_ZlibStreamGet
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 produce a data error if
the compression dictionary is missing or incorrect.)
If you wish to clear a stream and reuse it for a new compression or decompression action,
Tcl_ZlibStreamReset will do this and return a normal 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. Finally,
Tcl_ZlibStreamClose will clean up the stream and delete the associated command: using
Tcl_DeleteCommand on the stream's command is equivalent (when such a command exists).
GZIP OPTIONS DICTIONARY
The dictObj parameter to Tcl_ZlibDeflate, Tcl_ZlibInflate and Tcl_ZlibStreamInit is used
to pass a dictionary of options about that is used to describe the gzip header in the
compressed data. When creating compressed data, the dictionary is read and when unpacking
compressed data the dictionary is written (in which case the dictObj parameter must refer
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 stream.
comment
This holds the comment field of the header, if present. If absent, no comment was
supplied (on decompression) or will be created (on compression).
crc A boolean value describing whether a CRC of the header is computed. Note that the
gzip program does not use or allow a CRC on the header.
filename
The name of the file that held the uncompressed data. This should not contain any
directory separators, and should be sanitized 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 compression; 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 known.
PORTABILITY NOTES
These functions will fail gracefully if Tcl is not linked with the zlib library.
SEE ALSO
Tcl_NewByteArrayObj(3tcl), zlib(3tcl)
KEYWORDS
compress, decompress, deflate, gzip, inflate