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
44

DESCRIPTION

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

KEYWORDS

182       boolean, integer, link, read-only, real, string, traces, variable
183
184
185
186Tcl                                   7.5                       Tcl_LinkVar(3)
Impressum