diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/TclZlib.3 | 69 | ||||
| -rw-r--r-- | doc/zlib.n | 6 |
2 files changed, 67 insertions, 8 deletions
diff --git a/doc/TclZlib.3 b/doc/TclZlib.3 index 42d82b5..43ec0a8 100644 --- a/doc/TclZlib.3 +++ b/doc/TclZlib.3 @@ -4,7 +4,7 @@ '\" 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 $ +'\" RCS: @(#) $Id: TclZlib.3,v 1.5 2010/02/10 16:12:11 dkf Exp $ '\" .so man.macros .TH TclZlib 3 8.6 Tcl "Tcl Library Procedures" @@ -77,7 +77,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 @@ -129,14 +131,17 @@ checksum = \fBTcl_ZlibCRC32\fR(\fBTcl_ZlibCRC32\fR(0,NULL,0), data, length); 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. .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. +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 @@ -144,7 +149,61 @@ whether the end of the uncompressed data has been reached. .PP 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 object). +.PP +The following fields in the dictionary object 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. @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: zlib.n,v 1.7 2009/01/24 00:03:18 dkf Exp $ +'\" RCS: @(#) $Id: zlib.n,v 1.8 2010/02/10 16:12:11 dkf Exp $ '\" .so man.macros .TH zlib n 8.6 Tcl "Tcl Built-In Commands" @@ -75,8 +75,8 @@ The size of the uncompressed data. \fBtime\fR . The time field from the header if non-zero, expected to be time that the file -named by the \fBfilename\fR field was modified. Suitable for use with \fBclock -format\fR. +named by the \fBfilename\fR field was modified. Suitable for use with +\fBclock format\fR. .TP \fBtype\fR . |