Tcl_UpVar(3)          Tcl Library Procedures         Tcl_UpVar(3)



_________________________________________________________________

NAME
       Tcl_UpVar, Tcl_UpVar2 - link one variable to another

SYNOPSIS
       #include 

       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   con-
                                                     taining
                                                     source vari-
                                                     able.    May
                                                     have any  of
                                                     the    forms
                                                     accepted  by
                                                     the    upvar
                                                     command,
                                                     such  as  #0
                                                     or 1.

       CONST 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.

       CONST char         *destName        (in)      Name of des-
                                                     tination
                                                     variable,
                                                     which  is to
                                                     be linked to
                                                     source vari-
                                                     able 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   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).

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

       CONST 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.
_________________________________________________________________


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



Tcl                            7.4                   Tcl_UpVar(3)