Tcl_LinkVar(3Tcl)Tcl_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
Page 1
Tcl_LinkVar(3Tcl)Tcl_LinkVar(3Tcl)
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
Page 2
