Tcl_CreateAlias(3tcl)

📦
version 9.0.4 · 5 versions
, in ubuntu stonking

✨ NAME ✨

okay so bestie, this whole page is about one iconic squad of functions: Tcl_IsSafe, Tcl_CreateChild, Tcl_GetChild, Tcl_GetParent, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAliasObj, Tcl_ExposeCommand, and Tcl_HideCommand. They all live in the Tcl Library Procedures and they’re here to help you manage multiple Tcl interpreters, aliases and hidden commands. This is the Tcl_CreateAlias(3tcl) manual page, and it’s giving very much “I run a whole multiverse of interpreters” energy. 🦋

🌸 SYNOPSIS 🌸

#include <tcl.h>

int
Tcl_IsSafe(interp)

Tcl_Interp *
Tcl_CreateChild(interp, name, isSafe)

Tcl_Interp *
Tcl_GetChild(interp, name)

Tcl_Interp *
Tcl_GetParent(interp)

int
Tcl_GetInterpPath(interp, childInterp)

int
Tcl_CreateAlias(childInterp, childCmd, targetInterp, targetCmd, argc, argv)

int
Tcl_CreateAliasObj(childInterp, childCmd, targetInterp, targetCmd, objc, objv)

int
Tcl_GetAliasObj(interp, childCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr)

int
Tcl_ExposeCommand(interp, hiddenCmdName, cmdName)

int
Tcl_HideCommand(interp, cmdName, hiddenCmdName)

💅 ARGUMENTS 💅

  • Tcl_Interp *interp (in) — the interpreter where you want to run the specified command. Like, the main character’s home base. 🏠
  • const char *name (in) — the name of the child interpreter you’re creating or manipulating. Gotta name your babies. 👑
  • int isSafe (in) — if this is non-zero, you get a “safe” child that’s suitable for running untrusted code. If it’s zero, you get a trusted child. Choose wisely, bestie. 🔒
  • Tcl_Interp *childInterp (in) — the interpreter used to create the source command for an alias (peep the description below for the full tea). ☕
  • const char *childCmd (in) — the name of the source command for the alias. It’s the command that gets aliased. ✨
  • Tcl_Interp *targetInterp (in) — the interpreter that contains the target command for an alias. So, where the real magic happens. 🎯
  • const char *targetCmd (in) — the name of the target command for the alias, living inside targetInterp. 👯
  • Tcl_Size argc (in) — how many additional arguments you’re passing to the alias command. Count ‘em up. 🔢
  • const char *const *argv (in) — a vector of strings: the additional arguments to pass to the alias command. This storage is owned by the caller. So you brought it, you manage it. 🎒
  • Tcl_Size objc (in) — count of additional value arguments to pass to the aliased command. Same vibes as argc, but for objects. 📦
  • Tcl_Obj **objv (in) — a vector of Tcl_Obj structures, the additional value arguments to pass to the aliased command. This storage is owned by the caller too. You keep it, you clean it. 🧹
  • Tcl_Interp **targetInterpPtr (in) — pointer to a location where we’ll store the address of the interpreter where a target command is defined for an alias. It’s like a little mailbox for an interpreter address. 📬
  • const char **targetCmdPtr (out) — pointer to a location where we’ll store the address of the name of the target command for an alias. Another mailbox, but for a command name. 📮
  • Tcl_Size | int *objcPtr (out) — pointer to a location where we’ll store the count of additional value arguments to be passed to the alias. The location is in storage owned by the caller. If it points to a variable whose type is not Tcl_Size, a compiler warning will be generated. If your extension is compiled with -DTCL_8_API, this function will return TCL_ERROR for aliases with more than INT_MAX value arguments — otherwise, expect it to crash 💀. No cap, that’s the warning.
  • Tcl_Obj ***objvPtr (out) — pointer to a location where we’ll store a vector of Tcl_Obj structures: the additional arguments to pass to an alias command. The location is in storage owned by the caller, but the vector of Tcl_Obj structures is owned by the called function. So like, you get the address, they own the goodies. 🫶
  • const char *cmdName (in) — the name of an exposed command to hide or create. It’s the command’s public-facing name. 🌟
  • const char *hiddenCmdName (in) — the name under which a hidden command is stored, and with which it can be exposed or invoked. It’s the secret identity. 🕵️‍♀️

that’s part 1, bestie — more Tcl interpreter chaos is coming in part 2, so don’t go anywhere 💖

💫 DESCRIPTION 💫

Okay bestie, listen up, because these procedures are literally the VIP pass into Tcl's multiple interpreter facility from inside C programs. They let you manage a whole lil hierarchy of interpreters, plus handle aliases — and an alias is just a command that, when you invoke it in one interpreter, runs a command over in another interpreter. Iconic crossover behavior, fr.

The return value for any of these procedures that returns an int is either TCL_OK or TCL_ERROR. And if it hands you back TCL_ERROR? Then the interpreter's result is holding an error message. No cap, go read it.

  • Tcl_CreateChild — makes a brand new interpreter as a child of interp. It also creates a child command named name in interp, which is how interp gets to manipulate the new baby child. If isSafe is zero, the command creates a trusted child, where Tcl code has access to all the Tcl commands. If isSafe is 1, you get a “safe” child, where Tcl code only gets access to the set of Tcl commands defined as “Safe Tcl” — peep the manual entry for the Tcl interp command for the details. And if creating that new child interpreter failed? You get NULL. 💀
  • Tcl_IsSafe — returns 1 if interp is “safe” (meaning it was created with the TCL_SAFE_INTERPRETER flag specified), and 0 otherwise. Simple as.
  • Tcl_GetChild — hands you back a pointer to a child interpreter of interp. The child is identified by name. If no such child interpreter exists, you get NULL. 🙈
  • Tcl_GetParent — hands you back a pointer to the parent interpreter of interp. If interp has no parent (it's a top-level interpreter, main character energy), then NULL comes back.
  • Tcl_GetInterpPath — stores in the result of interp the relative path between interp and childInterp; and heads up, childInterp must be a child of interp. If the computation of the relative path goes well, TCL_OK is returned. Otherwise TCL_ERROR comes back and an error message gets stored as the result of interp.
  • Tcl_CreateAlias — creates a command named childCmd in childInterp that, when invoked, will cause targetCmd to be invoked in targetInterp. The arguments specified by the strings contained in argv are always prepended to any arguments supplied in the invocation of childCmd, and passed along to targetCmd. Returns TCL_OK if it succeeds, or TCL_ERROR if it fails — and in that failure case, an error message is left in the value result of childInterp. Also, bestie, plot twist: there are no restrictions on the ancestry relationship (as created by Tcl_CreateChild) between childInterp and targetInterp. Any two interpreters can be used, with zero restrictions on how they're related. Slay.
  • Tcl_CreateAliasObj — same vibe as Tcl_CreateAlias, except it takes a vector of values to pass as additional arguments instead of a vector of strings. Small change, big difference. ✨
  • Tcl_GetAliasObj — returns info in the form of a pointer to a vector of Tcl_Obj structures about an alias aliasName in interp. Any of the result fields can be NULL, in which case the corresponding datum is just not returned. If a result field is non-NULL, the address indicated gets set to the corresponding datum. For example, if targetCmdPtr is non-NULL, it gets set to a pointer to the string containing the name of the target command. 🎀
  • Tcl_ExposeCommand — moves the command named hiddenCmdName from the set of hidden commands over to the set of exposed commands, putting it under the name cmdName. hiddenCmdName must be the name of an existing hidden command, or the operation returns TCL_ERROR and leaves an error message as the result of interp. If an exposed command named cmdName already exists, the operation returns TCL_ERROR and leaves an error message as the result of interp. If everything goes right, it returns TCL_OK. After executing this command, attempts to use cmdName in any script evaluation mechanism will again succeed. Welcome back to the spotlight, babe. 👑
  • Tcl_HideCommand — moves the command named cmdName from the set of exposed commands to the set of hidden commands, under the name hiddenCmdName. cmdName must be the name of an existing exposed command, or the operation returns TCL_ERROR and leaves an error message as the result of interp. Currently both cmdName and hiddenCmdName must not contain namespace qualifiers, or the operation returns TCL_ERROR and leaves an error message as the result of interp. Also, cmdName will be looked up in the global namespace, and not relative to the current namespace — even if the current namespace is not the global one. Sneaky but true. And if a hidden command whose name is hiddenCmdName already exists, the operation also returns TCL_ERROR and an error message is left as the result of interp. If it succeeds, it returns TCL_OK. After executing this command, attempts to use cmdName in any script evaluation mechanism will fail. Gone. Ghosted. 👻
If you want the deets on the Tcl interface to multiple interpreters, go see interp(3tcl).

🫶 REFERENCE COUNT MANAGEMENT 🫶

Okay this part is important, don't skip it:

  • Tcl_CreateAliasObj increments the reference counts of the values in its objv argument. (And that reference lasts the same length of time as the owning alias.) So it's holding onto those values, periodt.
  • Tcl_GetAliasObj returns — via its objvPtr argument — a pointer to values that it holds a reference to. Keep that in mind and you won't get got. 💅

🌈 SEE ALSO 🌈

⭐ KEYWORDS ⭐

alias, command, exposed commands, hidden commands, interpreter, invoke, parent, child

And that's the whole tea, bestie 💖 this was Tcl_CreateAlias(3tcl) from Tcl 7.6, dated the same way the page itself signs off — go forth and manage those interpreters like the icon you are, mwah 🎀✨

📦 where this page comes from