2 '\" Copyright (c) 2008 Donal K. Fellows
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH TclZlib 3 8.6 Tcl "Tcl Library Procedures"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
11 .\" .AP type name in/out ?indent?
12 .\" Start paragraph describing an argument to a library procedure.
13 .\" type is type of argument (int, etc.), in/out is either "in", "out",
14 .\" or "in/out" to describe whether procedure reads or modifies arg,
15 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 .\" needed; use .AS below instead)
19 .\" Give maximum sizes of arguments for setting tab stops. Type and
20 .\" name are examples of largest possible arguments that will be passed
21 .\" to .AP later. If args are omitted, default tab stops are used.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
36 .\" .VS ?version? ?br?
37 .\" Begin vertical sidebar, for use in marking newly-changed parts
38 .\" of man pages. The first argument is ignored and used for recording
39 .\" the version when the .VS was added, so that the sidebars can be
40 .\" found and removed when they reach a certain age. If another argument
41 .\" is present, then a line break is forced before starting the sidebar.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
59 .\" End of list of standard options for a Tk widget.
61 .\" .OP cmdName dbName dbClass
62 .\" Start of description of a specific option. cmdName gives the
63 .\" option's name as specified in the class command, dbName gives
64 .\" the option's name in the option database, and dbClass gives
65 .\" the option's class in the option database.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
276 '\" Note: do not modify the .SH NAME line immediately below!
278 Tcl_ZlibAdler32, Tcl_ZlibCRC32, Tcl_ZlibDeflate, Tcl_ZlibInflate, Tcl_ZlibStreamChecksum, Tcl_ZlibStreamClose, Tcl_ZlibStreamEof, Tcl_ZlibStreamGet, Tcl_ZlibStreamGetCommandName, Tcl_ZlibStreamInit, Tcl_ZlibStreamPut \- compression and decompression functions
284 \fBTcl_ZlibDeflate\fR(\fIinterp, format, dataObj, level, dictObj\fR)
287 \fBTcl_ZlibInflate\fR(\fIinterp, format, dataObj, dictObj\fR)
290 \fBTcl_ZlibCRC32\fR(\fIinitValue, bytes, length\fR)
293 \fBTcl_ZlibAdler32\fR(\fIinitValue, bytes, length\fR)
296 \fBTcl_ZlibStreamInit\fR(\fIinterp, mode, format, level, dictObj, zshandlePtr\fR)
299 \fBTcl_ZlibStreamGetCommandName\fR(\fIzshandle\fR)
302 \fBTcl_ZlibStreamEof\fR(\fIzshandle\fR)
305 \fBTcl_ZlibStreamClose\fR(\fIzshandle\fR)
308 \fBTcl_ZlibStreamReset\fR(\fIzshandle\fR)
311 \fBTcl_ZlibStreamChecksum\fR(\fIzshandle\fR)
314 \fBTcl_ZlibStreamPut\fR(\fIzshandle, dataObj, flush\fR)
317 \fBTcl_ZlibStreamGet\fR(\fIzshandle, dataObj, count\fR)
319 \fBTcl_ZlibStreamSetCompressionDictionary\fR(\fIzshandle, compDict\fR)
322 .AS Tcl_ZlibStream zshandle in
323 .AP Tcl_Interp *interp in
324 The interpreter to store resulting compressed or uncompressed data in. Also
325 where any error messages are written. For \fBTcl_ZlibStreamInit\fR, this can
326 be NULL to create a stream that is not bound to a command.
328 What format of compressed data to work with. Must be one of
329 \fBTCL_ZLIB_FORMAT_ZLIB\fR for zlib-format data, \fBTCL_ZLIB_FORMAT_GZIP\fR
330 for gzip-format data, or \fBTCL_ZLIB_FORMAT_RAW\fR for raw compressed data. In
331 addition, for decompression only, \fBTCL_ZLIB_FORMAT_AUTO\fR may also be
332 chosen which can automatically detect whether the compressed data was in zlib
334 .AP Tcl_Obj *dataObj in/out
335 A byte-array value containing the data to be compressed or decompressed, or
336 to which the data extracted from the stream is appended when passed to
337 \fBTcl_ZlibStreamGet\fR.
339 What level of compression to use. Should be a number from 0 to 9 or one of the
340 following: \fBTCL_ZLIB_COMPRESS_NONE\fR for no compression,
341 \fBTCL_ZLIB_COMPRESS_FAST\fR for fast but inefficient compression,
342 \fBTCL_ZLIB_COMPRESS_BEST\fR for slow but maximal compression, or
343 \fBTCL_ZLIB_COMPRESS_DEFAULT\fR for the level recommended by the zlib library.
344 .AP Tcl_Obj *dictObj in/out
345 A dictionary that contains, or which will be updated to contain, a description
346 of the gzip header associated with the compressed data. Only useful when the
347 \fIformat\fR is \fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. If
348 a NULL is passed, a default header will be used on compression and the header
349 will be ignored (apart from integrity checks) on decompression. See the
350 section \fBGZIP OPTIONS DICTIONARY\fR for details about the contents of this
352 .AP "unsigned int" initValue in
353 The initial value for the checksum algorithm.
354 .AP "unsigned char" *bytes in
355 An array of bytes to run the checksum algorithm over, or NULL to get the
356 recommended initial value for the checksum algorithm.
358 The number of bytes in the array.
360 What mode to operate the stream in. Should be either
361 \fBTCL_ZLIB_STREAM_DEFLATE\fR for a compressing stream or
362 \fBTCL_ZLIB_STREAM_INFLATE\fR for a decompressing stream.
363 .AP Tcl_ZlibStream *zshandlePtr out
364 A pointer to a variable in which to write the abstract token for the stream
365 upon successful creation.
366 .AP Tcl_ZlibStream zshandle in
367 The abstract token for the stream to operate on.
369 Whether and how to flush the stream after writing the data to it. Must be one
370 of: \fBTCL_ZLIB_NO_FLUSH\fR if no flushing is to be done, \fBTCL_ZLIB_FLUSH\fR
371 if the currently compressed data must be made available for access using
372 \fBTcl_ZlibStreamGet\fR, \fBTCL_ZLIB_FULLFLUSH\fR if the stream must be put
373 into a state where the decompressor can recover from on corruption, or
374 \fBTCL_ZLIB_FINALIZE\fR to ensure that the stream is finished and that any
375 trailer demanded by the format is written.
377 The maximum number of bytes to get from the stream, or -1 to get all remaining
378 bytes from the stream's buffers.
379 .AP Tcl_Obj *compDict in
380 A byte array value that is the compression dictionary to use with the stream.
381 Note that this is \fInot a Tcl dictionary\fR, and it is recommended that this
382 only ever be used with streams that were created with their \fIformat\fR set
383 to \fBTCL_ZLIB_FORMAT_ZLIB\fR because the other formats have no mechanism to
384 indicate whether a compression dictionary was present other than to fail on
388 These functions form the interface from the Tcl library to the Zlib
389 library by Jean-loup Gailly and Mark Adler.
391 \fBTcl_ZlibDeflate\fR and \fBTcl_ZlibInflate\fR respectively compress and
392 decompress the data contained in the \fIdataObj\fR argument, according to the
393 \fIformat\fR and, for compression, \fIlevel\fR arguments. The dictionary in
394 the \fIdictObj\fR parameter is used to convey additional header information
395 about the compressed data when the compression format supports it; currently,
396 the dictionary is only used when the \fIformat\fR parameter is
397 \fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. For details of the
398 contents of the dictionary, see the \fBGZIP OPTIONS DICTIONARY\fR section
399 below. Upon success, both functions leave the resulting compressed or
400 decompressed data in a byte-array value that is the Tcl interpreter's result;
401 the returned value is a standard Tcl result code.
403 \fBTcl_ZlibAdler32\fR and \fBTcl_ZlibCRC32\fR compute checksums on arrays of
404 bytes, returning the computed checksum. Checksums are computed incrementally,
405 allowing data to be processed one block at a time, but this requires the
406 caller to maintain the current checksum and pass it in as the \fIinitValue\fR
407 parameter; the initial value to use for this can be obtained by using NULL for
408 the \fIbytes\fR parameter instead of a pointer to the array of bytes to
409 compute the checksum over. Thus, typical usage in the single data block case
413 checksum = \fBTcl_ZlibCRC32\fR(\fBTcl_ZlibCRC32\fR(0,NULL,0), data, length);
416 Note that the Adler-32 algorithm is not a real checksum, but instead is a
417 related type of hash that works best on longer data.
420 \fBTcl_ZlibStreamInit\fR creates a compressing or decompressing stream that is
421 linked to a Tcl command, according to its arguments, and provides an abstract
422 token for the stream and returns a normal Tcl result code;
423 \fBTcl_ZlibStreamGetCommandName\fR returns the name of that command given the
424 stream token, or NULL if the stream has no command. Streams are not designed
425 to be thread-safe; each stream should only ever be used from the thread that
426 created it. When working with gzip streams, a dictionary (fields as given in
427 the \fBGZIP OPTIONS DICTIONARY\fR section below) can be given via the
428 \fIdictObj\fR parameter that on compression allows control over the generated
429 headers, and on decompression allows discovery of the existing headers. Note
430 that the dictionary will be written to on decompression once sufficient data
431 has been read to have a complete header. This means that the dictionary must
432 be an unshared value in that case; a blank value created with
433 \fBTcl_NewObj\fR is suggested.
435 Once a stream has been constructed, \fBTcl_ZlibStreamPut\fR is used to add
436 data to the stream and \fBTcl_ZlibStreamGet\fR is used to retrieve data from
437 the stream after processing. Both return normal Tcl result codes and leave an
438 error message in the result of the interpreter that the stream is registered
439 with in the error case (if such a registration has been performed). With
440 \fBTcl_ZlibStreamPut\fR, the data buffer value passed to it should not be
441 modified afterwards. With \fBTcl_ZlibStreamGet\fR, the data buffer value
442 passed to it will have the data bytes appended to it. Internally to the
443 stream, data is kept compressed so as to minimize the cost of buffer space.
445 \fBTcl_ZlibStreamChecksum\fR returns the checksum computed over the
446 uncompressed data according to the format, and \fBTcl_ZlibStreamEof\fR returns
447 a boolean value indicating whether the end of the uncompressed data has been
450 \fBTcl_ZlibStreamSetCompressionDictionary\fR is used to control the
451 compression dictionary used with the stream, a compression dictionary being an
452 array of bytes (such as might be created with \fBTcl_NewByteArrayObj\fR) that
453 is used to initialize the compression engine rather than leaving it to create
454 it on the fly from the data being compressed. Setting a compression dictionary
455 allows for more efficient compression in the case where the start of the data
456 is highly regular, but it does require both the compressor and the
457 decompressor to agreee on the value to use. Compression dictionaries are only
458 fully supported for zlib-format data; on compression, they must be set before
459 any data is sent in with \fBTcl_ZlibStreamPut\fR, and on decompression they
460 should be set when \fBTcl_ZlibStreamGet\fR produces an \fBerror\fR with its
461 \fB\-errorcode\fR set to
462 .QW "\fBZLIB NEED_DICT\fI code\fR" ;
463 the \fIcode\fR will be the Adler-32 checksum (see \fBTcl_ZlibAdler32\fR) of
464 the compression dictionary sought. (Note that this is only true for
465 zlib-format streams; gzip streams ignore compression dictionaries as the
466 format specification doesn't permit them, and raw streams just produce a data
467 error if the compression dictionary is missing or incorrect.)
469 If you wish to clear a stream and reuse it for a new compression or
470 decompression action, \fBTcl_ZlibStreamReset\fR will do this and return a
471 normal Tcl result code to indicate whether it was successful; if the stream is
472 registered with an interpreter, an error message will be left in the
473 interpreter result when this function returns TCL_ERROR.
474 Finally, \fBTcl_ZlibStreamClose\fR will clean up the stream and delete the
475 associated command: using \fBTcl_DeleteCommand\fR on the stream's command is
476 equivalent (when such a command exists).
477 .SH "GZIP OPTIONS DICTIONARY"
479 The \fIdictObj\fR parameter to \fBTcl_ZlibDeflate\fR, \fBTcl_ZlibInflate\fR
480 and \fBTcl_ZlibStreamInit\fR is used to pass a dictionary of options about
481 that is used to describe the gzip header in the compressed data. When creating
482 compressed data, the dictionary is read and when unpacking compressed data the
483 dictionary is written (in which case the \fIdictObj\fR parameter must refer to
484 an unshared dictionary value).
486 The following fields in the dictionary value are understood. All other fields
487 are ignored. No field is required when creating a gzip-format stream.
491 This holds the comment field of the header, if present. If absent, no comment
492 was supplied (on decompression) or will be created (on compression).
496 A boolean value describing whether a CRC of the header is computed. Note that
497 the \fBgzip\fR program does \fInot\fR use or allow a CRC on the header.
501 The name of the file that held the uncompressed data. This should not contain
502 any directory separators, and should be sanitized before use on decompression
503 with \fBfile tail\fR.
507 The operating system type code field from the header (if not the
509 value). See RFC 1952 for the meaning of these codes. On compression, if this
510 is absent then the field will be set to the
516 The size of the uncompressed data. This is ignored on compression; the size
517 of the data compressed depends on how much data is supplied to the
522 The time field from the header if non-zero, expected to be the time that the
523 file named by the \fBfilename\fR field was modified. Suitable for use with
524 \fBclock format\fR. On creation, the right value to use is that from
525 \fBclock seconds\fR or \fBfile mtime\fR.
529 The type of the uncompressed data (either \fBbinary\fR or \fBtext\fR) if
531 .SH "PORTABILITY NOTES"
532 These functions will fail gracefully if Tcl is not linked with the zlib
535 Tcl_NewByteArrayObj(3), zlib(n)
536 '\"Tcl_StackChannel(3)
538 compress, decompress, deflate, gzip, inflate
OSDN Git Service
