LinkVar

     _________________________________________________________________

     NAME
          Tcl_LinkVar, Tcl_UnlinkVar - link Tcl variable to C variable

     SYNOPSIS
          #include <tcl.h>

          int
          Tcl_LinkVar(interp, varName, addr, type)

          Tcl_UnlinkVar(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.

          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 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
          interp->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_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''.  Whenver 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 malloc.  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.


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