Tcl_LinkVar(3) Tcl (7.5) Tcl_LinkVar(3)
_________________________________________________________________
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
temporary modifications to
it while parsing the
variable 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,
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
Page 1 (printed 2/19/99)
Tcl_LinkVar(3) Tcl (7.5) Tcl_LinkVar(3)
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
Page 2 (printed 2/19/99)
Tcl_LinkVar(3) Tcl (7.5) Tcl_LinkVar(3)
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
variable are invoked.
KEYWORDS
boolean, integer, link, read-only, real, string, traces,
variable
Page 3 (printed 2/19/99)
