TclLinkVar(3) Tcl Library Procedures TclLinkVar(3)

NAME
       TclLinkVar,  TclUnlinkVar, TclUpdateLinkedVar - link Tcl variable to
       C variable

SYNOPSIS
       ##iinncclluuddee <>

       int
       TTccllLLiinnkkVVaarr(interp, varName, addr, type)

       TTccllUUnnlliinnkkVVaarr(interp, varName)

       TTccllUUppddaatteeLLiinnkkeeddVVaarr(interp, varName)

AARRGGUUMMEENNTTSS
       TclInterp   *interp    (in)      Interpreter  that  contains  varName.
                                         Also  used  by  TTccllLLiinnkkVVaarr 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
                                         TCLLINKINT,        TCLLINKDOUBLE, |
                                         TCLLINKWIDEINT,  TCLLINKBOOLEAN,
                                         or TCLLINKSTRING, optionally  OR'ed
                                         with  TCLLINKREADONLY  to make Tcl
                                         variable read-only.



DESCRIPTION
       TTccllLLiinnkkVVaarr 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.   TTccllLLiinnkkVVaarr  normally  returns
       TCLOK;   if  an  error  occurs while setting up the link (e.g. because
       varName is the name of array) then TCLERROR 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 TCLLINKREADONLY:

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

       TTCCLLLLIINNKKDDOOUUBBLLEE
              The  C  variable  is of type ddoouubbllee.  Any value written into the
              Tcl variable must have a proper real form acceptable to TTccllGGeett-
              DDoouubblleeFFrroommOObbjj;   attempts  to write non-real values into varName
              will be rejected with Tcl errors.

       TTCCLLLLIINNKKWWIIDDEEIINNTT
              The C variable is of type TTccllWWiiddeeIInntt (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 TTccllGGeettWWiiddeeIInnttFFrroommOObbjj;  attempts to write |
              non-integer values  into  varName  will  be  rejected  with  Tcl |
              errors.

       TTCCLLLLIINNKKBBOOOOLLEEAANN
              The  C  variable  is  of type iinntt.  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 TTccllGGeettBBoooolleeaannFFrroommOObbjj;
              attempts to  write  non-boolean  values  into  varName  will  be
              rejected with Tcl errors.

       TTCCLLLLIINNKKSSTTRRIINNGG
              The C variable is of type cchhaarr **.  If its value is not NULL then |
              it must be a pointer to a string  allocated  with  TTccllAAlllloocc  or |
              cckkaalllloocc.   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 TCLLINKREADONLY 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.

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

       TTccllUUppddaatteeLLiinnkkeeddVVaarr  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.  TTccllUUppddaatteeLLiinnkkeeddVVaarr ensures that any traces on
       the Tcl variable are invoked.


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



Tcl                                   7.5                       TclLinkVar(3)