Tcl_UpVar(3)

🦋 Tcl_UpVar — link one variable to another 🦋

okay bestie, sit down, hydrate, because this is the Tcl library page for Tcl_UpVar and Tcl_UpVar2 (that's the Tcl_UpVar(3) manual, she's iconic, she's from the Tcl Library Procedures, mwah 💅) and she's literally about making two variables hold hands forever.

---

✨ 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 your variables; also the one that's gonna spill the tea if something goes wrong, because it's used for error reporting.
• const char *frameName (in) — this is how we find the stack frame that's holding the source variable. she accepts literally any of the forms that the upvar command accepts, like #0 or 1. yes ma'am, all of them. 🌈
• const char *sourceName (in) — the name of the source variable, living inside the frame that frameName picked out. this can be a plain scalar variable, OR an array variable with a parenthesized index. so like, both vibes are valid. ✨
• const char *destName (in) — the name of the destination variable, aka the one that gets linked to the source so that anything you say about destName is secretly about the other variable. 👀 big "we're the same person actually" energy.

🚨 bestie listen: destName must not currently exist, unless it exists as an upvar-ed variable. no random pre-existing variable, that's not the move.

• 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, if no procedure is active, local to the current namespace). pick your fighter. 💀
• const char *name1 (in) — the first part of the source variable's name. that's 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 is the index of that element. for scalar source variables? it's NULL. that's it, that's the whole job. 🙈

---

👑 DESCRIPTION 👑

Tcl_UpVar and Tcl_UpVar2 do exactly what the upvar command does — same functionality, no cap. 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're my proxy now, bestie". 🔥

you can name the source variable two ways:

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

the destination variable name gets given as a single string. and nope, it may not be an array element. periodt. 💅

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, okay? 😭

and just like with the upvar command, the source variable doesn't even have to exist. iconic behaviour honestly. if it does exist, unsetting it later does not destroy the link — the link survives, she's resilient. 🧚

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 rule, we don't make them. ⭐

---

🔑 KEYWORDS 🔑

linked variable, upvar, variable 💜

---

okay that's the whole page, you ate it, I'm so proud of you 🎀 this was Tcl_UpVar(3) from the Tcl manual, version 7.4, dated 7.4 — and that's the cute little sign-off from your fave manpage bestie. go forth and link some variables, mwah 💖✨🦋