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
                                                     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_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 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 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