Tcl_LinkVar(3) Tcl Library Procedures 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 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-
able 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, 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
Tcl 7.5 1
Tcl_LinkVar(3) Tcl Library Procedures Tcl_LinkVar(3)
(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 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.
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 val-
ues 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 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-
diately. In many cases this procedure is not needed,
since any attempt to read the Tcl variable will return the
Tcl 7.5 2
Tcl_LinkVar(3) Tcl Library Procedures Tcl_LinkVar(3)
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
Tcl 7.5 3
