1zlib(n) Tcl Built-In Commands zlib(n)
2______________________________________________________________________________
6
8 zlib - compression and decompression operations
9
11 zlib subcommand arg ...
12______________________________________________________________________________
13
15 The zlib command provides access to the compression and check-summing
16 facilities of the Zlib library by Jean-loup Gailly and Mark Adler. It
17 has the following subcommands.
18 COMPRESSION SUBCOMMANDS
20 zlib compress string ?level?
21 Returns the zlib-format compressed binary data of the binary
22 string in string. If present, level gives the compression level
23 to use (from 0, which is uncompressed, to 9, maximally com‐
24 pressed).
25 zlib decompress string ?bufferSize?
27 Returns the uncompressed version of the raw compressed binary
28 data in string. If present, bufferSize is a hint as to what size
29 of buffer is to be used to receive the data.
30 zlib deflate string ?level?
32 Returns the raw compressed binary data of the binary string in
33 string. If present, level gives the compression level to use
34 (from 0, which is uncompressed, to 9, maximally compressed).
35 zlib gunzip string ?-headerVar varName?
37 Return the uncompressed contents of binary string string, which
38 must have been in gzip format. If -headerVar is given, store a
39 dictionary describing the contents of the gzip header in the
40 variable called varName. The keys of the dictionary that may be
41 present are:
42 comment
44 The comment field from the header, if present.
45 crc A boolean value describing whether a CRC of the header is
47 computed.
48 filename
50 The filename field from the header, if present.
51 os The operating system type code field from the header (if
53 not the QW unknown value). See RFC 1952 for the meaning
54 of these codes.
55 size The size of the uncompressed data.
57 time The time field from the header if non-zero, expected to
59 be time that the file named by the filename field was
60 modified. Suitable for use with clock format.
61 type The type of the uncompressed data (binary or text) if
63 known.
64 zlib gzip string ?-level level? ?-header dict?
66 Return the compressed contents of binary string string in gzip
67 format. If -level is given, level gives the compression level
68 to use (from 0, which is uncompressed, to 9, maximally com‐
69 pressed). If -header is given, dict is a dictionary containing
70 values used for the gzip header. The following keys may be de‐
71 fined:
72 comment
74 Add the given comment to the header of the gzip-format
75 data.
76 crc A boolean saying whether to compute a CRC of the header.
78 Note that if the data is to be interchanged with the gzip
79 program, a header CRC should not be computed.
80 filename
82 The name of the file that the data to be compressed came
83 from.
84 os The operating system type code, which should be one of
86 the values described in RFC 1952.
87 time The time that the file named in the filename key was last
89 modified. This will be in the same as is returned by
90 clock seconds or file mtime.
91 type The type of the data being compressed, being binary or
93 text.
94 zlib inflate string ?bufferSize?
96 Returns the uncompressed version of the raw compressed binary
97 data in string. If present, bufferSize is a hint as to what size
98 of buffer is to be used to receive the data.
99 CHANNEL SUBCOMMAND
101 zlib push mode channel ?options ...?
102 Pushes a compressing or decompressing transformation onto the
103 channel channel. The transformation can be removed again with
104 chan pop. The mode argument determines what type of transforma‐
105 tion is pushed; the following are supported:
106 compress
108 The transformation will be a compressing transformation
109 that produces zlib-format data on channel, which must be
110 writable.
111 decompress
113 The transformation will be a decompressing transformation
114 that reads zlib-format data from channel, which must be
115 readable.
116 deflate
118 The transformation will be a compressing transformation
119 that produces raw compressed data on channel, which must
120 be writable.
121 gunzip The transformation will be a decompressing transformation
123 that reads gzip-format data from channel, which must be
124 readable.
125 gzip The transformation will be a compressing transformation
127 that produces gzip-format data on channel, which must be
128 writable.
129 inflate
131 The transformation will be a decompressing transformation
132 that reads raw compressed data from channel, which must
133 be readable.
134 The following options may be set when creating a transformation
136 via the “options ...” to the zlib push command:
137 -dictionary binData
139 Sets the compression dictionary to use when working with │
140 compressing or decompressing the data to be binData. Not │
141 valid for transformations that work with gzip-format │
142 data. The dictionary should consist of strings (byte se‐ │
143 quences) that are likely to be encountered later in the │
144 data to be compressed, with the most commonly used │
145 strings preferably put towards the end of the dictionary. │
146 Tcl provides no mechanism for choosing a good such dic‐ │
147 tionary for a particular data sequence.
148 -header dictionary
150 Passes a description of the gzip header to create, in the
151 same format that zlib gzip understands.
152 -level compressionLevel
154 How hard to compress the data. Must be an integer from 0
155 (uncompressed) to 9 (maximally compressed).
156 -limit readaheadLimit
158 The maximum number of bytes ahead to read when decom‐
159 pressing.
160 This option has become irrelevant. It was originally in‐
162 troduced to prevent Tcl from reading beyond the end of a
163 compressed stream in multi-stream channels to ensure that
164 the data after was left alone for further reading, at the
165 cost of speed.
166 Tcl now automatically returns any bytes it has read be‐
168 yond the end of a compressed stream back to the channel,
169 making them appear as unread to further readers.
170 Both compressing and decompressing channel transformations add
172 extra configuration options that may be accessed through chan
173 configure. The options are:
174 -checksum checksum
176 This read-only option gets the current checksum for the
177 uncompressed data that the compression engine has seen so
178 far. It is valid for both compressing and decompressing
179 transforms, but not for the raw inflate and deflate for‐
180 mats. The compression algorithm depends on what format is
181 being produced or consumed.
182 -dictionary binData
184 This read-write options gets or sets the initial compres‐ │
185 sion dictionary to use when working with compressing or │
186 decompressing the data to be binData. It is not valid │
187 for transformations that work with gzip-format data, and │
188 should not normally be set on compressing transformations │
189 other than at the point where the transformation is │
190 stacked. Note that this cannot be used to get the current │
191 active compression dictionary mid-stream, as that infor‐ │
192 mation is not exposed by the underlying library.
193 -flush type
195 This write-only operation flushes the current state of
196 the compressor to the underlying channel. It is only
197 valid for compressing transformations. The type must be
198 either sync or full for a normal flush or an expensive
199 flush respectively. Flushing degrades the compression ra‐
200 tio, but makes it easier for a decompressor to recover
201 more of the file in the case of data corruption.
202 -header dictionary
204 This read-only option, only valid for decompressing
205 transforms that are processing gzip-format data, returns
206 the dictionary describing the header read off the data
207 stream.
208 -limit readaheadLimit
210 This read-write option is used by decompressing channels
211 to control the maximum number of bytes ahead to read from
212 the underlying data source. See above for more informa‐
213 tion.
214 STREAMING SUBCOMMAND
216 zlib stream mode ?options?
217 Creates a streaming compression or decompression command based
218 on the mode, and return the name of the command. For a descrip‐
219 tion of how that command works, see STREAMING INSTANCE COMMAND
220 below. The following modes and options are supported:
221 zlib stream compress ?-dictionary bindata? ?-level level?
223 The stream will be a compressing stream that produces
224 zlib-format output, using compression level level (if
225 specified) which will be an integer from 0 to 9, and the │
226 compression dictionary bindata (if specified).
227 zlib stream decompress ?-dictionary bindata?
229 The stream will be a decompressing stream that takes
230 zlib-format input and produces uncompressed output. If │
231 bindata is supplied, it is a compression dictionary to │
232 use if required.
233 zlib stream deflate ?-dictionary bindata? ?-level level?
235 The stream will be a compressing stream that produces raw
236 output, using compression level level (if specified)
237 which will be an integer from 0 to 9, and the compression │
238 dictionary bindata (if specified). Note that the raw com‐ │
239 pressed data includes no metadata about what compression │
240 dictionary was used, if any; that is a feature of the │
241 zlib-format data.
242 zlib stream gunzip
244 The stream will be a decompressing stream that takes
245 gzip-format input and produces uncompressed output.
246 zlib stream gzip ?-header header? ?-level level?
248 The stream will be a compressing stream that produces
249 gzip-format output, using compression level level (if
250 specified) which will be an integer from 0 to 9, and the
251 header descriptor dictionary header (if specified; for
252 keys see zlib gzip).
253 zlib stream inflate ?-dictionary bindata?
255 The stream will be a decompressing stream that takes raw
256 compressed input and produces uncompressed output. If │
257 bindata is supplied, it is a compression dictionary to │
258 use. Note that there are no checks in place to determine │
259 whether the compression dictionary is correct.
260 CHECKSUMMING SUBCOMMANDS
262 zlib adler32 string ?initValue?
263 Compute a checksum of binary string string using the Adler-32
264 algorithm. If given, initValue is used to initialize the check‐
265 sum engine.
266 zlib crc32 string ?initValue?
268 Compute a checksum of binary string string using the CRC-32 al‐
269 gorithm. If given, initValue is used to initialize the checksum
270 engine.
271
273 Streaming compression instance commands are produced by the zlib stream
274 command. They are used by calling their put subcommand one or more
275 times to load data in, and their get subcommand one or more times to
276 extract the transformed data.
277 The full set of subcommands supported by a streaming instance command,
279 stream, is as follows:
280 stream add ?option...? data
282 A short-cut for “stream put ?option...? data” followed by
283 “stream get”.
284 stream checksum
286 Returns the checksum of the uncompressed data seen so far by
287 this stream.
288 stream close
290 Deletes this stream and frees up all resources associated with
291 it.
292 stream eof
294 Returns a boolean indicating whether the end of the stream (as
295 determined by the compressed data itself) has been reached. Not
296 all formats support detection of the end of the stream.
297 stream finalize
299 A short-cut for “stream put -finalize {}”.
300 stream flush
302 A short-cut for “stream put -flush {}”.
303 stream fullflush
305 A short-cut for “stream put -fullflush {}”.
306 stream get ?count?
308 Return up to count bytes from stream's internal buffers with the
309 transformation applied. If count is omitted, the entire contents
310 of the buffers are returned. stream header Return the gzip
311 header description dictionary extracted from the stream. Only
312 supported for streams created with their mode parameter set to
313 gunzip.
314 stream put ?option...? data
316 Append the contents of the binary string data to stream's inter‐
317 nal buffers while applying the transformation. The following op‐
318 tions are supported (or an unambiguous prefix of them), which
319 are used to modify the way in which the transformation is ap‐
320 plied:
321 -dictionary binData
323 Sets the compression dictionary to use when working with │
324 compressing or decompressing the data to be binData.
325 -finalize
327 Mark the stream as finished, ensuring that all bytes have
328 been wholly compressed or decompressed. For gzip streams,
329 this also ensures that the footer is written to the
330 stream. The stream will need to be reset before having
331 more data written to it after this, though data can still
332 be read out of the stream with the get subcommand.
333 This option is mutually exclusive with the -flush and
335 -fullflush options.
336 -flush Ensure that a decompressor consuming the bytes that the
338 current (compressing) stream is producing will be able to
339 produce all the bytes that have been compressed so far,
340 at some performance penalty.
341 This option is mutually exclusive with the -finalize and
343 -fullflush options.
344 -fullflush
346 Ensure that not only can a decompressor handle all the
347 bytes produced so far (as with -flush above) but also
348 that it can restart from this point if it detects that
349 the stream is partially corrupt. This incurs a substan‐
350 tial performance penalty.
351 This option is mutually exclusive with the -finalize and
353 -flush options.
354 stream reset
356 Puts any stream, including those that have been finalized or
357 that have reached eof, back into a state where it can process
358 more data. Throws away all internally buffered data.
359
361 To compress a Tcl string, it should be first converted to a particular
362 charset encoding since the zlib command always operates on binary
363 strings.
364 set binData [encoding convertto utf-8 $string]
366 set compData [zlib compress $binData]
367 When converting back, it is also important to reverse the charset en‐
369 coding:
370 set binData [zlib decompress $compData]
372 set string [encoding convertfrom utf-8 $binData]
373 The compression operation from above can also be done with streams,
375 which is especially helpful when you want to accumulate the data by
376 stages:
377 set strm [zlib stream compress]
379 $strm put [encoding convertto utf-8 $string]
380 # ...
381 $strm finalize
382 set compData [$strm get]
383 $strm close
384
386 binary(n), chan(n), encoding(n), Tcl_ZlibDeflate(3), RFC1950 - RFC1952
387
389 compress, decompress, deflate, gzip, inflate, zlib
390Tcl 8.6 zlib(n)