Tcl_LinkVar(3tcl)

______________________________________________________________________________

NAME

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

SYNOPSIS

       #include <tcl.h>

       int
       Tcl_LinkVar(interp, varName, addr, type)

       Tcl_UnlinkVar(interp, varName)

       Tcl_UpdateLinkedVar(interp, varName)

ARGUMENTS

       Tcl_Interp   *interp    (in)      Interpreter  that  contains  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, optionally  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 var-
       Name  in  sync with the C variable at the address given by addr.  When-
       ever 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 inter-
       preter'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_Get-
              IntFromObj;  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 written into the
              Tcl variable must have a proper real form acceptable to Tcl_Get-
              DoubleFromObj;   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 inte- |
              ger 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 variable 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 proce-
       dure has no effect.

       Tcl_UpdateLinkedVar  may be invoked after the C variable has changed to
       force the Tcl variable to be updated immediately.  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)