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
79                                             extracted  from  the  stream   is
80                                             appended 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
126                                             decompressing 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
150                                             demanded  by  the format is writ‐
151                                             ten.
152
153       int count (in)                        The maximum number  of  bytes  to
154                                             get from the stream, or -1 to get
155                                             all  remaining  bytes  from   the
156                                             stream's buffers.
157
158       Tcl_Obj *compDict (in)                A  byte  array  value that is the
159                                             compression  dictionary  to   use
160                                             with  the stream.  Note that this
161                                             is not a Tcl dictionary,  and  it
162                                             is  recommended  that  this  only
163                                             ever be used  with  streams  that
164                                             were  created  with  their format
165                                             set    to    TCL_ZLIB_FORMAT_ZLIB
166                                             because the other formats have no
167                                             mechanism to indicate  whether  a
168                                             compression     dictionary    was
169                                             present other  than  to  fail  on
170                                             decompression.
171______________________________________________________________________________
172

DESCRIPTION

174       These  functions  form  the  interface from the Tcl library to the Zlib
175       library by Jean-loup Gailly and Mark Adler.
176
177       Tcl_ZlibDeflate and Tcl_ZlibInflate respectively  compress  and  decom‐
178       press the data contained in the dataObj argument, according to the for‐
179       mat and, for compression, level arguments. The dictionary in  the  dic‐
180       tObj  parameter  is  used to convey additional header information about
181       the compressed data when the compression format supports it; currently,
182       the  dictionary is only used when the format parameter is TCL_ZLIB_FOR‐
183       MAT_GZIP or TCL_ZLIB_FORMAT_AUTO. For details of the  contents  of  the
184       dictionary,  see  the  GZIP OPTIONS DICTIONARY section below. Upon suc‐
185       cess, both functions leave the  resulting  compressed  or  decompressed
186       data  in  a  byte-array value that is the Tcl interpreter's result; the
187       returned value is a standard Tcl result code.
188
189       Tcl_ZlibAdler32 and Tcl_ZlibCRC32 compute checksums on arrays of bytes,
190       returning  the computed checksum. Checksums are computed incrementally,
191       allowing data to be processed one block at a time,  but  this  requires
192       the caller to maintain the current checksum and pass it in as the init‐
193       Value parameter; the initial value to use for this can be  obtained  by
194       using NULL for the bytes parameter instead of a pointer to the array of
195       bytes to compute the checksum over. Thus, typical usage in  the  single
196       data block case is like this:
197
198              checksum = Tcl_ZlibCRC32(Tcl_ZlibCRC32(0,NULL,0), data, length);
199
200       Note that the Adler-32 algorithm is not a real checksum, but instead is
201       a related type of hash that works best on longer data.
202
203   ZLIB STREAMS
204       Tcl_ZlibStreamInit creates a compressing or decompressing  stream  that
205       is linked to a Tcl command, according to its arguments, and provides an
206       abstract token for the stream and returns a  normal  Tcl  result  code;
207       Tcl_ZlibStreamGetCommandName returns the name of that command given the
208       stream token, or NULL if the stream has no  command.  Streams  are  not
209       designed  to  be thread-safe; each stream should only ever be used from
210       the thread that created it. When working with gzip streams,  a  dictio‐
211       nary (fields as given in the GZIP OPTIONS DICTIONARY section below) can
212       be given via the dictObj parameter that on compression  allows  control
213       over  the  generated  headers, and on decompression allows discovery of
214       the existing headers. Note that the dictionary will be  written  to  on
215       decompression  once  sufficient  data  has been read to have a complete
216       header. This means that the dictionary must be  an  unshared  value  in
217       that case; a blank value created with Tcl_NewObj is suggested.
218
219       Once  a  stream  has been constructed, Tcl_ZlibStreamPut is used to add
220       data to the stream and Tcl_ZlibStreamGet is used to retrieve data  from
221       the  stream  after  processing. Both return normal Tcl result codes and
222       leave an error message in the result of the interpreter that the stream
223       is  registered  with in the error case (if such a registration has been
224       performed). With Tcl_ZlibStreamPut, the data buffer value passed to  it
225       should  not  be  modified  afterwards. With Tcl_ZlibStreamGet, the data
226       buffer value passed to it will have the  data  bytes  appended  to  it.
227       Internally to the stream, data is kept compressed so as to minimize the
228       cost of buffer space.
229
230       Tcl_ZlibStreamChecksum returns the checksum computed  over  the  uncom‐
231       pressed  data  according to the format, and Tcl_ZlibStreamEof returns a
232       boolean value indicating whether the end of the uncompressed  data  has
233       been reached.
234
235       Tcl_ZlibStreamSetCompressionDictionary  is used to control the compres‐
236       sion dictionary used with the stream, a compression dictionary being an
237       array of bytes (such as might be created with Tcl_NewByteArrayObj) that
238       is used to initialize the compression engine rather than leaving it  to
239       create it on the fly from the data being compressed. Setting a compres‐
240       sion dictionary allows for more efficient compression in the case where
241       the  start  of the data is highly regular, but it does require both the
242       compressor and the decompressor to agreee on the value to use. Compres‐
243       sion  dictionaries  are  only  fully supported for zlib-format data; on
244       compression, they must be set before any data is sent in with Tcl_Zlib‐
245       StreamPut,  and  on  decompression  they  should  be set when Tcl_Zlib‐
246       StreamGet produces an error with its -errorcode set to “ZLIB  NEED_DICT
247       code”;  the code will be the Adler-32 checksum (see Tcl_ZlibAdler32) of
248       the compression dictionary sought. (Note that this  is  only  true  for
249       zlib-format  streams;  gzip  streams ignore compression dictionaries as
250       the format specification doesn't permit them, and raw streams just pro‐
251       duce  a  data  error if the compression dictionary is missing or incor‐
252       rect.)
253
254       If you wish to clear a stream and reuse it for  a  new  compression  or
255       decompression  action,  Tcl_ZlibStreamReset  will  do this and return a
256       normal Tcl result code to indicate whether it was  successful;  if  the
257       stream is registered with an interpreter, an error message will be left
258       in  the  interpreter  result  when  this  function  returns  TCL_ERROR.
259       Finally,  Tcl_ZlibStreamClose  will  clean up the stream and delete the
260       associated command: using Tcl_DeleteCommand on the stream's command  is
261       equivalent (when such a command exists).
262

GZIP OPTIONS DICTIONARY

264       The dictObj parameter to Tcl_ZlibDeflate, Tcl_ZlibInflate and Tcl_Zlib‐
265       StreamInit is used to pass a dictionary of options about that  is  used
266       to  describe the gzip header in the compressed data. When creating com‐
267       pressed data, the dictionary is read and when unpacking compressed data
268       the  dictionary  is  written  (in which case the dictObj parameter must
269       refer to an unshared dictionary value).
270
271       The following fields in the dictionary value are understood. All  other
272       fields  are  ignored.  No field is required when creating a gzip-format
273       stream.
274
275       comment
276              This holds the comment field  of  the  header,  if  present.  If
277              absent,  no  comment  was supplied (on decompression) or will be
278              created (on compression).
279
280       crc    A boolean value describing whether a CRC of the header  is  com‐
281              puted. Note that the gzip program does not use or allow a CRC on
282              the header.
283
284       filename
285              The name of the file  that  held  the  uncompressed  data.  This
286              should not contain any directory separators, and should be sani‐
287              tized before use on decompression with file tail.
288
289       os     The operating system type code field from the header (if not the
290              “unknown”  value).  See RFC 1952 for the meaning of these codes.
291              On compression, if this is absent then the field will be set  to
292              the “unknown” value.
293
294       size   The  size  of the uncompressed data. This is ignored on compres‐
295              sion; the size of the data compressed depends on how  much  data
296              is supplied to the compression engine.
297
298       time   The  time  field from the header if non-zero, expected to be the
299              time that the file named by the  filename  field  was  modified.
300              Suitable for use with clock format. On creation, the right value
301              to use is that from clock seconds or file mtime.
302
303       type   The type of the uncompressed data (either  binary  or  text)  if
304              known.
305

PORTABILITY NOTES

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

SEE ALSO

311       Tcl_NewByteArrayObj(3), zlib(n)
312

KEYWORDS

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