## Tcl8.6.17/Tk8.6.17 Documentation > Tcl C API > TclZlib

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    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
  SYNOPSIS
    #include <tcl.h>
    int
    Tcl_ZlibDeflate(interp, format, dataObj, level, dictObj)
    int
    Tcl_ZlibInflate(interp, format, dataObj, bufferSize, dictObj)
    unsigned int
    Tcl_ZlibCRC32(initValue, bytes, length)
    unsigned int
    Tcl_ZlibAdler32(initValue, bytes, length)
    int
    Tcl_ZlibStreamInit(interp, mode, format, level, dictObj, zshandlePtr)
    Tcl_Obj *
    Tcl_ZlibStreamGetCommandName(zshandle)
    int
    Tcl_ZlibStreamEof(zshandle)
    int
    Tcl_ZlibStreamClose(zshandle)
    int
    Tcl_ZlibStreamReset(zshandle)
    int
    Tcl_ZlibStreamChecksum(zshandle)
    int
    Tcl_ZlibStreamPut(zshandle, dataObj, flush)
    int
    Tcl_ZlibStreamGet(zshandle, dataObj, count)
    Tcl_ZlibStreamSetCompressionDictionary(zshandle, compDict)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    int format (入力in)
    Tcl_Obj *dataObj (入出力in/out)
    int level (入力in)
    Tcl_Obj *dictObj (入出力in/out)
    unsigned int initValue (入力in)
    int bufferSize (入力in)
    unsigned char *bytes (入力in)
    int length (入力in)
    int mode (入力in)
    Tcl_ZlibStream *zshandlePtr (出力out)
    Tcl_ZlibStream zshandle (入力in)
    int flush (入力in)
    int count (入力in)
    Tcl_Obj *compDict (入力in)
  説明 DESCRIPTION
  ZLIB STREAMS
  GZIP OPTIONS DICTIONARY
    comment
    crc
    filename
    os
    size
    time
    type
  互換性の註意 PORTABILITY NOTES
  SEE ALSO
  KEYWORDS

### NAME

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

### SYNOPSIS

#include <tcl.h>
int
Tcl_ZlibDeflate(interp, format, dataObj, level, dictObj)
int
Tcl_ZlibInflate(interp, format, dataObj, bufferSize, dictObj)
unsigned int
Tcl_ZlibCRC32(initValue, bytes, length)
unsigned int
Tcl_ZlibAdler32(initValue, bytes, length)
int
Tcl_ZlibStreamInit(interp, mode, format, level, dictObj, zshandlePtr)
Tcl_Obj *
Tcl_ZlibStreamGetCommandName(zshandle)
int
Tcl_ZlibStreamEof(zshandle)
int
Tcl_ZlibStreamClose(zshandle)
int
Tcl_ZlibStreamReset(zshandle)
int
Tcl_ZlibStreamChecksum(zshandle)
int
Tcl_ZlibStreamPut(zshandle, dataObj, flush)
int
Tcl_ZlibStreamGet(zshandle, dataObj, count)
Tcl_ZlibStreamSetCompressionDictionary(zshandle, compDict)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  圧縮又は解凍結果を保存する解釈実行機能｡亦､何かの不都合伝言文が書かれる場所｡ Tcl_ZlibStreamInit については､命令に束縛されない流れを作成する NULL でもよい｡ The interpreter to store resulting compressed or uncompressed data in. Also where any error messages are written. For Tcl_ZlibStreamInit, this can be NULL to create a stream that is not bound to a command.

int format (入力in)
  一緒にデータを圧縮する書式｡zlib-format データ には TCL_ZLIB_FORMAT_ZLIB ､gzip-format データ には TCL_ZLIB_FORMAT_GZIP ､そのまま圧縮データには TCL_ZLIB_FORMAT_RAW の内の一つでなければならない｡更に､解凍のみでは､圧縮データが zlib か gzip かを自動的に検出できる TCL_ZLIB_FORMAT_AUTO が選択される｡ 　 What format of compressed data to work with. Must be one of TCL_ZLIB_FORMAT_ZLIB for zlib-format data, TCL_ZLIB_FORMAT_GZIP for gzip-format data, or TCL_ZLIB_FORMAT_RAW for raw compressed data. In addition, for decompression only, TCL_ZLIB_FORMAT_AUTO may also be chosen which can automatically detect whether the compressed data was in zlib or gzip format.

Tcl_Obj *dataObj (入出力in/out)
  圧縮又は解凍されるデータを含むか､又は Tcl_ZlibStreamGet に渡された時にそれに流れから抽出されたデータが追記されるバイト配列値｡ A byte-array value containing the data to be compressed or decompressed, or to which the data extracted from the stream is appended when passed to Tcl_ZlibStreamGet.

int level (入力in)
  使用すべき圧縮の水準｡数字 0 から 9 迄か､次の内の一つであるべき: 非圧縮には TCL_ZLIB_COMPRESS_NONE ､圧縮効果は低いが速い TCL_ZLIB_COMPRESS_FAST ､遅いが最高の圧縮には TCL_ZLIB_COMPRESS_BEST ､ zlib 外部函数によって推奨される水準には TCL_ZLIB_COMPRESS_DEFAULT ｡　　　　 What level of compression to use. Should be a number from 0 to 9 or one of the following: TCL_ZLIB_COMPRESS_NONE for no compression, TCL_ZLIB_COMPRESS_FAST for fast but inefficient compression, TCL_ZLIB_COMPRESS_BEST for slow but maximal compression, or TCL_ZLIB_COMPRESS_DEFAULT for the level recommended by the zlib library.

Tcl_Obj *dictObj (入出力in/out)
  圧縮データに関連する gzip 冒頭部の記述を､含むか含む為に更新される辞書｡書式が TCL_ZLIB_FORMAT_GZIP か TCL_ZLIB_FORMAT_AUTO の時のみ便利である｡もし NULL が渡されると圧縮用の無為設定の冒頭部が使用され､解凍時には冒頭部は(信頼性確認を除いて)無視される｡この辞書の内容の詳細については GZIP OPTIONS DICTIONARY の節を参照されたい｡　 A dictionary that contains, or which will be updated to contain, a description of the gzip header associated with the compressed data. Only useful when the format is TCL_ZLIB_FORMAT_GZIP or TCL_ZLIB_FORMAT_AUTO. If a NULL is passed, a default header will be used on compression and the header will be ignored (apart from integrity checks) on decompression. See the section GZIP OPTIONS DICTIONARY for details about the contents of this dictionary.

unsigned int initValue (入力in)
  内容検査算法の為の初期値｡　 The initial value for the checksum algorithm.

int bufferSize (入力in)
  データを受取る為に使れる緩衝域の寸法が幾らかの示唆｡入力データに基づく一般的な推測の使用には 0 を使われたい｡[譯註:geric→generic] A hint as to what size of buffer is to be used to receive the data. Use 0 to use a geric guess based on the input data.

unsigned char *bytes (入力in)
  内容検査算法を実行するバイトの配列､又は NULL では､内容検査算法の為の推奨される初期値を得る｡　 An array of bytes to run the checksum algorithm over, or NULL to get the recommended initial value for the checksum algorithm.

int length (入力in)
  配列内のバイトの個数｡　 The number of bytes in the array.

int mode (入力in)
  流れに操作すべき様式｡圧縮流れには TCL_ZLIB_STREAM_DEFLATE ､解凍流れには TCL_ZLIB_STREAM_INFLATE のどちらかであるべき｡　 What mode to operate the stream in. Should be either TCL_ZLIB_STREAM_DEFLATE for a compressing stream or TCL_ZLIB_STREAM_INFLATE for a decompressing stream.

Tcl_ZlibStream *zshandlePtr (出力out)
  成功裡に生成した流れの為の要約字句を書く変数への指示子｡　 A pointer to a variable in which to write the abstract token for the stream upon successful creation.

Tcl_ZlibStream zshandle (入力in)
  流れに対して操作する為の要約字句｡　 The abstract token for the stream to operate on.

int flush (入力in)
  データを記入した後､流れを如何に追払うか｡次の内の１つでなければならない:TCL_ZLIB_NO_FLUSH は追出しはされない､ TCL_ZLIB_FLUSH は現在圧縮されたデータは必ず利用できる 利用して使うには Tcl_ZlibStreamGet,､ TCL_ZLIB_FULLFLUSH は､流れが､崩壊から回復できる解凍の状態に入る場合､又は TCL_ZLIB_FINALIZE は流れは終わり書式によるどの末尾要求も確実に書ける｡ Whether and how to flush the stream after writing the data to it. Must be one of: TCL_ZLIB_NO_FLUSH if no flushing is to be done, TCL_ZLIB_FLUSH if the currently compressed data must be made available for access using Tcl_ZlibStreamGet, TCL_ZLIB_FULLFLUSH if the stream must be put into a state where the decompressor can recover from on corruption, or TCL_ZLIB_FINALIZE to ensure that the stream is finished and that any trailer demanded by the format is written.

int count (入力in)
  流れから得られる最大のバイト数､流れの緩衝域から残りの全てのバイトを得る時は -1 ｡ The maximum number of bytes to get from the stream, or -1 to get all remaining bytes from the stream's buffers.

Tcl_Obj *compDict (入力in)
  バイト配列値であって､流れと一緒に使う圧縮辞書である｡註意すべきは､これは Tcl 辞書ではない ､亦､これだけをTCL_ZLIB_FORMAT_ZLIB に設定した形式によって作成された流れと一緒に使うべき､理由は他の形式は解凍失敗以外に圧縮辞書が存在下か否かを示す仕組みがないから｡ A byte array value that is the compression dictionary to use with the stream. Note that this is not a Tcl dictionary, and it is recommended that this only ever be used with streams that were created with their format set to TCL_ZLIB_FORMAT_ZLIB because the other formats have no mechanism to indicate whether a compression dictionary was present other than to fail on decompression.

### 説明 DESCRIPTION

これ等の函数は Tcl 外部函数から Jean-loup Gailly 氏と Mark Adler 氏による Zlib 外部函数への相互作用を形成する｡ These functions form the interface from the Tcl library to the Zlib library by Jean-loup Gailly and Mark Adler.

Tcl_ZlibDeflate and Tcl_ZlibInflate はそれぞれ dataObj 引数に含まれるデータを､ format に沿って圧縮と解凍を行う､圧縮の場合は level 引数にも従う｡ dictObj 假引数内の辞書は､圧縮形式がそれを運営している時は､圧縮されたデータに関する情報を運ぶ; 現在辞書は､ format 假引数が TCL_ZLIB_FORMAT_GZI か TCL_ZLIB_FORMAT_AUTO の時のみ使われる｡辞書の内容の更なる詳細は下の GZIP OPTIONS DICTIONARY の節を参照されたい｡両方の函数は､成功すると､結果の圧縮された又は解凍されたデータをバイト配列値形式で Tcl 解釈実行機能の結果として残す; 返り値は標準の Tcl 結果符号である｡ Tcl_ZlibDeflate and Tcl_ZlibInflate respectively compress and decompress the data contained in the dataObj argument, according to the format and, for compression, level arguments. The dictionary in the dictObj parameter is used to convey additional header information about the compressed data when the compression format supports it; currently, the dictionary is only used when the format parameter is TCL_ZLIB_FORMAT_GZIP or TCL_ZLIB_FORMAT_AUTO. For details of the contents of the dictionary, see the GZIP OPTIONS DICTIONARY section below. Upon success, both functions leave the resulting compressed or decompressed data in a byte-array value that is the Tcl interpreter's result; the returned value is a standard Tcl result code.

Tcl_ZlibAdler32 and Tcl_ZlibCRC32 はバイト配列の検査用値を算出し､計算した検査用値を返す｡検査用値は累積的に算出される､一つの時に一つの区分の処理のみを許容するが､これは､呼出し側が現在の検査用値を維持しそれを初期値 initValue 假引数として渡すことを要求する; この為に使う初期値は､検査用値を累積して計算する為のバイト配列へのポインターを渡す代りに､バイト假引数として NULL を使うことによって得られる｡従って典型的な１区分のデータの場合の使用法はこうなる: Tcl_ZlibAdler32 and Tcl_ZlibCRC32 compute checksums on arrays of bytes, returning the computed checksum. Checksums are computed incrementally, allowing data to be processed one block at a time, but this requires the caller to maintain the current checksum and pass it in as the initValue parameter; the initial value to use for this can be obtained by using NULL for the bytes parameter instead of a pointer to the array of bytes to compute the checksum over. Thus, typical usage in the single data block case is like this:

    checksum = Tcl_ZlibCRC32(Tcl_ZlibCRC32(0,NULL,0), data, length);

註意すべきは Adler-32 式計算法は実際の検査用値に使わず､代りに長いデータによりよく働く連想記憶の関連型を使う｡ Note that the Adler-32 algorithm is not a real checksum, but instead is a related type of hash that works best on longer data.

#### ZLIB STREAMS

Tcl_ZlibStreamInit は圧縮又は解凍流れを作成し､その引数に従って Tcl 命令に連結する､亦､流れに関する要約字句を提供し､通常の Tcl 結果符号を返す; Tcl_ZlibStreamGetCommandName は与えられた流れの字句の命令の名前を返す､流れに命令がない場合は NULL を返す｡流れは時分割に対して安全には設計されていない; それぞれの流れはそれが作られた時分割片からのみ使われるべきである｡ gzip 流れと共に働く時(下の GZIP OPTIONS DICTIONARY 節内で与えられた欄として)､辞書は dictObj 假引数経由で与えられてもよい､それは圧縮では作成された冒頭情報の制御を許容する､亦解凍では既存の冒頭情報の捜索を許容する｡註意すべきは､完全な冒頭情報を有する為に一度充分なデータが読込まれ､書かれる｡この意味は､辞書はその場合非共有値でなければならない; Tcl_NewObj によって作成された空白の値が暗示されている｡ Tcl_ZlibStreamInit creates a compressing or decompressing stream that is linked to a Tcl command, according to its arguments, and provides an abstract token for the stream and returns a normal Tcl result code; Tcl_ZlibStreamGetCommandName returns the name of that command given the stream token, or NULL if the stream has no command. Streams are not designed to be thread-safe; each stream should only ever be used from the thread that created it. When working with gzip streams, a dictionary (fields as given in the GZIP OPTIONS DICTIONARY section below) can be given via the dictObj parameter that on compression allows control over the generated headers, and on decompression allows discovery of the existing headers. Note that the dictionary will be written to on decompression once sufficient data has been read to have a complete header. This means that the dictionary must be an unshared value in that case; a blank value created with Tcl_NewObj is suggested.

一たび流れが構成されると､その流れにデータを追加する為に Tcl_ZlibStreamPut が使われ､処理後に流れからデータを取出すために Tcl_ZlibStreamGet が使われる｡両方供､通常の Tcl 結果符号を返し､流れが不都合によって登録された場合､解釈実行機能の結果の中に不都合伝言文を残す(もしその様な登録が完了した場合)｡ Tcl_ZlibStreamPut によってデータ緩衝域値に渡された値は後からは修正されない｡データ緩衝域値はTcl_ZlibStreamGet によってそれに渡され､それはデータバイトをそれに追加させる事になる｡内部的にはデータは圧縮されたままで緩衝域の費用を最小化している｡ Once a stream has been constructed, Tcl_ZlibStreamPut is used to add data to the stream and Tcl_ZlibStreamGet is used to retrieve data from the stream after processing. Both return normal Tcl result codes and leave an error message in the result of the interpreter that the stream is registered with in the error case (if such a registration has been performed). With Tcl_ZlibStreamPut, the data buffer value passed to it should not be modified afterwards. With Tcl_ZlibStreamGet, the data buffer value passed to it will have the data bytes appended to it. Internally to the stream, data is kept compressed so as to minimize the cost of buffer space.

Tcl_ZlibStreamChecksum は非圧縮データ上で形式に沿って計算された検査用値を返す｡亦､ Tcl_ZlibStreamEof は非圧縮データの末尾に達したか否かを示す論理値を返す｡ Tcl_ZlibStreamChecksum returns the checksum computed over the uncompressed data according to the format, and Tcl_ZlibStreamEof returns a boolean value indicating whether the end of the uncompressed data has been reached.

Tcl_ZlibStreamSetCompressionDictionary は流れと一緒に使用する圧縮辞書の制御に使用される､圧縮辞書はバイトの配列であり( Tcl_NewByteArrayObj 等によって作成されるかのごとく)､圧縮されるデータからその場でそれを作成する様にするのではなく､圧縮専用譜を初期化する為に使われる｡圧縮辞書の設定はデータが高度に規則的な場合､より効果的な圧縮を許容するが､圧縮譜と解凍譜の両方に値を使うことを同意することを要求する｡圧縮辞書は単に zlib形式データについてのみ完全に運営されている; 圧縮では Tcl_ZlibStreamPut 内にどのデータが送られるより先に辞書を設定しなければならない､解凍では､ “ZLIB NEED_DICT code” に設定した -errorcode によって Tcl_ZlibStreamGet が不都合が産出される時に設定されるべきである; 符号は圧縮辞書の要求する Adler-32 式検査値( Tcl_ZlibAdler32 参照)になる｡(註意すべきは､これは zlib-形式流れの場合にのみ正しい; gzip 流れは圧縮辞書を無視する､理由は書式仕様がそれを許容していない､亦､生の流れは圧縮辞書が失われたり誤っている場合､データ不都合を生じる) Tcl_ZlibStreamSetCompressionDictionary is used to control the compression dictionary used with the stream, a compression dictionary being an array of bytes (such as might be created with Tcl_NewByteArrayObj) that is used to initialize the compression engine rather than leaving it to create it on the fly from the data being compressed. Setting a compression dictionary allows for more efficient compression in the case where the start of the data is highly regular, but it does require both the compressor and the decompressor to agreee on the value to use. Compression dictionaries are only fully supported for zlib-format data; on compression, they must be set before any data is sent in with Tcl_ZlibStreamPut, and on decompression they should be set when Tcl_ZlibStreamGet produces an error with its -errorcode set to “ZLIB NEED_DICT code”; the code will be the Adler-32 checksum (see Tcl_ZlibAdler32) of the compression dictionary sought. (Note that this is only true for zlib-format streams; gzip streams ignore compression dictionaries as the format specification doesn't permit them, and raw streams just produce a data error if the compression dictionary is missing or incorrect.)

流れを刷新しそれを新しい圧縮化解凍動作に再使用したい場合､ Tcl_ZlibStreamReset がそれを行い､それが成功したことを指し示す通常の Tcl 結果符号を返す; もし流れが解釈実行機能に登録されている場合､この函数が TCL_ERROR を返す時､不都合伝言文が解釈実行機能の結果内に残される｡最終的に､ Tcl_ZlibStreamClose が流れを清掃し結合した命令を削除する: 流れの命令上での Tcl_DeleteCommand の使用と等価である(その様な命令が実在する場合)｡ If you wish to clear a stream and reuse it for a new compression or decompression action, Tcl_ZlibStreamReset will do this and return a normal Tcl result code to indicate whether it was successful; if the stream is registered with an interpreter, an error message will be left in the interpreter result when this function returns TCL_ERROR. Finally, Tcl_ZlibStreamClose will clean up the stream and delete the associated command: using Tcl_DeleteCommand on the stream's command is equivalent (when such a command exists).

### GZIP OPTIONS DICTIONARY

Tcl_ZlibDeflate, Tcl_ZlibInflate and Tcl_ZlibStreamInit への假引数 dictObj は､圧縮データ内の gzip 冒頭情報の記述に使われる指示項目の辞書に渡される為に使われる｡圧縮データ作成の時､その辞書が読まれ､圧縮データの解凍時にそのデータが書かれる(その場合､ dictObj 假引数は非共有辞書値を参照していなければならない)｡ The dictObj parameter to Tcl_ZlibDeflate, Tcl_ZlibInflate and Tcl_ZlibStreamInit is used to pass a dictionary of options about that is used to describe the gzip header in the compressed data. When creating compressed data, the dictionary is read and when unpacking compressed data the dictionary is written (in which case the dictObj parameter must refer to an unshared dictionary value).

辞書内の次の欄の値は理解できる｡他の欄は無視する｡ gzip-書式流れを作成する時はどの欄も要求されない｡ The following fields in the dictionary value are understood. All other fields are ignored. No field is required when creating a gzip-format stream.

comment
  これがある場合は､冒頭情報の注釈欄を保有する｡ない場合は､注釈は供給されず(解凍時)､生成されない(圧縮時)｡ This holds the comment field of the header, if present. If absent, no comment was supplied (on decompression) or will be created (on compression).

crc
  冒頭情報の CRC が計算されているかを記述する論理値｡註意すべきは gzip 算譜は冒頭情報上の CRC は使わないか許容しない｡ A boolean value describing whether a CRC of the header is computed. Note that the gzip program does not use or allow a CRC on the header.

filename
  非圧縮のデータを保有するファイルの名前｡これはどのディレクトリーの区切りも含まないし､ file tail による解凍に使用する前に清掃はしない｡ The name of the file that held the uncompressed data. This should not contain any directory separators, and should be sanitized before use on decompression with file tail.

os
  冒頭情報からのOSの型の符号( “未知” 値でない場合)｡この符号の意味に就いては RFC 1952 を参照されたい｡圧縮に於いては､不在であれば､この欄は “未知” に設定される｡ The operating system type code field from the header (if not the “unknown” value). See RFC 1952 for the meaning of these codes. On compression, if this is absent then the field will be set to the “unknown” value.

size
  非圧縮データの寸法｡圧縮ではこれは無視される; 圧縮されたデータの寸法は､圧縮専用譜にいくらデータが供給されたかに依存する｡ The size of the uncompressed data. This is ignored on compression; the size of the data compressed depends on how much data is supplied to the compression engine.

time
  冒頭情報の時刻欄､非零の場合､ filename 欄によるファイル名が変更された時刻が修正されたことを表す｡ clock format の使用に適する｡作成時には､使用に適した正しい値は､ clock seconds か file mtime である｡ The time field from the header if non-zero, expected to be the time that the file named by the filename field was modified. Suitable for use with clock format. On creation, the right value to use is that from clock seconds or file mtime.

type
  既知であれば､非圧縮データの型( binary か textのどちらか)｡ The type of the uncompressed data (either binary or text) if known.

### 互換性の註意 PORTABILITY NOTES

もし Tcl が zlib 外部函数に連結していない場合は､これ等の函数は､失敗する｡ These functions will fail gracefully if Tcl is not linked with the zlib library.

### SEE ALSO

Tcl_NewByteArrayObj, zlib

### KEYWORDS

compress, decompress, deflate, gzip, inflate
Copyright © 2008 Donal K. Fellows