util/src/TclTk/tcl8.6.12/doc/zlib.n

   1 '\"
   2 '\" Copyright (c) 2008-2012 Donal K. Fellows
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH zlib n 8.6 Tcl "Tcl Built-In Commands"
   8 .so man.macros
   9 .BS
  10 '\" Note:  do not modify the .SH NAME line immediately below!
  11 .SH NAME
  12 zlib \- compression and decompression operations
  13 .SH SYNOPSIS
  14 .nf
  15 \fBzlib \fIsubcommand arg ...\fR
  16 .fi
  17 .BE
  18 .SH DESCRIPTION
  19 .PP
  20 The \fBzlib\fR command provides access to the compression and check-summing
  21 facilities of the Zlib library by Jean-loup Gailly and Mark Adler. It has the
  22 following subcommands.
  23 .SS "COMPRESSION SUBCOMMANDS"
  24 .TP
  25 \fBzlib compress\fI string\fR ?\fIlevel\fR?
  26 .
  27 Returns the zlib-format compressed binary data of the binary string in
  28 \fIstring\fR. If present, \fIlevel\fR gives the compression level to use (from
  29 0, which is uncompressed, to 9, maximally compressed).
  30 .TP
  31 \fBzlib decompress\fI string\fR ?\fIbufferSize\fR?
  32 .
  33 Returns the uncompressed version of the raw compressed binary data in
  34 \fIstring\fR. If present, \fIbufferSize\fR is a hint as to what size of buffer
  35 is to be used to receive the data.
  36 .TP
  37 \fBzlib deflate\fI string\fR ?\fIlevel\fR?
  38 .
  39 Returns the raw compressed binary data of the binary string in \fIstring\fR.
  40 If present, \fIlevel\fR gives the compression level to use (from 0, which is
  41 uncompressed, to 9, maximally compressed).
  42 .TP
  43 \fBzlib gunzip\fI string\fR ?\fB\-headerVar \fIvarName\fR?
  44 .
  45 Return the uncompressed contents of binary string \fIstring\fR, which must
  46 have been in gzip format. If \fB\-headerVar\fR is given, store a dictionary
  47 describing the contents of the gzip header in the variable called
  48 \fIvarName\fR. The keys of the dictionary that may be present are:
  49 .RS
  50 .TP
  51 \fBcomment\fR
  52 .
  53 The comment field from the header, if present.
  54 .TP
  55 \fBcrc\fR
  56 .
  57 A boolean value describing whether a CRC of the header is computed.
  58 .TP
  59 \fBfilename\fR
  60 .
  61 The filename field from the header, if present.
  62 .TP
  63 \fBos\fR
  64 .
  65 The operating system type code field from the header (if not the
  66 QW unknown
  67 value). See RFC 1952 for the meaning of these codes.
  68 .TP
  69 \fBsize\fR
  70 .
  71 The size of the uncompressed data.
  72 .TP
  73 \fBtime\fR
  74 .
  75 The time field from the header if non-zero, expected to be time that the file
  76 named by the \fBfilename\fR field was modified. Suitable for use with
  77 \fBclock format\fR.
  78 .TP
  79 \fBtype\fR
  80 .
  81 The type of the uncompressed data (\fBbinary\fR or \fBtext\fR) if known.
  82 .RE
  83 .TP
  84 \fBzlib gzip\fI string\fR ?\fB\-level \fIlevel\fR? ?\fB\-header \fIdict\fR?
  85 .
  86 Return the compressed contents of binary string \fIstring\fR in gzip format.
  87 If \fB\-level\fR is given, \fIlevel\fR gives the compression level to use
  88 (from 0, which is uncompressed, to 9, maximally compressed). If \fB\-header\fR
  89 is given, \fIdict\fR is a dictionary containing values used for the gzip
  90 header. The following keys may be defined:
  91 .RS
  92 .TP
  93 \fBcomment\fR
  94 .
  95 Add the given comment to the header of the gzip-format data.
  96 .TP
  97 \fBcrc\fR
  98 .
  99 A boolean saying whether to compute a CRC of the header. Note that if the data
 100 is to be interchanged with the \fBgzip\fR program, a header CRC should
 101 \fInot\fR be computed.
 102 .TP
 103 \fBfilename\fR
 104 .
 105 The name of the file that the data to be compressed came from.
 106 .TP
 107 \fBos\fR
 108 .
 109 The operating system type code, which should be one of the values described in
 110 RFC 1952.
 111 .TP
 112 \fBtime\fR
 113 .
 114 The time that the file named in the \fBfilename\fR key was last modified. This
 115 will be in the same as is returned by \fBclock seconds\fR or \fBfile mtime\fR.
 116 .TP
 117 \fBtype\fR
 118 .
 119 The type of the data being compressed, being \fBbinary\fR or \fBtext\fR.
 120 .RE
 121 .TP
 122 \fBzlib inflate\fI string\fR ?\fIbufferSize\fR?
 123 .
 124 Returns the uncompressed version of the raw compressed binary data in
 125 \fIstring\fR. If present, \fIbufferSize\fR is a hint as to what size of buffer
 126 is to be used to receive the data.
 127 .SS "CHANNEL SUBCOMMAND"
 128 .TP
 129 \fBzlib push\fI mode channel\fR ?\fIoptions ...\fR?
 130 .
 131 Pushes a compressing or decompressing transformation onto the channel
 132 \fIchannel\fR.
 133 The transformation can be removed again with \fBchan pop\fR.
 134 The \fImode\fR argument determines what type of transformation
 135 is pushed; the following are supported:
 136 .RS
 137 .TP
 138 \fBcompress\fR
 139 .
 140 The transformation will be a compressing transformation that produces
 141 zlib-format data on \fIchannel\fR, which must be writable.
 142 .TP
 143 \fBdecompress\fR
 144 .
 145 The transformation will be a decompressing transformation that reads
 146 zlib-format data from \fIchannel\fR, which must be readable.
 147 .TP
 148 \fBdeflate\fR
 149 .
 150 The transformation will be a compressing transformation that produces raw
 151 compressed data on \fIchannel\fR, which must be writable.
 152 .TP
 153 \fBgunzip\fR
 154 .
 155 The transformation will be a decompressing transformation that reads
 156 gzip-format data from \fIchannel\fR, which must be readable.
 157 .TP
 158 \fBgzip\fR
 159 .
 160 The transformation will be a compressing transformation that produces
 161 gzip-format data on \fIchannel\fR, which must be writable.
 162 .TP
 163 \fBinflate\fR
 164 .
 165 The transformation will be a decompressing transformation that reads raw
 166 compressed data from \fIchannel\fR, which must be readable.
 167 .PP
 168 The following options may be set when creating a transformation via
 169 the
 170 .QW "\fIoptions ...\fR"
 171 to the \fBzlib push\fR command:
 172 .TP
 173 \fB\-dictionary\fI binData\fR
 174 .VS "TIP 400"
 175 Sets the compression dictionary to use when working with compressing or
 176 decompressing the data to be \fIbinData\fR. Not valid for transformations that
 177 work with gzip-format data.  The dictionary should consist of strings (byte
 178 sequences) that are likely to be encountered later in the data to be compressed,
 179 with the most commonly used strings preferably put towards the end of the
 180 dictionary. Tcl provides no mechanism for choosing a good such dictionary for
 181 a particular data sequence.
 182 .VE
 183 .TP
 184 \fB\-header\fI dictionary\fR
 185 .
 186 Passes a description of the gzip header to create, in the same format that
 187 \fBzlib gzip\fR understands.
 188 .TP
 189 \fB\-level\fI compressionLevel\fR
 190 .
 191 How hard to compress the data. Must be an integer from 0 (uncompressed) to 9
 192 (maximally compressed).
 193 .TP
 194 \fB\-limit\fI readaheadLimit\fR
 195 .
 196 The maximum number of bytes ahead to read when decompressing.
 197 .RS
 198 .PP
 199 This option has become \fBirrelevant\fR. It was originally introduced
 200 to prevent Tcl from reading beyond the end of a compressed stream in
 201 multi-stream channels to ensure that the data after was left alone for
 202 further reading, at the cost of speed.
 203 .PP
 204 Tcl now automatically returns any bytes it has read beyond the end of
 205 a compressed stream back to the channel, making them appear as unread
 206 to further readers.
 207 .RE
 208 .PP
 209 Both compressing and decompressing channel transformations add extra
 210 configuration options that may be accessed through \fBchan configure\fR. The
 211 options are:
 212 .TP
 213 \fB\-checksum\fI checksum\fR
 214 .
 215 This read-only option gets the current checksum for the uncompressed data that
 216 the compression engine has seen so far. It is valid for both compressing and
 217 decompressing transforms, but not for the raw inflate and deflate formats. The
 218 compression algorithm depends on what format is being produced or consumed.
 219 .TP
 220 \fB\-dictionary\fI binData\fR
 221 .VS "TIP 400"
 222 This read-write options gets or sets the initial compression dictionary to use
 223 when working with compressing or decompressing the data to be \fIbinData\fR.
 224 It is not valid for transformations that work with gzip-format data, and should
 225 not normally be set on compressing transformations other than at the point where
 226 the transformation is stacked. Note that this cannot be used to get the
 227 current active compression dictionary mid-stream, as that information is not
 228 exposed by the underlying library.
 229 .VE
 230 .TP
 231 \fB\-flush\fI type\fR
 232 .
 233 This write-only operation flushes the current state of the compressor to the
 234 underlying channel. It is only valid for compressing transformations. The
 235 \fItype\fR must be either \fBsync\fR or \fBfull\fR for a normal flush or an
 236 expensive flush respectively. Flushing degrades the compression ratio, but
 237 makes it easier for a decompressor to recover more of the file in the case of
 238 data corruption.
 239 .TP
 240 \fB\-header\fI dictionary\fR
 241 .
 242 This read-only option, only valid for decompressing transforms that are
 243 processing gzip-format data, returns the dictionary describing the header read
 244 off the data stream.
 245 .TP
 246 \fB\-limit\fI readaheadLimit\fR
 247 .
 248 This read-write option is used by decompressing channels to control the
 249 maximum number of bytes ahead to read from the underlying data source. See
 250 above for more information.
 251 .RE
 252 .SS "STREAMING SUBCOMMAND"
 253 .TP
 254 \fBzlib stream\fI mode\fR ?\fIoptions\fR?
 255 .
 256 Creates a streaming compression or decompression command based on the
 257 \fImode\fR, and return the name of the command. For a description of how that
 258 command works, see \fBSTREAMING INSTANCE COMMAND\fR below. The following modes
 259 and \fIoptions\fR are supported:
 260 .RS
 261 .TP
 262 \fBzlib stream compress\fR ?\fB\-dictionary \fIbindata\fR? ?\fB\-level \fIlevel\fR?
 263 .
 264 The stream will be a compressing stream that produces zlib-format output,
 265 using compression level \fIlevel\fR (if specified) which will be an integer
 266 from 0 to 9,
 267 .VS "TIP 400"
 268 and the compression dictionary \fIbindata\fR (if specified).
 269 .VE
 270 .TP
 271 \fBzlib stream decompress\fR ?\fB\-dictionary \fIbindata\fR?
 272 .
 273 The stream will be a decompressing stream that takes zlib-format input and
 274 produces uncompressed output.
 275 .VS "TIP 400"
 276 If \fIbindata\fR is supplied, it is a compression dictionary to use if
 277 required.
 278 .VE
 279 .TP
 280 \fBzlib stream deflate\fR ?\fB\-dictionary \fIbindata\fR? ?\fB\-level \fIlevel\fR?
 281 .
 282 The stream will be a compressing stream that produces raw output, using
 283 compression level \fIlevel\fR (if specified) which will be an integer from 0
 284 to 9,
 285 .VS "TIP 400"
 286 and the compression dictionary \fIbindata\fR (if specified). Note that
 287 the raw compressed data includes no metadata about what compression
 288 dictionary was used, if any; that is a feature of the zlib-format data.
 289 .VE
 290 .TP
 291 \fBzlib stream gunzip\fR
 292 .
 293 The stream will be a decompressing stream that takes gzip-format input and
 294 produces uncompressed output.
 295 .TP
 296 \fBzlib stream gzip\fR ?\fB\-header \fIheader\fR? ?\fB\-level \fIlevel\fR?
 297 .
 298 The stream will be a compressing stream that produces gzip-format output,
 299 using compression level \fIlevel\fR (if specified) which will be an integer
 300 from 0 to 9, and the header descriptor dictionary \fIheader\fR (if specified;
 301 for keys see \fBzlib gzip\fR).
 302 .TP
 303 \fBzlib stream inflate\fR ?\fB\-dictionary \fIbindata\fR?
 304 .
 305 The stream will be a decompressing stream that takes raw compressed input and
 306 produces uncompressed output.
 307 .VS "TIP 400"
 308 If \fIbindata\fR is supplied, it is a compression dictionary to use. Note that
 309 there are no checks in place to determine whether the compression dictionary
 310 is correct.
 311 .VE
 312 .RE
 313 .SS "CHECKSUMMING SUBCOMMANDS"
 314 .TP
 315 \fBzlib adler32\fI string\fR ?\fIinitValue\fR?
 316 .
 317 Compute a checksum of binary string \fIstring\fR using the Adler-32 algorithm.
 318 If given, \fIinitValue\fR is used to initialize the checksum engine.
 319 .TP
 320 \fBzlib crc32\fI string\fR ?\fIinitValue\fR?
 321 .
 322 Compute a checksum of binary string \fIstring\fR using the CRC-32 algorithm.
 323 If given, \fIinitValue\fR is used to initialize the checksum engine.
 324 .SH "STREAMING INSTANCE COMMAND"
 325 .PP
 326 Streaming compression instance commands are produced by the \fBzlib stream\fR
 327 command. They are used by calling their \fBput\fR subcommand one or more times
 328 to load data in, and their \fBget\fR subcommand one or more times to extract
 329 the transformed data.
 330 .PP
 331 The full set of subcommands supported by a streaming instance command,
 332 \fIstream\fR, is as follows:
 333 .TP
 334 \fIstream \fBadd\fR ?\fIoption...\fR? \fIdata\fR
 335 .
 336 A short-cut for
 337 .QW "\fIstream \fBput \fR?\fIoption...\fR? \fIdata\fR"
 338 followed by
 339 .QW "\fIstream \fBget\fR" .
 340 .TP
 341 \fIstream \fBchecksum\fR
 342 .
 343 Returns the checksum of the uncompressed data seen so far by this stream.
 344 .TP
 345 \fIstream \fBclose\fR
 346 .
 347 Deletes this stream and frees up all resources associated with it.
 348 .TP
 349 \fIstream \fBeof\fR
 350 .
 351 Returns a boolean indicating whether the end of the stream (as determined by
 352 the compressed data itself) has been reached. Not all formats support
 353 detection of the end of the stream.
 354 .TP
 355 \fIstream \fBfinalize\fR
 356 .
 357 A short-cut for
 358 .QW "\fIstream \fBput \-finalize {}\fR" .
 359 .TP
 360 \fIstream \fBflush\fR
 361 .
 362 A short-cut for
 363 .QW "\fIstream \fBput \-flush {}\fR" .
 364 .TP
 365 \fIstream \fBfullflush\fR
 366 .
 367 A short-cut for
 368 .QW "\fIstream \fBput \-fullflush {}\fR" .
 369 .TP
 370 \fIstream \fBget \fR?\fIcount\fR?
 371 .
 372 Return up to \fIcount\fR bytes from \fIstream\fR's internal buffers with the
 373 transformation applied. If \fIcount\fR is omitted, the entire contents of the
 374 buffers are returned.
 375 .
 376 \fIstream \fBheader\fR
 377 .
 378 Return the gzip header description dictionary extracted from the stream. Only
 379 supported for streams created with their \fImode\fR parameter set to
 380 \fBgunzip\fR.
 381 .TP
 382 \fIstream \fBput\fR ?\fIoption...\fR? \fIdata\fR
 383 .
 384 Append the contents of the binary string \fIdata\fR to \fIstream\fR's internal
 385 buffers while applying the transformation. The following \fIoption\fRs are
 386 supported (or an unambiguous prefix of them), which are used to modify the
 387 way in which the transformation is applied:
 388 .RS
 389 .TP
 390 \fB\-dictionary\fI binData\fR
 391 .VS "TIP 400"
 392 Sets the compression dictionary to use when working with compressing or
 393 decompressing the data to be \fIbinData\fR.
 394 .VE
 395 .TP
 396 \fB\-finalize\fR
 397 .
 398 Mark the stream as finished, ensuring that all bytes have been wholly
 399 compressed or decompressed. For gzip streams, this also ensures that the
 400 footer is written to the stream. The stream will need to be reset before
 401 having more data written to it after this, though data can still be read out
 402 of the stream with the \fBget\fR subcommand.
 403 .RS
 404 .PP
 405 This option is mutually exclusive with the \fB\-flush\fR and \fB\-fullflush\fR
 406 options.
 407 .RE
 408 .TP
 409 \fB\-flush\fR
 410 .
 411 Ensure that a decompressor consuming the bytes that the current (compressing)
 412 stream is producing will be able to produce all the bytes that have been
 413 compressed so far, at some performance penalty.
 414 .RS
 415 .PP
 416 This option is mutually exclusive with the \fB\-finalize\fR and
 417 \fB\-fullflush\fR options.
 418 .RE
 419 .TP
 420 \fB\-fullflush\fR
 421 .
 422 Ensure that not only can a decompressor handle all the bytes produced so far
 423 (as with \fB\-flush\fR above) but also that it can restart from this point if
 424 it detects that the stream is partially corrupt. This incurs a substantial
 425 performance penalty.
 426 .RS
 427 .PP
 428 This option is mutually exclusive with the \fB\-finalize\fR and \fB\-flush\fR
 429 options.
 430 .RE
 431 .RE
 432 .TP
 433 \fIstream \fBreset\fR
 434 .
 435 Puts any stream, including those that have been finalized or that have reached
 436 eof, back into a state where it can process more data. Throws away all
 437 internally buffered data.
 438 .SH EXAMPLES
 439 .PP
 440 To compress a Tcl string, it should be first converted to a particular charset
 441 encoding since the \fBzlib\fR command always operates on binary strings.
 442 .PP
 443 .CS
 444 set binData [encoding convertto utf-8 $string]
 445 set compData [\fBzlib compress\fR $binData]
 446 .CE
 447 .PP
 448 When converting back, it is also important to reverse the charset encoding:
 449 .PP
 450 .CS
 451 set binData [\fBzlib decompress\fR $compData]
 452 set string [encoding convertfrom utf-8 $binData]
 453 .CE
 454 .PP
 455 The compression operation from above can also be done with streams, which is
 456 especially helpful when you want to accumulate the data by stages:
 457 .PP
 458 .CS
 459 set strm [\fBzlib stream\fR compress]
 460 $\fIstrm \fBput\fR [encoding convertto utf-8 $string]
 461 # ...
 462 $\fIstrm \fBfinalize\fR
 463 set compData [$\fIstrm \fBget\fR]
 464 $\fIstrm \fBclose\fR
 465 .CE
 466 .SH "SEE ALSO"
 467 binary(n), chan(n), encoding(n), Tcl_ZlibDeflate(3), RFC1950 \- RFC1952
 468 .SH "KEYWORDS"
 469 compress, decompress, deflate, gzip, inflate, zlib
 470 '\" Local Variables:
 471 '\" mode: nroff
 472 '\" End: