Tcl_UpVar(3tcl)

______________________________________________________________________________

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.

       CONST char         *frameName       (in)      Identifies    the   stack
                                                     frame  containing  source
                                                     variable.   May  have any
                                                     of the forms accepted  by
                                                     the  upvar  command, such
                                                     as #0 or 1.

       CONST char         *sourceName      (in)      Name of source  variable,
                                                     in  the  frame  given  by
                                                     frameName.  May refer  to
                                                     a  scalar  variable or to
                                                     an array variable with  a
                                                     parenthesized index.

       CONST char         *destName        (in)      Name of destination vari-
                                                     able,  which  is  to   be
                                                     linked to source variable
                                                     so  that  references   to
                                                     destName   refer  to  the
                                                     other variable.  Must not
                                                     currently exist except as
                                                     an upvar-ed variable.

       int                flags            (in)      Either TCL_GLOBAL_ONLY or
                                                     0;    if  non-zero,  then
                                                     destName  is   a   global
                                                     variable;   otherwise  it
                                                     is a local to the current
                                                     procedure  (or  global if
                                                     no procedure is  active).

       CONST char         *name1           (in)      First   part   of  source
                                                     variable's  name  (scalar
                                                     name,  or  name  of array
                                                     without array index).

       CONST char         *name2           (in)      If source variable is  an
                                                     element   of   an  array,
                                                     gives the  index  of  the
                                                     element.     For   scalar
                                                     source   variables,    is
                                                     NULL.
_________________________________________________________________

DESCRIPTION

       Tcl_UpVar  and  Tcl_UpVar2  provide the same functionality as the upvar
       command:  they make a link from a  source  variable  to  a  destination
       variable,  so  that  references to the destination are passed transpar-
       ently 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 the interpreter's 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 destina-
       tion 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                         Tcl_UpVar(3)