"Fossies" - the Fresh Open Source Software Archive

Member "SAOImageDS9/tcl8.6/doc/TclZlib.3" (13 Nov 2019, 12643 Bytes) of package /linux/misc/ds9.8.1.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

    1 '\"
    2 '\" Copyright (c) 2008 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 TclZlib 3 8.6 Tcl "Tcl Library Procedures"
    8 .so man.macros
    9 .BS
   10 '\" Note:  do not modify the .SH NAME line immediately below!
   11 .SH NAME
   12 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
   13 .SH SYNOPSIS
   14 .nf
   15 #include <tcl.h>
   16 .sp
   17 int
   18 \fBTcl_ZlibDeflate\fR(\fIinterp, format, dataObj, level, dictObj\fR)
   19 .sp
   20 int
   21 \fBTcl_ZlibInflate\fR(\fIinterp, format, dataObj, dictObj\fR)
   22 .sp
   23 unsigned int
   24 \fBTcl_ZlibCRC32\fR(\fIinitValue, bytes, length\fR)
   25 .sp
   26 unsigned int
   27 \fBTcl_ZlibAdler32\fR(\fIinitValue, bytes, length\fR)
   28 .sp
   29 int
   30 \fBTcl_ZlibStreamInit\fR(\fIinterp, mode, format, level, dictObj, zshandlePtr\fR)
   31 .sp
   32 Tcl_Obj *
   33 \fBTcl_ZlibStreamGetCommandName\fR(\fIzshandle\fR)
   34 .sp
   35 int
   36 \fBTcl_ZlibStreamEof\fR(\fIzshandle\fR)
   37 .sp
   38 int
   39 \fBTcl_ZlibStreamClose\fR(\fIzshandle\fR)
   40 .sp
   41 int
   42 \fBTcl_ZlibStreamReset\fR(\fIzshandle\fR)
   43 .sp
   44 int
   45 \fBTcl_ZlibStreamChecksum\fR(\fIzshandle\fR)
   46 .sp
   47 int
   48 \fBTcl_ZlibStreamPut\fR(\fIzshandle, dataObj, flush\fR)
   49 .sp
   50 int
   51 \fBTcl_ZlibStreamGet\fR(\fIzshandle, dataObj, count\fR)
   52 .sp
   53 \fBTcl_ZlibStreamSetCompressionDictionary\fR(\fIzshandle, compDict\fR)
   54 .fi
   55 .SH ARGUMENTS
   56 .AS Tcl_ZlibStream zshandle in
   57 .AP Tcl_Interp *interp in
   58 The interpreter to store resulting compressed or uncompressed data in. Also
   59 where any error messages are written. For \fBTcl_ZlibStreamInit\fR, this can
   60 be NULL to create a stream that is not bound to a command.
   61 .AP int format in
   62 What format of compressed data to work with. Must be one of
   63 \fBTCL_ZLIB_FORMAT_ZLIB\fR for zlib-format data, \fBTCL_ZLIB_FORMAT_GZIP\fR
   64 for gzip-format data, or \fBTCL_ZLIB_FORMAT_RAW\fR for raw compressed data. In
   65 addition, for decompression only, \fBTCL_ZLIB_FORMAT_AUTO\fR may also be
   66 chosen which can automatically detect whether the compressed data was in zlib
   67 or gzip format.
   68 .AP Tcl_Obj *dataObj in/out
   69 A byte-array value containing the data to be compressed or decompressed, or
   70 to which the data extracted from the stream is appended when passed to
   71 \fBTcl_ZlibStreamGet\fR.
   72 .AP int level in
   73 What level of compression to use. Should be a number from 0 to 9 or one of the
   74 following: \fBTCL_ZLIB_COMPRESS_NONE\fR for no compression,
   75 \fBTCL_ZLIB_COMPRESS_FAST\fR for fast but inefficient compression,
   76 \fBTCL_ZLIB_COMPRESS_BEST\fR for slow but maximal compression, or
   77 \fBTCL_ZLIB_COMPRESS_DEFAULT\fR for the level recommended by the zlib library.
   78 .AP Tcl_Obj *dictObj in/out
   79 A dictionary that contains, or which will be updated to contain, a description
   80 of the gzip header associated with the compressed data. Only useful when the
   81 \fIformat\fR is \fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. If
   82 a NULL is passed, a default header will be used on compression and the header
   83 will be ignored (apart from integrity checks) on decompression. See the
   84 section \fBGZIP OPTIONS DICTIONARY\fR for details about the contents of this
   85 dictionary.
   86 .AP "unsigned int" initValue in
   87 The initial value for the checksum algorithm.
   88 .AP "unsigned char" *bytes in
   89 An array of bytes to run the checksum algorithm over, or NULL to get the
   90 recommended initial value for the checksum algorithm.
   91 .AP int length in
   92 The number of bytes in the array.
   93 .AP int mode in
   94 What mode to operate the stream in. Should be either
   95 \fBTCL_ZLIB_STREAM_DEFLATE\fR for a compressing stream or
   96 \fBTCL_ZLIB_STREAM_INFLATE\fR for a decompressing stream.
   97 .AP Tcl_ZlibStream *zshandlePtr out
   98 A pointer to a variable in which to write the abstract token for the stream
   99 upon successful creation.
  100 .AP Tcl_ZlibStream zshandle in
  101 The abstract token for the stream to operate on.
  102 .AP int flush in
  103 Whether and how to flush the stream after writing the data to it. Must be one
  104 of: \fBTCL_ZLIB_NO_FLUSH\fR if no flushing is to be done, \fBTCL_ZLIB_FLUSH\fR
  105 if the currently compressed data must be made available for access using
  106 \fBTcl_ZlibStreamGet\fR, \fBTCL_ZLIB_FULLFLUSH\fR if the stream must be put
  107 into a state where the decompressor can recover from on corruption, or
  108 \fBTCL_ZLIB_FINALIZE\fR to ensure that the stream is finished and that any
  109 trailer demanded by the format is written.
  110 .AP int count in
  111 The maximum number of bytes to get from the stream, or -1 to get all remaining
  112 bytes from the stream's buffers.
  113 .AP Tcl_Obj *compDict in
  114 A byte array value that is the compression dictionary to use with the stream.
  115 Note that this is \fInot a Tcl dictionary\fR, and it is recommended that this
  116 only ever be used with streams that were created with their \fIformat\fR set
  117 to \fBTCL_ZLIB_FORMAT_ZLIB\fR because the other formats have no mechanism to
  118 indicate whether a compression dictionary was present other than to fail on
  119 decompression.
  120 .BE
  121 .SH DESCRIPTION
  122 These functions form the interface from the Tcl library to the Zlib
  123 library by Jean-loup Gailly and Mark Adler.
  124 .PP
  125 \fBTcl_ZlibDeflate\fR and \fBTcl_ZlibInflate\fR respectively compress and
  126 decompress the data contained in the \fIdataObj\fR argument, according to the
  127 \fIformat\fR and, for compression, \fIlevel\fR arguments. The dictionary in
  128 the \fIdictObj\fR parameter is used to convey additional header information
  129 about the compressed data when the compression format supports it; currently,
  130 the dictionary is only used when the \fIformat\fR parameter is
  131 \fBTCL_ZLIB_FORMAT_GZIP\fR or \fBTCL_ZLIB_FORMAT_AUTO\fR. For details of the
  132 contents of the dictionary, see the \fBGZIP OPTIONS DICTIONARY\fR section
  133 below. Upon success, both functions leave the resulting compressed or
  134 decompressed data in a byte-array value that is the Tcl interpreter's result;
  135 the returned value is a standard Tcl result code.
  136 .PP
  137 \fBTcl_ZlibAdler32\fR and \fBTcl_ZlibCRC32\fR compute checksums on arrays of
  138 bytes, returning the computed checksum. Checksums are computed incrementally,
  139 allowing data to be processed one block at a time, but this requires the
  140 caller to maintain the current checksum and pass it in as the \fIinitValue\fR
  141 parameter; the initial value to use for this can be obtained by using NULL for
  142 the \fIbytes\fR parameter instead of a pointer to the array of bytes to
  143 compute the checksum over. Thus, typical usage in the single data block case
  144 is like this:
  145 .PP
  146 .CS
  147 checksum = \fBTcl_ZlibCRC32\fR(\fBTcl_ZlibCRC32\fR(0,NULL,0), data, length);
  148 .CE
  149 .PP
  150 Note that the Adler-32 algorithm is not a real checksum, but instead is a
  151 related type of hash that works best on longer data.
  152 .SS "ZLIB STREAMS"
  153 .PP
  154 \fBTcl_ZlibStreamInit\fR creates a compressing or decompressing stream that is
  155 linked to a Tcl command, according to its arguments, and provides an abstract
  156 token for the stream and returns a normal Tcl result code;
  157 \fBTcl_ZlibStreamGetCommandName\fR returns the name of that command given the
  158 stream token, or NULL if the stream has no command. Streams are not designed
  159 to be thread-safe; each stream should only ever be used from the thread that
  160 created it. When working with gzip streams, a dictionary (fields as given in
  161 the \fBGZIP OPTIONS DICTIONARY\fR section below) can be given via the
  162 \fIdictObj\fR parameter that on compression allows control over the generated
  163 headers, and on decompression allows discovery of the existing headers. Note
  164 that the dictionary will be written to on decompression once sufficient data
  165 has been read to have a complete header. This means that the dictionary must
  166 be an unshared value in that case; a blank value created with
  167 \fBTcl_NewObj\fR is suggested.
  168 .PP
  169 Once a stream has been constructed, \fBTcl_ZlibStreamPut\fR is used to add
  170 data to the stream and \fBTcl_ZlibStreamGet\fR is used to retrieve data from
  171 the stream after processing. Both return normal Tcl result codes and leave an
  172 error message in the result of the interpreter that the stream is registered
  173 with in the error case (if such a registration has been performed). With
  174 \fBTcl_ZlibStreamPut\fR, the data buffer value passed to it should not be
  175 modified afterwards. With \fBTcl_ZlibStreamGet\fR, the data buffer value
  176 passed to it will have the data bytes appended to it. Internally to the
  177 stream, data is kept compressed so as to minimize the cost of buffer space.
  178 .PP
  179 \fBTcl_ZlibStreamChecksum\fR returns the checksum computed over the
  180 uncompressed data according to the format, and \fBTcl_ZlibStreamEof\fR returns
  181 a boolean value indicating whether the end of the uncompressed data has been
  182 reached.
  183 .PP
  184 \fBTcl_ZlibStreamSetCompressionDictionary\fR is used to control the
  185 compression dictionary used with the stream, a compression dictionary being an
  186 array of bytes (such as might be created with \fBTcl_NewByteArrayObj\fR) that
  187 is used to initialize the compression engine rather than leaving it to create
  188 it on the fly from the data being compressed. Setting a compression dictionary
  189 allows for more efficient compression in the case where the start of the data
  190 is highly regular, but it does require both the compressor and the
  191 decompressor to agreee on the value to use. Compression dictionaries are only
  192 fully supported for zlib-format data; on compression, they must be set before
  193 any data is sent in with \fBTcl_ZlibStreamPut\fR, and on decompression they
  194 should be set when \fBTcl_ZlibStreamGet\fR produces an \fBerror\fR with its
  195 \fB\-errorcode\fR set to
  196 .QW "\fBZLIB NEED_DICT\fI code\fR" ;
  197 the \fIcode\fR will be the Adler-32 checksum (see \fBTcl_ZlibAdler32\fR) of
  198 the compression dictionary sought. (Note that this is only true for
  199 zlib-format streams; gzip streams ignore compression dictionaries as the
  200 format specification doesn't permit them, and raw streams just produce a data
  201 error if the compression dictionary is missing or incorrect.)
  202 .PP
  203 If you wish to clear a stream and reuse it for a new compression or
  204 decompression action, \fBTcl_ZlibStreamReset\fR will do this and return a
  205 normal Tcl result code to indicate whether it was successful; if the stream is
  206 registered with an interpreter, an error message will be left in the
  207 interpreter result when this function returns TCL_ERROR.
  208 Finally, \fBTcl_ZlibStreamClose\fR will clean up the stream and delete the
  209 associated command: using \fBTcl_DeleteCommand\fR on the stream's command is
  210 equivalent (when such a command exists).
  211 .SH "GZIP OPTIONS DICTIONARY"
  212 .PP
  213 The \fIdictObj\fR parameter to \fBTcl_ZlibDeflate\fR, \fBTcl_ZlibInflate\fR
  214 and \fBTcl_ZlibStreamInit\fR is used to pass a dictionary of options about
  215 that is used to describe the gzip header in the compressed data. When creating
  216 compressed data, the dictionary is read and when unpacking compressed data the
  217 dictionary is written (in which case the \fIdictObj\fR parameter must refer to
  218 an unshared dictionary value).
  219 .PP
  220 The following fields in the dictionary value are understood. All other fields
  221 are ignored. No field is required when creating a gzip-format stream.
  222 .TP
  223 \fBcomment\fR
  224 .
  225 This holds the comment field of the header, if present. If absent, no comment
  226 was supplied (on decompression) or will be created (on compression).
  227 .TP
  228 \fBcrc\fR
  229 .
  230 A boolean value describing whether a CRC of the header is computed. Note that
  231 the \fBgzip\fR program does \fInot\fR use or allow a CRC on the header.
  232 .TP
  233 \fBfilename\fR
  234 .
  235 The name of the file that held the uncompressed data. This should not contain
  236 any directory separators, and should be sanitized before use on decompression
  237 with \fBfile tail\fR.
  238 .TP
  239 \fBos\fR
  240 .
  241 The operating system type code field from the header (if not the
  242 .QW unknown
  243 value). See RFC 1952 for the meaning of these codes. On compression, if this
  244 is absent then the field will be set to the
  245 .QW unknown
  246 value.
  247 .TP
  248 \fBsize\fR
  249 .
  250 The size of the uncompressed data. This is ignored on compression; the size
  251 of the data compressed depends on how much data is supplied to the
  252 compression engine.
  253 .TP
  254 \fBtime\fR
  255 .
  256 The time field from the header if non-zero, expected to be the time that the
  257 file named by the \fBfilename\fR field was modified. Suitable for use with
  258 \fBclock format\fR. On creation, the right value to use is that from
  259 \fBclock seconds\fR or \fBfile mtime\fR.
  260 .TP
  261 \fBtype\fR
  262 .
  263 The type of the uncompressed data (either \fBbinary\fR or \fBtext\fR) if
  264 known.
  265 .SH "PORTABILITY NOTES"
  266 These functions will fail gracefully if Tcl is not linked with the zlib
  267 library.
  268 .SH "SEE ALSO"
  269 Tcl_NewByteArrayObj(3), zlib(n)
  270 '\"Tcl_StackChannel(3)
  271 .SH "KEYWORDS"
  272 compress, decompress, deflate, gzip, inflate
  273 '\" Local Variables:
  274 '\" mode: nroff
  275 '\" fill-column: 78
  276 '\" End: