summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordkf <donal.k.fellows@manchester.ac.uk>2010-02-10 23:17:06 (GMT)
committerdkf <donal.k.fellows@manchester.ac.uk>2010-02-10 23:17:06 (GMT)
commit828f72e7957c659ea67bfae6c63ecbcb221e1bb7 (patch)
tree59cb5444e02f4bf6268524347bd29216373964cf
parent25174c675ed97c5219e2e92570ee0760a7081d0f (diff)
downloadtcl-828f72e7957c659ea67bfae6c63ecbcb221e1bb7.zip
tcl-828f72e7957c659ea67bfae6c63ecbcb221e1bb7.tar.gz
tcl-828f72e7957c659ea67bfae6c63ecbcb221e1bb7.tar.bz2
More zlib documentation improvements.
-rw-r--r--doc/TclZlib.358
-rw-r--r--doc/zlib.n21
-rwxr-xr-xtools/tcltk-man2html.tcl8
3 files changed, 63 insertions, 24 deletions
diff --git a/doc/TclZlib.3 b/doc/TclZlib.3
index 43ec0a8..6d5ec7f 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.5 2010/02/10 16:12:11 dkf Exp $
+'\" RCS: @(#) $Id: TclZlib.3,v 1.6 2010/02/10 23:17:06 dkf Exp $
'\"
.so man.macros
.TH TclZlib 3 8.6 Tcl "Tcl Library Procedures"
@@ -16,10 +16,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 +41,9 @@ int
\fBTcl_ZlibStreamClose\fR(\fIzshandle\fR)
.sp
int
+\fBTcl_ZlibStreamReset\fR(\fIzshandle\fR)
+.sp
+int
\fBTcl_ZlibStreamChecksum\fR(\fIzshandle\fR)
.sp
int
@@ -112,19 +115,33 @@ bytes from the stream's buffers.
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 object 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
@@ -133,11 +150,20 @@ 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. Streams are not designed
to be thread-safe; each stream should only ever be used from the thread that
-created it.
+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 object in that case; a blank object 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
+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 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. Internally to the
@@ -145,8 +171,14 @@ 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
+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 (when such a command exists).
diff --git a/doc/zlib.n b/doc/zlib.n
index 6c2af2f..f633cea 100644
--- a/doc/zlib.n
+++ b/doc/zlib.n
@@ -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.8 2010/02/10 16:12:11 dkf Exp $
+'\" RCS: @(#) $Id: zlib.n,v 1.9 2010/02/10 23:17:06 dkf Exp $
'\"
.so man.macros
.TH zlib n 8.6 Tcl "Tcl Built-In Commands"
@@ -126,9 +126,9 @@ The type of the data being compressed, being \fBbinary\fR or \fBtext\fR.
Returns the uncompressed version of the raw compressed binary data in
\fIstring\fR. If present, \fIbufferSize\fR is a hint as to what size of buffer
is to be used to receive the data.
-.SS "STREAMING AND CHANNEL SUBCOMMANDS"
+.SS "CHANNEL SUBCOMMAND"
.TP
-\fBzlib push\fI mode channel\fR ?\fIoptions ...\fR
+\fBzlib push\fI mode channel\fR ?\fIoptions ...\fR?
.
Pushes a compressing or decompressing transformation onto the channel
\fIchannel\fR.
@@ -167,7 +167,10 @@ gzip-format data on \fIchannel\fR, which must be writable.
The transformation will be a decompressing transformation that reads raw
compressed data from \fIchannel\fR, which must be readable.
.PP
-The following options may be set when creating a transformation:
+The following options may be set when creating a transformation via
+the
+.QW "\fIoptions ...\fR"
+to the \fBzlib push\fR command:
.TP
\fB\-header\fI dictionary\fR
.
@@ -184,15 +187,18 @@ How hard to compress the data. Must be an integer from 0 (uncompressed) to 9
'\"The maximum number of bytes ahead to read.
'\"\fITODO: not yet implemented!\fR
.PP
-Both compressing and decompressing channel transformations add extra options
-that may be accessed through \fBchan configure\fR. These are:
+Both compressing and decompressing channel transformations add extra
+configuration options that may be accessed through \fBchan configure\fR. Each
+option is either a read-only or a write-only option. The options are:
.TP
\fB\-flush\fI type\fR
.
This write-only operation flushes the current state of the compressor to the
underlying channel. It is only valid for compressing transformations. The
\fItype\fR must be either \fBsync\fR or \fBfull\fR for a normal flush or an
-expensive flush respectively. Note that flushing degrades compression.
+expensive flush respectively. Flushing degrades the compression ratio, but
+makes it easier for a decompressor to recover more of the file in the case of
+data corruption.
.TP
\fB\-checksum\fR
.
@@ -207,6 +213,7 @@ This read-only option, only valid for decompressing transforms that are
processing gzip-format data, returns the dictionary describing the header read
off the data stream.
.RE
+.SS "STREAMING SUBCOMMAND"
.TP
\fBzlib stream\fI mode\fR ?\fIlevel\fR?
.
diff --git a/tools/tcltk-man2html.tcl b/tools/tcltk-man2html.tcl
index 7af1512..fd8a258 100755
--- a/tools/tcltk-man2html.tcl
+++ b/tools/tcltk-man2html.tcl
@@ -18,9 +18,9 @@ package require Tcl 8.6
# Copyright (c) 1995-1997 Roger E. Critchlow Jr
# Copyright (c) 2004-2010 Donal K. Fellows
#
-# CVS: $Id: tcltk-man2html.tcl,v 1.45 2010/02/10 16:12:11 dkf Exp $
+# CVS: $Id: tcltk-man2html.tcl,v 1.46 2010/02/10 23:17:07 dkf Exp $
-regexp {\d+\.\d+} {$Revision: 1.45 $} ::Version
+regexp {\d+\.\d+} {$Revision: 1.46 $} ::Version
set ::CSSFILE "docs.css"
##
@@ -813,7 +813,7 @@ array set exclude_refs_map {
clock.n {next}
history.n {exec}
next.n {unknown}
- zlib.n {binary filename text}
+ zlib.n {binary close filename text}
canvas.n {bitmap text}
checkbutton.n {image}
clipboard.n {string}
@@ -839,7 +839,7 @@ array set exclude_refs_map {
ttk_spinbox.n {format}
ttk_treeview.n {text open}
ttk_widget.n {image text variable}
- TclZlib.3 {binary filename text}
+ TclZlib.3 {binary flush filename text}
}
array set exclude_when_followed_by_map {
canvas.n {