Tcl_UpVar(3) Tcl Library Procedures Tcl_UpVar(3)_________________________________________________________________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) Interpreter
containing
variables;
also used
for error
reporting.
char *frameName (in) Identifies
the stack
frame con-
taining
source vari-
able. May
have any of
the forms
accepted by
the upvar
command,
such as #0
or 1.
char *sourceName (in) Name of
source vari-
able, in the
frame given
by frame-
Name. May
refer to a
scalar vari-
able or to
an array
variable
with a
parenthe-
sized index.
char *destName (in) Name of des-
tination
variable,
Tcl 7.4 1
Tcl_UpVar(3) Tcl Library Procedures Tcl_UpVar(3)
which is to
be linked to
source vari-
able so that
references
to destName
refer to the
other vari-
able. Must
not cur-
rently exist
except as an
upvar-ed
variable.
int flags (in) Either
TCL_GLOBAL_ONLY
or 0; if
non-zero,
then dest-
Name is a
global vari-
able; oth-
erwise it is
a local to
the current
procedure
(or global
if no proce-
dure is
active).
char *name1 (in) First part
of source
variable's
name (scalar
name, or
name of
array with-
out array
index).
char *name2 (in) If source
variable is
an element
of an array,
gives the
index of the
element.
For scalar
source vari-
ables, is
NULL.
_________________________________________________________________Tcl 7.4 2
Tcl_UpVar(3) Tcl Library Procedures Tcl_UpVar(3)DESCRIPTION
Tcl_UpVar and Tcl_UpVar2 provide the same functionality as
the upvar command: they make a link from a source vari-
able to a destination variable, so that references to the
destination are passed transparently through to the
source. The name of the source variable may be specified
either as a single string such as xyx or a(24) (by calling
Tcl_UpVar) or in two parts where the array name has been
separated from the element name (by calling Tcl_UpVar2).
The destination variable name is specified in a single
string; it may not be an array element.
Both procedures return either TCL_OK or TCL_ERROR, and
they leave an error message in interp->result if an error
occurs.
As with the upvar command, the source variable need not
exist; if it does exist, unsetting it later does not
destroy the link. The destination variable may exist at
the time of the call, but if so it must exist as a linked
variable.
KEYWORDS
linked variable, upvar, variable
Tcl 7.4 3
