1Tcl_CreateAlias(3) Tcl Library Procedures Tcl_CreateAlias(3)
2______________________________________________________________________________
6
8 Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateChild, Tcl_CreateSlave,
9 Tcl_GetChild, Tcl_GetSlave, Tcl_GetParent, Tcl_GetMaster, Tcl_Get‐
10 InterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias,
11 Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand - manage multiple
12 Tcl interpreters, aliases and hidden commands
13
15 #include <tcl.h>
16 int
18 Tcl_IsSafe(interp)
19 int
21 Tcl_MakeSafe(interp)
22 Tcl_Interp * │
24 Tcl_CreateChild(interp, name, isSafe) │
25 Tcl_Interp *
27 Tcl_CreateSlave(interp, name, isSafe)
28 Tcl_Interp * │
30 Tcl_GetChild(interp, name) │
31 Tcl_Interp *
33 Tcl_GetSlave(interp, name)
34 Tcl_Interp * │
36 Tcl_GetParent(interp) │
37 Tcl_Interp *
39 Tcl_GetMaster(interp)
40 int
42 Tcl_GetInterpPath(interp, childInterp)
43 int
45 Tcl_CreateAlias(childInterp, childCmd, targetInterp, targetCmd,
46 argc, argv)
47 int
49 Tcl_CreateAliasObj(childInterp, childCmd, targetInterp, targetCmd,
50 objc, objv)
51 int
53 Tcl_GetAlias(interp, childCmd, targetInterpPtr, targetCmdPtr,
54 argcPtr, argvPtr)
55 int
57 Tcl_GetAliasObj(interp, childCmd, targetInterpPtr, targetCmdPtr,
58 objcPtr, objvPtr)
59 int
61 Tcl_ExposeCommand(interp, hiddenCmdName, cmdName)
62 int
64 Tcl_HideCommand(interp, cmdName, hiddenCmdName)
65
67 Tcl_Interp *interp (in) Interpreter in which
68 to execute the speci‐
69 fied command.
70 const char *name (in) Name of child inter‐
72 preter to create or
73 manipulate.
74 int isSafe (in) If non-zero, a “safe”
76 child that is suit‐
77 able for running un‐
78 trusted code is cre‐
79 ated, otherwise a
80 trusted child is cre‐
81 ated.
82 Tcl_Interp *childInterp (in) Interpreter to use
84 for creating the
85 source command for an
86 alias (see below).
87 const char *childCmd (in) Name of source com‐
89 mand for alias.
90 Tcl_Interp *targetInterp (in) Interpreter that con‐
92 tains the target com‐
93 mand for an alias.
94 const char *targetCmd (in) Name of target com‐
96 mand for alias in
97 targetInterp.
98 int argc (in) Count of additional
100 arguments to pass to
101 the alias command.
102 const char *const *argv (in) Vector of strings,
104 the additional argu‐
105 ments to pass to the
106 alias command. This
107 storage is owned by
108 the caller.
109 int objc (in) Count of additional
111 value arguments to
112 pass to the aliased
113 command.
114 Tcl_Obj **objv (in) Vector of Tcl_Obj
116 structures, the addi‐
117 tional value argu‐
118 ments to pass to the
119 aliased command.
120 This storage is owned
121 by the caller.
122 Tcl_Interp **targetInterpPtr (in) Pointer to location
124 to store the address
125 of the interpreter
126 where a target com‐
127 mand is defined for
128 an alias.
129 const char **targetCmdPtr (out) Pointer to location
131 to store the address
132 of the name of the
133 target command for an
134 alias.
135 int *argcPtr (out) Pointer to location
137 to store count of ad‐
138 ditional arguments to
139 be passed to the
140 alias. The location
141 is in storage owned
142 by the caller.
143 const char ***argvPtr (out) Pointer to location
145 to store a vector of
146 strings, the addi‐
147 tional arguments to
148 pass to an alias. The
149 location is in stor‐
150 age owned by the
151 caller, the vector of
152 strings is owned by
153 the called function.
154 int *objcPtr (out) Pointer to location
156 to store count of ad‐
157 ditional value argu‐
158 ments to be passed to
159 the alias. The loca‐
160 tion is in storage
161 owned by the caller.
162 Tcl_Obj ***objvPtr (out) Pointer to location
164 to store a vector of
165 Tcl_Obj structures,
166 the additional argu‐
167 ments to pass to an
168 alias command. The
169 location is in stor‐
170 age owned by the
171 caller, the vector of
172 Tcl_Obj structures is
173 owned by the called
174 function.
175 const char *cmdName (in) Name of an exposed
177 command to hide or
178 create.
179 const char *hiddenCmdName (in) Name under which a
181 hidden command is
182 stored and with which
183 it can be exposed or
184 invoked.
185______________________________________________________________________________
186
189 These procedures are intended for access to the multiple interpreter
190 facility from inside C programs. They enable managing multiple inter‐
191 preters in a hierarchical relationship, and the management of aliases,
192 commands that when invoked in one interpreter execute a command in an‐
193 other interpreter. The return value for those procedures that return an
194 int is either TCL_OK or TCL_ERROR. If TCL_ERROR is returned then the
195 interpreter's result contains an error message.
196 Tcl_CreateSlave creates a new interpreter as a child of interp. It
198 also creates a child command named childName in interp which allows in‐
199 terp to manipulate the new child. If isSafe is zero, the command cre‐
200 ates a trusted child in which Tcl code has access to all the Tcl com‐
201 mands. If it is 1, the command creates a “safe” child in which Tcl
202 code has access only to set of Tcl commands defined as “Safe Tcl”; see
203 the manual entry for the Tcl interp command for details. If the cre‐
204 ation of the new child interpreter failed, NULL is returned.
205 Tcl_CreateChild is a synonym for Tcl_CreateSlave. │
207 Tcl_IsSafe returns 1 if interp is “safe” (was created with the
209 TCL_SAFE_INTERPRETER flag specified), 0 otherwise.
210 Tcl_MakeSafe marks interp as “safe”, so that future calls to Tcl_IsSafe
212 will return 1. It also removes all known potentially-unsafe core func‐
213 tionality (both commands and variables) from interp. However, it can‐
214 not know what parts of an extension or application are safe and does
215 not make any attempt to remove those parts, so safety is not guaranteed
216 after calling Tcl_MakeSafe. Callers will want to take care with their
217 use of Tcl_MakeSafe to avoid false claims of safety. For many situa‐
218 tions, Tcl_CreateSlave may be a better choice, since it creates inter‐
219 preters in a known-safe state.
220 Tcl_GetSlave returns a pointer to a child interpreter of interp. The
222 child interpreter is identified by childName. If no such child inter‐
223 preter exists, NULL is returned.
224 Tcl_GetChild is a synonym for Tcl_GetSlave. │
226 Tcl_GetMaster returns a pointer to the master interpreter of interp. If
228 interp has no master (it is a top-level interpreter) then NULL is re‐
229 turned.
230 Tcl_GetParent is a synonym for Tcl_GetMaster. │
232 Tcl_GetInterpPath stores in the result of interp the relative path be‐
234 tween interp and childInterp; childInterp must be a child of interp. If
235 the computation of the relative path succeeds, TCL_OK is returned, else
236 TCL_ERROR is returned and an error message is stored as the result of
237 interp.
238 Tcl_CreateAlias creates a command named childCmd in childInterp that
240 when invoked, will cause the command targetCmd to be invoked in target‐
241 Interp. The arguments specified by the strings contained in argv are
242 always prepended to any arguments supplied in the invocation of child‐
243 Cmd and passed to targetCmd. This operation returns TCL_OK if it suc‐
244 ceeds, or TCL_ERROR if it fails; in that case, an error message is left
245 in the value result of childInterp. Note that there are no restric‐
246 tions on the ancestry relationship (as created by Tcl_CreateSlave) be‐
247 tween childInterp and targetInterp. Any two interpreters can be used,
248 without any restrictions on how they are related.
249 Tcl_CreateAliasObj is similar to Tcl_CreateAlias except that it takes a
251 vector of values to pass as additional arguments instead of a vector of
252 strings.
253 Tcl_GetAlias returns information about an alias aliasName in interp.
255 Any of the result fields can be NULL, in which case the corresponding
256 datum is not returned. If a result field is non-NULL, the address indi‐
257 cated is set to the corresponding datum. For example, if targetNamePtr
258 is non-NULL it is set to a pointer to the string containing the name of
259 the target command.
260 Tcl_GetAliasObj is similar to Tcl_GetAlias except that it returns a
262 pointer to a vector of Tcl_Obj structures instead of a vector of
263 strings.
264 Tcl_ExposeCommand moves the command named hiddenCmdName from the set of
266 hidden commands to the set of exposed commands, putting it under the
267 name cmdName. HiddenCmdName must be the name of an existing hidden
268 command, or the operation will return TCL_ERROR and leave an error mes‐
269 sage as the result of interp. If an exposed command named cmdName al‐
270 ready exists, the operation returns TCL_ERROR and leaves an error mes‐
271 sage as the result of interp. If the operation succeeds, it returns
272 TCL_OK. After executing this command, attempts to use cmdName in any
273 script evaluation mechanism will again succeed.
274 Tcl_HideCommand moves the command named cmdName from the set of exposed
276 commands to the set of hidden commands, under the name hiddenCmdName.
277 CmdName must be the name of an existing exposed command, or the opera‐
278 tion will return TCL_ERROR and leave an error message as the result of
279 interp. Currently both cmdName and hiddenCmdName must not contain
280 namespace qualifiers, or the operation will return TCL_ERROR and leave
281 an error message as the result of interp. The CmdName will be looked
282 up in the global namespace, and not relative to the current namespace,
283 even if the current namespace is not the global one. If a hidden com‐
284 mand whose name is hiddenCmdName already exists, the operation also re‐
285 turns TCL_ERROR and an error message is left as the result of interp.
286 If the operation succeeds, it returns TCL_OK. After executing this
287 command, attempts to use cmdName in any script evaluation mechanism
288 will fail.
289 For a description of the Tcl interface to multiple interpreters, see
291 interp(n).
292
294 interp
295
298 alias, command, exposed commands, hidden commands, interpreter, invoke,
299 parent, child
300Tcl 7.6 Tcl_CreateAlias(3)