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

FreeBSD Manual Pages

  
 
  

home | help
Tcl_LinkVar(3)		    Tcl	Library	Procedures		Tcl_LinkVar(3)

______________________________________________________________________________

NAME
       Tcl_LinkArray,  Tcl_LinkVar,  Tcl_UnlinkVar, Tcl_UpdateLinkedVar	- link
       Tcl variable to C variable

SYNOPSIS
       #include	<tcl.h>

       int
       Tcl_LinkVar(interp, varName, addr, type)

       int								       2
       Tcl_LinkArray(interp, varName, addr, type, size)			       2

       Tcl_UnlinkVar(interp, varName)

       Tcl_UpdateLinkedVar(interp, varName)

ARGUMENTS
       Tcl_Interp *interp (in)		Interpreter  that  contains   varName.
					Also used by Tcl_LinkVar to return er-
					ror messages.

       const char *varName (in)		Name of	global variable.

       void *addr (in)			Address	 of  C	variable that is to be
					linked to varName.

					In Tcl_LinkArray, may be NULL to  tell 2
					Tcl  to	create the storage for the ar- 2
					ray in the variable.

       int type	(in)			Type of	C variable for Tcl_LinkVar  or
					type  of array element for Tcl_LinkAr-
					ray.  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
					one of the extra ones listed below.

					In  Tcl_LinkVar, the additional	linked
					type TCL_LINK_STRING may be used.

					In   Tcl_LinkArray,   the   additional 2
					linked	  types	  TCL_LINK_CHARS   and 2
					TCL_LINK_BINARY	may be used.

					All the	above for both	functions  may
					be	optionally	OR'ed	  with
					TCL_LINK_READ_ONLY  to	make  the  Tcl
					variable read-only.

       Tcl_Size	size (in)		The number of elements in the C	array. 2
					Must be	greater	than zero.
______________________________________________________________________________

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.

       Tcl_LinkArray  is  similar,  but	for arrays of fixed size (given	by the 2
       size argument). When asked to allocate the backing C array storage (via 2
       the addr	argument being NULL), it writes	the address that it  allocated 2
       to the Tcl interpreter result.

       The  type argument specifies the	type of	the C variable,	or the type of
       the elements of the C array, and	must have one of the following values,
       optionally OR'ed	with TCL_LINK_READ_ONLY:

       TCL_LINK_INT
	      The C variable, or each element of the C array, is of type  int.
	      Any value	written	into the Tcl variable must have	a proper inte-
	      ger  form	 acceptable  to	 Tcl_GetIntFromObj;  attempts to write
	      non-integer values into varName will be rejected	with  Tcl  er-
	      rors. Incomplete integer representations (like the empty string,
	      '+', '-' or the hex/octal/decimal/binary prefix) are accepted as
	      if they are valid	too.

       TCL_LINK_UINT
	      The  C  variable,	or each	element	of the C array,	is of type un-
	      signed int.  Any value written into the Tcl variable must	have a
	      proper unsigned integer form acceptable 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 rejected with	Tcl errors. Incomplete
	      integer representations (like the	empty string, '+', '-' or  the
	      hex/octal/decimal/binary	prefix)	 are  accepted	as if they are
	      valid too.

       TCL_LINK_CHAR
	      The C variable, or each element of the C array, is of type char.
	      Any value	written	into the Tcl variable must have	a proper inte-
	      ger form acceptable to Tcl_GetIntFromObj 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. Incomplete
	      integer  representations (like the empty string, '+', '-'	or the
	      hex/octal/decimal/binary prefix) are accepted  as	 if  they  are
	      valid too.

	      If  using	 an  array of these, consider using TCL_LINK_CHARS in- 2
	      stead.

       TCL_LINK_CHARS
	      The C array is of	type char *  and  is  mapped  into  Tcl	 as  a 2
	      string.	Any  value written into	the Tcl	variable must have the 2
	      same length as  the  underlying  storage.	 Only  supported  with 2
	      Tcl_LinkArray.

       TCL_LINK_UCHAR
	      The  C  variable,	or each	element	of the C array,	is of type un-
	      signed char.  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 char	 type;
	      attempts	to  write  non-integer	values	(or values outside the
	      range) into varName will be rejected with	Tcl errors. Incomplete
	      integer representations (like the	empty string, '+', '-' or  the
	      hex/octal/decimal/binary	prefix)	 are  accepted	as if they are
	      valid too.

	      If using an array	of these, consider using  TCL_LINK_BINARY  in- 2
	      stead.

       TCL_LINK_BINARY
	      The C array is of	type unsigned char * and is mapped into	Tcl as 2
	      a	 bytearray.  Any value written into the	Tcl variable must have 2
	      the same length as the underlying	storage. Only  supported  with 2
	      Tcl_LinkArray.

       TCL_LINK_SHORT
	      The  C  variable,	 or  each  element  of the C array, is of type
	      short.  Any value	written	into the  Tcl  variable	 must  have  a
	      proper  integer  form  acceptable	to Tcl_GetIntFromObj 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.  Incomplete  integer  representations  (like  the	 empty
	      string, '+', '-' or the hex/octal/decimal/binary prefix) are ac-
	      cepted as	if they	are valid too.

       TCL_LINK_USHORT
	      The  C  variable,	or each	element	of the C array,	is of type un-
	      signed 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 rejected with	Tcl errors. Incomplete
	      integer representations (like the	empty string, '+', '-' or  the
	      hex/octal/decimal/binary	prefix)	 are  accepted	as if they are
	      valid too.

       TCL_LINK_LONG
	      The C variable, or each element of the C array, is of type long.
	      Any value	written	into the Tcl variable must have	a proper inte-
	      ger form acceptable to  Tcl_GetLongFromObj;  attempts  to	 write
	      non-integer or out-of-range values into varName will be rejected
	      with  Tcl	 errors.  Incomplete integer representations (like the
	      empty string, '+', '-' or	the  hex/octal/decimal/binary  prefix)
	      are accepted as if they are valid	too.

       TCL_LINK_ULONG
	      The  C  variable,	or each	element	of the C array,	is of type un-
	      signed long.  Any	value written into the Tcl variable must  have
	      a	 proper	unsigned integer form acceptable to Tcl_GetWideIntFro-
	      mObj 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 rejected with Tcl	errors.	Incom-
	      plete integer representations (like the empty string,  '+',  '-'
	      or  the hex/octal/decimal/binary prefix) are accepted as if they
	      are valid	too.

       TCL_LINK_DOUBLE
	      The C variable, or each element of the C array, is of type  dou-
	      ble.  Any	value written into the Tcl variable must have a	proper
	      real form	acceptable to Tcl_GetDoubleFromObj;  attempts to write
	      non-real	values	into varName will be rejected with Tcl errors.
	      Incomplete integer  or  real  representations  (like  the	 empty
	      string,  '.',  '+',  '-' or the hex/octal/decimal/binary prefix)
	      are accepted as if they are valid	too.

       TCL_LINK_FLOAT
	      The C variable, or each element of  the  C  array,  is  of  type
	      float.   Any  value  written  into  the Tcl variable must	have a
	      proper real form acceptable to Tcl_GetDoubleFromObj 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.	Incomplete integer or real representa-
	      tions  (like  the	 empty	string,	 '.',  '+', '-'	or the hex/oc-
	      tal/decimal/binary prefix) are accepted as  if  they  are	 valid
	      too.

       TCL_LINK_WIDE_INT
	      The  C  variable,	 or  each  element  of the C array, 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	 integer  form	acceptable  to
	      Tcl_GetWideIntFromObj;   attempts	 to  write  non-integer	values
	      into varName will	be rejected with Tcl errors. Incomplete	 inte-
	      ger  representations  (like  the	empty  string, '+', '-'	or the
	      hex/octal/decimal/binary prefix) are accepted  as	 if  they  are
	      valid too.

       TCL_LINK_WIDE_UINT
	      The  C  variable,	 or  each  element  of the C array, is of type
	      Tcl_WideUInt (which is an	unsigned 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 unsigned wideinteger
	      form acceptable to  Tcl_GetWideUIntFromObj;  attempts  to	 write
	      non-integer  values  into	 varName will be rejected with Tcl er-
	      rors. Incomplete integer representations (like the empty string,
	      '+', '-' or the hex/octal/decimal/binary prefix) are accepted as
	      if they are valid	too.

       TCL_LINK_BOOLEAN
	      The C variable, or each element of the C array, is of type  int.
	      If  its  value is	zero then it will read from Tcl	as "0";	other-
	      wise it will read	from Tcl as "1".  Whenever  varName  is	 modi-
	      fied,  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 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	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".  This is only sup-
	      ported by	Tcl_LinkVar.

       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.

       Note  that,  as with any	call to	a Tcl interpreter, Tcl_UpdateLinkedVar
       must be called from the same thread that	created	the  interpreter.  The
       safest  mechanism is to ensure that the C variable is only ever updated
       from the	same thread that created the interpreter (possibly in response
       to an event posted with Tcl_ThreadQueueEvent), but when it is necessary
       to update the variable  in  a  separate	thread,	 it  is	 advised  that
       Tcl_AsyncMark be	used to	indicate to the	thread hosting the interpreter
       that it is ready	to run Tcl_UpdateLinkedVar.

SEE ALSO
       Tcl_TraceVar(3)

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

Tcl				      7.5			Tcl_LinkVar(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_UpdateLinkedVar.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help