diff options
Diffstat (limited to 'doc/TclZlib.3')
| -rw-r--r-- | doc/TclZlib.3 | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/doc/TclZlib.3 b/doc/TclZlib.3 new file mode 100644 index 0000000..103f2e8 --- /dev/null +++ b/doc/TclZlib.3 @@ -0,0 +1,148 @@ +'\" +'\" Copyright (c) 2008 Donal K. Fellows +'\" +'\" 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.1 2008/12/13 17:36:34 dkf Exp $ +'\" +.so man.macros +.TH TclZlib 3 8.6 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Tcl_ZlibAdler32, Tcl_ZlibCRC32, Tcl_ZlibDeflate, Tcl_ZlibInflate, Tcl_ZlibStreamAdler32, Tcl_ZlibStreamClose, Tcl_ZlibStreamEof, Tcl_ZlibStreamGet, Tcl_ZlibStreamGetCommandName, Tcl_ZlibStreamInit, Tcl_ZlibStreamPut \- compression and decompression functions +.SH SYNOPSIS +.nf +#include <tcl.h> +.sp +Tcl_Obj * +\fBTcl_ZlibDeflate\fR(\fIinterp, format, dataObj, level, dictObj\fR) +.sp +Tcl_Obj * +\fBTcl_ZlibInflate\fR(\fIinterp, format, dataObj, dictObj\fR) +.sp +unsigned int +\fBTcl_ZlibCRC32\fR(\fIinitValue, bytes, length\fR) +.sp +unsigned int +\fBTcl_ZlibAdler32\fR(\fIinitValue, bytes, length\fR) +.sp +int +\fBTcl_ZlibStreamInit\fR(\fIinterp, mode, format, level, dictObj, zshandlePtr\fR) +.sp +Tcl_Obj * +\fBTcl_ZlibStreamGetCommandName\fR(\fIzshandle\fR) +.sp +int +\fBTcl_ZlibStreamEof\fR(\fIzshandle\fR) +.sp +int +\fBTcl_ZlibStreamClose\fR(\fIzshandle\fR) +.sp +int +\fBTcl_ZlibStreamAdler32\fR(\fIzshandle\fR) +.sp +int +\fBTcl_ZlibStreamPut\fR(\fIzshandle, dataObj, flush\fR) +.sp +int +\fBTcl_ZlibStreamGet\fR(\fIzshandle, dataObj, count\fR) +.fi +.SH ARGUMENTS +.AS Tcl_ZlibStream *zshandlePtr out +.AP Tcl_Interp *interp in +The interpreter to store resulting compressed or uncompressed data in. Also +where any error messages are written. +.AP int format in +What format of compressed data to work with. Must be one of +\fBTCL_ZLIB_FORMAT_ZLIB\fR for zlib-format data, \fBTCL_ZLIB_FORMAT_GZIP\fR +for gzip-format data, or \fBTCL_ZLIB_FORMAT_RAW\fR for raw compressed data. In +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 +which is set to the data extracted from the stream when passed to +\fBTcl_ZlibStreamGet\fR. +.AP int level in +What level of compression to use. Should be a number from 0 to 9 or one of the +following: \fBTCL_ZLIB_COMPRESS_NONE\fR for no compression, +\fBTCL_ZLIB_COMPRESS_FAST\fR for fast but inefficient compression, +\fBTCL_ZLIB_COMPRESS_BEST\fR for slow but maximal compression, or +\fBTCL_ZLIB_COMPRESS_DEFAULT\fR for the level recommended by the zlib library. +.AP 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 +\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. +.AP "unsigned int" initValue in +The initial value for the checksum algorithm. +.AP "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. +.AP int length in +The number of bytes in the array. +.AP int mode in +What mode to operate the stream in. Should be either +\fBTCL_ZLIB_STREAM_DEFLATE\fR for a compressing stream or +\fBTCL_ZLIB_STREAM_INFLATE\fR for a decompressing stream. +.AP Tcl_ZlibStream *zshandlePtr out +A pointer to a variable in which to write the abstract token for the stream +upon successful creation. +.AP Tcl_ZlibStream zshandle in +The abstract token for the stream to operate on. +.AP int flush in +Whether and how to flush the stream after writing the data to it. Must be one +of: \fBTCL_ZLIB_NO_FLUSH\fR if no flushing is to be done, \fBTCL_ZLIB_FLUSH\fR +if the currently compressed data must be made available for access using +\fBTcl_ZlibStreamGet\fR, \fBTCL_ZLIB_FULLFLUSH\fR if the stream must be put +into a state where the decompressor can recover from on corruption, or +\fBTCL_ZLIB_FINALIZE\fR to ensure that the stream is finished and that any +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. +.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. +.PP +\fBTcl_ZlibAdler32\fR and \fBTcl_ZlibCRC32\fR compute checksums on arrays of +bytes. Typical usage is: +.PP +.CS +checksum = Tcl_ZlibCRC32(Tcl_ZlibCRC32(0,NULL,0), data, length); +.CE +.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; \fBTcl_ZlibStreamGetCommandName\fR returns the name of +that command given the stream token. 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. \fBTcl_ZlibStreamAdler32\fR returns the checksum computed over the +uncompressed data, and \fBTcl_ZlibStreamEof\fR returns whether the end of the +uncompressed data has been reached. 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. +.SH "PORTABILITY NOTES" +These functions will fail gracefully if Tcl is not linked with the zlib +library. +.SH "SEE ALSO" +Tcl_NewByteArrayObj(3), zlib(n) +'\"Tcl_StackChannel(3) +.SH "KEYWORDS" +compress, decompress, deflate, gzip, inflate +'\" Local Variables: +'\" mode: nroff +'\" fill-column: 78 +'\" End: |