Windows PowerShell command on Get-command Tcl

Manual Pages for UNIX Operating System command usage for man Tcl_CreateTrace

Tcl Library Procedures Tcl_CreateTrace(3TCL)

_________________________________________________________________

NAME

Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace -

arrange for command execution to be traced

SYNOPSIS

#include

Tcl_Trace

Tcl_CreateTrace(interp, level, proc, clientData)

Tcl_Trace

Tcl_CreateObjTrace(interp, level, flags, objProc, clientData, deleteProc)

Tcl_DeleteTrace(interp, trace)

ARGUMENTS

Tcl_Interp *interp (in) Interpreter

con-

tain-

ing

com-

mand to be traced or untraced. int level (in) Only

com-

mands at or below this

nest-

ing level will be traced unless 0 is

speci-

fied. 1 means

top-

level

com-

mands only, Tcl Last change: 1

Tcl Library Procedures Tcl_CreateTrace(3TCL)

2 means

top-

level

com-

mands or those that are invoked as

immedi-

ate

conse-

quences of

exe-

cut-

ing

top-

level

com-

mands

(pro-

cedure bodies,

brack-

eted

com-

mands, etc.) and so on. A value of 0 means that

com-

mands at any level are traced. int flags (in) Flags

govern-

ing the Tcl Last change: 2

Tcl Library Procedures Tcl_CreateTrace(3TCL)

trace

exe-

cu-

tion. See below for details.

Tcl_CmdObjTraceProc *objProc (in) Procedure

to call for each

com-

mand that's

exe-

cuted. See below for details of the

cal-

ling sequence.

Tcl_CmdTraceProc *proc (in) Procedure

to call for each

com-

mand that's

exe-

cuted. See below for details on the

cal-

ling sequence. ClientData clientData (in) Arbitrary

one-

word Tcl Last change: 3

Tcl Library Procedures Tcl_CreateTrace(3TCL)

value to pass to objProc or proc.

Tcl_CmdObjTraceDeleteProc *deleteProc Procedure

to call when the trace is deleted. See below for details of the

cal-

ling sequence. A NULL pointer is

per-

mis-

sible and results in no

call-

back when the trace is deleted.

Tcl_Trace trace (in) Token

for trace to be removed (return value from previous Tcl Last change: 4

Tcl Library Procedures Tcl_CreateTrace(3TCL)

call to

Tcl_CreateTrace).

_________________________________________________________________

DESCRIPTION

Tcl_CreateObjTrace arranges for command tracing. After it

is called, objProc will be invoked before the Tcl inter-

preter 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 should have arguments and result that match the

type, Tcl_CmdObjTraceProc:

typedef int Tcl_CmdObjTraceProc(

ClientData clientData,

Tcl_Interp* interp,

int level, CONST char* command,

Tcl_Command commandToken,

int objc,

Tcl_Obj *CONST objv[] );

The clientData and interp parameters are copies of the

corresponding arguments given to Tcl_CreateTrace. Client-

Data typically points to an application-specific data struc-

ture 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 applica-

tion, 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 identi-

fies the command to be invoked. The token may be passed to

Tcl_GetCommandName, Tcl_GetCommandTokenInfo, or

Tcl_SetCommandTokenInfo 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. 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. The objProc callback must not modify objv in any way. It is, however, permissible to change the command by calling

Tcl_SetCommandTokenInfo prior to returning. Any such change

takes effect immediately, and the command is invoked with Tcl Last change: 5

Tcl Library Procedures Tcl_CreateTrace(3TCL)

the new information. Tracing will only occur for commands at nesting level less

than or equal to the level parameter (i.e. the level parame-

ter to objProc will always be less than or equal to the

level parameter to Tcl_CreateTrace).

Tracing has a significant effect on runtime performance

because it causes the bytecode compiler to refrain from gen-

erating 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.)

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 substitu-

tion, 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 com-

mand procedure associated with a command name, then no trac-

ing will occur for that command. If a string passed to

Tcl_Eval contains multiple commands (bracketed, or on dif-

ferent lines) then multiple calls to objProc will occur, one for each command.

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.

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(

ClientData clientData ); The clientData parameter will be the same as the clientData

parameter that was originally passed to Tcl_CreateObjTrace.

Tcl_CreateTrace is an alternative interface for command

tracing, not recommended for new applications. It is pro-

vided 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 parame-

ter should have arguments and result that match the type Tcl Last change: 6

Tcl Library Procedures Tcl_CreateTrace(3TCL)

Tcl_CmdTraceProc:

typedef void Tcl_CmdTraceProc(

ClientData clientData,

Tcl_Interp *interp,

int level, char *command,

Tcl_CmdProc *cmdProc,

ClientData cmdClientData, int argc, CONST char *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 pro-

cedure that will be invoked; and cmdClientData, the client

data that will be passed to the procedure. The objc parame-

ter is replaced with an argv parameter, that gives the argu-

ments to the command as character strings. Proc must not modify the command or argv strings.

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.

KEYWORDS command, create, delete, interpreter, trace

ATTRIBUTES

See attributes(5) for descriptions of the following attri-

butes:

_______________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE|

|____________________|__________________|_

| Availability | runtime/tcl-8 |

|____________________|__________________|_

| Interface Stability| Uncommitted |

|____________________|_________________|

NOTES Source for Tcl is available on http://opensolaris.org. Tcl Last change: 7