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

NAME

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

SYNOPSIS

14       #include <tcl.h>
15
16       int
17       Tcl_IsSafe(interp)
18
19       int
20       Tcl_MakeSafe(interp)
21
22       Tcl_Interp *
23       Tcl_CreateSlave(interp, slaveName, isSafe)
24
25       Tcl_Interp *
26       Tcl_GetSlave(interp, slaveName)
27
28       Tcl_Interp *
29       Tcl_GetMaster(interp)
30
31       int
32       Tcl_GetInterpPath(askingInterp, slaveInterp)
33
34       int
35       Tcl_CreateAlias(slaveInterp, slaveCmd, targetInterp, targetCmd,
36                       argc, argv)
37
38       int
39       Tcl_CreateAliasObj(slaveInterp, slaveCmd, targetInterp, targetCmd,
40                          objc, objv)
41
42       int
43       Tcl_GetAlias(interp, slaveCmd, targetInterpPtr, targetCmdPtr,
44                    argcPtr, argvPtr)
45
46       int
47       Tcl_GetAliasObj(interp, slaveCmd, targetInterpPtr, targetCmdPtr,
48                       objcPtr, objvPtr)
49
50       int
51       Tcl_ExposeCommand(interp, hiddenCmdName, cmdName)
52
53       int
54       Tcl_HideCommand(interp, cmdName, hiddenCmdName)
55

ARGUMENTS

57       Tcl_Interp *interp (in)                           Interpreter in  which
58                                                         to execute the speci‐
59                                                         fied command.
60
61       const char *slaveName (in)                        Name of slave  inter‐
62                                                         preter  to  create or
63                                                         manipulate.
64
65       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
73       Tcl_Interp *slaveInterp (in)                      Interpreter  to   use
74                                                         for    creating   the
75                                                         source command for an
76                                                         alias (see below).
77
78       const char *slaveCmd (in)                         Name  of  source com‐
79                                                         mand for alias.
80
81       Tcl_Interp *targetInterp (in)                     Interpreter that con‐
82                                                         tains the target com‐
83                                                         mand for an alias.
84
85       const char *targetCmd (in)                        Name of  target  com‐
86                                                         mand   for  alias  in
87                                                         targetInterp.
88
89       int argc (in)                                     Count  of  additional
90                                                         arguments  to pass to
91                                                         the alias command.
92
93       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
100       int objc (in)                                     Count  of  additional
101                                                         object  arguments  to
102                                                         pass   to  the  alias
103                                                         object command.
104
105       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
113       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
120       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
126       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
134       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
145       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
154       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
167       const char *cmdName (in)                          Name  of  an  exposed
168                                                         command  to  hide  or
169                                                         create.
170
171       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
178

DESCRIPTION

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
188       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
197       Tcl_IsSafe  returns  1  if  interp  is  “safe”  (was  created  with the
198       TCL_SAFE_INTERPRETER flag specified), 0 otherwise.
199
200       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
210       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
214       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
218       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
224       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
235       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
239       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
246       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
250       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
261       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
276       For a description of the Tcl interface to  multiple  interpreters,  see
277       interp(n).
278

SEE ALSO

280       interp
281
282

KEYWORDS

284       alias, command, exposed commands, hidden commands, interpreter, invoke,
285       master, slave
286
287
288
289Tcl                                   7.6                   Tcl_CreateSlave(3)
Impressum