ABCDEFGHIJKLMNOPQRSTUVWXYZ

Tcl_LinkVar

Tcl_LinkVar(3)              Tcl Library Procedures              Tcl_LinkVar(3)



______________________________________________________________________________

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.

       char         *varName   (in)      Name of global variable.  Must be  in
                                         writable  memory: Tcl may make tempo-
                                         rary modifications to it while  pars-
                                         ing the variable name.

       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_BOOLEAN, or TCL_LINK_STRING,
                                         optionally         OR'ed         with
                                         TCL_LINK_READ_ONLY to make Tcl  vari-
                                         able 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_GetInt;   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-
              Double;  attempts to write non-real 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_GetBoolean;
              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.
              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)