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,
36 argc, argv)
37 int
39 Tcl_CreateAliasObj(slaveInterp, slaveCmd, targetInterp, targetCmd,
40 objc, objv)
41 int
43 Tcl_GetAlias(interp, slaveCmd, targetInterpPtr, targetCmdPtr,
44 argcPtr, argvPtr)
45 int
47 Tcl_GetAliasObj(interp, slaveCmd, targetInterpPtr, targetCmdPtr,
48 objcPtr, objvPtr)
49 int
51 Tcl_ExposeCommand(interp, hiddenCmdName, cmdName)
52 int
54 Tcl_HideCommand(interp, cmdName, hiddenCmdName)
55
57 Tcl_Interp *interp (in) Interpreter in which
58 to execute the speci‐
59 fied command.
60 const char *slaveName (in) Name of slave inter‐
62 preter to create or
63 manipulate.
64 int isSafe (in) If non-zero, a “safe”
66 slave that is suit‐
67 able for running
68 untrusted code is
69 created, otherwise a
70 trusted slave is cre‐
71 ated.
72 Tcl_Interp *slaveInterp (in) Interpreter to use
74 for creating the
75 source command for an
76 alias (see below).
77 const char *slaveCmd (in) Name of source com‐
79 mand for alias.
80 Tcl_Interp *targetInterp (in) Interpreter that con‐
82 tains the target com‐
83 mand for an alias.
84 const char *targetCmd (in) Name of target com‐
86 mand for alias in
87 targetInterp.
88 int argc (in) Count of additional
90 arguments to pass to
91 the alias command.
92 const char *const *argv (in) Vector of strings,
94 the additional argu‐
95 ments to pass to the
96 alias command. This
97 storage is owned by
98 the caller.
99 int objc (in) Count of additional
101 object arguments to
102 pass to the alias
103 object command.
104 Tcl_Obj **objv (in) Vector of Tcl_Obj
106 structures, the addi‐
107 tional object argu‐
108 ments to pass to the
109 alias object command.
110 This storage is owned
111 by the caller.
112 Tcl_Interp **targetInterpPtr (in) Pointer to location
114 to store the address
115 of the interpreter
116 where a target com‐
117 mand is defined for
118 an alias.
119 const char **targetCmdPtr (out) Pointer to location
121 to store the address
122 of the name of the
123 target command for an
124 alias.
125 int *argcPtr (out) Pointer to location
127 to store count of
128 additional arguments
129 to be passed to the
130 alias. The location
131 is in storage owned
132 by the caller.
133 const char ***argvPtr (out) Pointer to location
135 to store a vector of
136 strings, the addi‐
137 tional arguments to
138 pass to an alias. The
139 location is in stor‐
140 age owned by the
141 caller, the vector of
142 strings is owned by
143 the called function.
144 int *objcPtr (out) Pointer to location
146 to store count of
147 additional object
148 arguments to be
149 passed to the alias.
150 The location is in
151 storage owned by the
152 caller.
153 Tcl_Obj ***objvPtr (out) Pointer to location
155 to store a vector of
156 Tcl_Obj structures,
157 the additional argu‐
158 ments to pass to an
159 object alias command.
160 The location is in
161 storage owned by the
162 caller, the vector of
163 Tcl_Obj structures is
164 owned by the called
165 function.
166 const char *cmdName (in) Name of an exposed
168 command to hide or
169 create.
170 const char *hiddenCmdName (in) Name under which a
172 hidden command is
173 stored and with which
174 it can be exposed or
175 invoked.
176_________________________________________________________________
177
180 These procedures are intended for access to the multiple interpreter
181 facility from inside C programs. They enable managing multiple inter‐
182 preters in a hierarchical relationship, and the management of aliases,
183 commands that when invoked in one interpreter execute a command in
184 another interpreter. The return value for those procedures that return
185 an int is either TCL_OK or TCL_ERROR. If TCL_ERROR is returned then the
186 result field of the interpreter contains an error message.
187 Tcl_CreateSlave creates a new interpreter as a slave of interp. It
189 also creates a slave command named slaveName in interp which allows
190 interp to manipulate the new slave. If isSafe is zero, the command
191 creates a trusted slave in which Tcl code has access to all the Tcl
192 commands. If it is 1, the command creates a “safe” slave in which Tcl
193 code has access only to set of Tcl commands defined as “Safe Tcl”; see
194 the manual entry for the Tcl interp command for details. If the cre‐
195 ation of the new slave interpreter failed, NULL is returned.
196 Tcl_IsSafe returns 1 if interp is “safe” (was created with the
198 TCL_SAFE_INTERPRETER flag specified), 0 otherwise.
199 Tcl_MakeSafe marks interp as “safe”, so that future calls to Tcl_IsSafe
201 will return 1. It also removes all known potentially-unsafe core func‐
202 tionality (both commands and variables) from interp. However, it can‐
203 not know what parts of an extension or application are safe and does
204 not make any attempt to remove those parts, so safety is not guaranteed
205 after calling Tcl_MakeSafe. Callers will want to take care with their
206 use of Tcl_MakeSafe to avoid false claims of safety. For many situa‐
207 tions, Tcl_CreateSlave may be a better choice, since it creates inter‐
208 preters in a known-safe state.
209 Tcl_GetSlave returns a pointer to a slave interpreter of interp. The
211 slave interpreter is identified by slaveName. If no such slave inter‐
212 preter exists, NULL is returned.
213 Tcl_GetMaster returns a pointer to the master interpreter of interp. If
215 interp has no master (it is a top-level interpreter) then NULL is
216 returned.
217 Tcl_GetInterpPath sets the result field in askingInterp to the relative
219 path between askingInterp and slaveInterp; slaveInterp must be a slave
220 of askingInterp. If the computation of the relative path succeeds,
221 TCL_OK is returned, else TCL_ERROR is returned and the result field in
222 askingInterp contains the error message.
223 Tcl_CreateAlias creates an object command named slaveCmd in slaveInterp
225 that when invoked, will cause the command targetCmd to be invoked in
226 targetInterp. The arguments specified by the strings contained in argv
227 are always prepended to any arguments supplied in the invocation of
228 slaveCmd and passed to targetCmd. This operation returns TCL_OK if it
229 succeeds, or TCL_ERROR if it fails; in that case, an error message is
230 left in the object result of slaveInterp. Note that there are no
231 restrictions on the ancestry relationship (as created by Tcl_Cre‐
232 ateSlave) between slaveInterp and targetInterp. Any two interpreters
233 can be used, without any restrictions on how they are related.
234 Tcl_CreateAliasObj is similar to Tcl_CreateAlias except that it takes a
236 vector of objects to pass as additional arguments instead of a vector
237 of strings.
238 Tcl_GetAlias returns information about an alias aliasName in interp.
240 Any of the result fields can be NULL, in which case the corresponding
241 datum is not returned. If a result field is non-NULL, the address indi‐
242 cated is set to the corresponding datum. For example, if targetNamePtr
243 is non-NULL it is set to a pointer to the string containing the name of
244 the target command.
245 Tcl_GetAliasObj is similar to Tcl_GetAlias except that it returns a
247 pointer to a vector of Tcl_Obj structures instead of a vector of
248 strings.
249 Tcl_ExposeCommand moves the command named hiddenCmdName from the set of
251 hidden commands to the set of exposed commands, putting it under the
252 name cmdName. HiddenCmdName must be the name of an existing hidden
253 command, or the operation will return TCL_ERROR and leave an error mes‐
254 sage in the result field in interp. If an exposed command named cmd‐
255 Name already exists, the operation returns TCL_ERROR and leaves an
256 error message in the object result of interp. If the operation suc‐
257 ceeds, it returns TCL_OK. After executing this command, attempts to
258 use cmdName in a call to Tcl_Eval or with the Tcl eval command will
259 again succeed.
260 Tcl_HideCommand moves the command named cmdName from the set of exposed
262 commands to the set of hidden commands, under the name hiddenCmdName.
263 CmdName must be the name of an existing exposed command, or the opera‐
264 tion will return TCL_ERROR and leave an error message in the object
265 result of interp. Currently both cmdName and hiddenCmdName must not
266 contain namespace qualifiers, or the operation will return TCL_ERROR
267 and leave an error message in the object result of interp. The CmdName
268 will be looked up in the global namespace, and not relative to the cur‐
269 rent namespace, even if the current namespace is not the global one.
270 If a hidden command whose name is hiddenCmdName already exists, the
271 operation also returns TCL_ERROR and the result field in interp con‐
272 tains an error message. If the operation succeeds, it returns TCL_OK.
273 After executing this command, attempts to use cmdName in a call to
274 Tcl_Eval or with the Tcl eval command will fail.
275 For a description of the Tcl interface to multiple interpreters, see
277 interp(n).
278
280 interp
281
284 alias, command, exposed commands, hidden commands, interpreter, invoke,
285 master, slave
286Tcl 7.6 Tcl_CreateSlave(3)