diff options
Diffstat (limited to 'doc/TclZlib.3')
| -rw-r--r-- | doc/TclZlib.3 | 161 |
1 files changed, 139 insertions, 22 deletions
diff --git a/doc/TclZlib.3 b/doc/TclZlib.3 index 42d82b5..c6a6417 100644 --- a/doc/TclZlib.3 +++ b/doc/TclZlib.3 @@ -4,10 +4,8 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: TclZlib.3,v 1.4 2008/12/27 00:04:17 dkf Exp $ -'\" -.so man.macros .TH TclZlib 3 8.6 Tcl "Tcl Library Procedures" +.so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -16,10 +14,10 @@ Tcl_ZlibAdler32, Tcl_ZlibCRC32, Tcl_ZlibDeflate, Tcl_ZlibInflate, Tcl_ZlibStream .nf #include <tcl.h> .sp -Tcl_Obj * +int \fBTcl_ZlibDeflate\fR(\fIinterp, format, dataObj, level, dictObj\fR) .sp -Tcl_Obj * +int \fBTcl_ZlibInflate\fR(\fIinterp, format, dataObj, dictObj\fR) .sp unsigned int @@ -41,6 +39,9 @@ int \fBTcl_ZlibStreamClose\fR(\fIzshandle\fR) .sp int +\fBTcl_ZlibStreamReset\fR(\fIzshandle\fR) +.sp +int \fBTcl_ZlibStreamChecksum\fR(\fIzshandle\fR) .sp int @@ -48,9 +49,11 @@ int .sp int \fBTcl_ZlibStreamGet\fR(\fIzshandle, dataObj, count\fR) +.sp +\fBTcl_ZlibStreamSetCompressionDictionary\fR(\fIzshandle, compDict\fR) .fi .SH ARGUMENTS -.AS Tcl_ZlibStream *zshandlePtr out +.AS Tcl_ZlibStream zshandle in .AP Tcl_Interp *interp in The interpreter to store resulting compressed or uncompressed data in. Also where any error messages are written. For \fBTcl_ZlibStreamInit\fR, this can @@ -63,7 +66,7 @@ addition, for decompression only, \fBTCL_ZLIB_FORMAT_AUTO\fR may also be chosen which can automatically detect whether the compressed data was in zlib or gzip format. .AP Tcl_Obj *dataObj in/out -A byte-array object containing the data to be compressed or decompressed, or +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 \fBTcl_ZlibStreamGet\fR. .AP int level in @@ -77,7 +80,9 @@ 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 \fIformat\fR is \fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. 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. +will be ignored (apart from integrity checks) on decompression. See the +section \fBGZIP OPTIONS DICTIONARY\fR for details about the contents of this +dictionary. .AP "unsigned int" initValue in The initial value for the checksum algorithm. .AP "unsigned char" *bytes in @@ -105,46 +110,158 @@ trailer demanded by the format is written. .AP 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. +.AP Tcl_Obj *compDict in +A byte array value that is the compression dictionary to use with the stream. +Note that this is \fInot a Tcl dictionary\fR, and it is recommended that this +only ever be used with streams that were created with their \fIformat\fR set +to \fBTCL_ZLIB_FORMAT_ZLIB\fR because the other formats have no mechanism to +indicate whether a compression dictionary was present other than to fail on +decompression. .BE .SH DESCRIPTION These functions form the interface from the Tcl library to the Zlib library by Jean-loup Gailly and Mark Adler. .PP -\fBTcl_ZlibDeflate\fR and \fBTcl_ZlibInflate\fR 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 \fIdictObj\fR parameter is only used when the -\fIformat\fR parameter is \fBTCL_ZLIB_FORMAT_GZIP\fR or -\fBTCL_ZLIB_FORMAT_AUTO\fR. +\fBTcl_ZlibDeflate\fR and \fBTcl_ZlibInflate\fR respectively compress and +decompress the data contained in the \fIdataObj\fR argument, according to the +\fIformat\fR and, for compression, \fIlevel\fR arguments. The dictionary in +the \fIdictObj\fR 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 \fIformat\fR parameter is +\fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. For details of the +contents of the dictionary, see the \fBGZIP OPTIONS DICTIONARY\fR 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. .PP \fBTcl_ZlibAdler32\fR and \fBTcl_ZlibCRC32\fR compute checksums on arrays of -bytes. Typical usage is: +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 \fIinitValue\fR +parameter; the initial value to use for this can be obtained by using NULL for +the \fIbytes\fR 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: .PP .CS checksum = \fBTcl_ZlibCRC32\fR(\fBTcl_ZlibCRC32\fR(0,NULL,0), data, length); .CE +.PP +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. .SS "ZLIB STREAMS" .PP \fBTcl_ZlibStreamInit\fR 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; \fBTcl_ZlibStreamGetCommandName\fR returns the name of that command given the -stream token, or NULL if the stream has no command. +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 \fBGZIP OPTIONS DICTIONARY\fR section below) can be given via the +\fIdictObj\fR 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 +\fBTcl_NewObj\fR is suggested. .PP Once a stream has been constructed, \fBTcl_ZlibStreamPut\fR is used to add data to the stream and \fBTcl_ZlibStreamGet\fR is used to retrieve data from -the stream after processing. Both return normal Tcl result codes. With -\fBTcl_ZlibStreamPut\fR, the data buffer object passed to it should not be -modified afterwards. With \fBTcl_ZlibStreamGet\fR, the data buffer object -passed to it will have the data bytes appended to it. +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 +\fBTcl_ZlibStreamPut\fR, the data buffer value passed to it should not be +modified afterwards. With \fBTcl_ZlibStreamGet\fR, 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. .PP \fBTcl_ZlibStreamChecksum\fR returns the checksum computed over the uncompressed data according to the format, and \fBTcl_ZlibStreamEof\fR returns -whether the end of the uncompressed data has been reached. +a boolean value indicating whether the end of the uncompressed data has been +reached. .PP +\fBTcl_ZlibStreamSetCompressionDictionary\fR 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 \fBTcl_NewByteArrayObj\fR) 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 \fBTcl_ZlibStreamPut\fR, and on decompression they +should be set when \fBTcl_ZlibStreamGet\fR produces an \fBerror\fR with its +\fB\-errorcode\fR set to +.QW "\fBZLIB NEED_DICT\fI code\fR" ; +the \fIcode\fR will be the Adler-32 checksum (see \fBTcl_ZlibAdler32\fR) 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.) +.PP +If you wish to clear a stream and reuse it for a new compression or +decompression action, \fBTcl_ZlibStreamReset\fR 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, \fBTcl_ZlibStreamClose\fR will clean up the stream and delete the associated command: using \fBTcl_DeleteCommand\fR on the stream's command is -equivalent. +equivalent (when such a command exists). +.SH "GZIP OPTIONS DICTIONARY" +.PP +The \fIdictObj\fR parameter to \fBTcl_ZlibDeflate\fR, \fBTcl_ZlibInflate\fR +and \fBTcl_ZlibStreamInit\fR 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 \fIdictObj\fR parameter must refer to +an unshared dictionary value). +.PP +The following fields in the dictionary value are understood. All other fields +are ignored. No field is required when creating a gzip-format stream. +.TP +\fBcomment\fR +. +This holds the comment field of the header, if present. If absent, no comment +was supplied (on decompression) or will be created (on compression). +.TP +\fBcrc\fR +. +A boolean value describing whether a CRC of the header is computed. Note that +the \fBgzip\fR program does \fInot\fR use or allow a CRC on the header. +.TP +\fBfilename\fR +. +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 \fBfile tail\fR. +.TP +\fBos\fR +. +The operating system type code field from the header (if not the +.QW 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 +.QW unknown +value. +.TP +\fBsize\fR +. +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. +.TP +\fBtime\fR +. +The time field from the header if non-zero, expected to be the time that the +file named by the \fBfilename\fR field was modified. Suitable for use with +\fBclock format\fR. On creation, the right value to use is that from +\fBclock seconds\fR or \fBfile mtime\fR. +.TP +\fBtype\fR +. +The type of the uncompressed data (either \fBbinary\fR or \fBtext\fR) if +known. .SH "PORTABILITY NOTES" These functions will fail gracefully if Tcl is not linked with the zlib library. |