Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar - link Tcl
variable to C variable
Tcl_LinkVar(interp, varName, addr, type)
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
char *addr (in) Address of C variable
that is to be linked to
int type (in) Type of C variable.
Must be one of
ally OR'ed with
make Tcl variable read-
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
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:
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.
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.
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.
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.
boolean, integer, link, read-only, real, string, traces,