Scripting Laboratory: Shibashiba Dustproof API Room(05)

Tcl API一気に流し読み

　まずはTcl APIにはどんな関数があるのかざっと流し読みしてみましょう。色わけは私の独断でこんなかんじになっています：
赤…必須の基本的なAPIです
紫…本格的にやりこむにはこれらからお勧めします
緑…かなり濃いAPIです。必要になればマニュアルを読めばいいでしょう
青…通常の範囲で使うなら決して必要になるとは思えません

青色のAPIについては、ここでは紹介していません。それ以外のAPI のほとんどは本文中で一度は名前が出てくるでしょう。

関数のプロトタイプは、あまり重要でないものは省略してあります。また、Tcl_Interp* interp のように、変数名(interp)から変数の型(Tcl_Interp*) がすぐに推測できるものに関しては、変数の型を省略しています。

●インタープリタ管理

Tcl_Interp* Tcl_CreateInterp(void)
void Tcl_DeleteInterp(interp)
int Tcl_InterpDeleted(interp)
Tcl APIを使った独立したアプリケーションを作る場合、Tcl APIを利用する部分の最初でTcl_CreateInterpを呼び、最後にTcl_DeleteInterpを呼びます。interpは複数同時に作れますが、通常は一度に1つで十分です。

int Tcl_IsSafe(interp)
int Tcl_MakeSafe(interp)
Tcl_Interp* Tcl_CreateSlave(interp, char* slaveName, int safef)
Tcl_Interp* Tcl_GetSlave(interp, char* slaveName)
Tcl_Interp* Tcl_GetMaster(interp)
int Tcl_GetInterpPath(Tcl_Interp* askerInterp, Tcl_Interp* slaveInterp)
int Tcl_CreateAlias(Tcl_Interp* slaveInterp, char* srccmd, Tcl_Interp* targetInterp, char* targetcmd, int argc, char** argv)
int Tcl_CreateAliasObj(Tcl_Interp* slaveInterp, char* srccmd, Tcl_Interp* targetInterp, char* targetcmd, int objc, Tcl_Obj** objv)
int Tcl_GetAlias(Tcl_Interp* interp, char* srccmd, Tcl_Interp** targetInterpptr, char** targetcmdptr, int* argcptr, char*** argvptr)
int Tcl_GetAliasObj(Tcl_Interp* interp, char* srccmd, Tcl_Interp** targetInterpptr, char** targetcmdptr, int* objcptr, Tcl_Obj*** objvptr)
int Tcl_ExposeCommand(interp, char* hiddencmd, char* cmd)
int Tcl_HideCommand(interp, char* cmd, char* hiddencmd)
Tclコマンドを一時的に使用不能にしたりする関数群。Safe Tcl を作るのに使われているようですが、我々が使う必要はあまりないかも。ていうかポインタのポインタのポインタ乱射気味。

void Tcl_SetErrno(int errcode)
int Tcl_GetErrno(void)
エラーコード(ANSI CやPOSIX規格で言うerrno) を取得したりセットしたりする関数です。 errno.h の実装はシステムによってさまざまなので、直接 errno にアクセスする代わりにこれらを使え、と勧められています。ファイルを開いたりするAPI関数がOSレベルでエラーを起こしたとき（ファイルが存在しないのでオープンできないとか）、 Tcl_GetErrnoで対応するerrnoがゲットできます。

void Tcl_AddObjErrorInfo(interp, char* msg, length)
void Tcl_AddErrorInfo(interp, char* msg)
void Tcl_SetObjErrorCode(interp, Tcl_Obj* errobjptr)
void Tcl_SetErrorCode(interp, ele, ele..., NULL)
char* Tcl_PosixError(interp)
Tcl言語の大域変数errorInfoとerrorCodeを操作する関数群。例えばエラーが発生するまえにあらかじめこれらを使って、「現在これこれの処理を実行中…」とerrorInfoに書いておけば、エラーが発生したところで「ファイル ??? がない」というエラーメッセージを出すだけで、ユーザーには「現在これこれの処理を実行中、ファイル ??? がない」というふうに状況がわかるようになります。一番便利な Tcl_AddErrorInfo だけ使えておけばいいでしょう。なおOSレベルのエラーでerrnoがセットされたときにTcl_PosixError を呼ぶと、errnoの値をTcl変数errorCodeにセットした後、それに対応する POSIXのエラーメッセージ(strerror(errno)みたいなの)を返してきます。

int Tcl_SetRecursionLimit(interp, int depth)
いまいち使用価値がわかりません。

void Tcl_AllowExceptions(interp)
これもまず使いません。

void Tcl_FindExecutable(char* argv0)
CONST char* Tcl_GetNameOfExecutable(void)
Tcl_FindExecutableはTclライブラリがインストールされているパスを環境変数やレジストリなどを見ながら探すAPI関数で、8.1b2で突然必須のAPI になりました。後者はこのプログラムのフルパス([info nameofexecutable]と同じ)を返します。

int Tcl_PkgProvide(interp, char* name, char* version)
char* Tcl_PkgRequire(interp, char* name, char* version, int exact)
パッケージ管理を行う関数群です。Ｃで拡張パッケージを書いた場合、その(パッケージ名)_Init という自作関数の最後にTcl_PkgProvide を呼ぶのが正則の使い方のようです。Tcl_PkgRequire は他のパッケージに依存するパッケージをＣで自作するときに使うのでしょう。

void Tcl_SaveResult(interp, Tcl_SavedResult* stateptr)
void Tcl_RestoreResult(interp, Tcl_SavedResult* stateptr)
void Tcl_DiscardResult(Tcl_SavedResult* stateptr)
interpの現在の結果の状態を保存したり復元したりする関数群だそうです。

●オブジェクト操作

void Tcl_RegisterObjType(Tcl_ObjType* typeptr)
Tcl_ObjType* Tcl_GetObjType(char* typeName)
int Tcl_AppendAllObjTypes(interp, objptr)
int Tcl_ConvertToType(interp, objptr, Tcl_ObjType* typeptr)
Tcl_Objを使って何かのデータ構造(Tcl_ObjType)を作って操作する関数群です。線形リストのようなデータ構造を自作したいときに使うのですが、なかなか複雑です。

Tcl_Obj* Tcl_NewObj(void)
Tcl_Obj* Tcl_DuplicateObj(objptr)
void Tcl_IncrRefCount(objptr)
void Tcl_DecrRefCount(objptr)
int Tcl_IsShared(objptr)
void Tcl_InvalidateStringRep(objptr)
オブジェクト(Tcl_Obj)を操作する重要な関数群です。マニュアルではAPIを使うさいには内部データは全部オブジェクトとして扱うことが推奨されていますが、実際には文字列で扱うよりも (若干処理が高速ですが)書くのは面倒です。オブジェクトとして扱わざるをえないバイナリデータを扱うコマンドを作る場合を除けば、旧来の文字列を対象とした関数だけで済ますこともできます。最初から無理にこれらを使う必要はないかもしれません。

Tcl_Obj* Tcl_NewStringObj(char* bytes, int len)
void Tcl_SetStringObj(objptr, char* bytes, int len)
char* Tcl_GetStringFromObj(objptr, int len)
char* Tcl_GetString(objptr)
void Tcl_AppendToObj(objptr, char* bytes, int len)
void Tcl_AppendObjToObj(objptr, Tcl_Obj* appendedobjptr)
void Tcl_AppendStringsToObj(objptr, string, string, ..., NULL)
void Tcl_SetObjLength(objptr, int newlen)
Tcl_Obj* Tcl_ConcatObj(objc, objv)
Tclオブジェクトと文字列の間の相互変換を行う関数群です。バイナリデータを扱うコマンドを作るさいに多くの場合必要になるでしょう。そうでなければ無理に使う必要はないかもしれません。

Tcl_Obj* Tcl_NewBooleanObj(int boolval)
void Tcl_SetBooleanObj(objptr, boolval)
int Tcl_GetBooleanFromObj(interp, objptr, int* boolptr)
BOOL値を保持するTclオブジェクトを操作する関数です。 API内部には「BOOLEAN」を表す型は現れず、本質的にはintと同じ扱いのようです。

Tcl_Obj* Tcl_NewByteArrayObj(unsigned char* bytes, int len)
void Tcl_SetByteArrayObj(objptr, unsigned char* bytes, int len)
unsigned char* Tcl_GetByteArrayFromObj(objptr, int* lenptr)
unsigned char* Tcl_SetByteArrayLength(objptr, int len)
Tcl 8.1からは文字列の内部表現がUnicodeになったため、ネイティブなバイナリデータとその文字列表現は全く同じとは限りません。 ByteArray一族は Unicodeだのエンコーディングだのを無視して、ネイティブなバイナリデータとしてバイト列を扱うために Tcl 8.1で追加された関数群です。

Tcl_Obj* Tcl_NewDoubleObj(double v)
void Tcl_SetDoubleObj(objptr, double v)
int Tcl_GetDoubleFromObj(interp, objptr, double* vp)
Tcl_Obj* Tcl_NewIntObj(int v)
void Tcl_SetIntObj(objptr, int v)
int Tcl_GetIntFromObj(interp, objptr, int* vp)
Tcl_Obj* Tcl_NewLongObj(long v)
void Tcl_SetLongObj(objptr, long v)
int Tcl_GetLongFromObj(interp, objptr, long* vp)
それぞれDouble,Int,Long型の値とTclオブジェクトの相互変換をする関数です。

int Tcl_ListObjAppendList(interp, Tcl_Obj* listptr, Tcl_Obj* elemlptr)
int Tcl_ListObjAppendElement(interp, Tcl_Obj* listptr, Tcl_Obj* objptr)
Tcl_Obj* Tcl_NewListObj(objc, objv)
void Tcl_SetListObj(objptr, objc, objv)
int Tcl_ListObjGetElements(interp, Tcl_Obj* listptr, int* objcptr, Tcl_Obj*** objvptr)
int Tcl_ListObjLength(interp, Tcl_Obj* listptr, int* intptr)
int Tcl_ListObjIndex(interp, Tcl_Obj* listptr, int index, Tcl_Obj** objptrptr)
int Tcl_ListObjReplace(interp, Tcl_Obj* listptr, int first, int count, objc, objv)
バイナリデータからなるリストなどを扱うときに使うのでしょう。

●コマンドとコマンドプロシージャ

void Tcl_SetObjResult(interp, objptr)
Tcl_Obj* Tcl_GetObjResult(interp)
void Tcl_SetResult(interp, char* string, freeproc)
char* Tcl_GetStringResult(interp)
void Tcl_AppendResult(interp, string, string, ... NULL)
void Tcl_AppendElement(interp, string)
void Tcl_ResetResult(interp)
void Tcl_FreeResult(interp)
自分でTclコマンドを作ったとき、その「戻り値」を呼び出し元に返すために使われる重要な関数群です。マニュアルでは、「戻り値」をC型の文字列でしか返せない Tcl_AppendResult, Tcl_AppendElement, Tcl_SetResult は旧式扱いになっていて、代わりにTcl_SetObjResult の使用が推奨されています。また、その結果を格納している文字列へのポインタ interp->result を直接参照することもよくないとされ、結果をオブジェクトとして取り出す Tcl_GetObjResult または文字列として取り出す Tcl_GetStringResult を使うようにとのことです。

Tcl_Command Tcl_CreateCommand(interp, cmdname, proc, clientData, deleteproc)
Tcl_Command Tcl_CreateObjCommand(interp, cmdname, proc, clientData, deleteproc)
int Tcl_DeleteCommand(interp, cmdname)
int Tcl_DeleteCommandFromToken(interp, Tcl_Command token)
int Tcl_GetCommandInfo(interp, cmdname, Tcl_CmdInfo* infoptr)
int Tcl_SetCommandInfo(interp, cmdname, Tcl_CmdInfo* infoptr)
char* Tcl_GetCommandName(interp, Tcl_Command token)
重要な関数です。コマンドを自作するときに使います。 Tcl_CreateCommandで作るコマンドは、バイナリ文字列を引数に扱えません。バイナリ文字列を引数にとるコマンドを追加するには、 Tcl_CreateObjCommandが必要です。

●データ構造

void Tcl_DStringInit(dsp)
char* Tcl_DStringAppend(dsp,string,length)
char* Tcl_DStringAppendElement(dsp,string)
void Tcl_DStringStartSublist(dsp)
void Tcl_DStringEndSublist(dsp)
int Tcl_DStringLength(dsp)
char* Tcl_DStringValue(dsp)
void Tcl_DStringSetLength(dsp, length)
void Tcl_DStringFree(dsp)
void Tcl_DStringResult(dsp)
void Tcl_DStringGetResult(interp,dsp)

DString関連です。

ClientData Tcl_GetAssocData(interp, char* key, delprocptr)
void Tcl_SetAssocData(interp, char* key, delproc, clientData)
void Tcl_DeleteAssocData(interp, char* key)
interpごとに１つ作られるハッシュテーブルを操作する関数群です。インタープリタごとに保持させておきたい情報をユーザーが自由に決めて使うことができます。delprocは

void InterpDeleteProc(ClientData clientData, Tcl_Interp* interp)

の形をしている必要があり、delprocptrはそのポインタのポインタです。

Tcl_Encoding Tcl_GetEncoding(interp, char* ename)
void Tcl_FreeEncoding(Tcl_Encoding encoding)
int Tcl_ExternalToUtf(interp, Tcl_Encoding encoding, char* src, int srclen, int flags, Tcl_EncodingState* stateptr, char* dest, int destlen, int* srcreadptr, int* destwroteptr, int* destcharsptr)
void Tcl_ExternalToUtfDString(Tcl_Encoding encoding, char* src, int srclen, Tcl_DString* dsp)
int Tcl_UtfToExternal(interp, Tcl_Encoding encoding, char* src, int srclen, int flags, Tcl_EncodingState* stateptr, char* dest, int destlen, int* srcreadptr, int* destwroteptr, int* destcharsptr)
void Tcl_UtfToExternalDString(Tcl_Encoding encoding, char* src, int srclen, Tcl_DString* dsp)
char* Tcl_GetEncodingName(Tcl_Encoding encoding)
int Tcl_SetSystemEncoding(interp, char* ename)
void Tcl_GetEncodingNames(interp)
Tcl_Encoding Tcl_CreateEncoding(Tcl_EncodingType* typeptr)
char* Tcl_GetDefaultEncodingDir(void)
void Tcl_SetDefaultEncodingDir(char* path)
エンコーディング関係です。

Tcl_UniChar
Tcl_UniCharToUtf
Tcl_UtfToUniChar
Tcl_UtfToUniCharComplete
Tcl_NumUtfChars
Tcl_UtfFindFirst
Tcl_UtfFindLast
Tcl_UtfNext
Tcl_UtfPrev
Tcl_UniCharAtIndex
Tcl_UtfAtIndex
Tcl_UtfBackslash
UTF-8文字列を扱う関数群です。

void Tcl_InitHashTable(htable, int keytype)
void Tcl_DeleteHashTable(htable)
Tcl_HashEntry* Tcl_CreateHashEntry(htable,key,int* newp)
void Tcl_DeleteHashEntry(hentry)
Tcl_HashEntry* Tcl_FindHashEntry(htable,key)
ClientData Tcl_GetHashValue(hentry)
void Tcl_SetHashValue(hentry,ClientData value)
char* Tcl_GetHashKey(htable, hentry)
Tcl_HashEntry* Tcl_FirstHashEntry(htable,hsearch)
Tcl_HashEntry* Tcl_NextHashEntry(hsearch)
char* Tcl_HashStats(htable)
ハッシュテーブル関係

int Tcl_RegExpMatch(interp,string,pattern)
Tcl_RegExp Tcl_RegExpCompile(interp,pattern)
int Tcl_RegExpExec(interp,Tcl_RegExp regexp,string,char* stringheadptr)
void Tcl_RegExpRange(Tcl_RegExp regexp, int index, char** startptr, char** endptr)
正規表現関係

●コマンドと式の評価

int Tcl_EvalObjEx(interp, objptr, int flags)
int Tcl_EvalFile(interp, char* filename)
int Tcl_EvalObjv(interp, objc, objv, int flags)
int Tcl_Eval(interp, char* command)
int Tcl_EvalEx(interp, char* command, int length, int flags)
int Tcl_GlobalEval(interp, char* command)
int Tcl_GlobalEvalObj(interp, objptr, int flags)
int Tcl_VarEval(interp, string, ... , NULL)
int Tcl_VarEvalVA(interp, va_list valist)
文字列またはオブジェクトで指定されたコマンドを解釈実行します。ＣとTclをリンクするとき、最も気軽に使えるAPIで、恐らくほとんどのTcl APIプログラマはTcl_Evalから使い始めたことでしょう。現在では少し仕様が厳しくなり、 Tcl_Evalに渡すTclコマンドは書き込み可能なメモリ領域にないといけません。

int Tcl_RecordAndEval(interp, char* cmd, int flags)
int Tcl_RecordAndEvalObj(interp, Tcl_Obj* objptr, int flags)
ヒストリに記録しながら解釈実行します。

void Tcl_CreateMathFunc(interp, char* name, int argc, Tcl_ValueType* typeinit, proc, clientData)
式で使える新しい数学関数を追加する関数です。

int Tcl_ExprLong(interp, char* string, long* result)
int Tcl_ExprDouble(interp, char* string, double* result)
int Tcl_ExprBoolean(interp, char* string, int* result)
int Tcl_ExprString(interp, char* string)
int Tcl_ExprLongObj(interp, objptr, long* result)
int Tcl_ExprDoubleObj(interp, objptr, double* result)
int Tcl_ExprBooleanObj(interp, objptr, int* result)
int Tcl_ExprObj(interp, objptr, Tcl_Obj* resultobjptr
式の評価をします。式を文字列で渡すものとTclオブジェクトで渡すものの２系統、計８つの関数があります。結果はTcl_ExprString以外は全て第３引数で渡したアドレスに、 Tcl_ExprStringはinterp->resultに格納され、 TCL_OKまたはTCL_ERRORを返します。

●変数

Tcl_Obj* Tcl_SetVar2Ex(interp, name1, name2, newobjptr, int flags)
char* Tcl_SetVar(interp, varname, newstring, int flags)
char* Tcl_SetVar2(interp, name1, name2, newstring, int flags)
Tcl_Obj* Tcl_ObjSetVar2(interp, Tcl_Obj* p1ptr, Tcl_Obj* p2ptr, Tcl_Obj* newobj, int flags)
Tcl_Obj* Tcl_GetVar2Ex(interp, name1, name2, int flags)
char* Tcl_GetVar(interp, varname, int flags)
char* Tcl_GetVar2(interp, name1, name2, int flags)
Tcl_Obj* Tcl_ObjGetVar2(interp, Tcl_Obj* p1ptr, Tcl_Obj* p2ptr, int flags)
int Tcl_UnsetVar(interp, varname, int flags)
int Tcl_UnsetVar2(interp, name1, name2, int flags)
Tcl変数と文字列やオブジェクトの相互変換を行う関数群です。 Tcl言語の解釈機能をもつＣプログラムをAPIを使って作る場合はほぼ必ず使うことになるでしょう。変数の値としてバイナリデータが出てこない場合は Tcl_Evalなどで代用も効きますが、普遍的なTcl変数へのアクセスはこれらの関数群を使ったほうがよいでしょう。

int Tcl_LinkVar(interp, char* varname, char* addr, int type)
void Tcl_UnlinkVar(interp, char* varname)
void Tcl_UpdateLinkedVar(interp, char* varname)
Tcl変数とC変数のリンクを行う関数群です。片方の値の変化が他方にもすぐに反映されます。

int Tcl_UpVar(interp, char* frameName, char* srcName, char* destName, int flags)
int Tcl_UpVar2(interp, char* frameName, char* name1, char* name2, char* destName, int flags)
2つのTcl変数へのアクセスを「透過的」にする関数。同じ変数に複数の名前がついたような(正確ではないですが)状態になります。これはTcl言語のupvarコマンドを作るのに使われているようですが、我々がAPIを使うさいにはほとんど必要にならないでしょう。

●チャネルとファイルチャネル

Tcl_Channel Tcl_CreateChannel(Tcl_ChannelType* typeptr, char* channame, ClientData instancedata, int mask)
ClientData Tcl_GetChannelInstanceData(chan)
Tcl_ChannelType* Tcl_GetChannelType(chan)
char* Tcl_GetChannelName(chan)
int Tcl_GetChannelHandle(chan, int direction, ClientData* handlePtr)
int Tcl_GetChannelFlags(chan)
void Tcl_SetDefaultTranslation(chan, Tcl_EolTranslation transmode)
int Tcl_GetChannelBufferSize(chan)
void Tcl_SetChannelBufferSize(chan, int size)
void Tcl_NotifyChannel(chan, int mask)
int Tcl_BadChannelOption(interp, char* optionname, char* optionmode)
Tclチャネルを扱う最低位の関数群です。どれ１つとして覚えておく必要のある関数ではありません。

Tcl_Channel Tcl_OpenFileChannel(interp, char* filename, mode, perm)
Tcl_Channel Tcl_OpenCommandChannel(interp, argc, argv, flags)
Tcl_Channel Tcl_MakeFileChannel(int fd, int r_or_w)
Tcl_Channel Tcl_GetChannel(interp, channame, modeptr)
void Tcl_RegisterChannel(interp, chan)
int Tcl_UnregisterChannel(interp, chan)
int Tcl_Close(interp, chan)
int Tcl_ReadChars(chan, readobjptr, maxlen, aflag)
int Tcl_Read(chan, bytebuf, maxlen)
int Tcl_GetsObj(chan, lineobjptr)
int Tcl_Gets(chan, Tcl_DString* linebuf)
int Tcl_WriteObj(chan, writeobjptr)
int Tcl_WriteChars(chan, charbuf, maxlen)
int Tcl_Write(chan, bytebuf, maxlen)
int Tcl_Flush(chan)
int Tcl_Seek(chan, offset, seekmode)
int Tcl_Tell(chan)
int Tcl_GetChannelOption(interp, chan, optionname, optionval)
int Tcl_SetChannelOption(interp, chan, optionname, optionval)
int Tcl_Eof(chan)
int Tcl_InputBlocked(chan)
int Tcl_InputBuffered(chan)
int Tcl_GetOpenFile(interp,string,write,checkUsage,fileptr)
ファイルチャネルを扱う（大規模な）関数群です。御覧の通り、チャネル(Tcl_Channel)をFILE構造体やUNIXのファイル記述子に置きかえて考えれば、オープン、最大文字数指定リード (オブジェクトに読むものと文字列に読むものがある)、改行文字までのリード（同）、文字数指定ライト（同）、フラッシュ、シーク、現在の読み出し位置の取得（テル）、クローズ、それに非バッファリングI/O、非ブロッキングI/Oなどの指定に至るまでおよそＣでファイルI/Oに関して書けるものはほとんどこれで書けます。ただ、実際に自分で書くときにはファイルはやっぱりFILE 構造体で扱うほうが簡単なので、簡単なファイルI/O ならFILE構造体とfopen - fclose などの標準関数を使うとよいでしょう。ただし、これらの関数のうちTcl_ReadCharsなどはあらかじめ入力データを格納するための領域を確保する必要がないため、入力データサイズが予測できないバイト列をまるごと保持しておく必要がある場合にはとても便利です。以前この実験室では 8.1 になってバイナリデータがそのまま内部文字列に変換されないのはバグだバグだと言っていましたが、どうもこれが仕様のようです。というわけで、Tcl_ReadChars で読みこんだ文字列をネイティブなバイナリデータとして読み出すには 8.0 のときと全く違う処理になるので注意が必要です。
なお、UNIXやWindowsのファイル記述子とTcl_Channel構造体の相互変換、FILE構造体からTcl_Channel構造体への変換は上のように関数がありますが、Tcl_ChannelからFILE への変換はできないようになっています。

Tcl_Channel Tcl_OpenTcpClient(interp, int port, char* host, char* myaddr, myport, int async)
Tcl_Channel Tcl_MakeTcpClientChannel(ClientData sock)
Tcl_Channel Tcl_OpenTcpServer(interp, int port, char* myaddr, proc, clientData)
TCPソケットチャネルを扱う関数群です。

Tcl_CreateChannelHandler
Tcl_DeleteChannelHandler
Tcl_CreateCloseHandler
Tcl_DeleteCloseHandler
修業中

Tcl_CreateFileHandler
Tcl_DeleteFileHandler
修業中

●イベントとスレッド

Tcl_AsyncCreate
Tcl_AsyncMark
Tcl_AsyncInvoke
Tcl_AsyncDelete
Tcl_AsyncReady
修業中

Tcl_CreateEventSource
Tcl_DeleteEventSource
Tcl_SetMaxBlockTime
Tcl_QueueEvent
Tcl_DeleteEvents
Tcl_WaitForEvent
Tcl_SetTimer
Tcl_ServiceAll
Tcl_ServiceEvent
Tcl_GetServiceMode
Tcl_SetServiceMode
修業中

int Tcl_DoOneEvent(int flags)
イベントを待ち、対応するイベントハンドラを呼び出します。

void Tcl_BackgroundError(interp)
イベントハンドラ内で起きたエラーを処理系に伝えるために使う関数です。

void Tcl_CallWhenDeleted(interp, delproc, clientData)
Tcl_DontCallWhenDeleted(interp, delproc, clientData)
Tcl_DoWhenIdle(idleproc, clientData)
Tcl_CancelIdleCall(idleproc, clientData)
Tcl_CallWhenDeletedはインタープリタが消去される直前に呼ばれる関数を登録します。 Tcl_DoWhenIdleはインタープリタが次に「暇になった」瞬間に呼ばれる関数を登録します。 delprocは

  void InterpDeleteProc(ClientData clientData, Tcl_Interp* interp)

idleprocは

  void IdleProc(ClientData clientData)

の形をしている必要があります。

Tcl_ConditionNotify
Tcl_ConditionWait
Tcl_GetThreadData
Tcl_MutexLock
Tcl_MutexUnlock
これがうわさのスレッド操作関数群。わかんないけど…

Tcl_Exit
Tcl_Finalize
Tcl_FinalizeThread
Tcl_CreateExitHandler
Tcl_DeteleExitHandler
Tcl_CreateThreadExitHandler
Tcl_DeleteThreadExitHandler
これもスレッド関係か。難しい

Tcl_TimerToken Tcl_CreateTimerHandler(msec, proc, clientData)
Tcl_DeleteTimerHandler(Tcl_TimerToken token)
一定時間(msecミリ秒)後に指定したＣ関数を実行させる関数とそれを取り消す関数です。 Tkを使ったGUIアプリケーションなどで特に有効です。

●トレース

Tcl_Trace Tcl_CreateTrace(interp, int level, cmdtraceproc, clientData)
void Tcl_DeleteTrace(interp, Tcl_Trace trace)
Tclコマンドが呼び出される直前に呼ばれる関数を登録します。 levelは1(トップレベルのみ)2(下位階層も含め全部)から選びます。 cmdtraceprocは

  void CmdTraceProc(ClientData clientData, Tcl_Interp *interp,
	int level, char *command, Tcl_CmdProc *cmdProc,
	ClientData cmdClientData, int argc, char *argv[])

の形をしている必要があります。

int Tcl_TraceVar(interp, char* varname, int flags, proc, clientData)
int Tcl_TraceVar2(interp, char* name1, char* name2, int flags, proc, clientData)
void Tcl_UntraceVar(interp, char* varname, int flags, proc, clientData)
void Tcl_UntraceVar2(interp, char* name1, char* name2, int flags, proc, clientData)
ClientData Tcl_VarTraceInfo(interp, char* varname, int flags, proc, prevclientData)
ClientData Tcl_VarTraceInfo2(interp, char* name1, char* name2, int flags, proc, prevclientData)
Tcl変数のトレースを行います。トレースというとデバッグ作業を連想される方も多いと思いますが、それ以外にも便利に使えます。この機能をよく理解して駆使すると、いわゆる「データドリブンプログラミング」というすさまじいことも可能になります。

●プロセス

Tcl_DetachPids
Tcl_ReapDetachedProcs
修業中

Tcl_Channel Tcl_GetStdChannel(int type)
void Tcl_SetStdChannel(Tcl_Channel, int type)
Tclインタープリタのプロセスのstdin,stdout,stderrを変更できます。これはopen/execで開いたプロセスにも継承されます。

●ユーティリティ関数

int Tcl_GetIndexFromObj(interp, objptr, char** tableptr, char* msg, int flags, int indexptr)
Tcl_GetIndexFromObjStruct
自作Tclコマンドのオプションの解析に便利なユーティリティ関数です。

void Tcl_SplitPath(char* path, int* argcptr, char*** argvptr)
char* Tcl_JoinPath(int argc, char** argv, Tcl_DString* dsp)
Tcl_PathType Tcl_GetPathType(char* path)
プラットフォーム依存のパスの分割・接合をするユーティリティ関数です。 file splitコマンドやfile joinコマンドのＣレベルの関数です。 Tcl_SplitPathとTcl_JoinPathを続けて呼ぶと、連続するスラッシュ(UNIX)やバックスラッシュ(Windows)などを１つに縮めるなど、「正規化」した名前にすることができます。 Tcl_GetPathTypeは、指定されたパスが絶対パスか相対パスかを記号定数で返します。

Tcl_TranslateFileName
~(チルダ)記号をシステム依存のパスに変換するユーティリティ関数です。

int Tcl_GetInt(interp, string, int* result)
int Tcl_GetDouble(interp, string, double* result)
int Tcl_GetBoolean(interp, string, int* result)
文字列からそれぞれの型の値への変換をします。～FromObjのラインアップが Tcl_GetLongFromObj / Tcl_GetDoubleFromObj / Tcl_GetBooleanFromObj なのに比べて妙に整合性がないのが謎ですね。

int Tcl_CommandComplete(cmd)
文字列cmd内の{}などが対応がとれているかどうか調べる関数です。

char* Tcl_Concat(int argc, char* argv[])
与えられた文字列を全部つなげた文字列を返します。Tcl_Mergeと違って、結果が完全なTclリストになることは保証されません(大部分はリストになりますが)。結果はTcl_Allocで確保された領域に入っているので、必要がなくなったらTcl_Freeで解放します。

int Tcl_SplitList(interp, char* list, int* argcptr, char*** argvptr)
char* Tcl_Merge(int argc, char** argv)
Tcl_ScanElement
Tcl_ScanCountedElement
Tcl_ConvertElement
Tcl_ConvertCounterdElement
TclリストをDStringでなく文字列ベースで扱う関数群。 Tcl_Scan～以下はTcl_Mergeの下請け関数で、普段は特に使わないでしょう。

int Tcl_StringMatch(char* string, char* pattern)
string matchコマンドと同様の簡単な文字列照合をするユーティリティ関数です。複雑なものは正規表現を扱う関数を使うとよいでしょう。

char* Tcl_Alloc(int size)
void Tcl_Free(char* ptr)
char* Tcl_Realloc(char* ptr, int size)
それぞれANSI標準のmalloc,free,realloc関数と使い方は同じです。 TclとCを混ぜるときにはできるだけこれらを使うほうがいいでしょう。

Tcl_Preserve(clientData)
Tcl_Release(clientData)
Tcl_EventuallyFree(clientData, freeproc)
これらが追加された経緯はマニュアルをご覧ください。普通に使う限りではまず使わないでしょう。

Tcl_PrintDouble
Double数を文字列に変換するユーティリティ関数です。

void Tcl_Sleep(int msec)
お休み関数

void Tcl_StaticPackage(interp, char* pkgname, initproc, safeinitproc)
これはなんぞ？

void Tcl_WrongNumArgs(interp, objc, objv, message)
コマンドプロシージャを書くとき、引数の数が違う場合のエラーメッセージを簡便につくってくれるユーティリティ関数です。ただ、オブジェクトで指定しないといけません。

(first uploaded 1999/03/12 last updated 2000/11/28 , Urano398 - EK )