Tcl\_CreateTrace(3) Tcl Library Procedures Tcl\_CreateTrace(3)

```

```

# [NAME](#NAME)

Tcl\_CreateTrace, Tcl\_CreateObjTrace, Tcl\_CreateObjTrace2, Tcl\_DeleteTrace - arrange for command execution to be traced

# [SYNOPSIS](#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](#ARGUMENTS)

Tcl\_Interp *\*interp* (in)

Interpreter containing command to be traced or untraced.

Tcl\_Size *level* (in)

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)

Arbitrary one-word value to pass to *objProc*, *objProc2* or *proc*.

Tcl\_CmdObjTraceDeleteProc *\*deleteProc* (in)

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)

Token for trace to be removed (return value from previous call to **Tcl\_CreateTrace**).

```
    
```

# [DESCRIPTION](#DESCRIPTION)

**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* 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* 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[]);
```

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.

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.

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

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

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** 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(


        void * 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 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[]);
```

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.

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](#REFERENCE_COUNT_MANAGEMENT)

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](#SEE_ALSO)

[trace(n)](/man/os/tcl/trace.n)

# [KEYWORDS](#KEYWORDS)

command, create, delete, interpreter, trace

Tcl

---

Document: Tcl_DeleteTrace(3) from tcl 9.1.0-r0 (Chainguard OS)
Source: https://downloads.sourceforge.net/project/tcl/Tcl/9.1.0/tcl9.1.0-src.tar.gz