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

### 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_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand — 命令の改名と削除を監視する　 monitor renames and deletes of a command
  SYNOPSIS
    #include <tcl.h>
    ClientData
    Tcl_CommandTraceInfo(interp, cmdName, flags, proc, prevClientData)
    int
    Tcl_TraceCommand(interp, cmdName, flags, proc, clientData)
    void
    Tcl_UntraceCommand(interp, cmdName, flags, proc, clientData)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    const char *cmdName (入力in)
    int flags (入力in)
    Tcl_CommandTraceProc *proc (入力in)
    ClientData clientData (入力in)
    ClientData prevClientData (入力in)
  説明 DESCRIPTION
    TCL_TRACE_RENAME
    TCL_TRACE_DELETE
  追跡中の命令呼出 CALLING COMMANDS DURING TRACES
  多重追跡 MULTIPLE TRACES
  TCL_TRACE_DESTROYED FLAG
  KEYWORDS

### NAME

Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand — 命令の改名と削除を監視する　 monitor renames and deletes of a command

### SYNOPSIS

#include <tcl.h>
ClientData
Tcl_CommandTraceInfo(interp, cmdName, flags, proc, prevClientData)
int
Tcl_TraceCommand(interp, cmdName, flags, proc, clientData)
void
Tcl_UntraceCommand(interp, cmdName, flags, proc, clientData)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  命令を含んでいる解釈実行機能｡　 Interpreter containing the command.

const char *cmdName (入力in)
  命令の名前｡　 Name of command.

int flags (入力in)
  TCL_TRACE_RENAME と TCL_TRACE_DELETE の値の論理和の集まり｡　 OR'ed collection of the values TCL_TRACE_RENAME and TCL_TRACE_DELETE.

Tcl_CommandTraceProc *proc (入力in)
  指定された操作が cmdName に生じた時に呼ぶ手続函数｡　 Procedure to call when specified operations occur to cmdName.

ClientData clientData (入力in)
  手続函数に渡す任意の引数｡　 Arbitrary argument to pass to proc.

ClientData prevClientData (入力in)
  もし非-NULL なら､Tcl_CommandTraceInfo によって返される最後の値を与える､それでこの呼出は次の追跡に関する情報を返すことになる｡もし NULL ならこの呼出しは最初の追跡に関する情報を返す｡　 If non-NULL, gives last value returned by Tcl_CommandTraceInfo, so this call will return information about next trace. If NULL, this call will return information about first trace.

### 説明 DESCRIPTION

Tcl_TraceCommand は Tcl 命令上で操作が遂行されていることを監視することを C 手続き函数 に許容する､それ故に C 手続き函数は何時であれ命令が名前変更されるか削除されると起動される｡もし追跡が成功裡に生成されると､ Tcl_TraceCommand は TCL_OK を返す｡もし不都合が生じると(譬えば､cmdName が実在しない命令を指定する) TCL_ERROR が返され､不都合伝言文が解釈実行機能の結果内に残される｡ Tcl_TraceCommand allows a C procedure to monitor operations performed on a Tcl command, so that the C procedure is invoked whenever the command is renamed or deleted. If the trace is created successfully then Tcl_TraceCommand returns TCL_OK. If an error occurred (e.g. cmdName specifies a non-existent command) then TCL_ERROR is returned and an error message is left in the interpreter's result.

Tcl_TraceCommand への flags 引数は追跡手続き函数が起動されるべき時期を指し示す｡それは次の値のどれかの論理和の組合せで構成される｡ The flags argument to Tcl_TraceCommand indicates when the trace procedure is to be invoked. It consists of an OR'ed combination of any of the following values:

TCL_TRACE_RENAME
  何時であれ命令が改名された時に proc を起動する｡ Invoke proc whenever the command is renamed.

TCL_TRACE_DELETE
  命令が取除かれた時に proc を起動する｡ Invoke proc when the command is deleted.

何時であれ命令に対する指定された操作の内の一つが起ると､ proc が起動される｡それは､Tcl_CommandTraceProc の型に合致する引数と結果を有するべきである: Whenever one of the specified operations occurs to the command, proc will be invoked. It should have arguments and result that match the type Tcl_CommandTraceProc:

    typedef void Tcl_CommandTraceProc(
            ClientData clientData,
            Tcl_Interp *interp,
            const char *oldName,
            const char *newName,
            int flags);

clientData と interp 假引数は追跡が作成された時に Tcl_TraceCommand に渡されたものと同じ値を有する｡ clientData は典型的には proc が起動された時になすべきことを記載してある応用譜固有のデータ構造を指す｡OldName は､変更される命令の名前を与える､そしてnewName は､それに換えるべき名前(若しくは､命令を削除する場合は NULL )を与える｡ flags は幾つかの情報を潜在的に与えるビットを論理和で結合している｡命令のどの操作が遂行されたかを指し示す為に､ TCL_TRACE_RENAME と TCL_TRACE_DELETE ビットの内の一つが flags 内に設定される｡もし､追跡が破壊されようとする場合､ flags 内に TCL_TRACE_DESTROYED のビットが設定される; この情報は proc に対して便利である､そこで自身の内部データ構造を清掃できる(更なる詳細については下の TCL_TRACE_DESTROYED を参照されたい)｡命令の削除は､それを含む解釈実行機能の削除として起り得るので､実行させる為に解釈実行機能にどのような値が渡されるかの確認に proc は充分注意しなくてはならない｡この目的に Tcl_InterpDeleted 業務は重要な道具である｡ Tcl_InterpDeleted が 1 を返す時､ proc は解釈実行機能内のどの記述譜も起動することはできない｡環境内の proc の機能はそれ自身のデータの清掃に限定される｡ The clientData and interp parameters will have the same values as those passed to Tcl_TraceCommand when the trace was created. ClientData typically points to an application-specific data structure that describes what to do when proc is invoked. OldName gives the name of the command being renamed, and newName gives the name that the command is being renamed to (or NULL when the command is being deleted.) Flags is an OR'ed combination of bits potentially providing several pieces of information. One of the bits TCL_TRACE_RENAME and TCL_TRACE_DELETE will be set in flags to indicate which operation is being performed on the command. The bit TCL_TRACE_DESTROYED will be set in flags if the trace is about to be destroyed; this information may be useful to proc so that it can clean up its own internal data structures (see the section TCL_TRACE_DESTROYED below for more details). Because the deletion of commands can take place as part of the deletion of the interp that contains them, proc must be careful about checking what the passed in interp value can be called upon to do. The routine Tcl_InterpDeleted is an important tool for this. When Tcl_InterpDeleted returns 1, proc will not be able to invoke any scripts in interp. The function of proc in that circumstance is limited to the cleanup of its own data structures.

Tcl_UntraceCommand は､追跡の取去りにも使える｡もし､命令が interp により指定され､且つ､ cmdName と flags が flagsと proc と clientData により追跡を設定させた場合､対応する追跡が取去られる｡もしこのような追跡が実在しない場合Tcl_UntraceCommand の呼出しは効果を有さない｡ flags ではTcl_UntraceCommand の呼出しと同じビットが有効である｡ Tcl_UntraceCommand may be used to remove a trace. If the command specified by interp, cmdName, and flags has a trace set with flags, proc, and clientData, then the corresponding trace is removed. If no such trace exists, then the call to Tcl_UntraceCommand has no effect. The same bits are valid for flags as for calls to Tcl_TraceCommand.

Tcl_CommandTraceInfo は､与えられた命令への追跡に関する情報の取得に使える｡ Tcl_CommandTraceInfo からの返り値は特定の追跡に結びついた clientData である｡その追跡は interp,と cmdName と flags 引数により指定された命令である(註意すべきは､現在は旗標は無視されている; flags は将来の互換性を保つ為に 0 に設定しておくべきである)｡又その追跡手続函数はproc 引数と同じでなければならない｡もし prevClientData 引数が NULL である場合､返り値は追跡に合致する最初(最も最近作成された)と対応するか､合致する追跡がない場合は NULL である｡もし prevClientData が NULL でない場合それは以前のTcl_CommandTraceInfo への呼び出しの値が返る筈である｡この場合､新しい返り値は､そのclientData が prevClientData,に合致するか､もし prevClientData に合致する追跡がない場合にはNULL であるか､其の後には合致するような追跡が全くないような､それの後に合致する次の合致の追跡に対応する｡この仕組みにより､同じ proc を有する様な与えられた命令の為の追跡は全て飛越しさせることが可能になる｡ Tcl_CommandTraceInfo may be used to retrieve information about traces set on a given command. The return value from Tcl_CommandTraceInfo is the clientData associated with a particular trace. The trace must be on the command specified by the interp, cmdName, and flags arguments (note that currently the flags are ignored; flags should be set to 0 for future compatibility) and its trace procedure must the same as the proc argument. If the prevClientData argument is NULL then the return value corresponds to the first (most recently created) matching trace, or NULL if there are no matching traces. If the prevClientData argument is not NULL, then it should be the return value from a previous call to Tcl_CommandTraceInfo. In this case, the new return value will correspond to the next matching trace after the one whose clientData matches prevClientData, or NULL if no trace matches prevClientData or if there are no more matching traces after it. This mechanism makes it possible to step through all of the traces for a given command that have the same proc.

### 追跡中の命令呼出 CALLING COMMANDS DURING TRACES

名前変更の追跡の間､名前変更された命令が同時に両方の名前で可視である､又､削除の追跡の間､解釈実行機能が命令を含んでいる限りは､その命令が存在する｡しかし､追跡手続函数内で起った不都合を告げる仕組みは存在しないので､不都合が報告なしに失われない様細心の注意が必要である｡しかし､追跡手続の間に生じた不都合を伝達する仕組みがないので､不都合が少しでも損なわれないように最大限註意する必要がある｡ During rename traces, the command being renamed is visible with both names simultaneously, and the command still exists during delete traces, unless the interp that contains it is being deleted. However, there is no mechanism for signaling that an error occurred in a trace procedure, so great care should be taken that errors do not get silently lost.

### 多重追跡 MULTIPLE TRACES

同じ命令上に複数の追跡が存在する事は可能である｡この状態が生じたとき､全ての追跡手続函数がそれぞれの利用毎に起動される､最も最近作成されたものから､最も以前に作成されたものの順になる｡削除の追跡中の命令の削除の試みは報告無く失敗する､理由はその命令は既に何かの削除に組み入れられているから｡名前変更している命令が､名前変更追跡の内の一つにより名前変更されると､追跡を起動されたものに名前変更が優先し､追跡の訂正は再実行されない; もし､幾つかの追跡が命令の名前を変更する場合､最後の名前変更が優先される｡ It is possible for multiple traces to exist on the same command. When this happens, all of the trace procedures will be invoked on each access, in order from most-recently-created to least-recently-created. Attempts to delete the command during a delete trace will fail silently, since the command is already scheduled for deletion anyway. If the command being renamed is renamed by one of its rename traces, that renaming takes precedence over the one that triggered the trace and the collection of traces will not be reexecuted; if several traces rename the command, the last renaming takes precedence.

### TCL_TRACE_DESTROYED FLAG

proc への回答の削除内でTCL_TRACE_DESTROYED ビットが flags 内に設定される｡ In a delete callback to proc, the TCL_TRACE_DESTROYED bit is set in flags.

### KEYWORDS

clientData, trace, command
Copyright © 2002 Donal K. Fellows