Scroll to navigation

TclZlib(3tcl) Tcl Library Procedures TclZlib(3tcl) 





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, bufferSize, 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.

  
Tcl_Size bufferSize (in)

  
A hint as to what size of buffer is to be used to receive the data. Use 0
      to use a geric guess based on the input data.

  
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.

  
Tcl_Size 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.

  
Tcl_Size 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 agree 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.



  

  
This holds the comment field of the header, if present. If absent, no
      comment was supplied (on decompression) or will be created (on
      compression).

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

  
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.

  

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








REFERENCE COUNT MANAGEMENT


Tcl_ZlibDeflate and Tcl_ZlibInflate take a value
    with arbitrary reference count for their dataObj and dictObj
    arguments (the latter often being NULL instead), and set the interpreter
    result with their output value (or an error). The existing interpreter
    result should not be passed as any argument value unless an additional
    reference is held.


Tcl_ZlibStreamInit takes a value with arbitrary reference
    count for its dictObj argument; it only reads from it. The existing
    interpreter result should not be passed unless an additional reference is
    held.


Tcl_ZlibStreamGetCommandName returns a zero reference count
    value, much like Tcl_NewObj.


The dataObj argument to Tcl_ZlibStreamPut is a value
    with arbitrary reference count; it is only ever read from.


The dataObj argument to Tcl_ZlibStreamGet is an
    unshared value (see Tcl_IsShared) that will be updated by the
    function.


The compDict argument to
    Tcl_ZlibStreamSetCompressionDictionary, if non-NULL, may be
    duplicated or may have its reference count incremented. Using a zero
    reference count value is not recommended.








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







  

    8.6
    Tcl