summaryrefslogtreecommitdiffstats
path: root/tcl8.6/doc/zlib.n
diff options
context:
space:
mode:
authorWilliam Joye <wjoye@cfa.harvard.edu>2018-12-25 19:55:50 (GMT)
committerWilliam Joye <wjoye@cfa.harvard.edu>2018-12-25 19:55:50 (GMT)
commitff51550ee89b473c63df78de6b2a413f21105687 (patch)
treebcdca927ed2a7b05c647b9a6bfdfd4a7ca5c730e /tcl8.6/doc/zlib.n
parent01cbf5b15ea760408c24288ccb5cf8e0af9aa299 (diff)
downloadblt-ff51550ee89b473c63df78de6b2a413f21105687.zip
blt-ff51550ee89b473c63df78de6b2a413f21105687.tar.gz
blt-ff51550ee89b473c63df78de6b2a413f21105687.tar.bz2
update tcl/tk
Diffstat (limited to 'tcl8.6/doc/zlib.n')
-rw-r--r--tcl8.6/doc/zlib.n466
1 files changed, 0 insertions, 466 deletions
diff --git a/tcl8.6/doc/zlib.n b/tcl8.6/doc/zlib.n
deleted file mode 100644
index fd29e0d..0000000
--- a/tcl8.6/doc/zlib.n
+++ /dev/null
@@ -1,466 +0,0 @@
-'\"
-'\" 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: