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   con­
                                         tains   varName.    Also
                                         used by  Tcl_LinkVar  to
                                         return error messages.

       char         *varName   (in)      Name of global variable.
                                         Must be in writable mem­
                                         ory: Tcl may make tempo­
                                         rary modifications to it
                                         while  parsing the vari­
                                         able 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, 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
       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_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  writ­
              ten  into  the Tcl variable must have a proper real
              form  acceptable  to  Tcl_GetDouble;   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 val­
              ues  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  vari­
              able 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 con­
              tains 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­
       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