1Tcl_LinkVar(3) Tcl Library Procedures Tcl_LinkVar(3)
2______________________________________________________________________________
6
8 Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar - link Tcl variable to
9 C variable
10
12 #include <tcl.h>
13 int
15 Tcl_LinkVar(interp, varName, addr, type)
16 Tcl_UnlinkVar(interp, varName)
18 Tcl_UpdateLinkedVar(interp, varName)
20
22 Tcl_Interp *interp (in) Interpreter that contains varName.
23 Also used by Tcl_LinkVar to return
24 error messages.
25 const char *varName (in) Name of global variable.
27 char *addr (in) Address of C variable that is to be
29 linked to varName.
30 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
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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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
215 Tcl_TraceVar(3)
216
218 boolean, integer, link, read-only, real, string, trace, variable
219Tcl 7.5 Tcl_LinkVar(3)