1TclZlib(3) Tcl Library Procedures TclZlib(3)
2______________________________________________________________________________
6
8 Tcl_ZlibAdler32, Tcl_ZlibCRC32, Tcl_ZlibDeflate, Tcl_ZlibInflate,
9 Tcl_ZlibStreamChecksum, Tcl_ZlibStreamClose, Tcl_ZlibStreamEof,
10 Tcl_ZlibStreamGet, Tcl_ZlibStreamGetCommandName, Tcl_ZlibStreamInit,
11 Tcl_ZlibStreamPut - compression and decompression functions
12
14 #include <tcl.h>
15 int
17 Tcl_ZlibDeflate(interp, format, dataObj, level, dictObj)
18 int
20 Tcl_ZlibInflate(interp, format, dataObj, dictObj)
21 unsigned int
23 Tcl_ZlibCRC32(initValue, bytes, length)
24 unsigned int
26 Tcl_ZlibAdler32(initValue, bytes, length)
27 int
29 Tcl_ZlibStreamInit(interp, mode, format, level, dictObj, zshandlePtr)
30 Tcl_Obj *
32 Tcl_ZlibStreamGetCommandName(zshandle)
33 int
35 Tcl_ZlibStreamEof(zshandle)
36 int
38 Tcl_ZlibStreamClose(zshandle)
39 int
41 Tcl_ZlibStreamReset(zshandle)
42 int
44 Tcl_ZlibStreamChecksum(zshandle)
45 int
47 Tcl_ZlibStreamPut(zshandle, dataObj, flush)
48 int
50 Tcl_ZlibStreamGet(zshandle, dataObj, count)
51 Tcl_ZlibStreamSetCompressionDictionary(zshandle, compDict)
53
55 Tcl_Interp *interp (in) The interpreter to store result‐
56 ing compressed or uncompressed
57 data in. Also where any error
58 messages are written. For
59 Tcl_ZlibStreamInit, this can be
60 NULL to create a stream that is
61 not bound to a command.
62 int format (in) What format of compressed data to
64 work with. Must be one of
65 TCL_ZLIB_FORMAT_ZLIB for zlib-
66 format data, TCL_ZLIB_FORMAT_GZIP
67 for gzip-format data, or
68 TCL_ZLIB_FORMAT_RAW for raw com‐
69 pressed data. In addition, for
70 decompression only, TCL_ZLIB_FOR‐
71 MAT_AUTO may also be chosen which
72 can automatically detect whether
73 the compressed data was in zlib
74 or gzip format.
75 Tcl_Obj *dataObj (in/out) A byte-array value containing the
77 data to be compressed or decom‐
78 pressed, or to which the data ex‐
79 tracted from the stream is ap‐
80 pended when passed to Tcl_Zlib‐
81 StreamGet.
82 int level (in) What level of compression to use.
84 Should be a number from 0 to 9 or
85 one of the following:
86 TCL_ZLIB_COMPRESS_NONE for no
87 compression, TCL_ZLIB_COM‐
88 PRESS_FAST for fast but ineffi‐
89 cient compression, TCL_ZLIB_COM‐
90 PRESS_BEST for slow but maximal
91 compression, or TCL_ZLIB_COM‐
92 PRESS_DEFAULT for the level rec‐
93 ommended by the zlib library.
94 Tcl_Obj *dictObj (in/out) A dictionary that contains, or
96 which will be updated to contain,
97 a description of the gzip header
98 associated with the compressed
99 data. Only useful when the format
100 is TCL_ZLIB_FORMAT_GZIP or
101 TCL_ZLIB_FORMAT_AUTO. If a NULL
102 is passed, a default header will
103 be used on compression and the
104 header will be ignored (apart
105 from integrity checks) on decom‐
106 pression. See the section GZIP
107 OPTIONS DICTIONARY for details
108 about the contents of this dic‐
109 tionary.
110 unsigned int initValue (in) The initial value for the check‐
112 sum algorithm.
113 unsigned char *bytes (in) An array of bytes to run the
115 checksum algorithm over, or NULL
116 to get the recommended initial
117 value for the checksum algorithm.
118 int length (in) The number of bytes in the array.
120 int mode (in) What mode to operate the stream
122 in. Should be either
123 TCL_ZLIB_STREAM_DEFLATE for a
124 compressing stream or
125 TCL_ZLIB_STREAM_INFLATE for a de‐
126 compressing stream.
127 Tcl_ZlibStream *zshandlePtr (out) A pointer to a variable in which
129 to write the abstract token for
130 the stream upon successful cre‐
131 ation.
132 Tcl_ZlibStream zshandle (in) The abstract token for the stream
134 to operate on.
135 int flush (in) Whether and how to flush the
137 stream after writing the data to
138 it. Must be one of:
139 TCL_ZLIB_NO_FLUSH if no flushing
140 is to be done, TCL_ZLIB_FLUSH if
141 the currently compressed data
142 must be made available for access
143 using Tcl_ZlibStreamGet,
144 TCL_ZLIB_FULLFLUSH if the stream
145 must be put into a state where
146 the decompressor can recover from
147 on corruption, or TCL_ZLIB_FINAL‐
148 IZE to ensure that the stream is
149 finished and that any trailer de‐
150 manded by the format is written.
151 int count (in) The maximum number of bytes to
153 get from the stream, or -1 to get
154 all remaining bytes from the
155 stream's buffers.
156 Tcl_Obj *compDict (in) A byte array value that is the
158 compression dictionary to use
159 with the stream. Note that this
160 is not a Tcl dictionary, and it
161 is recommended that this only
162 ever be used with streams that
163 were created with their format
164 set to TCL_ZLIB_FORMAT_ZLIB be‐
165 cause the other formats have no
166 mechanism to indicate whether a
167 compression dictionary was
168 present other than to fail on de‐
169 compression.
170______________________________________________________________________________
171
173 These functions form the interface from the Tcl library to the Zlib li‐
174 brary by Jean-loup Gailly and Mark Adler.
175 Tcl_ZlibDeflate and Tcl_ZlibInflate respectively compress and decom‐
177 press the data contained in the dataObj argument, according to the for‐
178 mat and, for compression, level arguments. The dictionary in the dic‐
179 tObj parameter is used to convey additional header information about
180 the compressed data when the compression format supports it; currently,
181 the dictionary is only used when the format parameter is TCL_ZLIB_FOR‐
182 MAT_GZIP or TCL_ZLIB_FORMAT_AUTO. For details of the contents of the
183 dictionary, see the GZIP OPTIONS DICTIONARY section below. Upon suc‐
184 cess, both functions leave the resulting compressed or decompressed
185 data in a byte-array value that is the Tcl interpreter's result; the
186 returned value is a standard Tcl result code.
187 Tcl_ZlibAdler32 and Tcl_ZlibCRC32 compute checksums on arrays of bytes,
189 returning the computed checksum. Checksums are computed incrementally,
190 allowing data to be processed one block at a time, but this requires
191 the caller to maintain the current checksum and pass it in as the init‐
192 Value parameter; the initial value to use for this can be obtained by
193 using NULL for the bytes parameter instead of a pointer to the array of
194 bytes to compute the checksum over. Thus, typical usage in the single
195 data block case is like this:
196 checksum = Tcl_ZlibCRC32(Tcl_ZlibCRC32(0,NULL,0), data, length);
198 Note that the Adler-32 algorithm is not a real checksum, but instead is
200 a related type of hash that works best on longer data.
201 ZLIB STREAMS
203 Tcl_ZlibStreamInit creates a compressing or decompressing stream that
204 is linked to a Tcl command, according to its arguments, and provides an
205 abstract token for the stream and returns a normal Tcl result code;
206 Tcl_ZlibStreamGetCommandName returns the name of that command given the
207 stream token, or NULL if the stream has no command. Streams are not de‐
208 signed to be thread-safe; each stream should only ever be used from the
209 thread that created it. When working with gzip streams, a dictionary
210 (fields as given in the GZIP OPTIONS DICTIONARY section below) can be
211 given via the dictObj parameter that on compression allows control over
212 the generated headers, and on decompression allows discovery of the ex‐
213 isting headers. Note that the dictionary will be written to on decom‐
214 pression once sufficient data has been read to have a complete header.
215 This means that the dictionary must be an unshared value in that case;
216 a blank value created with Tcl_NewObj is suggested.
217 Once a stream has been constructed, Tcl_ZlibStreamPut is used to add
219 data to the stream and Tcl_ZlibStreamGet is used to retrieve data from
220 the stream after processing. Both return normal Tcl result codes and
221 leave an error message in the result of the interpreter that the stream
222 is registered with in the error case (if such a registration has been
223 performed). With Tcl_ZlibStreamPut, the data buffer value passed to it
224 should not be modified afterwards. With Tcl_ZlibStreamGet, the data
225 buffer value passed to it will have the data bytes appended to it. In‐
226 ternally to the stream, data is kept compressed so as to minimize the
227 cost of buffer space.
228 Tcl_ZlibStreamChecksum returns the checksum computed over the uncom‐
230 pressed data according to the format, and Tcl_ZlibStreamEof returns a
231 boolean value indicating whether the end of the uncompressed data has
232 been reached.
233 Tcl_ZlibStreamSetCompressionDictionary is used to control the compres‐
235 sion dictionary used with the stream, a compression dictionary being an
236 array of bytes (such as might be created with Tcl_NewByteArrayObj) that
237 is used to initialize the compression engine rather than leaving it to
238 create it on the fly from the data being compressed. Setting a compres‐
239 sion dictionary allows for more efficient compression in the case where
240 the start of the data is highly regular, but it does require both the
241 compressor and the decompressor to agreee on the value to use. Compres‐
242 sion dictionaries are only fully supported for zlib-format data; on
243 compression, they must be set before any data is sent in with Tcl_Zlib‐
244 StreamPut, and on decompression they should be set when Tcl_Zlib‐
245 StreamGet produces an error with its -errorcode set to “ZLIB NEED_DICT
246 code”; the code will be the Adler-32 checksum (see Tcl_ZlibAdler32) of
247 the compression dictionary sought. (Note that this is only true for
248 zlib-format streams; gzip streams ignore compression dictionaries as
249 the format specification doesn't permit them, and raw streams just pro‐
250 duce a data error if the compression dictionary is missing or incor‐
251 rect.)
252 If you wish to clear a stream and reuse it for a new compression or de‐
254 compression action, Tcl_ZlibStreamReset will do this and return a nor‐
255 mal Tcl result code to indicate whether it was successful; if the
256 stream is registered with an interpreter, an error message will be left
257 in the interpreter result when this function returns TCL_ERROR. Fi‐
258 nally, Tcl_ZlibStreamClose will clean up the stream and delete the as‐
259 sociated command: using Tcl_DeleteCommand on the stream's command is
260 equivalent (when such a command exists).
261
263 The dictObj parameter to Tcl_ZlibDeflate, Tcl_ZlibInflate and Tcl_Zlib‐
264 StreamInit is used to pass a dictionary of options about that is used
265 to describe the gzip header in the compressed data. When creating com‐
266 pressed data, the dictionary is read and when unpacking compressed data
267 the dictionary is written (in which case the dictObj parameter must re‐
268 fer to an unshared dictionary value).
269 The following fields in the dictionary value are understood. All other
271 fields are ignored. No field is required when creating a gzip-format
272 stream.
273 comment
275 This holds the comment field of the header, if present. If ab‐
276 sent, no comment was supplied (on decompression) or will be cre‐
277 ated (on compression).
278 crc A boolean value describing whether a CRC of the header is com‐
280 puted. Note that the gzip program does not use or allow a CRC on
281 the header.
282 filename
284 The name of the file that held the uncompressed data. This
285 should not contain any directory separators, and should be sani‐
286 tized before use on decompression with file tail.
287 os The operating system type code field from the header (if not the
289 “unknown” value). See RFC 1952 for the meaning of these codes.
290 On compression, if this is absent then the field will be set to
291 the “unknown” value.
292 size The size of the uncompressed data. This is ignored on compres‐
294 sion; the size of the data compressed depends on how much data
295 is supplied to the compression engine.
296 time The time field from the header if non-zero, expected to be the
298 time that the file named by the filename field was modified.
299 Suitable for use with clock format. On creation, the right value
300 to use is that from clock seconds or file mtime.
301 type The type of the uncompressed data (either binary or text) if
303 known.
304
306 These functions will fail gracefully if Tcl is not linked with the zlib
307 library.
308
310 Tcl_NewByteArrayObj(3), zlib(n)
311
313 compress, decompress, deflate, gzip, inflate
314Tcl 8.6 TclZlib(3)