Tcl_LinkVar(3Tcl)					     Tcl_LinkVar(3Tcl)

NAME    [Toc]    [Back]

     Tcl_LinkVar, Tcl_UnlinkVar	- link Tcl variable to C variable

SYNOPSIS    [Toc]    [Back]

     #include <tcl.h>

     int
     Tcl_LinkVar(interp, varName, addr,	type)

     Tcl_UnlinkVar(interp, varName)

ARGUMENTS    [Toc]    [Back]

     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    [Toc]    [Back]

     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    [Toc]    [Back]
	  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    [Toc]    [Back]
	  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    [Toc]    [Back]
	  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	nonboolean
 values into varName will be rejected with Tcl	errors.

     TCL_LINK_STRING    [Toc]    [Back]
	  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    [Toc]    [Back]

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


									PPPPaaaaggggeeee 2222