1Tcl_CreateSlave(3) Tcl Library Procedures Tcl_CreateSlave(3)
2______________________________________________________________________________
6
8 Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster,
9 Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias,
10 Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand - manage multiple
11 Tcl interpreters, aliases and hidden commands.
12
14 #include <tcl.h>
15 int
17 Tcl_IsSafe(interp)
18 int
20 Tcl_MakeSafe(interp)
21 Tcl_Interp *
23 Tcl_CreateSlave(interp, slaveName, isSafe)
24 Tcl_Interp *
26 Tcl_GetSlave(interp, slaveName)
27 Tcl_Interp *
29 Tcl_GetMaster(interp)
30 int
32 Tcl_GetInterpPath(askingInterp, slaveInterp)
33 int │
35 Tcl_CreateAlias(slaveInterp, slaveCmd, targetInterp, targetCmd, argc, argv)│
36 int │
38 Tcl_CreateAliasObj(slaveInterp, slaveCmd, targetInterp, targetCmd, objc, objv)│
39 int
41 Tcl_GetAlias(interp, slaveCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr)
42 int │
44 Tcl_GetAliasObj(interp, slaveCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr)│
45 int │
47 Tcl_ExposeCommand(interp, hiddenCmdName, cmdName) │
48 int │
50 Tcl_HideCommand(interp, cmdName, hiddenCmdName) │
51
53 Tcl_Interp *interp (in) │
54 Interpreter in which │
55 to execute the spec‐ │
56 ified command. │
57 CONST char *slaveName (in) │
59 Name of slave inter‐ │
60 preter to create or │
61 manipulate. │
62 int isSafe (in) │
64 If non-zero, a │
65 ``safe'' slave that │
66 is suitable for run‐ │
67 ning untrusted code │
68 is created, other‐ │
69 wise a trusted slave │
70 is created. │
71 Tcl_Interp *slaveInterp (in) │
73 Interpreter to use │
74 for creating the │
75 source command for │
76 an alias (see │
77 below). │
78 CONST char *slaveCmd (in) │
80 Name of source com‐ │
81 mand for alias. │
82 Tcl_Interp *targetInterp (in) │
84 Interpreter that │
85 contains the target │
86 command for an │
87 alias. │
88 CONST char *targetCmd (in) │
90 Name of target com‐ │
91 mand for alias in │
92 targetInterp. │
93 int argc (in) │
95 Count of additional │
96 arguments to pass to │
97 the alias command. │
98 CONST char * CONST *argv (in) │
100 Vector of strings, │
101 the additional argu‐ │
102 ments to pass to the │
103 alias command. This │
104 storage is owned by │
105 the caller. │
106 int objc (in) │
108 Count of additional │
109 object arguments to │
110 pass to the alias │
111 object command. │
112 Tcl_Object **objv (in) │
114 Vector of Tcl_Obj │
115 structures, the │
116 additional object │
117 arguments to pass to │
118 the alias object │
119 command. This stor‐ │
120 age is owned by the │
121 caller. │
122 Tcl_Interp **targetInterpPtr (in) │
124 Pointer to location │
125 to store the address │
126 of the interpreter │
127 where a target com‐ │
128 mand is defined for │
129 an alias. │
130 CONST char **targetCmdPtr (out) │
132 Pointer to location │
133 to store the address │
134 of the name of the │
135 target command for │
136 an alias. │
137 int *argcPtr (out) │
139 Pointer to location │
140 to store count of │
141 additional arguments │
142 to be passed to the │
143 alias. The location │
144 is in storage owned │
145 by the caller. │
146 CONST char ***argvPtr (out) │
148 Pointer to location │
149 to store a vector of │
150 strings, the addi‐ │
151 tional arguments to │
152 pass to an alias. │
153 The location is in │
154 storage owned by the │
155 caller, the vector │
156 of strings is owned │
157 by the called func‐ │
158 tion. │
159 int *objcPtr (out) │
161 Pointer to location │
162 to store count of │
163 additional object │
164 arguments to be │
165 passed to the alias. │
166 The location is in │
167 storage owned by the │
168 caller. │
169 Tcl_Obj ***objvPtr (out) │
171 Pointer to location │
172 to store a vector of │
173 Tcl_Obj structures, │
174 the additional argu‐ │
175 ments to pass to an │
176 object alias com‐ │
177 mand. The location │
178 is in storage owned │
179 by the caller, the │
180 vector of Tcl_Obj │
181 structures is owned │
182 by the called func‐ │
183 tion. │
184 CONST char *cmdName (in) │
186 Name of an exposed
187 command to hide or
188 create. │
189 CONST char *hiddenCmdName (in) │
191 Name under which a
192 hidden command is
193 stored and with
194 which it can be
195 exposed or invoked.
196_________________________________________________________________
197
200 These procedures are intended for access to the multiple interpreter
201 facility from inside C programs. They enable managing multiple inter‐
202 preters in a hierarchical relationship, and the management of aliases,
203 commands that when invoked in one interpreter execute a command in
204 another interpreter. The return value for those procedures that return
205 an int is either TCL_OK or TCL_ERROR. If TCL_ERROR is returned then the
206 result field of the interpreter contains an error message.
207 Tcl_CreateSlave creates a new interpreter as a slave of interp. It
209 also creates a slave command named slaveName in interp which allows
210 interp to manipulate the new slave. If isSafe is zero, the command
211 creates a trusted slave in which Tcl code has access to all the Tcl
212 commands. If it is 1, the command creates a ``safe'' slave in which
213 Tcl code has access only to set of Tcl commands defined as ``Safe
214 Tcl''; see the manual entry for the Tcl interp command for details. If
215 the creation of the new slave interpreter failed, NULL is returned.
216 Tcl_IsSafe returns 1 if interp is ``safe'' (was created with the
218 TCL_SAFE_INTERPRETER flag specified), 0 otherwise.
219 Tcl_MakeSafe marks interp as ``safe'', so that future calls to
221 Tcl_IsSafe will return 1. It also removes all known potentially-unsafe
222 core functionality (both commands and variables) from interp. However,
223 it cannot know what parts of an extension or application are safe and
224 does not make any attempt to remove those parts, so safety is not guar‐
225 anteed after calling Tcl_MakeSafe. Callers will want to take care with
226 their use of Tcl_MakeSafe to avoid false claims of safety. For many
227 situations, Tcl_CreateSlave may be a better choice, since it creates
228 interpreters in a known-safe state.
229 Tcl_GetSlave returns a pointer to a slave interpreter of interp. The
231 slave interpreter is identified by slaveName. If no such slave inter‐
232 preter exists, NULL is returned.
233 Tcl_GetMaster returns a pointer to the master interpreter of interp. If
235 interp has no master (it is a top-level interpreter) then NULL is
236 returned.
237 Tcl_GetInterpPath sets the result field in askingInterp to the relative
239 path between askingInterp and slaveInterp; slaveInterp must be a slave
240 of askingInterp. If the computation of the relative path succeeds,
241 TCL_OK is returned, else TCL_ERROR is returned and the result field in
242 askingInterp contains the error message.
243 Tcl_CreateAlias creates an object command named slaveCmd in slaveInterp │
245 that when invoked, will cause the command targetCmd to be invoked in │
246 targetInterp. The arguments specified by the strings contained in argv │
247 are always prepended to any arguments supplied in the invocation of │
248 slaveCmd and passed to targetCmd. This operation returns TCL_OK if it │
249 succeeds, or TCL_ERROR if it fails; in that case, an error message is │
250 left in the object result of slaveInterp. Note that there are no │
251 restrictions on the ancestry relationship (as created by Tcl_Cre‐ │
252 ateSlave) between slaveInterp and targetInterp. Any two interpreters │
253 can be used, without any restrictions on how they are related. │
254 Tcl_CreateAliasObj is similar to Tcl_CreateAlias except that it takes a │
256 vector of objects to pass as additional arguments instead of a vector │
257 of strings.
258 Tcl_GetAlias returns information about an alias aliasName in interp.
260 Any of the result fields can be NULL, in which case the corresponding
261 datum is not returned. If a result field is non-NULL, the address indi‐
262 cated is set to the corresponding datum. For example, if targetNamePtr
263 is non-NULL it is set to a pointer to the string containing the name of
264 the target command. │
265 Tcl_GetAliasObj is similar to Tcl_GetAlias except that it returns a │
267 pointer to a vector of Tcl_Obj structures instead of a vector of │
268 strings. │
269 Tcl_ExposeCommand moves the command named hiddenCmdName from the set of │
271 hidden commands to the set of exposed commands, putting it under the │
272 name cmdName. HiddenCmdName must be the name of an existing hidden │
273 command, or the operation will return TCL_ERROR and leave an error mes‐ │
274 sage in the result field in interp. If an exposed command named cmd‐ │
275 Name already exists, the operation returns TCL_ERROR and leaves an │
276 error message in the object result of interp. If the operation suc‐ │
277 ceeds, it returns TCL_OK. After executing this command, attempts to │
278 use cmdName in a call to Tcl_Eval or with the Tcl eval command will │
279 again succeed. │
280 Tcl_HideCommand moves the command named cmdName from the set of exposed │
282 commands to the set of hidden commands, under the name hiddenCmdName. │
283 CmdName must be the name of an existing exposed command, or the opera‐ │
284 tion will return TCL_ERROR and leave an error message in the object │
285 result of interp. Currently both cmdName and hiddenCmdName must not │
286 contain namespace qualifiers, or the operation will return TCL_ERROR │
287 and leave an error message in the object result of interp. The CmdName │
288 will be looked up in the global namespace, and not relative to the cur‐ │
289 rent namespace, even if the current namespace is not the global one. │
290 If a hidden command whose name is hiddenCmdName already exists, the │
291 operation also returns TCL_ERROR and the result field in interp con‐ │
292 tains an error message. If the operation succeeds, it returns TCL_OK. │
293 After executing this command, attempts to use cmdName in a call to │
294 Tcl_Eval or with the Tcl eval command will fail. │
295 For a description of the Tcl interface to multiple interpreters, see │
297 interp(n). │
298
300 interp │
301
304 alias, command, exposed commands, hidden commands, interpreter, invoke, │
305 master, slave │
306Tcl 7.6 Tcl_CreateSlave(3)