Tcl_CreateAlias(3tcl)

💖 Tcl_CreateAlias(3tcl) 💖

okay bestie, welcome to the Tcl Library Procedures corner of the man pages, and specifically the one called Tcl_CreateAlias(3tcl). this is the ✨ interpreter-management ✨ page — multiple Tcl interpreters, aliases, and hidden commands, all in one place. it's giving "one page, twelve functions, zero chill". buckle up 🎀

---

🌸 NAME 🌸

Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave, Tcl_GetChild, Tcl_GetSlave, Tcl_GetParent, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand — manage multiple Tcl interpreters, aliases and hidden commands. that's the whole vibe, no cap.

---

✨ SYNOPSIS ✨

#include <tcl.h>

int
Tcl_IsSafe(interp)

int
Tcl_MakeSafe(interp)

Tcl_Interp *                                                             2
Tcl_CreateChild(interp, name, isSafe)                                    2

Tcl_Interp *
Tcl_CreateSlave(interp, name, isSafe)

Tcl_Interp *                                                             2
Tcl_GetChild(interp, name)                                               2

Tcl_Interp *
Tcl_GetSlave(interp, name)

Tcl_Interp *                                                             2
Tcl_GetParent(interp)                                                    2

Tcl_Interp *
Tcl_GetMaster(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_GetAlias(interp, childCmd, targetInterpPtr, targetCmdPtr,
             argcPtr, argvPtr)

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

int
Tcl_ExposeCommand(interp, hiddenCmdName, cmdName)

int
Tcl_HideCommand(interp, cmdName, hiddenCmdName)

bestie those little stray 2s floating off to the right? yeah. they're literally in the source. we keep them. periodt. 💅

---

🦋 ARGUMENTS 🦋

okay so every single one of these, in order, no skipping, i know it's a lot 🫶

• Tcl_Interp *interp (in) — the interpreter where you want the specified command to actually run.
• const char *name (in) — the name of the child interpreter you're creating or messing with.
• int isSafe (in) — if it's non-zero, you get a “safe” child, aka the kind that's suitable for running untrusted code. otherwise you get a trusted child. choose wisely, main character.
• Tcl_Interp *childInterp (in) — the interpreter to use for creating the source command for an alias (peep below for the deets).
• const char *childCmd (in) — the name of the source command for the alias.
• Tcl_Interp *targetInterp (in) — the interpreter that contains the target command for an alias.
• const char *targetCmd (in) — the name of the target command for the alias, inside targetInterp.
• int argc (in) — how many additional arguments to pass to the alias command.
• const char *const *argv (in) — a vector of strings: the additional arguments to pass to the alias command. heads up, this storage is owned by the caller. 👑
• int objc (in) — how many additional value arguments to pass to the aliased command.
• Tcl_Obj **objv (in) — a vector of Tcl_Obj structures: the additional value arguments to pass to the aliased command. and again, this storage is owned by the caller.
• Tcl_Interp **targetInterpPtr (in) — pointer to a location where you want to store the address of the interpreter where a target command is defined for an alias.
• const char **targetCmdPtr (out) — pointer to a location to store the address of the name of the target command for an alias.
• int *argcPtr (out) — pointer to a location to store the count of additional arguments that'll be passed to the alias. the location lives in storage owned by the caller.
• const char ***argvPtr (out) — pointer to a location to store a vector of strings — the additional arguments to pass to an alias. the location is in storage owned by the caller, but the vector of strings is owned by the called function. yes those are two different owners, yes it matters 😭
• int *objcPtr (out) — pointer to a location to store the count of additional value arguments that'll be passed to the alias. the location is in storage owned by the caller.
• Tcl_Obj ***objvPtr (out) — pointer to a location to store a vector of Tcl_Obj structures — the additional arguments to pass to an alias command. location = storage owned by the caller; the vector of Tcl_Obj structures = owned by the called function.
• const char *cmdName (in) — the name of an exposed command to hide or to create.
• const char *hiddenCmdName (in) — the name under which a hidden command is stored, and the name you use to expose or invoke it.

---

and that's the setup, bestie — we got the names, we got the signatures, we got every single argument and who owns what storage 🧚 part 2 is where it all gets explained, so don't go anywhere…

✨ DESCRIPTION ✨

Okay bestie, listen up, because these procedures are the VIP backstage pass to the multiple interpreter facility from inside C programs 💅. They let you run a whole hierarchy of interpreters — a little family tree of them — and they let you manage aliases, which are commands that, when you invoke them in one interpreter, go and execute a command in a different interpreter. It's giving long-distance relationship but make it functional 🫶.

For all the procedures that return an int, the return value is either TCL_OK or TCL_ERROR. And if you get TCL_ERROR back? The interpreter's result holds an error message. No mystery, no silence, it will tell you what went wrong 😭.

---

Tcl_CreateSlave creates a new interpreter as a child of interp. It also creates a child command named childName inside interp, which lets interp boss the new child around. Now the safety tea 🍵:

• If isSafe is zero, the command creates a trusted child, where Tcl code has access to all the Tcl commands.
• If isSafe is 1, the command creates a “safe” child, where Tcl code only gets access to the set of Tcl commands defined as “Safe Tcl”. (Go read the manual entry for the Tcl interp command for the deets, iykyk.)

And if creating that new child interpreter fails? You get NULL back. Periodt 💀.

Tcl_CreateChild is a synonym for Tcl_CreateSlave. (2)

Tcl_IsSafe returns 1 if interp is “safe” — meaning it was created with the TCL_SAFE_INTERPRETER flag specified — and 0 otherwise. Simple vibe check ✅.

Tcl_MakeSafe marks interp as “safe”, so future calls to Tcl_IsSafe will return 1. It also removes all known potentially-unsafe core functionality (both commands and variables) from interp.

But hold on bestie, this is the important part: it cannot know what parts of an extension or application are safe, and it does not make any attempt to remove those parts. So safety is not guaranteed after calling Tcl_MakeSafe. Callers will want to take care with their use of Tcl_MakeSafe to avoid false claims of safety. For many situations, Tcl_CreateSlave may be a better choice, since it creates interpreters in a known-safe state. Don't be out here making promises you can't keep 🙈.

Tcl_GetSlave returns a pointer to a child interpreter of interp. That child is identified by childName. If no such child interpreter exists, NULL is returned. Ngl, no child, no pointer 🦋.

Tcl_GetChild is a synonym for Tcl_GetSlave. (2)

Tcl_GetMaster returns a pointer to the master interpreter of interp. If interp has no master — because it's a top-level interpreter, the main character 👑 — then NULL is returned.

Tcl_GetParent is a synonym for Tcl_GetMaster. (2)

Tcl_GetInterpPath stores in the result of interp the relative path between interp and childInterp. And yes, childInterp must be a child of interp — that's not optional, bestie. If the computation of the relative path succeeds, TCL_OK is returned; otherwise TCL_ERROR is returned and an error message is stored as the result of interp.

Tcl_CreateAlias creates a command named childCmd in childInterp that, when invoked, will cause the command 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 to targetCmd — so those ones go first, every single time, no cutting the line 💅.

This operation returns TCL_OK if it succeeds, or TCL_ERROR if it fails; in that failure case, an error message is left in the value result of childInterp. And here's the iconic part: there are no restrictions on the ancestry relationship (as created by Tcl_CreateSlave) between childInterp and targetInterp. Any two interpreters can be used, without any restrictions on how they are related. Chosen family energy fr fr 🌈.

Tcl_CreateAliasObj is similar to Tcl_CreateAlias, except that it takes a vector of values to pass as additional arguments instead of a vector of strings.

Tcl_GetAliasObj returns information 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 not returned. If a result field is non-NULL, the address indicated is set to the corresponding datum. For example, if targetCmdPtr is non-NULL, it is set to a pointer to the string containing the name of the target command. Cute, right? You get to pick exactly which receipts you want 🧾✨.

Tcl_GetAlias is similar to Tcl_GetAliasObj, except that it returns a pointer to a vector of string instead of a vector of Tcl_Obj structures.

🚨 Tcl_GetAlias is deprecated. She's retired, let her rest, use the Obj version instead 😭.

Tcl_ExposeCommand moves the command named hiddenCmdName from the set of hidden commands 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 will return TCL_ERROR and leave 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. Name collision? Not on our watch 💀.
• If the operation succeeds, it returns TCL_OK.

After executing this command, attempts to use cmdName in any script evaluation mechanism will again succeed. She's back on stage, out of the shadows 👑✨.

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 will return TCL_ERROR and leave an error message as the result of interp.
• Currently, both cmdName and hiddenCmdName must not contain namespace qualifiers, or the operation will return TCL_ERROR and leave an error message as the result of interp. No namespace qualifiers allowed, that's the rule 📏.
• The 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. Global means global, bestie 🌍.
• 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 the operation succeeds, it returns TCL_OK.

After executing this command, attempts to use cmdName in any script evaluation mechanism will fail. Gone. Undercover. You didn't see her 🙈🕶️.

For a description of the Tcl interface to multiple interpreters, see interp(3tcl). Go read it, I'll wait 🫶.

---

🌸 SEE ALSO 🌸

• interp

---

🔑 KEYWORDS 🔑

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

---

And that's the whole page, bestie, we ate and left no crumbs 💅🍓. This little masterpiece comes from Tcl 7.6, and it's the Tcl_CreateAlias(3tcl) manual page. Go forth and make interpreters talk to each other, you absolute icon 🎀✨💖.