tcl7.6 C API - LinkVar






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  tem-
                                       porary modifications to it
                                       while parsing the variable
                                       name.

     char         *addr      (in)      Address of C variable that
                                       is  to  be  linked to var-
                                       Name.

     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 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''.  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 procedure 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 vari-
     able are invoked.



KEYWORDS

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