1TclZlib(3)                  Tcl Library Procedures                  TclZlib(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

14       #include <tcl.h>
15
16       int
17       Tcl_ZlibDeflate(interp, format, dataObj, level, dictObj)
18
19       int
20       Tcl_ZlibInflate(interp, format, dataObj, dictObj)
21
22       unsigned int
23       Tcl_ZlibCRC32(initValue, bytes, length)
24
25       unsigned int
26       Tcl_ZlibAdler32(initValue, bytes, length)
27
28       int
29       Tcl_ZlibStreamInit(interp, mode, format, level, dictObj, zshandlePtr)
30
31       Tcl_Obj *
32       Tcl_ZlibStreamGetCommandName(zshandle)
33
34       int
35       Tcl_ZlibStreamEof(zshandle)
36
37       int
38       Tcl_ZlibStreamClose(zshandle)
39
40       int
41       Tcl_ZlibStreamReset(zshandle)
42
43       int
44       Tcl_ZlibStreamChecksum(zshandle)
45
46       int
47       Tcl_ZlibStreamPut(zshandle, dataObj, flush)
48
49       int
50       Tcl_ZlibStreamGet(zshandle, dataObj, count)
51
52       Tcl_ZlibStreamSetCompressionDictionary(zshandle, compDict)
53

ARGUMENTS

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
63       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
76       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
83       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
95       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
111       unsigned int initValue (in)           The initial value for the  check‐
112                                             sum algorithm.
113
114       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
119       int length (in)                       The number of bytes in the array.
120
121       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
128       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
133       Tcl_ZlibStream zshandle (in)          The abstract token for the stream
134                                             to operate on.
135
136       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
152       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
157       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

DESCRIPTION

173       These functions form the interface from the Tcl library to the Zlib li‐
174       brary by Jean-loup Gailly and Mark Adler.
175
176       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
188       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
197              checksum = Tcl_ZlibCRC32(Tcl_ZlibCRC32(0,NULL,0), data, length);
198
199       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
202   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
218       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
229       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
234       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
253       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

GZIP OPTIONS DICTIONARY

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
270       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
274       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
279       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
283       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
288       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
293       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
297       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
302       type   The  type  of  the  uncompressed data (either binary or text) if
303              known.
304

PORTABILITY NOTES

306       These functions will fail gracefully if Tcl is not linked with the zlib
307       library.
308

SEE ALSO

310       Tcl_NewByteArrayObj(3), zlib(n)
311

KEYWORDS

313       compress, decompress, deflate, gzip, inflate
314
315
316
317Tcl                                   8.6                           TclZlib(3)
Impressum