linkvar(3Tcl)

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

     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.


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