1Tcl_CreateAlias(3)          Tcl Library Procedures          Tcl_CreateAlias(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

15       #include <tcl.h>
16
17       int
18       Tcl_IsSafe(interp)
19
20       int
21       Tcl_MakeSafe(interp)
22
23       Tcl_Interp *                                                            │
24       Tcl_CreateChild(interp, name, isSafe)                                   │
25
26       Tcl_Interp *
27       Tcl_CreateSlave(interp, name, isSafe)
28
29       Tcl_Interp *                                                            │
30       Tcl_GetChild(interp, name)                                              │
31
32       Tcl_Interp *
33       Tcl_GetSlave(interp, name)
34
35       Tcl_Interp *                                                            │
36       Tcl_GetParent(interp)                                                   │
37
38       Tcl_Interp *
39       Tcl_GetMaster(interp)
40
41       int
42       Tcl_GetInterpPath(interp, childInterp)
43
44       int
45       Tcl_CreateAlias(childInterp, childCmd, targetInterp, targetCmd,
46                       argc, argv)
47
48       int
49       Tcl_CreateAliasObj(childInterp, childCmd, targetInterp, targetCmd,
50                          objc, objv)
51
52       int
53       Tcl_GetAlias(interp, childCmd, targetInterpPtr, targetCmdPtr,
54                    argcPtr, argvPtr)
55
56       int
57       Tcl_GetAliasObj(interp, childCmd, targetInterpPtr, targetCmdPtr,
58                       objcPtr, objvPtr)
59
60       int
61       Tcl_ExposeCommand(interp, hiddenCmdName, cmdName)
62
63       int
64       Tcl_HideCommand(interp, cmdName, hiddenCmdName)
65

ARGUMENTS

67       Tcl_Interp *interp (in)                           Interpreter  in which
68                                                         to execute the speci‐
69                                                         fied command.
70
71       const char *name (in)                             Name  of child inter‐
72                                                         preter to  create  or
73                                                         manipulate.
74
75       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
83       Tcl_Interp *childInterp (in)                      Interpreter   to  use
84                                                         for   creating    the
85                                                         source command for an
86                                                         alias (see below).
87
88       const char *childCmd (in)                         Name of  source  com‐
89                                                         mand for alias.
90
91       Tcl_Interp *targetInterp (in)                     Interpreter that con‐
92                                                         tains the target com‐
93                                                         mand for an alias.
94
95       const char *targetCmd (in)                        Name  of  target com‐
96                                                         mand  for  alias   in
97                                                         targetInterp.
98
99       int argc (in)                                     Count  of  additional
100                                                         arguments to pass  to
101                                                         the alias command.
102
103       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
110       int objc (in)                                     Count  of  additional
111                                                         value   arguments  to
112                                                         pass to  the  aliased
113                                                         command.
114
115       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
123       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
130       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
136       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
144       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
155       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
163       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
176       const char *cmdName (in)                          Name  of  an  exposed
177                                                         command  to  hide  or
178                                                         create.
179
180       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
187

DESCRIPTION

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
197       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
206       Tcl_CreateChild is a synonym for Tcl_CreateSlave.                       │
207
208       Tcl_IsSafe  returns  1  if  interp  is  “safe”  (was  created  with the
209       TCL_SAFE_INTERPRETER flag specified), 0 otherwise.
210
211       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
221       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
225       Tcl_GetChild is a synonym for Tcl_GetSlave.                             │
226
227       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
231       Tcl_GetParent is a synonym for Tcl_GetMaster.                           │
232
233       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
239       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
250       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
254       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
261       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
265       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
275       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
290       For  a  description  of the Tcl interface to multiple interpreters, see
291       interp(n).
292

SEE ALSO

294       interp
295
296

KEYWORDS

298       alias, command, exposed commands, hidden commands, interpreter, invoke,
299       parent, child
300
301
302
303Tcl                                   7.6                   Tcl_CreateAlias(3)
Impressum