Tcl_TraceCommand(3)

💖 Tcl_TraceCommand(3) — the tea on watching your commands get renamed & deleted

okay bestie, gather round, because this is the Tcl_TraceCommand(3) page from the Tcl Library Procedures and it's literally about spying on your own commands. Not in a creepy way. In a "hey, tell me when somebody renames or deletes this" way. 🫶

---

✨ NAME ✨

Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand — monitor renames and deletes of a command 👀

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

void *
Tcl_CommandTraceInfo(interp, cmdName, flags, proc, prevClientData)

int
Tcl_TraceCommand(interp, cmdName, flags, proc, clientData)

Tcl_UntraceCommand(interp, cmdName, flags, proc, clientData)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the interpreter that's holding your command, bestie.
• const char *cmdName (in) — the name of the command. iconic.
• int flags (in) — an OR'ed collection of the values TCL_TRACE_RENAME and TCL_TRACE_DELETE. mix & match, slay.
• Tcl_CommandTraceProc *proc (in) — the procedure to call when the specified operations happen to cmdName.
• void *clientData (in) — arbitrary argument to pass to proc. your little goodie bag 🎁
• void *prevClientData (in) — if non-NULL, gives the last value returned by Tcl_CommandTraceInfo, so this call will return information about the next trace. If NULL, this call will return information about the first trace. no cap.

---

💅 DESCRIPTION 💅

Tcl_TraceCommand lets a C procedure monitor operations performed on a Tcl command, so that the C procedure gets invoked whenever the command is renamed or deleted. So like, the command's whole glow-up and its tragic ending, you're there for both. 😭

If the trace is created successfully then Tcl_TraceCommand returns TCL_OK. If an error occurred (e.g. cmdName specifies a non-existent command) then TCL_ERROR is returned and an error message is left in the interpreter's result.

The flags argument to Tcl_TraceCommand indicates when the trace procedure is to be invoked. It's an OR'ed combination of any of these values:

• TCL_TRACE_RENAME — invoke proc whenever the command is renamed. new name, who dis ✨
• TCL_TRACE_DELETE — invoke proc when the command is deleted. rip bozo 💀

Whenever one of the specified operations occurs to the command, proc will be invoked. It should have arguments and result that match the type Tcl_CommandTraceProc:

typedef void Tcl_CommandTraceProc(
        void *clientData,
        Tcl_Interp *interp,
        const char *oldName,
        const char *newName,
        int flags);

The clientData and interp parameters will have the same values as those passed to Tcl_TraceCommand when the trace was created. clientData typically points to an application-specific data structure that describes what to do when proc is invoked. oldName gives the name of the command being renamed, and newName gives the name that the command is being renamed to (or NULL when the command is being deleted). flags is an OR'ed combination of bits potentially providing several pieces of information. One of the bits TCL_TRACE_RENAME and TCL_TRACE_DELETE will be set in flags to indicate which operation is being performed on the command. 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). 🧹

Because the deletion of commands can take place as part of the deletion of the interp that contains them, proc must be careful about checking what the passed in interp value can be called upon 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. The function of proc in that circumstance is limited to the cleanup of its own data structures. ⚠️ like, genuinely, do not try to run scripts here, bestie, it's not the vibe.

Tcl_UntraceCommand may be used to remove a trace. If the command specified by interp, cmdName, 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_UntraceCommand has no effect. The same bits are valid for flags as for calls to Tcl_TraceCommand. it's giving "no harm, no foul" 🦋

Tcl_CommandTraceInfo may be used to retrieve information about traces set on a given command. The return value from Tcl_CommandTraceInfo is the clientData associated with a particular trace. The trace must be on the command specified by the interp, cmdName, and flags arguments (note that currently the flags are ignored; flags should be set to 0 for future compatibility) and its trace procedure must be 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_CommandTraceInfo. 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 command that have the same proc. lowkey a lil linked list of vibes 🔗

---

🌈 CALLING COMMANDS DURING TRACES 🌈

During rename traces, the command being renamed is visible with both names simultaneously, and the command still exists during delete traces, unless the interp that contains it is being deleted. However, there is no mechanism for signaling that an error occurred in a trace procedure, so great care should be taken that errors do not get silently lost. 😭 like, they will just ✨ vanish ✨. be careful.

---

👑 MULTIPLE TRACES 👑

It is possible for multiple traces to exist on the same command. When this happens, all of the trace procedures will be invoked on each access, in order from most-recently-created to least-recently-created. main character first, obviously. 💅

Attempts to delete the command during a delete trace will fail silently, since the command is already scheduled for deletion anyway. If the command being renamed is renamed by one of its rename traces, that renaming takes precedence over the one that triggered the trace and the collection of traces will not be reexecuted; if several traces rename the command, the last renaming takes precedence. last one to rename it wins, periodt. 🏁

---

💜 TCL_TRACE_DESTROYED FLAG 💜

In a delete callback to proc, the TCL_TRACE_DESTROYED bit is set in flags. that's the signal, bestie — your trace is about to be gone. 🥀

---

⭐ KEYWORDS ⭐

clientData, trace, command

---

okay that's the whole page, no skips, no summaries, every flag and caveat accounted for 💖 this was Tcl version 7.4, dated Tcl_TraceCommand(3), and honestly? she ate. stay traced, stay iconic, and remember: rename traces see both names at once so don't be confused when the same command shows up twice. bye bestie 🎀🦋✨