1Tcl_LinkVar(3)              Tcl Library Procedures              Tcl_LinkVar(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_LinkVar,  Tcl_UnlinkVar, Tcl_UpdateLinkedVar - link Tcl variable to
9       C variable
10

SYNOPSIS

12       #include <tcl.h>
13
14       int
15       Tcl_LinkVar(interp, varName, addr, type)
16
17       Tcl_UnlinkVar(interp, varName)
18
19       Tcl_UpdateLinkedVar(interp, varName)
20

ARGUMENTS

22       Tcl_Interp *interp (in)           Interpreter  that  contains  varName.
23                                         Also  used  by  Tcl_LinkVar to return
24                                         error messages.
25
26       const char *varName (in)          Name of global variable.
27
28       char *addr (in)                   Address of C variable that is  to  be
29                                         linked to varName.
30
31       int type (in)                     Type  of  C variable.  Must be one of
32                                         TCL_LINK_INT,          TCL_LINK_UINT,
33                                         TCL_LINK_CHAR,        TCL_LINK_UCHAR,
34                                         TCL_LINK_SHORT,      TCL_LINK_USHORT,
35                                         TCL_LINK_LONG,        TCL_LINK_ULONG,
36                                         TCL_LINK_WIDE_INT,
37                                         TCL_LINK_WIDE_UINT,   TCL_LINK_FLOAT,
38                                         TCL_LINK_DOUBLE, TCL_LINK_BOOLEAN, or
39                                         TCL_LINK_STRING,   optionally   OR'ed
40                                         with TCL_LINK_READ_ONLY to  make  Tcl
41                                         variable read-only.
42______________________________________________________________________________
43

DESCRIPTION

45       Tcl_LinkVar uses variable traces to keep the Tcl variable named by var‐
46       Name in sync with the C variable at the address given by  addr.   When‐
47       ever  the  Tcl  variable  is  read  the value of the C variable will be
48       returned, and whenever the Tcl variable is written the C variable  will
49       be  updated  to  have  the  same  value.   Tcl_LinkVar normally returns
50       TCL_OK;  if an error occurs while setting up  the  link  (e.g.  because
51       varName is the name of array) then TCL_ERROR is returned and the inter‐
52       preter's result contains an error message.
53
54       The type argument specifies the type of the C variable, and  must  have
55       one of the following values, optionally OR'ed with TCL_LINK_READ_ONLY:
56
57       TCL_LINK_INT
58              The  C  variable is of type int.  Any value written into the Tcl
59              variable must have a proper integer form acceptable to  Tcl_Get‐
60              IntFromObj;   attempts  to write non-integer values into varName
61              will be rejected with Tcl errors. Incomplete integer representa‐
62              tions  (like  the empty string, '+', '-' or the hex/octal/binary
63              prefix) are accepted as if they are valid too.
64
65       TCL_LINK_UINT
66              The C variable is of type unsigned int.  Any value written  into
67              the  Tcl  variable  must  have  a  proper  unsigned integer form
68              acceptable  to  Tcl_GetWideIntFromObj  and  in  the   platform's
69              defined  range for the unsigned int type; attempts to write non-
70              integer values (or values outside the range) into  varName  will
71              be  rejected with Tcl errors. Incomplete integer representations
72              (like the empty string, '+', '-' or the hex/octal/binary prefix)
73              are accepted as if they are valid too.
74
75       TCL_LINK_CHAR
76              The  C variable is of type char.  Any value written into the Tcl
77              variable must have a proper integer form acceptable to  Tcl_Get‐
78              IntFromObj and be in the range of the char datatype; attempts to
79              write non-integer or out-of-range values into  varName  will  be
80              rejected  with  Tcl  errors.  Incomplete integer representations
81              (like the empty string, '+', '-' or the hex/octal/binary prefix)
82              are accepted as if they are valid too.
83
84       TCL_LINK_UCHAR
85              The C variable is of type unsigned char.  Any value written into
86              the Tcl variable  must  have  a  proper  unsigned  integer  form
87              acceptable  to  Tcl_GetIntFromObj  and in the platform's defined
88              range for the unsigned char type; attempts to write  non-integer
89              values  (or  values  outside  the  range)  into  varName will be
90              rejected with Tcl  errors.  Incomplete  integer  representations
91              (like the empty string, '+', '-' or the hex/octal/binary prefix)
92              are accepted as if they are valid too.
93
94       TCL_LINK_SHORT
95              The C variable is of type short.  Any value written into the Tcl
96              variable  must have a proper integer form acceptable to Tcl_Get‐
97              IntFromObj and be in the range of the short  datatype;  attempts
98              to write non-integer or out-of-range values into varName will be
99              rejected with Tcl  errors.  Incomplete  integer  representations
100              (like the empty string, '+', '-' or the hex/octal/binary prefix)
101              are accepted as if they are valid too.
102
103       TCL_LINK_USHORT
104              The C variable is of type unsigned  short.   Any  value  written
105              into  the  Tcl variable must have a proper unsigned integer form
106              acceptable to Tcl_GetIntFromObj and in  the  platform's  defined
107              range for the unsigned short type; attempts to write non-integer
108              values (or values  outside  the  range)  into  varName  will  be
109              rejected  with  Tcl  errors.  Incomplete integer representations
110              (like the empty string, '+', '-' or the hex/octal/binary prefix)
111              are accepted as if they are valid too.
112
113       TCL_LINK_LONG
114              The  C variable is of type long.  Any value written into the Tcl
115              variable must have a proper integer form acceptable to  Tcl_Get‐
116              LongFromObj;  attempts to write non-integer or out-of-range val‐
117              ues into varName will be rejected with  Tcl  errors.  Incomplete
118              integer  representations (like the empty string, '+', '-' or the
119              hex/octal/binary prefix) are accepted as if they are valid too.
120
121       TCL_LINK_ULONG
122              The C variable is of type unsigned long.  Any value written into
123              the  Tcl  variable  must  have  a  proper  unsigned integer form
124              acceptable  to  Tcl_GetWideIntFromObj  and  in  the   platform's
125              defined range for the unsigned long type; attempts to write non-
126              integer values (or values outside the range) into  varName  will
127              be  rejected with Tcl errors. Incomplete integer representations
128              (like the empty string, '+', '-' or the hex/octal/binary prefix)
129              are accepted as if they are valid too.
130
131       TCL_LINK_DOUBLE
132              The  C  variable  is of type double.  Any value written into the
133              Tcl variable must have a proper real form acceptable to Tcl_Get‐
134              DoubleFromObj;   attempts  to write non-real values into varName
135              will be rejected with Tcl errors.  Incomplete  integer  or  real
136              representations  (like  the  empty  string, '.', '+', '-' or the
137              hex/octal/binary prefix) are accepted as if they are valid too.
138
139       TCL_LINK_FLOAT
140              The C variable is of type float.  Any value written into the Tcl
141              variable  must have a proper real form acceptable to Tcl_GetDou‐
142              bleFromObj and must be within the range acceptable for a  float;
143              attempts  to write non-real values (or values outside the range)
144              into varName will be rejected with Tcl errors. Incomplete  inte‐
145              ger  or  real  representations (like the empty string, '.', '+',
146              '-' or the hex/octal/binary prefix) are accepted as if they  are
147              valid too.
148
149       TCL_LINK_WIDE_INT
150              The  C variable is of type Tcl_WideInt (which is an integer type
151              at least 64-bits wide on all platforms  that  can  support  it.)
152              Any value written into the Tcl variable must have a proper inte‐
153              ger form acceptable to Tcl_GetWideIntFromObj;  attempts to write
154              non-integer  values  into  varName  will  be  rejected  with Tcl
155              errors.  Incomplete  integer  representations  (like  the  empty
156              string, '+', '-' or the hex/octal/binary prefix) are accepted as
157              if they are valid too.
158
159       TCL_LINK_WIDE_UINT
160              The C variable is of type Tcl_WideUInt  (which  is  an  unsigned
161              integer  type  at  least  64-bits wide on all platforms that can
162              support it.)  Any value written into the Tcl variable must  have
163              a  proper unsigned integer form acceptable to Tcl_GetWideIntFro‐
164              mObj (it will be cast to unsigned); attempts to write  non-inte‐
165              ger values into varName will be rejected with Tcl errors. Incom‐
166              plete integer representations (like the empty string,  '+',  '-'
167              or  the  hex/octal/binary  prefix)  are  accepted as if they are
168              valid too.
169
170       TCL_LINK_BOOLEAN
171              The C variable is of type int.  If its value  is  zero  then  it
172              will  read  from  Tcl as “0”; otherwise it will read from Tcl as
173              “1”.  Whenever varName is modified, the C variable will  be  set
174              to a 0 or 1 value.  Any value written into the Tcl variable must
175              have a proper boolean form acceptable to  Tcl_GetBooleanFromObj;
176              attempts  to  write  non-boolean  values  into  varName  will be
177              rejected with Tcl errors.
178
179       TCL_LINK_STRING
180              The C variable is of type char *.  If its value is not NULL then
181              it  must  be  a  pointer to a string allocated with Tcl_Alloc or
182              ckalloc.  Whenever the Tcl variable is modified  the  current  C
183              string  will be freed and new memory will be allocated to hold a
184              copy of the variable's new value.  If the C variable contains  a
185              NULL pointer then the Tcl variable will read as “NULL”.
186
187       If  the  TCL_LINK_READ_ONLY  flag  is present in type then the variable
188       will be read-only from Tcl, so that its value can only  be  changed  by
189       modifying the C variable.  Attempts to write the variable from Tcl will
190       be rejected with errors.
191
192       Tcl_UnlinkVar removes the link previously set up for the variable given
193       by varName.  If there does not exist a link for varName then the proce‐
194       dure has no effect.
195
196       Tcl_UpdateLinkedVar may be invoked after the C variable has changed  to
197       force  the  Tcl variable to be updated immediately.  In many cases this
198       procedure is not needed, since any attempt to  read  the  Tcl  variable
199       will  return  the  latest value of the C variable.  However, if a trace
200       has been set on the Tcl variable (such as a Tk widget  that  wishes  to
201       display the value of the variable), the trace will not trigger when the
202       C variable has changed.  Tcl_UpdateLinkedVar ensures that any traces on
203       the Tcl variable are invoked.
204
205       Note  that,  as with any call to a Tcl interpreter, Tcl_UpdateLinkedVar
206       must be called from the same thread that created the  interpreter.  The
207       safest  mechanism is to ensure that the C variable is only ever updated
208       from the same thread that created the interpreter (possibly in response
209       to an event posted with Tcl_ThreadQueueEvent), but when it is necessary
210       to update the variable  in  a  separate  thread,  it  is  advised  that
211       Tcl_AsyncMark be used to indicate to the thread hosting the interpreter
212       that it is ready to run Tcl_UpdateLinkedVar.
213

SEE ALSO

215       Tcl_TraceVar(3)
216

KEYWORDS

218       boolean, integer, link, read-only, real, string, trace, variable
219
220
221
222Tcl                                   7.5                       Tcl_LinkVar(3)
Impressum