1Tcl_UpVar(3) Tcl Library Procedures Tcl_UpVar(3)
2______________________________________________________________________________
6
8 Tcl_UpVar, Tcl_UpVar2 - link one variable to another
9
11 #include <tcl.h>
12 int
14 Tcl_UpVar(interp, frameName, sourceName, destName, flags)
15 int
17 Tcl_UpVar2(interp, frameName, name1, name2, destName, flags)
18
20 Tcl_Interp *interp (in) Interpreter containing variables;
21 also used for error reporting.
22 const char *frameName (in) Identifies the stack frame con‐
24 taining source variable. May have
25 any of the forms accepted by the
26 upvar command, such as #0 or 1.
27 const char *sourceName (in) Name of source variable, in the
29 frame given by frameName. May
30 refer to a scalar variable or to
31 an array variable with a parenthe‐
32 sized index.
33 const char *destName (in) Name of destination variable,
35 which is to be linked to source
36 variable so that references to
37 destName refer to the other vari‐
38 able. Must not currently exist
39 except as an upvar-ed variable.
40 int flags (in) One of TCL_GLOBAL_ONLY, TCL_NAMES‐
42 PACE_ONLY or 0; if non-zero, then
43 destName is a global or namespace
44 variable; otherwise it is local
45 to the current procedure (or cur‐
46 rent namespace if no procedure is
47 active).
48 const char *name1 (in) First part of source variable's
50 name (scalar name, or name of
51 array without array index).
52 const char *name2 (in) If source variable is an element
54 of an array, gives the index of
55 the element. For scalar source
56 variables, is NULL.
57_________________________________________________________________
58
61 Tcl_UpVar and Tcl_UpVar2 provide the same functionality as the upvar
62 command: they make a link from a source variable to a destination
63 variable, so that references to the destination are passed transpar‐
64 ently through to the source. The name of the source variable may be
65 specified either as a single string such as xyx or a(24) (by calling
66 Tcl_UpVar) or in two parts where the array name has been separated from
67 the element name (by calling Tcl_UpVar2). The destination variable
68 name is specified in a single string; it may not be an array element.
69 Both procedures return either TCL_OK or TCL_ERROR, and they leave an
71 error message in the interpreter's result if an error occurs.
72 As with the upvar command, the source variable need not exist; if it
74 does exist, unsetting it later does not destroy the link. The destina‐
75 tion variable may exist at the time of the call, but if so it must
76 exist as a linked variable.
77
80 linked variable, upvar, variable
81Tcl 7.4 Tcl_UpVar(3)