Tcl_CreateAlias(3)

💅 Tcl_CreateAlias(3) — from the Tcl Library Procedures, bestie edition 🎀

Okay so real talk, this page is a whole family of functions bundled together: 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 — and they all live under one roof so you can manage multiple Tcl interpreters, aliases and hidden commands. Iconic behavior honestly. 👑

---

✨ 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 🌸

---

🌈 SYNOPSIS 🌈

#include <tcl.h>

int
Tcl_IsSafe(interp)

int
Tcl_MakeSafe(interp)

Tcl_Interp *
Tcl_CreateChild(interp, name, isSafe)

Tcl_Interp *
Tcl_CreateSlave(interp, name, isSafe)

Tcl_Interp *
Tcl_GetChild(interp, name)

Tcl_Interp *
Tcl_GetSlave(interp, name)

Tcl_Interp *
Tcl_GetParent(interp)

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)

🫶 tiny formatting heads-up: on the real printed page, some of the Child-flavoured entries have a little change-bar 2 hanging out in the margin. That's just typesetting marketing, the code above is the actual vibe. 💅

---

🦋 ARGUMENTS 🦋

• Tcl_Interp *interp (in) — the interpreter where the specified command is gonna get executed. main character interpreter, basically. ⭐
• const char *name (in) — the name of the child interpreter you're creating or manipulating. name it something cute. 🎀
• int isSafe (in) — if it's non-zero, you get a safe child, meaning one that's suitable for running untrusted code (sketchy lil code, protected). If it's zero, you get a trusted child. choose wisely bestie. 🙈
• Tcl_Interp *childInterp (in) — the interpreter used for creating the source command for an alias (more on that below, keep reading 💖).
• 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. that's where the actual work lives ✨
• const char *targetCmd (in) — the name of the target command for the alias, and it lives 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, so don't go freeing it thinking you're helping. 😭
• 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. no cap. 🫶
• Tcl_Interp **targetInterpPtr (in) — pointer to the location where we store the address of the interpreter where a target command is defined for an alias.
• const char **targetCmdPtr (out) — pointer to the location where we store the address of the name of the target command for an alias.
• int *argcPtr (out) — pointer to the location where we store the count of additional arguments that are gonna be passed to the alias. This location sits in storage owned by the caller. 🍓
• const char ***argvPtr (out) — pointer to the location where we 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. read that twice, it's giving plot twist 💀
• int *objcPtr (out) — pointer to the location where we store the count of additional value arguments that are gonna be passed to the alias. This location is in storage owned by the caller.
• Tcl_Obj ***objvPtr (out) — pointer to the location where we 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, the vector of Tcl_Obj structures is owned by the called function. same energy as above, stay woke 👑
• const char *cmdName (in) — the name of an exposed command to hide, or to create. slay.
• const char *hiddenCmdName (in) — the name under which a hidden command is stored, and the name you can use to expose it or invoke it. secret identity vibes 🕵️‍♀️

---

(bestie this is only part 1, the plot thickens — more incoming 💖)

💖 DESCRIPTION 💖

okay so here's the vibe: these procedures are for getting at the multiple-interpreter situation from inside C programs 🔥. They let you manage a whole hierarchy of interpreters — parent, child, the whole family tree — plus the management of aliases, which are literally just commands that, when you invoke them in one interpreter, execute a command in another interpreter. yes bestie, cross-interpreter teleportation 🧚✨

and the return value tea: for all of those procedures that return an int, it's either TCL_OK or TCL_ERROR. If TCL_ERROR comes back? The interpreter's result has an error message in it. no cap, always check 💅

---

🍼 Tcl_CreateSlave

Tcl_CreateSlave creates a new interpreter as a child of interp. It also creates a child command named childName in interp, which is what lets interp actually manipulate the new child 👑

now for the isSafe situation:

• If isSafe is zero, the command creates a trusted child — Tcl code in there has access to all the Tcl commands. full access, main character energy, nothing held back 😳
• If it is 1, the command creates a “safe” child, in which Tcl code has access only to the set of Tcl commands defined as “Safe Tcl”. for the details on that, go read the manual entry for the Tcl interp command, iykyk 💅

and if the creation of the new child interpreter failed? NULL is returned. that's it. no child for you 🙈

🪞 Tcl_CreateChild

Tcl_CreateChild is a synonym for Tcl_CreateSlave. same thing, different name, slay. (the original page has a lil footnote marker 2 sitting at the end of that line — consider it officially noted 🎀)

🛡️ Tcl_IsSafe

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, in and out 💜

🧼 Tcl_MakeSafe

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

⚠️ but listen 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 claiming safety you don't have, fr fr 😭

🔍 Tcl_GetSlave

Tcl_GetSlave returns a pointer to a child interpreter of interp. the child interpreter is identified by childName. if no such child interpreter exists, NULL is returned. no child, no pointer, no drama 🦋

🪞 Tcl_GetChild

Tcl_GetChild is a synonym for Tcl_GetSlave. (again with the footnote marker 2 at the end of the line — noted, girlie 🌸)

👑 Tcl_GetMaster

Tcl_GetMaster returns a pointer to the master interpreter of interp. if interp has no master (because it's a top-level interpreter, a rootless queen), then NULL is returned ✨

🪞 Tcl_GetParent

Tcl_GetParent is a synonym for Tcl_GetMaster. (yep, footnote marker 2 again, we see you 👀)

🗺️ Tcl_GetInterpPath

Tcl_GetInterpPath stores in the result of interp the relative path between interp and childInterp. important: childInterp must be a child of interp. if the computation of the relative path succeeds, TCL_OK is returned. if it doesn't, TCL_ERROR is returned and an error message is stored as the result of interp. it's giving directions-app energy 🧭

🔗 Tcl_CreateAlias

Tcl_CreateAlias creates a command named childCmd in childInterp that, when invoked, will cause the command targetCmd to be invoked in targetInterp. iconic behaviour, honestly 💅

the arguments specified by the strings contained in argv are always prepended to any arguments supplied in the invocation of childCmd, and then passed to targetCmd. always. prepended. no exceptions 🎀

this operation returns TCL_OK if it succeeds, or TCL_ERROR if it fails — and in that case, an error message is left in the value result of childInterp.

and here's the fun 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're related. cousins? strangers? doesn't matter. love wins 🌈

🔗 Tcl_CreateAliasObj

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. same energy, fancier types 💜

🔎 Tcl_GetAliasObj

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. pick and choose what you wanna know 🍓

🔎 Tcl_GetAlias

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.

💀 heads up: Tcl_GetAlias is deprecated. it's giving legacy. use accordingly.

👁️‍🗨️ Tcl_ExposeCommand

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. glow-up complete, she's public now ✨

the rules:

• 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's taken, bestie 😭
• if the operation succeeds, it returns TCL_OK.

and after executing this command, attempts to use cmdName in any script evaluation mechanism will again succeed. welcome back to the main stage 👑

🙈 Tcl_HideCommand

Tcl_HideCommand moves the command named cmdName from the set of exposed commands to the set of hidden commands, under the name hiddenCmdName. ninja mode activated 🥷

the rules, and there are several:

• 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. yes, currently. rules are rules 🎀
• 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. no shortcuts, no local searching, fr fr.
• 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. collision, denied 🙅‍♀️
• if the operation succeeds, it returns TCL_OK.

and after executing this command, attempts to use cmdName in any script evaluation mechanism will fail. gone. vanished. she's in the vault now 💀

---

for a description of the Tcl interface to multiple interpreters, see interp(n).

🦋 SEE ALSO 🦋

• interp

🔑 KEYWORDS 🔑

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

---

okay that's the whole page bestie, you're officially fluent in interpreter hierarchies 💖 this one shipped with Tcl 7.6 and the page is Tcl_CreateAlias(3) — go forth and alias responsibly, ily, bye 🫶✨🎀