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

### 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_CreateTrace, Tcl_CreateObjTrace, Tcl_CreateObjTrace2, Tcl_DeleteTrace — 追跡される命令の実行のために準備する arrange for command execution to be traced
  SYNOPSIS
    #include <tcl.h>
    Tcl_Trace
    Tcl_CreateTrace(interp, level, proc, clientData)
    Tcl_Trace
    Tcl_CreateObjTrace(interp, level, flags, objProc, clientData, deleteProc)
    Tcl_Trace
    Tcl_CreateObjTrace2(interp, level, flags, objProc2, clientData, deleteProc)
    Tcl_DeleteTrace(interp, trace)
  引数 ARGUMENTS
    Tcl_Interp *interp (入力in)
    Tcl_Size level (入力in)
    int flags (入力in)
    Tcl_CmdObjTraceProc *objProc (入力in)
    Tcl_CmdObjTraceProc2 *objProc2 (入力in)
    Tcl_CmdTraceProc *proc (入力in)
    void *clientData (入力in)
    Tcl_CmdObjTraceDeleteProc *deleteProc (入力in)
    Tcl_Trace trace (入力in)
  説明 DESCRIPTION
  参照回数管理 REFERENCE COUNT MANAGEMENT
  SEE ALSO
  KEYWORDS

### NAME

Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_CreateObjTrace2, Tcl_DeleteTrace — 追跡される命令の実行のために準備する arrange for command execution to be traced

### SYNOPSIS

#include <tcl.h>
Tcl_Trace
Tcl_CreateTrace(interp, level, proc, clientData)
Tcl_Trace
Tcl_CreateObjTrace(interp, level, flags, objProc, clientData, deleteProc)
Tcl_Trace
Tcl_CreateObjTrace2(interp, level, flags, objProc2, clientData, deleteProc)
Tcl_DeleteTrace(interp, trace)

### 引数 ARGUMENTS

Tcl_Interp *interp (入力in)
  追跡されるかされない命令を含む解釈実行機能｡ Interpreter containing command to be traced or untraced.

Tcl_Size level (入力in)
  0 が指定されていない限り､この入れ子水準と同じかより下の命令のみが追跡される｡ 1 は頂上水準の命令のみを意味し､ 2 は頂上水準の命令､又は頂上水準の命令の直接の影響として起動されるような命令(手続函数本体､各括弧で括った命令､等)を意味し､以下同様である｡値 0 は､どの様な水準の命令も追跡される意味である｡ 　　 Only commands at or below this nesting level will be traced unless 0 is specified. 1 means top-level commands only, 2 means top-level commands or those that are invoked as immediate consequences of executing top-level commands (procedure bodies, bracketed commands, etc.) and so on. A value of 0 means that commands at any level are traced.

int flags (入力in)
  追跡の実行を統治する旗印｡詳細については下を参照されたい｡ 　　　 Flags governing the trace execution. See below for details.

Tcl_CmdObjTraceProc *objProc (入力in)
  実行される各命令を呼ぶ手続函数｡呼出し手続の詳細は下を参照されたい｡　 Procedure to call for each command that is executed. See below for details of the calling sequence.

Tcl_CmdObjTraceProc2 *objProc2 (入力in)
  実行される各命令を呼ぶ手続函数｡呼出し手続の詳細は下を参照されたい｡　 　　 Procedure to call for each command that is executed. See below for details of the calling sequence.

Tcl_CmdTraceProc *proc (入力in)
  実行されるそれぞれの命令の為に呼出す手続き函数｡呼出し連鎖の詳細は下を参照｡ Procedure to call for each command that is executed. See below for details on the calling sequence.

void *clientData (入力in)
  objProc 又は objProc2 又は procに渡す任意の一語値｡　 Arbitrary one-word value to pass to objProc, objProc2 or proc.

Tcl_CmdObjTraceDeleteProc *deleteProc (入力in)
  追跡が削除されたときに呼ばれる手続函数｡呼出し手続の詳細は下を参照されたい｡NULL 指示子が許容され､その場合､追跡が削除された時に呼出しなしが結果となる｡　 　　 Procedure to call when the trace is deleted. See below for details of the calling sequence. A NULL pointer is permissible and results in no callback when the trace is deleted.

Tcl_Trace trace (入力in)
  取外される追跡の字句(事前の Tcl_CreateTrace への呼出しからの返り値)｡　 Token for trace to be removed (return value from previous call to Tcl_CreateTrace).

### 説明 DESCRIPTION

Tcl_CreateObjTrace は命令の追跡を手配する｡それが呼ばれた後､ objProc は interp 内で命令を評価する時どの命令手続函数を Tcl 解釈実行機能が呼ぶよりも前に起動される｡ Tcl_CreateObjTrace からの返り値は追跡の為の字句結果であり､追跡を取去る為に Tcl_DeleteTrace に渡されることもある｡同一の解釈実行機能の為に多くの追跡が同時に効果的に存在することもある｡ Tcl_CreateObjTrace arranges for command tracing. After it is called, objProc will be invoked before the Tcl interpreter calls any command procedure when evaluating commands in interp. The return value from Tcl_CreateObjTrace is a token for the trace, which may be passed to Tcl_DeleteTrace to remove the trace. There may be many traces in effect simultaneously for the same interpreter.

objProc は Tcl_CmdObjTraceProc 型と合致する引数と結果を有するべきである: objProc should have arguments and result that match the type, Tcl_CmdObjTraceProc:

    typedef int Tcl_CmdObjTraceProc(
            void * clientData,
            Tcl_Interp* interp,
            int level,
            const char *command,
            Tcl_Command commandToken,
            int objc,
            Tcl_Obj *const objv[]);

objProc2 は Tcl_CmdObjTraceProc2 型と合致する引数と結果を有するべきである: objProc2 should have arguments and result that match the type, Tcl_CmdObjTraceProc2:

    typedef int Tcl_CmdObjTraceProc2(
            void * clientData,
            Tcl_Interp* interp,
            Tcl_Size level,
            const char *command,
            Tcl_Command commandToken,
            Tcl_Size objc,
            Tcl_Obj *const objv[]);

clientData と interp 媒介変数は Tcl_CreateTrace に与えられた対応する引数の複写である｡ clientData は典型的には応用譜固有のデータ構造を指し､それは objProc が起動された時に何をすべきかを記述している｡その level 媒介変数は命令の入子になった水準を与える(1 は､応用譜によって Tcl_Eval に与えられた頂上水準の命令､ 2 は Tcl_Eval に解析の一部､又は解釈実行している第１水準命令として渡される次の水準の命令､以下同様)｡ command 媒介変数は､何も引数の置換を行う前の命令の文書を含む文字列を指す｡commandToken 媒介変数は Tcl 命令字句結果であって､起動されるべき命令を識別する｡字句結果は命令の定義を操つる為に Tcl_GetCommandName や Tcl_GetCommandInfoFromToken や Tcl_SetCommandInfoFromToken に渡されるかもしれいない｡ objc と objv 媒介変数は命令に渡される最終的な媒介変数の個数と媒介変数ベクトルを指定する又､全て置換を遂行させる｡ 　　　　　 The clientData and interp parameters are copies of the corresponding arguments given to Tcl_CreateTrace. clientData typically points to an application-specific data structure that describes what to do when objProc is invoked. The level parameter gives the nesting level of the command (1 for top-level commands passed to Tcl_Eval by the application, 2 for the next-level commands passed to Tcl_Eval as part of parsing or interpreting level-1 commands, and so on). The command parameter points to a string containing the text of the command, before any argument substitution. The commandToken parameter is a Tcl command token that identifies the command to be invoked. The token may be passed to Tcl_GetCommandName, Tcl_GetCommandInfoFromToken, or Tcl_SetCommandInfoFromToken to manipulate the definition of the command. The objc and objv parameters designate the final parameter count and parameter vector that will be passed to the command, and have had all substitutions performed.

objProc 呼戻しは標準 Tcl 状態返り符号を返すことが期待される｡もしこの符号が TCL_OK (通常の場合)であると､ Tcl 解釈実行機能が命令を起動するようになる｡他のどの様な符号も恰も命令がその状態を返すかのように扱われ､そしてその命令は起動されない｡ 　　　 The objProc callback is expected to return a standard Tcl status return code. If this code is TCL_OK (the normal case), then the Tcl interpreter will invoke the command. Any other return code is treated as if the command returned that status, and the command is not invoked.

objProc 呼戻しは如何なる方法によっても objv を修正してはならない｡ The objProc callback must not modify objv in any way.

追跡は入子水準が level 媒介変数より小さいか等しい命令に就いてのみ生じる(即ち､ objProc への level 媒介変数は Tcl_CreateTrace への level 媒介変数より常に小さいか等しい)｡ 　　 Tracing will only occur for commands at nesting level less than or equal to the level parameter (i.e. the level parameter to objProc will always be less than or equal to the level parameter to Tcl_CreateTrace).

追跡は実行時の出来ばえに重要な効果を有する､理由はバイト符号翻訳機能に､ if や while 等の様な Tcl 命令に関する即時実行符号をそれが追跡される様な順序に生成することを抑制するから｡もし組込み命令に関する追跡が要求されない場合､ flags 媒介変数は恒常的値 TCL_ALLOW_INLINE_COMPILATION に設定されるかもしれない｡この場合､組込み命令上の追跡は､解釈実行機能の状態によって､追跡呼戻しの結果になるかならないかもしれないが､出来ばえは大きく改善される｡(この機能は望ましい､譬えば､時間軸解析を実行する実装の為に Tcl_CreateObjTrace を使う時｡) 　　　 Tracing has a significant effect on runtime performance because it causes the bytecode compiler to refrain from generating in-line code for Tcl commands such as if and while in order that they may be traced. If traces for the built-in commands are not required, the flags parameter may be set to the constant value TCL_ALLOW_INLINE_COMPILATION. In this case, traces on built-in commands may or may not result in trace callbacks, depending on the state of the interpreter, but run-time performance will be improved significantly. (This functionality is desirable, for example, when using Tcl_CreateObjTrace to implement an execution time profiler.)

objProc の呼出しは､その命令の為の命令手続函数(cmdProc)を呼ぶ前に､ Tcl 解析により直接なされる｡之は引数の解析と置換の後に起るので､置換を含む命令の追跡の前に､置換命令の為の追跡が起る｡もし命令内に構文の不都合があるか､命令の名前に結合した命令手続函数がないと､その命令に関する追跡は起らない｡もし Tcl_Eval に渡した文字列が多重の命令を含んでいると(角括弧で括られた､又は異なる行上に)､それぞれの命令に就いて objProc への多重呼出しが起る｡ 　　　 Calls to objProc will be made by the Tcl parser immediately before it calls the command procedure for the command (cmdProc). This occurs after argument parsing and substitution, so tracing for substituted commands occurs before tracing of the commands containing the substitutions. If there is a syntax error in a command, or if there is no command procedure associated with a command name, then no tracing will occur for that command. If a string passed to Tcl_Eval contains multiple commands (bracketed, or on different lines) then multiple calls to objProc will occur, one for each command.

Tcl_DeleteTrace は追跡を取去る､追跡に結合した手続函数への更なる呼出しは生成されない｡ Tcl_DeleteTrace から返った後は､呼出し側は､ trace 字句解析結果を再び使うことをしてならない｡ Tcl_DeleteTrace removes a trace, so that no future calls will be made to the procedure associated with the trace. After Tcl_DeleteTrace returns, the caller should never again use the trace token.

Tcl_DeleteTrace が呼ばれた時､解釈実行機能は Tcl_CreateObjTrace に引数として渡された deleteProc を起動する｡ deleteProc は型 Tcl_CmdObjTraceDeleteProc に合致しなくてはならない: 　　　 When Tcl_DeleteTrace is called, the interpreter invokes the deleteProc that was passed as a parameter to Tcl_CreateObjTrace. The deleteProc must match the type, Tcl_CmdObjTraceDeleteProc:

    typedef void Tcl_CmdObjTraceDeleteProc(
            void * clientData);

clientData 媒介変数は元々 Tcl_CreateObjTrace に渡された clientData 媒介変数と同じになる｡ 　　　　 The clientData parameter will be the same as the clientData parameter that was originally passed to Tcl_CreateObjTrace.

Tcl_CreateTrace は追跡命令の為の代理的な相互作用であり､新しい応用譜には薦められない｡それは Tcl 解釈実行機能の古い版の為に開発された命令譜への互換性維持の為に提供されている｡それは Tcl_CreateObjTrace に似ているが､その proc 媒介変数は Tcl_CreateObjTrace 型に合致する引数と結果を有するべきであることが異なっている: Tcl_CreateTrace is an alternative interface for command tracing, not recommended for new applications. It is provided for backward compatibility with code that was developed for older versions of the Tcl interpreter. It is similar to Tcl_CreateObjTrace, except that its proc parameter should have arguments and result that match the type Tcl_CmdTraceProc:

    typedef void Tcl_CmdTraceProc(
            void *clientData,
            Tcl_Interp *interp,
            int level,
            char *command,
            Tcl_CmdProc *cmdProc,
            void *cmdClientData,
            int argc,
            const char *argv[]);

proc 呼戻しへの媒介変数は上述の objProc 呼戻しのものと似ている｡ commandToken は cmdProc 即ち､起動されることになる(文字列基準の)命令手続函数へのポインターと; cmdClientData ､即ち､手続函数に渡されることになる依頼者データ､とに置換される｡ objc 媒介変数は argv 媒介変数､即ち､文字列として命令に与える引数､に置換えられる｡ objc は command や argv 文字列を修正してはならない｡ 　　　 　　　 The parameters to the proc callback are similar to those of the objProc callback above. The commandToken is replaced with cmdProc, a pointer to the (string-based) command procedure that will be invoked; and cmdClientData, the client data that will be passed to the procedure. The objc parameter is replaced with an argv parameter, that gives the arguments to the command as character strings. Proc must not modify the command or argv strings.

もし Tcl_CreateTrace に生成された追跡が効果的でない場合､ if や while のような Tcl 命令の行内翻訳は常に不能である｡ Tcl_CreateTrace と共に作成された追跡が削除された時通知はされない｡ Tcl_CreateTrace と共に作成された追跡が削除された時通知する方法はない｡ Tcl_CreateTrace への呼出しに結合した proc の為に command.の実行を中断する為の方法はない｡ If a trace created with Tcl_CreateTrace is in effect, inline compilation of Tcl commands such as if and while is always disabled. There is no notification when a trace created with Tcl_CreateTrace is deleted. There is no way to be notified when the trace created by Tcl_CreateTrace is deleted. There is no way for the proc associated with a call to Tcl_CreateTrace to abort execution of command.

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

Tcl_CreateObjTraceに渡されるprocが呼出される時､その objv 引数内の値は､少なく共､値1であり､Tcl 評価棚から参照される事が保障されている｡ これ等のどの様な値に就いても､最初に､ Tcl_IncrRefCount を呼出さない限り､ Tcl_DecrRefCount を呼ばない方が好い｡ When the proc passed to Tcl_CreateObjTrace is called, the values in its objv argument will have a reference count of at least 1, with that guaranteed reference being from the Tcl evaluation stack. You should not call Tcl_DecrRefCount on any of those values unless you call Tcl_IncrRefCount on them first.

### SEE ALSO

trace

### KEYWORDS

command, create, delete, interpreter, trace
Copyright © 1989-1993 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.
Copyright © 2002 Kevin B. Kenny <kennykb(at)acm.org>. All rights reserved.