Tcl_LinkVar(3)        Tcl Library Procedures       Tcl_LinkVar(3)



_________________________________________________________________

NAME
       Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar - link Tcl
       variable to C variable

SYNOPSIS
       #include 

       int
       Tcl_LinkVar(interp, varName, addr, type)

       Tcl_UnlinkVar(interp, varName)

       Tcl_UpdateLinkedVar(interp, varName)

ARGUMENTS
       Tcl_Interp   *interp    (in)      Interpreter  that   con-
                                         tains   varName.    Also
                                         used by  Tcl_LinkVar  to
                                         return error messages.

       CONST char   *varName   (in)      Name of global variable.

       char         *addr      (in)      Address  of  C  variable
                                         that  is to be linked to
                                         varName.

       int          type       (in)      Type  of   C   variable.
                                         Must     be    one    of
                                         TCL_LINK_INT,
                                         TCL_LINK_DOUBLE,         |
                                         TCL_LINK_WIDE_INT,
                                         TCL_LINK_BOOLEAN,     or
                                         TCL_LINK_STRING, option-
                                         ally      OR'ed     with
                                         TCL_LINK_READ_ONLY    to
                                         make  Tcl variable read-
                                         only.
_________________________________________________________________


DESCRIPTION
       Tcl_LinkVar uses variable traces to keep the Tcl  variable
       named  by  varName  in  sync  with  the  C variable at the
       address given by addr.  Whenever the Tcl variable is  read
       the value of the C variable will be returned, and whenever
       the Tcl variable is written the C variable will be updated
       to  have  the  same  value.   Tcl_LinkVar normally returns
       TCL_OK;  if an error occurs  while  setting  up  the  link
       (e.g. because varName is the name of array) then TCL_ERROR
       is returned and the interpreter's result contains an error
       message.

       The  type  argument  specifies the type of the C variable,
       and must have one  of  the  following  values,  optionally
       OR'ed with TCL_LINK_READ_ONLY:

       TCL_LINK_INT
              The  C  variable is of type int.  Any value written
              into the Tcl variable must have  a  proper  integer
              form  acceptable to Tcl_GetIntFromObj;  attempts to
              write  non-integer  values  into  varName  will  be
              rejected with Tcl errors.

       TCL_LINK_DOUBLE
              The  C variable is of type double.  Any value writ-
              ten into the Tcl variable must have a  proper  real
              form  acceptable to Tcl_GetDoubleFromObj;  attempts
              to write  non-real  values  into  varName  will  be
              rejected with Tcl errors.

       TCL_LINK_WIDE_INT
              The  C variable is of type Tcl_WideInt (which is an |
              integer type at least 64-bits wide on all platforms |
              that  can  support it.)  Any value written into the |
              Tcl  variable  must  have  a  proper  integer  form |
              acceptable  to  Tcl_GetWideIntFromObj;  attempts to |
              write  non-integer  values  into  varName  will  be |
              rejected with Tcl errors.

       TCL_LINK_BOOLEAN
              The  C  variable  is  of type int.  If its value is
              zero then it will read from Tcl as ``0''; otherwise
              it  will  read from Tcl as ``1''.  Whenever varName
              is modified, the C variable will be set to a 0 or 1
              value.   Any  value  written  into the Tcl variable
              must have  a  proper  boolean  form  acceptable  to
              Tcl_GetBooleanFromObj;    attempts  to  write  non-
              boolean values into varName will be  rejected  with
              Tcl errors.

       TCL_LINK_STRING
              The  C variable is of type char *.  If its value is |
              not NULL then it must be  a  pointer  to  a  string |
              allocated  with Tcl_Alloc or ckalloc.  Whenever the
              Tcl variable is modified the current C string  will
              be freed and new memory will be allocated to hold a
              copy of the variable's new value.  If the  C  vari-
              able  contains a NULL pointer then the Tcl variable
              will read as ``NULL''.

       If the TCL_LINK_READ_ONLY flag is present in type then the
       variable will be read-only from Tcl, so that its value can
       only be changed by modifying the C variable.  Attempts  to
       write  the variable from Tcl will be rejected with errors.

       Tcl_UnlinkVar removes the link previously set up  for  the
       variable given by varName.  If there does not exist a link
       for varName then the procedure has no effect.

       Tcl_UpdateLinkedVar may be invoked after  the  C  variable
       has  changed to force the Tcl variable to be updated imme-
       diately.  In many cases  this  procedure  is  not  needed,
       since any attempt to read the Tcl variable will return the
       latest value of the C variable.  However, if a  trace  has
       been  set  on  the  Tcl variable (such as a Tk widget that
       wishes to display the value of the  variable),  the  trace
       will   not  trigger  when  the  C  variable  has  changed.
       Tcl_UpdateLinkedVar ensures that any  traces  on  the  Tcl
       variable are invoked.


KEYWORDS
       boolean,  integer,  link, read-only, real, string, traces,
       variable



Tcl                            7.5                 Tcl_LinkVar(3)