Tcl_CreateAlias(3)

okay bestie welcome to the Tcl_CreateAlias(3) page from the Tcl Library Procedures manual 💖 This one is all about juggling multiple Tcl interpreters, aliases, and hidden commands like the main character you are.

✨ NAME ✨

So this whole page is the friend group for:

• Tcl_IsSafe
• Tcl_CreateChild
• Tcl_GetChild
• Tcl_GetParent
• Tcl_GetInterpPath
• Tcl_CreateAlias
• Tcl_CreateAliasObj
• Tcl_GetAliasObj
• Tcl_ExposeCommand
• Tcl_HideCommand

and their collective slay is to manage multiple Tcl interpreters, aliases and hidden commands. no cap.

---

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

Here's the tea on every single parameter:

• Tcl_Interp *interp (in) — the interpreter where you wanna run the specified command. it's giving home base.
• const char *name (in) — the name of the child interpreter you're creating or manipulating. name drop, literally.
• int isSafe (in) — if this is non-zero, you get a "safe" child that's suitable for running untrusted code; otherwise you get a trusted child. choose wisely bestie.
• Tcl_Interp *childInterp (in) — the interpreter used to create the source command for an alias (see below). source command energy.
• const char *childCmd (in) — the name of the source command for the alias. the origin story.
• Tcl_Interp *targetInterp (in) — the interpreter that contains the target command for an alias. where the magic happens.
• const char *targetCmd (in) — the name of the target command for the alias in targetInterp. the destination.
• Tcl_Size argc (in) — count of additional arguments to pass to the alias command. how many extra besties you're bringing.
• const char *const *argv (in) — vector of strings, the additional arguments to pass to the alias command. this storage is owned by the caller. so you're responsible for it, not us.
• Tcl_Size objc (in) — count of additional value arguments to pass to the aliased command. same vibe but with Tcl_Obj.
• Tcl_Obj **objv (in) — 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, we just borrow.
• Tcl_Interp **targetInterpPtr (in) — pointer to a location to store the address of the interpreter where a target command is defined for an alias. it's a pointer to a pointer, very meta.
• const char **targetCmdPtr (out) — pointer to a location to store the address of the name of the target command for an alias. out means we write here.
• Tcl_Size | int *objcPtr (out) — pointer to a location to 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 💀. so yeah, not a vibe to ignore.
• 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. the location is in storage owned by the caller; the vector of Tcl_Obj structures is owned by the called function. so we own the vector, you own the location.
• const char *cmdName (in) — the name of an exposed command to hide or create. main character name.
• const char *hiddenCmdName (in) — the name under which a hidden command is stored and with which it can be exposed or invoked. secret identity, iykyk.

✨ DESCRIPTION ✨

okay so bestie, these procedures are literally intended for access to the multiple interpreter facility from inside C programs. They enable managing multiple interpreters in a hierarchical relationship, and the management of aliases — commands that when invoked in one interpreter execute a command in another interpreter. The return value for those procedures that return an int is either TCL_OK or TCL_ERROR. If TCL_ERROR is returned then the interpreter's result contains an error message. periodt 💅

• Tcl_CreateChild — creates a new interpreter as a child of interp. It also creates a child command named name in interp which allows interp to manipulate the new child. If isSafe is 0, the command creates a trusted child in which Tcl code has access to all the Tcl commands. If it is 1, the command creates a “safe” child in which Tcl code has access only to set of Tcl commands defined as “Safe Tcl”; see the manual entry for the Tcl interp command for details. If the creation of the new child interpreter failed, NULL is returned. 😭
• Tcl_IsSafe — returns 1 if interp is “safe” (was created with the TCL_SAFE_INTERPRETER flag specified), 0 otherwise. 👑
• Tcl_GetChild — returns a pointer to a child interpreter of interp. The child interpreter is identified by name. If no such child interpreter exists, NULL is returned. 🦋
• Tcl_GetParent — returns a pointer to the parent interpreter of interp. If interp has no parent (it is a top-level interpreter) then NULL is returned. 🌸
• Tcl_GetInterpPath — stores in the result of interp the relative path between interp and childInterp; childInterp must be a child of interp. If the computation of the relative path succeeds, TCL_OK is returned, else 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. This operation returns TCL_OK if it succeeds, or TCL_ERROR if it fails; in that case, an error message is left in the value result of childInterp. Note that there are no restrictions on the ancestry relationship (as created by Tcl_CreateChild) between childInterp and targetInterp. Any two interpreters can be used, without any restrictions on how they are related. 💖
• Tcl_CreateAliasObj — 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. 🎀
• 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. If the operation succeeds, it returns TCL_OK. After executing this command, attempts to use cmdName in any script evaluation mechanism will again succeed. 🌈
• 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. 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. 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. 💀

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

---

✨ REFERENCE COUNT MANAGEMENT ✨

• Tcl_CreateAliasObj increments the reference counts of the values in its objv argument. (That reference lasts the same length of time as the owning alias.) 💅
• Tcl_GetAliasObj returns (via its objvPtr argument) a pointer to values that it holds a reference to. 🧚

---

✨ SEE ALSO ✨

• interp(n) 🌟

---

✨ KEYWORDS ✨

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

---

💖 that's it bestie! this page is from Tcl 7.6, and it's the Tcl_CreateAlias(3) manual page. mwah! 💅