## Tcl9.0.3/Tk9.0.3 Documentation > Tcl C API > TraceVar

### 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_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 — 変数の利用を監視する monitor accesses to a variable
  SYNOPSIS
    #include <tcl.h>
    int
    Tcl_TraceVar(interp, varName, flags, proc, clientData)
    int
    Tcl_TraceVar2(interp, name1, name2, flags, proc, clientData)
    Tcl_UntraceVar(interp, varName, flags, proc, clientData)
    Tcl_UntraceVar2(interp, name1, name2, flags, proc, clientData)
    void *
    Tcl_VarTraceInfo(interp, varName, flags, proc, prevClientData)
    void *
    Tcl_VarTraceInfo2(interp, name1, name2, flags, proc, prevClientData)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    const char *varName (入力in)
    int flags (入力in)
    Tcl_VarTraceProc *proc (入力in)
    void *clientData (入力in)
    const char *name1 (入力in)
    const char *name2 (入力in)
    void *prevClientData (入力in)
  説明 DESCRIPTION
    TCL_GLOBAL_ONLY
    TCL_NAMESPACE_ONLY
    TCL_TRACE_READS
    TCL_TRACE_WRITES
    TCL_TRACE_UNSETS
    TCL_TRACE_ARRAY
    TCL_TRACE_RESULT_DYNAMIC
    TCL_TRACE_RESULT_OBJECT
  TWO-PART NAMES
  ACCESSING VARIABLES DURING TRACES
  CALLBACK TIMING
  配列全体の追跡 WHOLE-ARRAY TRACES
  多重追跡 MULTIPLE TRACES
  ERROR RETURNS
  制限事項 RESTRICTIONS
  未定義の変数 UNDEFINED VARIABLES
  TCL_TRACE_DESTROYED FLAG
  参照回数管理 REFERENCE COUNT MANAGEMENT
  瑕疵 BUGS
  SEE ALSO
  KEYWORDS

### NAME

Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 — 変数の利用を監視する monitor accesses to a variable

### SYNOPSIS

#include <tcl.h>
int
Tcl_TraceVar(interp, varName, flags, proc, clientData)
int
Tcl_TraceVar2(interp, name1, name2, flags, proc, clientData)
Tcl_UntraceVar(interp, varName, flags, proc, clientData)
Tcl_UntraceVar2(interp, name1, name2, flags, proc, clientData)
void *
Tcl_VarTraceInfo(interp, varName, flags, proc, prevClientData)
void *
Tcl_VarTraceInfo2(interp, name1, name2, flags, proc, prevClientData)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  変数を含んでいる解釈実行機能｡　 Interpreter containing variable.

const char *varName (入力in)
  変数の名前｡スカラー変数でも､配列変数を索引なしの配列変数でも､括弧で括られた索引を伴う配列変数でも参照してもよい｡　 Name of variable. May refer to a scalar variable, to an array variable with no index, or to an array variable with a parenthesized index.

int flags (入力in)
  TCL_TRACE_READS と TCL_TRACE_WRITES と TCL_TRACE_UNSETS と TCL_TRACE_ARRAY と TCL_GLOBAL_ONLY と TCL_NAMESPACE_ONLY と TCL_TRACE_RESULT_DYNAMIC と TCL_TRACE_RESULT_OBJECT の値の論理和の組合わせ｡必ずしも､全ての旗印が全ての手続函数で使われるわけではない｡詳細については下記を参照されたい｡　　 OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES, TCL_TRACE_UNSETS, TCL_TRACE_ARRAY, TCL_GLOBAL_ONLY, TCL_NAMESPACE_ONLY, TCL_TRACE_RESULT_DYNAMIC and TCL_TRACE_RESULT_OBJECT. Not all flags are used by all procedures. See below for more information.

Tcl_VarTraceProc *proc (入力in)
  いつであれ､追跡された操作の内の一つが生じると起動する手続函数｡　 Procedure to invoke whenever one of the traced operations occurs.

void *clientData (入力in)
  手続函数に渡す任意の一語値｡　 Arbitrary one-word value to pass to proc.

const char *name1 (入力in)
  スカラー又は配列変数(配列索引なし)の名前｡　 Name of scalar or array variable (without array index).

const char *name2 (入力in)
  配列の要素の追跡では､要素の索引を与える｡スカラー変数､又は配列全体の追跡では NULL である｡　 For a trace on an element of an array, gives the index of the element. For traces on scalar variables or on whole arrays, is NULL.

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

### 説明 DESCRIPTION

Tcl_TraceVar は､ Tcl 変数の利用を監視し制御する為の C 言語手続函数を許容する､そこで C 言語手続函数はいつであれ変数が読み､書き､消去されるときは起動される｡もし追跡が成功裏に作成されると Tcl_TraceVar は TCL_OK を返す｡もし不都合が生じた場合は(譬えば varName が配列の要素を指定するが､実際の変数は配列ではない場合)は TCL_ERROR 返され､不都合伝言文が解釈実行機能の結果に残される｡ Tcl_TraceVar allows a C procedure to monitor and control access to a Tcl variable, so that the C procedure is invoked whenever the variable is read or written or unset. If the trace is created successfully then Tcl_TraceVar returns TCL_OK. If an error occurred (e.g. varName specifies an element of an array, but the actual variable is not an array) then TCL_ERROR is returned and an error message is left in the interpreter's result.

Tcl_TraceVar に対する flags 引数は､追跡手続函数が何時起動されるかを指し示し､追跡を設定する為の情報を提供する｡それは次のどれかの値を若しくはの組合せで構成する: The flags argument to Tcl_TraceVar indicates when the trace procedure is to be invoked and provides information for setting up the trace. It consists of an OR-ed combination of any of the following values:

TCL_GLOBAL_ONLY
  通常､変数は現在の水準の手続函数呼出しで捜される; もしこのビットが設定されていると変数は大域水準で捜され､どの活性化した手続函数も無視される｡ Normally, the variable will be looked up at the current level of procedure call; if this bit is set then the variable will be looked up at global level, ignoring any active procedures.

TCL_NAMESPACE_ONLY
  通常､変数は現在の水準の手続函数呼出しで捜される;もしこのビットが設定されていると変数は現在の名前空間内で捜され､どの活性化した手続函数も無視される｡ Normally, the variable will be looked up at the current level of procedure call; if this bit is set then the variable will be looked up in the current namespace, ignoring any active procedures.

TCL_TRACE_READS
  変数を読み込む試みがなされるといつでも proc を起動する｡ Invoke proc whenever an attempt is made to read the variable.

TCL_TRACE_WRITES
  変数を修正する試みがなされるといつでも proc を起動する｡ Invoke proc whenever an attempt is made to modify the variable.

TCL_TRACE_UNSETS
  変数を消去する試みがなされるといつでも proc を起動する｡変数は unset 命令によって明示的に､又は手続函数からの返り(局所変数は自動的に消去される)とか､解釈実行機能や名前空間の削除(全ての変数は自動的に消去される)により暗示的に消去されてもよい｡ Invoke proc whenever the variable is unset. A variable may be unset either explicitly by an unset command, or implicitly when a procedure returns (its local variables are automatically unset) or when the interpreter or namespace is deleted (all variables are automatically unset).

TCL_TRACE_ARRAY
  配列命令が起動されるといつでも proc を起動する｡これは追跡手続函数に配列名や配列呼び出しの前に配列を更新する機会を与える｡註意すべきはこれは配列が設定される前に呼ばれるが､それが追跡書き込みを起動する｡ Invoke proc whenever the array command is invoked. This gives the trace procedure a chance to update the array before array names or array get is called. Note that this is called before an array set, but that will trigger write traces.

TCL_TRACE_RESULT_DYNAMIC
  proc を起動した結果は動的に割当てたれた文字列であって､ Tcl_Free の呼出し経由で Tcl 外部函数によって解放される｡同時に TCL_TRACE_RESULT_OBJECT として指定されてはならない｡ The result of invoking the proc is a dynamically allocated string that will be released by the Tcl library via a call to Tcl_Free. Must not be specified at the same time as TCL_TRACE_RESULT_OBJECT.

TCL_TRACE_RESULT_OBJECT
  proc を起動した結果は少なくとも１の参照回数のある Tcl_Obj* ( char*へのcast)である｡あの参照の所有は Tcl_DecrRefCount への呼出しを経由して解放する為に Tcl の核に移転される(核がそれと一緒に終了する時に)｡同時に TCL_TRACE_RESULT_DYNAMIC として指定されてはならない｡ The result of invoking the proc is a Tcl_Obj* (cast to a char*) with a reference count of at least one. The ownership of that reference will be transferred to the Tcl core for release (when the core has finished with it) via a call to Tcl_DecrRefCount. Must not be specified at the same time as TCL_TRACE_RESULT_DYNAMIC.

何時であれ､指定された操作の内の一つが変数上に起ると､ proc が起動される｡それは､ Tcl_VarTraceProc の型と合致する引数と結果を有するであろう: Whenever one of the specified operations occurs on the variable, proc will be invoked. It should have arguments and result that match the type Tcl_VarTraceProc:

    typedef char *Tcl_VarTraceProc(
            void *clientData,
            Tcl_Interp *interp,
            const char *name1,
            const char *name2,
            int flags);

その clientData と interp 假引数は､追跡が生成された時に Tcl_TraceVar に渡されたのと同じ値を有する｡ clientData は典型的には proc が起動された時に何をなすべきかを記述した応用譜固有のデータ構造を指し示す｡ Name1 と name2は､ 二つの通常の形式内の呼戻しに起動された､変数の名前を与える(詳細は､下のTcl_TraceVar2の記述を参照されたい)｡ name1が､ (upvarの様な設備によって生成された) 配列要素のショートカットの場合､ name2は､ヌルより寧ろ､配列要素の索引を保持する｡ flagsは､幾つかの情報の断片を提供する論理OR集合である｡ TCL_TRACE_READS か TCL_TRACE_WRITES か TCL_TRACE_ARRAY, か TCL_TRACE_UNSETS かのビットの内の一つが flags に設定され､どの操作が変数に遂行されてるかを指し示す｡ 利用されている変数が大局のもので現在の水準の手続函数呼出しからは利用できない場合は何時でも TCL_GLOBAL_ONLY のビットが設定される: 追跡手続函数は､もしこの変数の利用を試みる場合は､ Tcl_GetVar の様な変数解除手続函数にこの旗印を送り返す必要がある｡ 利用されている変数が名前空間のもので現在の水準の手続函数呼出しからは利用できない場合は何時でも TCL_NAMESPACE_ONLY のビットが設定される: 追跡手続函数は､もしこの変数を利用する場合は､ Tcl_GetVar の様な変数解除手続函数にこの旗印を送り返す必要がある｡ 追跡している対象が破壊された場合は TCL_TRACE_DESTROYED ビットが flags 内に設定される; この情報は proc に対して便利であり､それによりそれ自身の内部データ構造を浄化することが可能である(更なる詳細は下の TCL_TRACE_DESTROYED の項を参照されたい)｡ 追跡手続き函数が返す値は､通常はヌルの筈; 他の可能性の情報は下のERROR RETURNSを参照されたい｡ The clientData and interp parameters will have the same values as those passed to Tcl_TraceVar when the trace was created. clientData typically points to an application-specific data structure that describes what to do when proc is invoked. Name1 and name2 give the name of the variable that triggered the callback in the normal two-part form (see the description of Tcl_TraceVar2 below for details). In case name1 is an alias to an array element (created through facilities such as upvar), name2 holds the index of the array element, rather than NULL. Flags is an OR-ed combination of bits providing several pieces of information. One of the bits TCL_TRACE_READS, TCL_TRACE_WRITES, TCL_TRACE_ARRAY, or TCL_TRACE_UNSETS will be set in flags to indicate which operation is being performed on the variable. The bit TCL_GLOBAL_ONLY will be set whenever the variable being accessed is a global one not accessible from the current level of procedure call: the trace procedure will need to pass this flag back to variable-related procedures like Tcl_GetVar if it attempts to access the variable. The bit TCL_NAMESPACE_ONLY will be set whenever the variable being accessed is a namespace one not accessible from the current level of procedure call: the trace procedure will need to pass this flag back to variable-related procedures like Tcl_GetVar if it attempts to access the variable. 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). The trace procedure's return value should normally be NULL; see ERROR RETURNS below for information on other possibilities.

Tcl_UntraceVar は追跡を取除く為に使用してもよい｡もし interp によって指定され､varName と flags が flags と proc と clientData とによって追跡を設定させた場合､対応する追跡が取除かれる｡もしこの様な追跡がない場合､ Tcl_UntraceVar の呼出しは効果を有さない｡同じビットは Tcl_TraceVar の呼出しに対する flags にも有効である｡ Tcl_UntraceVar may be used to remove a trace. If the variable specified by interp, varName, 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_UntraceVar has no effect. The same bits are valid for flags as for calls to Tcl_TraceVar.

Tcl_VarTraceInfo は与えられた変数上に設定された追跡の情報の取出しに使い得る｡ Tcl_VarTraceInfo からの返り値は特定の追跡に結合した clientData である｡追跡は interp,により指定された変数 varName,上でなければならず､ flags 引数( flags の TCL_GLOBAL_ONLY と TCL_NAMESPACE_ONLY ビットのみが使われる; 他のビットは無視される)とその設定手続函数は proc 引数と同じでなければならない｡もし prevClientData 引数が NULL の場合､第１(最も最近に作成された)に相当する返り値は追跡に合致するか､追跡に合致するものがなければ NULL になる｡もし､ prevClientData 引数が NULL でない場合､その前の Tcl_VarTraceInfo.呼出しの返り値であろう｡この場合､新しい返り値は､その clientData が prevClientData,に合致する後の､次の合致した追跡に相当する､但し､もしその後に合致する追跡がない時は NULL になる｡この仕組みは､同じ proc.を有するような与えられた変数の為の全ての追跡を進めることを可能にする｡ Tcl_VarTraceInfo may be used to retrieve information about traces set on a given variable. The return value from Tcl_VarTraceInfo is the clientData associated with a particular trace. The trace must be on the variable specified by the interp, varName, and flags arguments (only the TCL_GLOBAL_ONLY and TCL_NAMESPACE_ONLY bits from flags is used; other bits are ignored) 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_VarTraceInfo. 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 variable that have the same proc.

### TWO-PART NAMES

手続函数 Tcl_TraceVar2, Tcl_UntraceVar2, and Tcl_VarTraceInfo2 は変数の名前が二つの部分からなることを除き､それぞれ Tcl_TraceVar, Tcl_UntraceVar, と Tcl_VarTraceInfo,と同じである｡ Name1 は単純変数か配列かの名前を与え､ name2 は配列内の要素の名前を与える｡ name2 が NULL,の時､name1 は配列か要素の両方を含むかもしれない: もし名前が左括弧を含み､右括弧で終っていると括弧の間の値は要素の名前として扱われる(それはどのような文字列も有し得る)､又初めの左括弧の前の文字並びは配列変数の名前として扱われる｡もし name2 が NULL で且つ name1 が配列要素を参照しない場合､変数は単純変数であるか追跡が個別の要素ではなく配列全体に設定されたことを意味する(更なる情報は下の WHOLE-ARRAY TRACES を参照されたい)｡ The procedures Tcl_TraceVar2, Tcl_UntraceVar2, and Tcl_VarTraceInfo2 are identical to Tcl_TraceVar, Tcl_UntraceVar, and Tcl_VarTraceInfo, respectively, except that the name of the variable consists of two parts. Name1 gives the name of a scalar variable or array, and name2 gives the name of an element within an array. When name2 is NULL, name1 may contain both an array and an element name: if the name contains an open parenthesis and ends with a close parenthesis, then the value between the parentheses is treated as an element name (which can have any string value) and the characters before the first open parenthesis are treated as the name of an array variable. If name2 is NULL and name1 does not refer to an array element it means that either the variable is a scalar or the trace is to be set on the entire array rather than an individual element (see WHOLE-ARRAY TRACES below for more information).

### ACCESSING VARIABLES DURING TRACES

読み､書き､配列追跡の間､追跡手続函数は Tcl_GetVar2,と Tcl_SetVar2, と他の手続函数を使用して変数を読み､書き､削除することができる｡ proc が実行されている間追跡は一時的に変数について無力になる､従って Tcl_GetVar2 と Tcl_SetVar2 への呼出しは､ proc や他の追跡手続函数を再起動することにはならない｡無力化は､それへの追跡手続函数が活動状態である変数に対してのみ起る; 他の変数への利用は猶追跡されている｡しかし､もし変数が､追跡の読み書き中に削除された場合､削除追跡が起動される｡ During read, write, and array traces, the trace procedure can read, write, or unset the traced variable using Tcl_GetVar2, Tcl_SetVar2, and other procedures. While proc is executing, traces are temporarily disabled for the variable, so that calls to Tcl_GetVar2 and Tcl_SetVar2 will not cause proc or other trace procedures to be invoked again. Disabling only occurs for the variable whose trace procedure is active; accesses to other variables will still be traced. However, if a variable is unset during a read or write trace then unset traces will be invoked.

削除の追跡の間変数は既に完全に削除されている｡追跡手続函数の為に変数を読み書きすることは可能であるが､これは変数の新しい版である｡削除追跡の間は読み書きの追跡としての追跡は不能であるが､どれかの追跡手続函数が起動される前に既存の追跡は取除かれる｡削除追跡手続函数によって新しい追跡が設定された場合､この追跡は追跡手続函数により変数の利用で起動される｡ During unset traces the variable has already been completely expunged. It is possible for the trace procedure to read or write the variable, but this will be a new version of the variable. Traces are not disabled during unset traces as they are for read and write traces, but existing traces have been removed from the variable before any trace procedures are invoked. If new traces are set by unset trace procedures, these traces will be invoked on accesses to the variable by the trace procedures.

### CALLBACK TIMING

読み追跡が変数に指定された時､変数の値が読まれた時はいつであれ､その追跡手続函数は起動される｡これはTcl の set 命令､ Tcl 命令内の$-記法､及び Tcl_GetVar と Tcl_GetVar2 手続函数の起動を含む｡ Proc は変数の値が返る直前に起動される｡それは､追跡された接見により返されたことに影響する為に変数の値を修正しうる｡もしそれが変数を削除する場合､接見は恰も変数が決して実在しないかの如く､接見が不都合を返す｡ When read tracing has been specified for a variable, the trace procedure will be invoked whenever the variable's value is read. This includes set Tcl commands, $-notation in Tcl commands, and invocations of the Tcl_GetVar and Tcl_GetVar2 procedures. Proc is invoked just before the variable's value is returned. It may modify the value of the variable to affect what is returned by the traced access. If it unsets the variable then the access will return an error just as if the variable never existed.

変数に対して記入追跡が指定された時､その追跡手続函数は何時であれ変数の値が修正されたときに起動される｡これは set 命令と､副作用として変数を修正する命令と( catch や scan の様な)､Tcl_SetVar と Tcl_SetVar2 手続の呼出しをを含む｡ Proc は変数の修正の後だが､変数の新しい値が返される前に起動される｡それは､変化を上書きする為に､又追跡の接見により実際に返された値を定める為に､変数の値を修正するかもしれない｡もしそれが変数を削除した場合､追跡された接見は空文字列を返す｡ When write tracing has been specified for a variable, the trace procedure will be invoked whenever the variable's value is modified. This includes set commands, commands that modify variables as side effects (such as catch and scan), and calls to the Tcl_SetVar and Tcl_SetVar2 procedures). Proc will be invoked after the variable's value has been modified, but before the new value of the variable has been returned. It may modify the value of the variable to override the change and to determine the value actually returned by the traced access. If it deletes the variable then the traced access will return an empty string.

配列の追跡が指定された時､追跡手続函数は配列命令実装の始まる時に､如何なる類ひの､取得､設定､起動された名前のような操作の前に､起動される｡追跡の手続函数は Tcl_SetVar と Tcl_SetVar2.により配列要素を修正する事ができる｡ When array tracing has been specified, the trace procedure will be invoked at the beginning of the array command implementation, before any of the operations like get, set, or names have been invoked. The trace procedure can modify the array elements with Tcl_SetVar and Tcl_SetVar2.

削除追跡が指定された時､何時であれ変数が破壊された時､追跡手続函数が起動される｡追跡は変数が完全に消去された後に呼ばれる｡ When unset tracing has been specified, the trace procedure will be invoked whenever the variable is destroyed. The traces will be called after the variable has been completely unset.

### 配列全体の追跡 WHOLE-ARRAY TRACES

もし Tcl_TraceVar や Tcl_TraceVar2 への呼出しが配列への索引なしで配列変数を指定する場合､追跡は配列全体に設定される｡これは､何時であれ､ flags.により指定された方法で配列の要素が利用されたときは､何時でも proc が起動されることを意味する｡配列が消去された時､全配列追跡は､ name1 が配列の名前に等しく､ name2 がNULL; に等しいとして､１度だけ呼出される; それぞれの要素毎に１度づつ起動されるのではない｡ If a call to Tcl_TraceVar or Tcl_TraceVar2 specifies the name of an array variable without an index into the array, then the trace will be set on the array as a whole. This means that proc will be invoked whenever any element of the array is accessed in the ways specified by flags. When an array is unset, a whole-array trace will be invoked just once, with name1 equal to the name of the array and name2 NULL; it will not be invoked once for each element.

### 多重追跡 MULTIPLE TRACES

同じ変数上に複数の追跡が存在する事は可能である｡この状態が生じたとき､全ての追跡手続函数がそれぞれの利用毎に起動される､最も最近作成されたものから､最も以前に作成されたものの順になる｡配列の全体追跡と同時に､配列の要素追跡が存在する時､個別の要素追跡が起動される前に全体追跡が起動される｡もし､読み書き追跡が変数を消去する場合､全ての消去追跡が起動されるが､残りの読み書き追跡は飛び越しされる｡ It is possible for multiple traces to exist on the same variable. When this happens, all of the trace procedures will be invoked on each access, in order from most-recently-created to least-recently-created. When there exist whole-array traces for an array as well as traces on individual elements, the whole-array traces are invoked before the individual-element traces. If a read or write trace unsets the variable then all of the unset traces will be invoked but the remainder of the read and write traces will be skipped.

### ERROR RETURNS

通常の状態の下で追跡手続函数はNULL,を返し成功裏に完了したことを指し示す｡もし proc が非-NULL 値を返す場合､不都合が生じたことを意味する｡その返り値は､不都合伝言文を含む静的文字列へのポインタでなければならない､但し､ TCL_TRACE_RESULT_DYNAMIC と TCL_TRACE_RESULT_OBJECT 旗印が(正確にはその内の一つが)設定された場合､それは結果が動的文字列( Tcl_Free により解放される)であるか､不都合伝言文を含む Tcl_Obj* (char* に投影され､ Tcl_DecrRefCount により解放される)である､ことを指し示す｡もし追跡手続函数が不都合を返す場合､利用に関する更なる追跡は起動されず､利用の追跡は与えられた伝言文により中断される｡追跡手続函数はその能力を読出し専用変数を作ることに使用できる､譬えば(但し､註意すべきは､変数の値は追跡手続函数が呼ばれる前に既に修正されてしまい､従って追跡手続函数が正しい値を再設定する必要がある)｡ Under normal conditions trace procedures should return NULL, indicating successful completion. If proc returns a non-NULL value it signifies that an error occurred. The return value must be a pointer to a static character string containing an error message, unless (exactly one of) the TCL_TRACE_RESULT_DYNAMIC and TCL_TRACE_RESULT_OBJECT flags is set, which specify that the result is either a dynamic string (to be released with Tcl_Free) or a Tcl_Obj* (cast to char* and to be released with Tcl_DecrRefCount) containing the error message. If a trace procedure returns an error, no further traces are invoked for the access and the traced access aborts with the given message. Trace procedures can use this facility to make variables read-only, for example (but note that the value of the variable will already have been modified before the trace procedure is called, so the trace procedure will have to restore the correct value).

proc からの返り値は読みと記入の追跡の間のみに使われる｡削除追跡の間､返り値は無視され全ての適切な追跡手続函数が常に起動される｡ The return value from proc is only used during read and write tracing. During unset traces, the return value is ignored and all relevant trace procedures will always be invoked.

### 制限事項 RESTRICTIONS

変数上の操作が､それを含む解釈実行機能の削除の一部として 行われ得るので､ 函数手続の假引数が何をするのに使えるかを､註意深く確認せねばならない｡ 業務譜Tcl_InterpDeletedは､その為の重要な道具である｡ Tcl_InterpDeletedが1を返す時､手続き函数は､解釈実行機能の中で､ どの記述譜も起動できなくなる｡ 使用者は､その状態を伝える､ 廃止された旗徴値TCL_INTERP_DESTROYEDを使う古い符号命令に 遭遇するかもしれないが､Tcl 9は最早それに対応しない｡ それを提供しているどの符号命令も､ その使用を停止する為に変換せねばならない｡ Because operations on variables may take place as part of the deletion of the interp that contains them, proc must be careful about checking what the interp parameter can be used 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. You may encounter old code using a deprecated flag value TCL_INTERP_DESTROYED to signal this condition, but Tcl 9 no longer supports this. Any supported code must be converted to stop using it.

たとえ解釈実行機能内に部分的に形成された結果が保存される場合でさえも､追跡手続函数は何時でも呼出し可能である｡もし追跡手続函数がこの結果を損ない得るような何かをする場合(譬えば Tcl_Eval の呼出し)､返る前に解釈実行機能の状態を保存し取戻す為に Tcl_SaveInterpState とその関連機能譜を使わねばならない｡ A trace procedure can be called at any time, even when there are partially formed results stored in the interpreter. If the trace procedure does anything that could damage this result (such as calling Tcl_Eval) then it must use the Tcl_SaveInterpState and related routines to save and restore the original state of the interpreter before it returns.

### 未定義の変数 UNDEFINED VARIABLES

未定義の変数への追跡の設定は合法である｡その変数は猶その値が設定される迄未定義として現れる｡もし未定義の変数が追跡され消去された場合､消去は不都合になって失敗するが(その様な変数はない“no such variable”)､追跡手続函数は猶起動される｡ It is legal to set a trace on an undefined variable. The variable will still appear to be undefined until the first time its value is set. If an undefined variable is traced and then unset, the unset will fail with an error (“no such variable”), but the trace procedure will still be invoked.

### TCL_TRACE_DESTROYED FLAG

proc への消去の戻りでは､もしその追跡が削除の部分として外される場合､ TCL_TRACE_DESTROYED ビットが flags 内に設定される｡変数上の追跡は､何時であれ変数が削除された時常に取去られる; TCL_TRACE_DESTROYED が設定されない唯一の場合は､配列の１つの要素だけが消去された時に配列全体の追跡が起動された場合だけである｡ In an unset callback to proc, the TCL_TRACE_DESTROYED bit is set in flags if the trace is being removed as part of the deletion. Traces on a variable are always removed whenever the variable is deleted; the only time TCL_TRACE_DESTROYED is not set is for a whole-array trace invoked when only a single element of an array is unset.

### 参照回数管理 REFERENCE COUNT MANAGEMENT

proc呼戻しが起動され､且つ､その呼戻しが､ TCL_TRACE_RESULT_OBJECT旗徴を伴って装填された場合､ 不都合が存在した時は､呼戻しの結果はTcl_Obj参照である｡ 結果は､最早必要ない時は､その参照回数を一度減少させる､ 又は､更なる参照にそれをさせる(譬えば､それをTcl_SetObjResultと共に解釈実行機能の結果として設定して)｡ When a proc callback is invoked, and that callback was installed with the TCL_TRACE_RESULT_OBJECT flag, the result of the callback is a Tcl_Obj reference when there is an error. The result will have its reference count decremented once when no longer needed, or may have additional references made to it (e.g., by setting it as the interpreter result with Tcl_SetObjResult).

### 瑕疵 BUGS

配列の追跡は Tcl info exists 命令と未だ統合されていないし､配列の追跡へのTcl-水準の利用もない｡ Array traces are not yet integrated with the Tcl info exists command, nor is there Tcl-level access to array traces.

### SEE ALSO

trace

### KEYWORDS

clientData, trace, variable
Copyright © 1989-1993 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.