Tcl_UpVar(3tcl)

💖 Tcl_UpVar — bestie, we're linking variables 💖

okay so welcome to the Tcl_UpVar page from the Tcl Library Procedures manual, section 3tcl. sit down, grab a boba, because we're about to make two variables share a whole soul. 🫶

---

✨ NAME ✨

Tcl_UpVar, Tcl_UpVar2 — link one variable to another

---

🌸 SYNOPSIS 🌸

#include <tcl.h>

int
Tcl_UpVar(interp, frameName, sourceName, destName, flags)

int
Tcl_UpVar2(interp, frameName, name1, name2, destName, flags)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the interpreter that's holding all these variables; it's also the one that gets to spill the tea when something goes wrong (error reporting, bestie).
• const char *frameName (in) — tells us which stack frame the source variable is chilling in. it can take any of the forms the upvar command accepts, like #0 or 1. slay.
• const char *sourceName (in) — the name of the source variable, living in the frame given by frameName. it can point at a plain scalar variable, or at an array variable with a parenthesized index. either way, we see you. 👀
• const char *destName (in) — the name of the destination variable, which is gonna get linked to the source variable so that literally every reference to destName secretly refers to the other one. it must not already exist, unless it exists as an upvar-ed variable. no squatters, periodt.
• int flags (in) — one of TCL_GLOBAL_ONLY, TCL_NAMESPACE_ONLY or 0. if it's non-zero, then destName is a global or namespace variable; otherwise it's local to the current procedure (or local to the current namespace if there's no procedure active). choose your fighter. 💅
• const char *name1 (in) — the first part of the source variable's name (the scalar name, or the name of the array without the array index).
• const char *name2 (in) — if the source variable is an element of an array, this gives the index of that element. for scalar source variables, it's NULL. icon behavior.

---

💅 DESCRIPTION 💅

Tcl_UpVar and Tcl_UpVar2 do exactly what the upvar command does: they make a link from a source variable to a destination variable, so that references to the destination get passed transparently through to the source. it's giving "you are me and I am you" energy. 🦋

the name of the source variable can be specified two ways:

• as a single string, like xyx or a(24) — that's when you call Tcl_UpVar
• in two parts, where the array name has been separated from the element name — that's when you call Tcl_UpVar2

the destination variable name is always specified as a single string, and no, it may not be an array element. not up for debate. 💀

both procedures return either TCL_OK or TCL_ERROR, and if an error happens they leave an error message in the interpreter's result. so check that result, bestie, don't just assume.

as with the upvar command, the source variable doesn't even need to exist yet — she can be a total mystery. and if she does exist, unsetting it later does not destroy the link. the link is forever, no cap. 🔥

the destination variable may exist at the time of the call, but if it does, it has to exist as a linked variable. that's the vibe check and it is non-negotiable.

---

🔑 KEYWORDS 🔑

linked variable, upvar, variable

---

and that's the whole page, bestie!! 🎀 this one's from the <strong>Tcl 7.4</strong> era, filed under <strong>Tcl_UpVar(3tcl)</strong> in the Tcl Library Procedures manual — like, old-school iconic but still hitting. go forth and link those variables. mwah. 💖✨🫶