Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  contains  varName.
					 Also  used  by	 Tcl_LinkVar to	return
					 error messages.

       const 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_UINT, |
					 TCL_LINK_CHAR,	       TCL_LINK_UCHAR, |
					 TCL_LINK_SHORT,      TCL_LINK_USHORT, |
					 TCL_LINK_LONG,	       TCL_LINK_ULONG,
					 TCL_LINK_WIDE_INT,		       |
					 TCL_LINK_WIDE_UINT,   TCL_LINK_FLOAT,
					 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 var-
       Name in sync with the C variable	at the address given by	 addr.	 When-
       ever  the  Tcl variable is read the value of the	C variable will	be re-
       turned, 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 the interpreter's re-
       sult 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_Get-
	      IntFromObj;   attempts  to write non-integer values into varName
	      will be rejected with Tcl	errors.				       |

       TCL_LINK_UINT							       |
	      The C variable is	of type	unsigned int.  Any value written  into |
	      the  Tcl	variable  must have a proper unsigned integer form ac- |
	      ceptable to Tcl_GetWideIntFromObj	and in the platform's  defined |
	      range  for  the unsigned int type; attempts to write non-integer |
	      values (or values	outside	the range) into	varName	 will  be  re- |
	      jected with Tcl errors.					       |

       TCL_LINK_CHAR							       |
	      The  C variable is of type char.	Any value written into the Tcl |
	      variable must have a proper integer form acceptable to  Tcl_Get- |
	      IntFromObj and be	in the range of	the char datatype; attempts to |
	      write non-integer	or out-of-range	values into  varName  will  be |
	      rejected with Tcl	errors.					       |

       TCL_LINK_UCHAR							       |
	      The C variable is	of type	unsigned char.	Any value written into |
	      the Tcl variable must have a proper unsigned  integer  form  ac- |
	      ceptable	to  Tcl_GetIntFromObj  and  in	the platform's defined |
	      range for	the unsigned char type;	attempts to write  non-integer |
	      values  (or  values  outside the range) into varName will	be re- |
	      jected with Tcl errors.					       |

       TCL_LINK_SHORT							       |
	      The C variable is	of type	short.	Any value written into the Tcl |
	      variable	must have a proper integer form	acceptable to Tcl_Get- |
	      IntFromObj and be	in the range of	the short  datatype;  attempts |
	      to write non-integer or out-of-range values into varName will be |
	      rejected with Tcl	errors.					       |

       TCL_LINK_USHORT							       |
	      The C variable is	of type	unsigned  short.   Any	value  written |
	      into  the	 Tcl variable must have	a proper unsigned integer form |
	      acceptable to Tcl_GetIntFromObj and in  the  platform's  defined |
	      range for	the unsigned short type; attempts to write non-integer |
	      values (or values	outside	the range) into	varName	 will  be  re- |
	      jected with Tcl errors.					       |

       TCL_LINK_LONG							       |
	      The  C variable is of type long.	Any value written into the Tcl |
	      variable must have a proper integer form acceptable to  Tcl_Get- |
	      LongFromObj;  attempts to	write non-integer or out-of-range val- |
	      ues into varName will be rejected	with Tcl errors.	       |

       TCL_LINK_ULONG							       |
	      The C variable is	of type	unsigned long.	Any value written into |
	      the  Tcl	variable  must have a proper unsigned integer form ac- |
	      ceptable to Tcl_GetWideIntFromObj	and in the platform's  defined |
	      range  for the unsigned long type; attempts to write non-integer |
	      values (or values	outside	the range) into	varName	 will  be  re- |
	      jected 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_Get-
	      DoubleFromObj;   attempts	 to write non-real values into varName
	      will be rejected with Tcl	errors.				       |

       TCL_LINK_FLOAT							       |
	      The C variable is	of type	float.	Any value written into the Tcl |
	      variable	must have a proper real	form acceptable	to Tcl_GetDou- |
	      bleFromObj and must be within the	range acceptable for a	float; |
	      attempts	to write non-real values (or values outside the	range) |
	      into varName will	be rejected with Tcl errors.

       TCL_LINK_WIDE_INT
	      The C variable is	of type	Tcl_WideInt (which is an integer  type
	      at  least	 64-bits  wide	on all platforms that can support it.)
	      Any value	written	into the Tcl variable must have	a proper inte-
	      ger form acceptable to Tcl_GetWideIntFromObj;  attempts to write
	      non-integer values into varName will be rejected	with  Tcl  er-
	      rors.							       |

       TCL_LINK_WIDE_UINT						       |
	      The C variable is	of type	Tcl_WideUInt (which is an unsigned in- |
	      teger type at least 64-bits wide on all platforms	that can  sup- |
	      port  it.)   Any value written into the Tcl variable must	have a |
	      proper unsigned integer form acceptable to Tcl_GetWideIntFromObj |
	      (it  will	 be  cast  to unsigned); attempts to write non-integer |
	      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_GetBooleanFromObj;
	      attempts	to  write  non-boolean values into varName will	be re-
	      jected 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	or ck-
	      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	proce-
       dure 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 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

Tcl				      7.5			Tcl_LinkVar(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_LinkVar.tcl85&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help