diff options
Diffstat (limited to 'doc/zlib.n')
| -rw-r--r-- | doc/zlib.n | 466 |
1 files changed, 466 insertions, 0 deletions
diff --git a/doc/zlib.n b/doc/zlib.n new file mode 100644 index 0000000..fd29e0d --- /dev/null +++ b/doc/zlib.n @@ -0,0 +1,466 @@ +'\" +'\" Copyright (c) 2008-2012 Donal K. Fellows +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH zlib n 8.6 Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +zlib \- compression and decompression operations +.SH SYNOPSIS +.nf +\fBzlib \fIsubcommand arg ...\fR +.fi +.BE +.SH DESCRIPTION +.PP +The \fBzlib\fR command provides access to the compression and check-summing +facilities of the Zlib library by Jean-loup Gailly and Mark Adler. It has the +following subcommands. +.SS "COMPRESSION SUBCOMMANDS" +.TP +\fBzlib compress\fI string\fR ?\fIlevel\fR? +. +Returns the zlib-format compressed binary data of the binary string in +\fIstring\fR. If present, \fIlevel\fR gives the compression level to use (from +0, which is uncompressed, to 9, maximally compressed). +.TP +\fBzlib decompress\fI string\fR ?\fIbufferSize\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. +.TP +\fBzlib deflate\fI string\fR ?\fIlevel\fR? +. +Returns the raw compressed binary data of the binary string in \fIstring\fR. +If present, \fIlevel\fR gives the compression level to use (from 0, which is +uncompressed, to 9, maximally compressed). +.TP +\fBzlib gunzip\fI string\fR ?\fB\-headerVar \fIvarName\fR? +. +Return the uncompressed contents of binary string \fIstring\fR, which must +have been in gzip format. If \fB\-headerVar\fR is given, store a dictionary +describing the contents of the gzip header in the variable called +\fIvarName\fR. The keys of the dictionary that may be present are: +.RS +.TP +\fBcomment\fR +. +The comment field from the header, if present. +.TP +\fBcrc\fR +. +A boolean value describing whether a CRC of the header is computed. +.TP +\fBfilename\fR +. +The filename field from the header, if present. +.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. +.TP +\fBsize\fR +. +The size of the uncompressed data. +.TP +\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. +.TP +\fBtype\fR +. +The type of the uncompressed data (\fBbinary\fR or \fBtext\fR) if known. +.RE +.TP +\fBzlib gzip\fI string\fR ?\fB\-level \fIlevel\fR? ?\fB\-header \fIdict\fR? +. +Return the compressed contents of binary string \fIstring\fR in gzip format. +If \fB\-level\fR is given, \fIlevel\fR gives the compression level to use +(from 0, which is uncompressed, to 9, maximally compressed). If \fB\-header\fR +is given, \fIdict\fR is a dictionary containing values used for the gzip +header. The following keys may be defined: +.RS +.TP +\fBcomment\fR +. +Add the given comment to the header of the gzip-format data. +.TP +\fBcrc\fR +. +A boolean saying whether to compute a CRC of the header. Note that if the data +is to be interchanged with the \fBgzip\fR program, a header CRC should +\fInot\fR be computed. +.TP +\fBfilename\fR +. +The name of the file that the data to be compressed came from. +.TP +\fBos\fR +. +The operating system type code, which should be one of the values described in +RFC 1952. +.TP +\fBtime\fR +. +The time that the file named in the \fBfilename\fR key was last modified. This +will be in the same as is returned by \fBclock seconds\fR or \fBfile mtime\fR. +.TP +\fBtype\fR +. +The type of the data being compressed, being \fBbinary\fR or \fBtext\fR. +.RE +.TP +\fBzlib inflate\fI string\fR ?\fIbufferSize\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 "CHANNEL SUBCOMMAND" +.TP +\fBzlib push\fI mode channel\fR ?\fIoptions ...\fR? +. +Pushes a compressing or decompressing transformation onto the channel +\fIchannel\fR. +The transformation can be removed again with \fBchan pop\fR. +The \fImode\fR argument determines what type of transformation +is pushed; the following are supported: +.RS +.TP +\fBcompress\fR +. +The transformation will be a compressing transformation that produces +zlib-format data on \fIchannel\fR, which must be writable. +.TP +\fBdecompress\fR +. +The transformation will be a decompressing transformation that reads +zlib-format data from \fIchannel\fR, which must be readable. +.TP +\fBdeflate\fR +. +The transformation will be a compressing transformation that produces raw +compressed data on \fIchannel\fR, which must be writable. +.TP +\fBgunzip\fR +. +The transformation will be a decompressing transformation that reads +gzip-format data from \fIchannel\fR, which must be readable. +.TP +\fBgzip\fR +. +The transformation will be a compressing transformation that produces +gzip-format data on \fIchannel\fR, which must be writable. +.TP +\fBinflate\fR +. +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 via +the +.QW "\fIoptions ...\fR" +to the \fBzlib push\fR command: +.TP +\fB\-dictionary\fI binData\fR +.VS "TIP 400" +Sets the compression dictionary to use when working with compressing or +decompressing the data to be \fIbinData\fR. Not valid for transformations that +work with gzip-format data. The dictionary should consist of strings (byte +sequences) that are likely to be encountered later in the data to be compressed, +with the most commonly used strings preferably put towards the end of the +dictionary. Tcl provides no mechanism for choosing a good such dictionary for +a particular data sequence. +.VE +.TP +\fB\-header\fI dictionary\fR +. +Passes a description of the gzip header to create, in the same format that +\fBzlib gzip\fR understands. +.TP +\fB\-level\fI compressionLevel\fR +. +How hard to compress the data. Must be an integer from 0 (uncompressed) to 9 +(maximally compressed). +.TP +\fB\-limit\fI readaheadLimit\fR +. +The maximum number of bytes ahead to read when decompressing. This defaults to +1, which ensures that data is always decompressed correctly, but may be +increased to improve performance. This is more useful when the channel is +non-blocking. +.PP +Both compressing and decompressing channel transformations add extra +configuration options that may be accessed through \fBchan configure\fR. The +options are: +.TP +\fB\-checksum\fI checksum\fR +. +This read-only option gets the current checksum for the uncompressed data that +the compression engine has seen so far. It is valid for both compressing and +decompressing transforms, but not for the raw inflate and deflate formats. The +compression algorithm depends on what format is being produced or consumed. +.TP +\fB\-dictionary\fI binData\fR +.VS "TIP 400" +This read-write options gets or sets the initial compression dictionary to use +when working with compressing or decompressing the data to be \fIbinData\fR. +It is not valid for transformations that work with gzip-format data, and should +not normally be set on compressing transformations other than at the point where +the transformation is stacked. Note that this cannot be used to get the +current active compression dictionary mid-stream, as that information is not +exposed by the underlying library. +.VE +.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. 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\-header\fI dictionary\fR +. +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. +.TP +\fB\-limit\fI readaheadLimit\fR +. +This read-write option is used by decompressing channels to control the +maximum number of bytes ahead to read from the underlying data source. This +defaults to 1, which ensures that data is always decompressed correctly, but +may be increased to improve performance. This is more useful when the channel +is non-blocking. +.RE +.SS "STREAMING SUBCOMMAND" +.TP +\fBzlib stream\fI mode\fR ?\fIoptions\fR? +. +Creates a streaming compression or decompression command based on the +\fImode\fR, and return the name of the command. For a description of how that +command works, see \fBSTREAMING INSTANCE COMMAND\fR below. The following modes +and \fIoptions\fR are supported: +.RS +.TP +\fBzlib stream compress\fR ?\fB\-dictionary \fIbindata\fR? ?\fB\-level \fIlevel\fR? +. +The stream will be a compressing stream that produces zlib-format output, +using compression level \fIlevel\fR (if specified) which will be an integer +from 0 to 9, +.VS "TIP 400" +and the compression dictionary \fIbindata\fR (if specified). +.VE +.TP +\fBzlib stream decompress\fR ?\fB\-dictionary \fIbindata\fR? +. +The stream will be a decompressing stream that takes zlib-format input and +produces uncompressed output. +.VS "TIP 400" +If \fIbindata\fR is supplied, it is a compression dictionary to use if +required. +.VE +.TP +\fBzlib stream deflate\fR ?\fB\-dictionary \fIbindata\fR? ?\fB\-level \fIlevel\fR? +. +The stream will be a compressing stream that produces raw output, using +compression level \fIlevel\fR (if specified) which will be an integer from 0 +to 9, +.VS "TIP 400" +and the compression dictionary \fIbindata\fR (if specified). Note that +the raw compressed data includes no metadata about what compression +dictionary was used, if any; that is a feature of the zlib-format data. +.VE +.TP +\fBzlib stream gunzip\fR +. +The stream will be a decompressing stream that takes gzip-format input and +produces uncompressed output. +.TP +\fBzlib stream gzip\fR ?\fB\-header \fIheader\fR? ?\fB\-level \fIlevel\fR? +. +The stream will be a compressing stream that produces gzip-format output, +using compression level \fIlevel\fR (if specified) which will be an integer +from 0 to 9, and the header descriptor dictionary \fIheader\fR (if specified; +for keys see \fBzlib gzip\fR). +.TP +\fBzlib stream inflate\fR ?\fB\-dictionary \fIbindata\fR? +. +The stream will be a decompressing stream that takes raw compressed input and +produces uncompressed output. +.VS "TIP 400" +If \fIbindata\fR is supplied, it is a compression dictionary to use. Note that +there are no checks in place to determine whether the compression dictionary +is correct. +.VE +.RE +.SS "CHECKSUMMING SUBCOMMANDS" +.TP +\fBzlib adler32\fI string\fR ?\fIinitValue\fR? +. +Compute a checksum of binary string \fIstring\fR using the Adler-32 algorithm. +If given, \fIinitValue\fR is used to initialize the checksum engine. +.TP +\fBzlib crc32\fI string\fR ?\fIinitValue\fR? +. +Compute a checksum of binary string \fIstring\fR using the CRC-32 algorithm. +If given, \fIinitValue\fR is used to initialize the checksum engine. +.SH "STREAMING INSTANCE COMMAND" +.PP +Streaming compression instance commands are produced by the \fBzlib stream\fR +command. They are used by calling their \fBput\fR subcommand one or more times +to load data in, and their \fBget\fR subcommand one or more times to extract +the transformed data. +.PP +The full set of subcommands supported by a streaming instance command, +\fIstream\fR, is as follows: +.TP +\fIstream \fBadd\fR ?\fIoption...\fR? \fIdata\fR +. +A short-cut for +.QW "\fIstream \fBput \fR?\fIoption...\fR? \fIdata\fR" +followed by +.QW "\fIstream \fBget\fR" . +.TP +\fIstream \fBchecksum\fR +. +Returns the checksum of the uncompressed data seen so far by this stream. +.TP +\fIstream \fBclose\fR +. +Deletes this stream and frees up all resources associated with it. +.TP +\fIstream \fBeof\fR +. +Returns a boolean indicating whether the end of the stream (as determined by +the compressed data itself) has been reached. Not all formats support +detection of the end of the stream. +.TP +\fIstream \fBfinalize\fR +. +A short-cut for +.QW "\fIstream \fBput \-finalize {}\fR" . +.TP +\fIstream \fBflush\fR +. +A short-cut for +.QW "\fIstream \fBput \-flush {}\fR" . +.TP +\fIstream \fBfullflush\fR +. +A short-cut for +.QW "\fIstream \fBput \-fullflush {}\fR" . +.TP +\fIstream \fBget \fR?\fIcount\fR? +. +Return up to \fIcount\fR bytes from \fIstream\fR's internal buffers with the +transformation applied. If \fIcount\fR is omitted, the entire contents of the +buffers are returned. +. +\fIstream \fBheader\fR +. +Return the gzip header description dictionary extracted from the stream. Only +supported for streams created with their \fImode\fR parameter set to +\fBgunzip\fR. +.TP +\fIstream \fBput\fR ?\fIoption...\fR? \fIdata\fR +. +Append the contents of the binary string \fIdata\fR to \fIstream\fR's internal +buffers while applying the transformation. The following \fIoption\fRs are +supported (or an unambiguous prefix of them), which are used to modify the +way in which the transformation is applied: +.RS +.TP +\fB\-dictionary\fI binData\fR +.VS "TIP 400" +Sets the compression dictionary to use when working with compressing or +decompressing the data to be \fIbinData\fR. +.VE +.TP +\fB\-finalize\fR +. +Mark the stream as finished, ensuring that all bytes have been wholly +compressed or decompressed. For gzip streams, this also ensures that the +footer is written to the stream. The stream will need to be reset before +having more data written to it after this, though data can still be read out +of the stream with the \fBget\fR subcommand. +.RS +.PP +This option is mutually exclusive with the \fB\-flush\fR and \fB\-fullflush\fR +options. +.RE +.TP +\fB\-flush\fR +. +Ensure that a decompressor consuming the bytes that the current (compressing) +stream is producing will be able to produce all the bytes that have been +compressed so far, at some performance penalty. +.RS +.PP +This option is mutually exclusive with the \fB\-finalize\fR and +\fB\-fullflush\fR options. +.RE +.TP +\fB\-fullflush\fR +. +Ensure that not only can a decompressor handle all the bytes produced so far +(as with \fB\-flush\fR above) but also that it can restart from this point if +it detects that the stream is partially corrupt. This incurs a substantial +performance penalty. +.RS +.PP +This option is mutually exclusive with the \fB\-finalize\fR and \fB\-flush\fR +options. +.RE +.RE +.TP +\fIstream \fBreset\fR +. +Puts any stream, including those that have been finalized or that have reached +eof, back into a state where it can process more data. Throws away all +internally buffered data. +.SH EXAMPLES +.PP +To compress a Tcl string, it should be first converted to a particular charset +encoding since the \fBzlib\fR command always operates on binary strings. +.PP +.CS +set binData [encoding convertto utf-8 $string] +set compData [\fBzlib compress\fR $binData] +.CE +.PP +When converting back, it is also important to reverse the charset encoding: +.PP +.CS +set binData [\fBzlib decompress\fR $compData] +set string [encoding convertfrom utf-8 $binData] +.CE +.PP +The compression operation from above can also be done with streams, which is +especially helpful when you want to accumulate the data by stages: +.PP +.CS +set strm [\fBzlib stream\fR compress] +$\fIstrm \fBput\fR [encoding convertto utf-8 $string] +# ... +$\fIstrm \fBfinalize\fR +set compData [$\fIstrm \fBget\fR] +$\fIstrm \fBclose\fR +.CE +.SH "SEE ALSO" +binary(n), chan(n), encoding(n), Tcl_ZlibDeflate(3), RFC1950 \- RFC1952 +.SH "KEYWORDS" +compress, decompress, deflate, gzip, inflate, zlib +'\" Local Variables: +'\" mode: nroff +'\" End: |