Tcl_CreateTrace(3)

okay so welcome to the Tcl_CreateTrace(3) page from the Tcl Library Procedures, bestie! 💖 This one is literally about arranging for command execution to be traced, and it's giving main character energy. ✨

---

✨ NAME ✨

The icons of this page are Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_CreateObjTrace2, and Tcl_DeleteTrace — together they arrange for command execution to be traced. periodt. 💅

---

🌸 SYNOPSIS 🌸

First, pull in the header like so, no cap:

#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 💅

Here's the whole cast, no skips, fr fr:

• Tcl_Interp *interp (in) — the interpreter that's holding the command you want to trace or untrace. It's literally the context, bestie.
• 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. So 0 is the "trace everything" vibe. 🔥
• int flags (in) — flags governing the trace execution. See below for details. The deets are coming, iykyk.
• Tcl_CmdObjTraceProc *objProc (in) — procedure to call for each command that is executed. See below for details of the calling sequence. Callback tea below. 🫶
• Tcl_CmdObjTraceProc2 *objProc2 (in) — procedure to call for each command that is executed. See below for details of the calling sequence. Same energy, different name.
• 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. It's your little carry-on for the callback. 🎀
• 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. So NULL is valid, no cap. 💀
• Tcl_Trace trace (in) — token for trace to be removed (return value from previous call to Tcl_CreateTrace). Basically the receipt you got earlier. 🧾

💫 DESCRIPTION 💫

Okay bestie, so Tcl_CreateObjTrace is the whole setup for command tracing. The second you call it, objProc gets invoked before the Tcl interpreter calls any command procedure while it's evaluating commands in interp. And what does it hand back? A token for the trace, bestie — which you can pass straight to Tcl_DeleteTrace to yeet the trace away. And yes, you can have many traces active at once on the same interpreter. The more the merrier, honestly. 🎀

objProc needs to have arguments and a result that match this 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[]);

And objProc2 has to match this type instead, 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[]);

Now let's vibe-check the parameters one by one, no skipping ✨

• clientData and interp — these are copies of the corresponding arguments you gave to Tcl_CreateTrace. clientData typically points at some application-specific data structure that says what to do when objProc fires.
• level — the nesting level of the command. It's 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 forever.
• command — points to a string containing the text of the command, before any argument substitution happens.
• commandToken — a Tcl command token that identifies the command about to be invoked. You can pass that token to Tcl_GetCommandName, Tcl_GetCommandInfoFromToken, or Tcl_SetCommandInfoFromToken to mess with the definition of the command. 💅
• objc and objv — the final parameter count and parameter vector that will be passed to the command, with all substitutions already performed.

The objProc callback is expected to return a standard Tcl status return code. If that code is TCL_OK (the normal case, the everyday slay), the Tcl interpreter will invoke the command. Any other return code is treated as if the command itself returned that status, and the command is not invoked. So like, no command for you. 🙈

⚠️ The objProc callback must not modify objv in any way. Not even a little. Hands off.

Tracing only happens for commands at a nesting level less than or equal to the level parameter — meaning the level parameter passed to objProc will always be less than or equal to the level parameter you gave to Tcl_CreateTrace.

---

Now the part nobody loves but everybody needs: performance. Tracing has a significant effect on runtime performance, because it makes the bytecode compiler refrain from generating in-line code for Tcl commands like if and while, all so they can be traced. If you don't actually need traces on the built-in commands, you can set the flags parameter to the constant value TCL_ALLOW_INLINE_COMPILATION. In that 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 improve significantly. (This functionality is desirable, for example, when you're using Tcl_CreateObjTrace to implement an execution time profiler. Bestie said optimization 🫶)

Calls to objProc get made by the Tcl parser immediately before it calls the command procedure for the command (cmdProc). This happens after argument parsing and substitution, so tracing for substituted commands happens before the tracing of the commands containing those substitutions. If there's a syntax error in a command, or if there's no command procedure associated with a command name, then no tracing occurs for that command. And if a string passed to Tcl_Eval contains multiple commands (bracketed, or on different lines), then multiple calls to objProc will happen — one for each command. One per. Fr fr. ✨

Tcl_DeleteTrace removes a trace, so no future calls get made to the procedure associated with that trace. And after Tcl_DeleteTrace returns, the caller should never again use the trace token. It's giving expired. 💀

When Tcl_DeleteTrace is called, the interpreter invokes the deleteProc that was passed as a parameter to Tcl_CreateObjTrace. That deleteProc must match the type Tcl_CmdObjTraceDeleteProc:

typedef void Tcl_CmdObjTraceDeleteProc(
        void * clientData);

The clientData parameter will be the same as the clientData parameter originally passed to Tcl_CreateObjTrace.

---

Tcl_CreateTrace is an alternative interface for command tracing, and ngl it is not recommended for new applications. It exists for backward compatibility with code that was developed for older versions of the Tcl interpreter. It's similar to Tcl_CreateObjTrace, except that its proc parameter should have arguments and result matching 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; plus cmdClientData, the client data that will be passed to the procedure. The objc parameter is replaced with an argv parameter, which gives the arguments to the command as character strings. And 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. And there is no way for the proc associated with a call to Tcl_CreateTrace to abort execution of a command. Like, zero. Nothing. Sorry bestie. 😭

---

🦋 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, and that guaranteed reference comes from the Tcl evaluation stack. So do not call Tcl_DecrRefCount on any of those values unless you call Tcl_IncrRefCount on them first. Balance the books, queen. 👑

---

🌸 SEE ALSO 🌸

• trace(n)

---

👑 KEYWORDS 👑

command, create, delete, interpreter, trace

---

And that's the whole page, bestie! This one comes to you from the Tcl manual — Tcl_CreateTrace(3) — so go forth, trace responsibly, and remember: don't touch objv. Mwah. 💖✨🎀