1 | '\" |
---|
2 | '\" Copyright (c) 1989-1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: SetVar.3,v 1.16 2007/12/13 15:22:32 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures" |
---|
12 | .BS |
---|
13 | .SH NAME |
---|
14 | Tcl_SetVar2Ex, Tcl_SetVar, Tcl_SetVar2, Tcl_ObjSetVar2, Tcl_GetVar2Ex, Tcl_GetVar, Tcl_GetVar2, Tcl_ObjGetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables |
---|
15 | .SH SYNOPSIS |
---|
16 | .nf |
---|
17 | \fB#include <tcl.h>\fR |
---|
18 | .sp |
---|
19 | Tcl_Obj * |
---|
20 | \fBTcl_SetVar2Ex\fR(\fIinterp, name1, name2, newValuePtr, flags\fR) |
---|
21 | .sp |
---|
22 | const char * |
---|
23 | \fBTcl_SetVar\fR(\fIinterp, varName, newValue, flags\fR) |
---|
24 | .sp |
---|
25 | const char * |
---|
26 | \fBTcl_SetVar2\fR(\fIinterp, name1, name2, newValue, flags\fR) |
---|
27 | .sp |
---|
28 | Tcl_Obj * |
---|
29 | \fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR) |
---|
30 | .sp |
---|
31 | Tcl_Obj * |
---|
32 | \fBTcl_GetVar2Ex\fR(\fIinterp, name1, name2, flags\fR) |
---|
33 | .sp |
---|
34 | const char * |
---|
35 | \fBTcl_GetVar\fR(\fIinterp, varName, flags\fR) |
---|
36 | .sp |
---|
37 | const char * |
---|
38 | \fBTcl_GetVar2\fR(\fIinterp, name1, name2, flags\fR) |
---|
39 | .sp |
---|
40 | Tcl_Obj * |
---|
41 | \fBTcl_ObjGetVar2\fR(\fIinterp, part1Ptr, part2Ptr, flags\fR) |
---|
42 | .sp |
---|
43 | int |
---|
44 | \fBTcl_UnsetVar\fR(\fIinterp, varName, flags\fR) |
---|
45 | .sp |
---|
46 | int |
---|
47 | \fBTcl_UnsetVar2\fR(\fIinterp, name1, name2, flags\fR) |
---|
48 | .SH ARGUMENTS |
---|
49 | .AS Tcl_Interp *newValuePtr |
---|
50 | .AP Tcl_Interp *interp in |
---|
51 | Interpreter containing variable. |
---|
52 | .AP "const char" *name1 in |
---|
53 | Contains the name of an array variable (if \fIname2\fR is non-NULL) |
---|
54 | or (if \fIname2\fR is NULL) either the name of a scalar variable |
---|
55 | or a complete name including both variable name and index. |
---|
56 | May include \fB::\fR namespace qualifiers |
---|
57 | to specify a variable in a particular namespace. |
---|
58 | .AP "const char" *name2 in |
---|
59 | If non-NULL, gives name of element within array; in this |
---|
60 | case \fIname1\fR must refer to an array variable. |
---|
61 | .AP Tcl_Obj *newValuePtr in |
---|
62 | Points to a Tcl object containing the new value for the variable. |
---|
63 | .AP int flags in |
---|
64 | OR-ed combination of bits providing additional information. See below |
---|
65 | for valid values. |
---|
66 | .AP "const char" *varName in |
---|
67 | Name of variable. |
---|
68 | May include \fB::\fR namespace qualifiers |
---|
69 | to specify a variable in a particular namespace. |
---|
70 | May refer to a scalar variable or an element of |
---|
71 | an array. |
---|
72 | .AP "const char" *newValue in |
---|
73 | New value for variable, specified as a null-terminated string. |
---|
74 | A copy of this value is stored in the variable. |
---|
75 | .AP Tcl_Obj *part1Ptr in |
---|
76 | Points to a Tcl object containing the variable's name. |
---|
77 | The name may include a series of \fB::\fR namespace qualifiers |
---|
78 | to specify a variable in a particular namespace. |
---|
79 | May refer to a scalar variable or an element of an array variable. |
---|
80 | .AP Tcl_Obj *part2Ptr in |
---|
81 | If non-NULL, points to an object containing the name of an element |
---|
82 | within an array and \fIpart1Ptr\fR must refer to an array variable. |
---|
83 | .BE |
---|
84 | |
---|
85 | .SH DESCRIPTION |
---|
86 | .PP |
---|
87 | These procedures are used to create, modify, read, and delete |
---|
88 | Tcl variables from C code. |
---|
89 | .PP |
---|
90 | \fBTcl_SetVar2Ex\fR, \fBTcl_SetVar\fR, \fBTcl_SetVar2\fR, and |
---|
91 | \fBTcl_ObjSetVar2\fR |
---|
92 | will create a new variable or modify an existing one. |
---|
93 | These procedures set the given variable to the value |
---|
94 | given by \fInewValuePtr\fR or \fInewValue\fR and return a |
---|
95 | pointer to the variable's new value, which is stored in Tcl's |
---|
96 | variable structure. |
---|
97 | \fBTcl_SetVar2Ex\fR and \fBTcl_ObjSetVar2\fR take the new value as a |
---|
98 | Tcl_Obj and return |
---|
99 | a pointer to a Tcl_Obj. \fBTcl_SetVar\fR and \fBTcl_SetVar2\fR |
---|
100 | take the new value as a string and return a string; they are |
---|
101 | usually less efficient than \fBTcl_ObjSetVar2\fR. Note that the |
---|
102 | return value may be different than the \fInewValuePtr\fR or |
---|
103 | \fInewValue\fR argument, due to modifications made by write traces. |
---|
104 | If an error occurs in setting the variable (e.g. an array |
---|
105 | variable is referenced without giving an index into the array) |
---|
106 | NULL is returned and an error message is left in \fIinterp\fR's |
---|
107 | result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR bit is set. |
---|
108 | .PP |
---|
109 | \fBTcl_GetVar2Ex\fR, \fBTcl_GetVar\fR, \fBTcl_GetVar2\fR, and |
---|
110 | \fBTcl_ObjGetVar2\fR |
---|
111 | return the current value of a variable. |
---|
112 | The arguments to these procedures are treated in the same way |
---|
113 | as the arguments to the procedures described above. |
---|
114 | Under normal circumstances, the return value is a pointer |
---|
115 | to the variable's value. For \fBTcl_GetVar2Ex\fR and |
---|
116 | \fBTcl_ObjGetVar2\fR the value is |
---|
117 | returned as a pointer to a Tcl_Obj. For \fBTcl_GetVar\fR and |
---|
118 | \fBTcl_GetVar2\fR the value is returned as a string; this is |
---|
119 | usually less efficient, so \fBTcl_GetVar2Ex\fR or \fBTcl_ObjGetVar2\fR |
---|
120 | are preferred. |
---|
121 | If an error occurs while reading the variable (e.g. the variable |
---|
122 | does not exist or an array element is specified for a scalar |
---|
123 | variable), then NULL is returned and an error message is left |
---|
124 | in \fIinterp\fR's result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR |
---|
125 | bit is set. |
---|
126 | .PP |
---|
127 | \fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove |
---|
128 | a variable, so that future attempts to read the variable will return |
---|
129 | an error. |
---|
130 | The arguments to these procedures are treated in the same way |
---|
131 | as the arguments to the procedures above. |
---|
132 | If the variable is successfully removed then \fBTCL_OK\fR is returned. |
---|
133 | If the variable cannot be removed because it does not exist then |
---|
134 | \fBTCL_ERROR\fR is returned and an error message is left |
---|
135 | in \fIinterp\fR's result if the \fBTCL_LEAVE_ERR_MSG\fR \fIflag\fR |
---|
136 | bit is set. |
---|
137 | If an array element is specified, the given element is removed |
---|
138 | but the array remains. |
---|
139 | If an array name is specified without an index, then the entire |
---|
140 | array is removed. |
---|
141 | .PP |
---|
142 | The name of a variable may be specified to these procedures in |
---|
143 | four ways: |
---|
144 | .IP [1] |
---|
145 | If \fBTcl_SetVar\fR, \fBTcl_GetVar\fR, or \fBTcl_UnsetVar\fR |
---|
146 | is invoked, the variable name is given as |
---|
147 | a single string, \fIvarName\fR. |
---|
148 | If \fIvarName\fR contains an open parenthesis and ends with a |
---|
149 | close parenthesis, then the value between the parentheses is |
---|
150 | treated as an index (which can have any string value) and |
---|
151 | the characters before the first open |
---|
152 | parenthesis are treated as the name of an array variable. |
---|
153 | If \fIvarName\fR does not have parentheses as described above, then |
---|
154 | the entire string is treated as the name of a scalar variable. |
---|
155 | .IP [2] |
---|
156 | If the \fIname1\fR and \fIname2\fR arguments are provided and |
---|
157 | \fIname2\fR is non-NULL, then an array element is specified and |
---|
158 | the array name and index have |
---|
159 | already been separated by the caller: \fIname1\fR contains the |
---|
160 | name and \fIname2\fR contains the index. An error is generated |
---|
161 | if \fIname1\fR contains an open parenthesis and ends with a |
---|
162 | close parenthesis (array element) and \fIname2\fR is non-NULL. |
---|
163 | .IP [3] |
---|
164 | If \fIname2\fR is NULL, \fIname1\fR is treated just like |
---|
165 | \fIvarName\fR in case [1] above (it can be either a scalar or an array |
---|
166 | element variable name). |
---|
167 | .PP |
---|
168 | The \fIflags\fR argument may be used to specify any of several |
---|
169 | options to the procedures. |
---|
170 | It consists of an OR-ed combination of the following bits. |
---|
171 | .TP |
---|
172 | \fBTCL_GLOBAL_ONLY\fR |
---|
173 | Under normal circumstances the procedures look up variables as follows. |
---|
174 | If a procedure call is active in \fIinterp\fR, |
---|
175 | the variable is looked up at the current level of procedure call. |
---|
176 | Otherwise, the variable is looked up first in the current namespace, |
---|
177 | then in the global namespace. |
---|
178 | However, if this bit is set in \fIflags\fR then the variable |
---|
179 | is looked up only in the global namespace |
---|
180 | even if there is a procedure call active. |
---|
181 | If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given, |
---|
182 | \fBTCL_GLOBAL_ONLY\fR is ignored. |
---|
183 | .TP |
---|
184 | \fBTCL_NAMESPACE_ONLY\fR |
---|
185 | If this bit is set in \fIflags\fR then the variable |
---|
186 | is looked up only in the current namespace; if a procedure is active |
---|
187 | its variables are ignored, and the global namespace is also ignored unless |
---|
188 | it is the current namespace. |
---|
189 | .TP |
---|
190 | \fBTCL_LEAVE_ERR_MSG\fR |
---|
191 | If an error is returned and this bit is set in \fIflags\fR, then |
---|
192 | an error message will be left in the interpreter's result, |
---|
193 | where it can be retrieved with \fBTcl_GetObjResult\fR |
---|
194 | or \fBTcl_GetStringResult\fR. |
---|
195 | If this flag bit is not set then no error message is left |
---|
196 | and the interpreter's result will not be modified. |
---|
197 | .TP |
---|
198 | \fBTCL_APPEND_VALUE\fR |
---|
199 | If this bit is set then \fInewValuePtr\fR or \fInewValue\fR is |
---|
200 | appended to the current value instead of replacing it. |
---|
201 | If the variable is currently undefined, then the bit is ignored. |
---|
202 | This bit is only used by the \fBTcl_Set*\fR procedures. |
---|
203 | .TP |
---|
204 | \fBTCL_LIST_ELEMENT\fR |
---|
205 | If this bit is set, then \fInewValue\fR is converted to a valid |
---|
206 | Tcl list element before setting (or appending to) the variable. |
---|
207 | A separator space is appended before the new list element unless |
---|
208 | the list element is going to be the first element in a list or |
---|
209 | sublist (i.e. the variable's current value is empty, or contains |
---|
210 | the single character |
---|
211 | .QW { , |
---|
212 | or ends in |
---|
213 | .QW " }" ). |
---|
214 | When appending, the original value of the variable must also be |
---|
215 | a valid list, so that the operation is the appending of a new |
---|
216 | list element onto a list. |
---|
217 | .PP |
---|
218 | \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR |
---|
219 | return the current value of a variable. |
---|
220 | The arguments to these procedures are treated in the same way |
---|
221 | as the arguments to \fBTcl_SetVar\fR and \fBTcl_SetVar2\fR. |
---|
222 | Under normal circumstances, the return value is a pointer |
---|
223 | to the variable's value (which is stored in Tcl's variable |
---|
224 | structure and will not change before the next call to \fBTcl_SetVar\fR |
---|
225 | or \fBTcl_SetVar2\fR). |
---|
226 | \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR use the flag bits \fBTCL_GLOBAL_ONLY\fR |
---|
227 | and \fBTCL_LEAVE_ERR_MSG\fR, both of |
---|
228 | which have |
---|
229 | the same meaning as for \fBTcl_SetVar\fR. |
---|
230 | If an error occurs in reading the variable (e.g. the variable |
---|
231 | does not exist or an array element is specified for a scalar |
---|
232 | variable), then NULL is returned. |
---|
233 | .PP |
---|
234 | \fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove |
---|
235 | a variable, so that future calls to \fBTcl_GetVar\fR or \fBTcl_GetVar2\fR |
---|
236 | for the variable will return an error. |
---|
237 | The arguments to these procedures are treated in the same way |
---|
238 | as the arguments to \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR. |
---|
239 | If the variable is successfully removed then \fBTCL_OK\fR is returned. |
---|
240 | If the variable cannot be removed because it does not exist then |
---|
241 | \fBTCL_ERROR\fR is returned. |
---|
242 | If an array element is specified, the given element is removed |
---|
243 | but the array remains. |
---|
244 | If an array name is specified without an index, then the entire |
---|
245 | array is removed. |
---|
246 | |
---|
247 | .SH "SEE ALSO" |
---|
248 | Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar |
---|
249 | |
---|
250 | .SH KEYWORDS |
---|
251 | array, get variable, interpreter, object, scalar, set, unset, variable |
---|