zlib -
compression and decompression operations
zlib subcommand arg ...
The zlib 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.
-
zlib compress string ?level?
- Returns the zlib-format compressed binary data of the binary string in
string. If present, level gives the compression level to use (from
0, which is uncompressed, to 9, maximally compressed).
-
zlib decompress string ?bufferSize?
- Returns the uncompressed version of the raw compressed binary data in
string. If present, bufferSize is a hint as to what size of buffer
is to be used to receive the data.
-
zlib deflate string ?level?
- Returns the raw compressed binary data of the binary string in string.
If present, level gives the compression level to use (from 0, which is
uncompressed, to 9, maximally compressed).
-
zlib gunzip string ?-headerVar varName?
- Return the uncompressed contents of binary string string, which must
have been in gzip format. If -headerVar is given, store a dictionary
describing the contents of the gzip header in the variable called
varName. The keys of the dictionary that may be present are:
- comment
- The comment field from the header, if present.
- crc
- A boolean value describing whether a CRC of the header is computed.
- filename
- The filename field from the header, if present.
- os
- The operating system type code field from the header (if not the
QW unknown
value). See RFC 1952 for the meaning of these codes.
- size
- The size of the uncompressed data.
- time
- The time field from the header if non-zero, expected to be time that the file
named by the filename field was modified. Suitable for use with clock
format.
- type
- The type of the uncompressed data (binary or text) if known.
-
zlib gzip string ?-level level? ?-header dict?
- Return the compressed contents of binary string string in gzip format.
If -level is given, level gives the compression level to use
(from 0, which is uncompressed, to 9, maximally compressed). If -header
is given, dict is a dictionary containing values used for the gzip
header. The following keys may be defined:
- comment
- Add the given comment to the header of the gzip-format data.
- crc
- A boolean saying whether to compute a CRC of the header. Note that if the data
is to be interchanged with the gzip program, a header CRC should
not be computed.
- filename
- The name of the file that the data to be compressed came from.
- os
- The operating system type code, which should be one of the values described in
RFC 1952.
- time
- The time that the file named in the filename key was last modified. This
will be in the same as is returned by clock seconds or file mtime.
- type
- The type of the data being compressed, being binary or text.
-
zlib inflate string ?bufferSize?
- Returns the uncompressed version of the raw compressed binary data in
string. If present, bufferSize is a hint as to what size of buffer
is to be used to receive the data.
-
zlib push mode channel ?options ...
- Pushes a compressing or decompressing transformation onto the channel
channel. The mode argument determines what type of transformation
is pushed; the following are supported:
- compress
- The transformation will be a compressing transformation that produces
zlib-format data on channel, which must be writable.
- decompress
- The transformation will be a decompressing transformation that reads
zlib-format data from channel, which must be readable.
- deflate
- The transformation will be a compressing transformation that produces raw
compressed data on channel, which must be writable.
- gunzip
- The transformation will be a decompressing transformation that reads
gzip-format data from channel, which must be readable.
- gzip
- The transformation will be a compressing transformation that produces
gzip-format data on channel, which must be writable.
- inflate
- The transformation will be a decompressing transformation that reads raw
compressed data from channel, which must be readable.
The following options may be set when creating a transformation:
-
-header dictionary
- Passes a description of the gzip header to create, in the same format that
zlib gzip understands.
-
-level compressionLevel
- How hard to compress the data. Must be an integer from 0 (uncompressed) to 9
(maximally compressed).
Both compressing and decompressing channel transformations add extra options
that may be accessed through chan configure. These are:
-
-flush type
- This write-only operation flushes the current state of the compressor to the
underlying channel. It is only valid for compressing transformations. The
type must be either sync or full for a normal flush or an
expensive flush respectively. Note that flushing degrades compression.
- -checksum
- This read-only option, valid for both compressing and decompressing
transforms, gets the current checksum for the uncompressed data that the
compression engine has seen so far. The compression algorithm depends on what
format is being produced or consumed.
- -header
- 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.
-
zlib stream mode ?level?
- Creates a streaming compression or decompression command based on the
mode, and return the name of the command. For a description of how that
command works, see STREAMING INSTANCE COMMAND below. The following modes
are supported:
-
zlib stream compress ?level?
- The stream will be a compressing stream that produces zlib-format output,
using compression level level (if specified) which will be an integer
from 0 to 9.
- zlib stream decompress
- The stream will be a decompressing stream that takes zlib-format input and
produces uncompressed output.
-
zlib stream deflate ?level?
- The stream will be a compressing stream that produces raw output, using
compression level level (if specified) which will be an integer from 0
to 9.
- zlib stream gunzip
- The stream will be a decompressing stream that takes gzip-format input and
produces uncompressed output.
-
zlib stream gzip ?level?
- The stream will be a compressing stream that produces gzip-format output,
using compression level level (if specified) which will be an integer
from 0 to 9.
- zlib stream inflate
- The stream will be a decompressing stream that takes raw compressed input and
produces uncompressed output.
-
zlib adler32 string ?initValue?
- Compute a checksum of binary string string using the Adler-32 algorithm.
If given, initValue is used to initialize the checksum engine.
-
zlib crc32 string ?initValue?
- Compute a checksum of binary string string using the CRC-32 algorithm.
If given, initValue is used to initialize the checksum engine.
Streaming compression instance commands are produced by the zlib stream
command. They are used by calling their put subcommand one or more times
to load data in, and their get subcommand one or more times to extract
the transformed data.
The full set of subcommands supported by a streaming instance command,
stream, is as follows:
-
stream add ?option? data
- A short-cut for
"stream put option data" followed by
"stream get".
-
stream checksum
- Returns the checksum of the uncompressed data seen so far by this stream.
-
stream close
- Deletes this stream and frees up all resources associated with it.
-
stream eof
- 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.
-
stream finalize
- A short-cut for
"stream put -finalize {}".
-
stream flush
- A short-cut for
"stream put -flush {}".
-
stream fullflush
- A short-cut for
"stream put -fullflush {}".
-
stream get ?count?
- Return up to count bytes from stream's internal buffers with the
transformation applied. If count is omitted, the entire contents of the
buffers are returned.
-
stream put ?option? data
- Append the contents of the binary string data to stream's internal
buffers while applying the transformation. If present, option must be
one of the following (or an unambiguous prefix) which are used to modify the
way in which the transformation is applied:
- -finalize
- 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 get subcommand.
- -flush
- 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.
- -fullflush
- Ensure that not only can a decompressor handle all the bytes produced so far
(as with -flush 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.
-
stream reset
- 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.
To compress a Tcl string, it should be first converted to a particular charset
encoding since the zlib command always operates on binary strings.
set binData [encoding convertto utf-8 $string]
set compData [zlib compress $binData]
When converting back, it is also important to reverse the charset encoding:
set binData [zlib decompress $compData]
set string [encoding convertfrom utf-8 $binData]
The compression operation from above can also be done with streams, which is
especially helpful when you want to accumulate the data by stages:
set strm [zlib stream compress]
$strm put [encoding convertto utf-8 $string]
# ...
$strm finalize
set compData [$strm get]
$strm close
binary(n), chan(n), encoding(n), Tcl_ZlibDeflate(3), RFC1950 - RFC1952
compress, decompress, deflate, gzip, inflate