1Tcl_UpVar(3)                Tcl Library Procedures                Tcl_UpVar(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_UpVar, Tcl_UpVar2 - link one variable to another
9

SYNOPSIS

11       #include <tcl.h>
12
13       int
14       Tcl_UpVar(interp, frameName, sourceName, destName, flags)
15
16       int
17       Tcl_UpVar2(interp, frameName, name1, name2, destName, flags)
18

ARGUMENTS

20       Tcl_Interp *interp (in)              Interpreter  containing variables;
21                                            also used for error reporting.
22
23       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
28       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
34       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
41       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
49       const char *name1 (in)               First part  of  source  variable's
50                                            name  (scalar  name,  or  name  of
51                                            array without array index).
52
53       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
59

DESCRIPTION

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
70       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
73       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
78

KEYWORDS

80       linked variable, upvar, variable
81
82
83
84Tcl                                   7.4                         Tcl_UpVar(3)
Impressum