Scroll to navigation

Tcl_CreateSlave(3tcl) Tcl Library Procedures Tcl_CreateSlave(3tcl)
 


NAME

Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster,
  Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias,
  Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand - manage multiple Tcl
  interpreters, aliases and hidden commands

SYNOPSIS


#include <tcl.h>


int
Tcl_IsSafe(interp)


int
Tcl_MakeSafe(interp)


Tcl_Interp *
Tcl_CreateSlave(interp, slaveName, isSafe)


Tcl_Interp *
Tcl_GetSlave(interp, slaveName)


Tcl_Interp *
Tcl_GetMaster(interp)


int
Tcl_GetInterpPath(askingInterp, slaveInterp)


int
Tcl_CreateAlias(slaveInterp, slaveCmd, targetInterp, targetCmd,
                argc, argv)


int
Tcl_CreateAliasObj(slaveInterp, slaveCmd, targetInterp, targetCmd,
                   objc, objv)


int
Tcl_GetAlias(interp, slaveCmd, targetInterpPtr, targetCmdPtr,
             argcPtr, argvPtr)


int
Tcl_GetAliasObj(interp, slaveCmd, targetInterpPtr, targetCmdPtr,
                objcPtr, objvPtr)


int
Tcl_ExposeCommand(interp, hiddenCmdName, cmdName)


int
Tcl_HideCommand(interp, cmdName, hiddenCmdName)



ARGUMENTS



  
Tcl_Interp *interp (in)

  
Interpreter in which to execute the specified command.





  
const char *slaveName (in)

  
Name of slave interpreter to create or manipulate.





  
int isSafe (in)

  
If non-zero, a “safe” slave that is suitable for running
      untrusted code is created, otherwise a trusted slave is created.





  
Tcl_Interp *slaveInterp (in)

  
Interpreter to use for creating the source command for an alias (see
      below).





  
const char *slaveCmd (in)

  
Name of source command for alias.





  
Tcl_Interp *targetInterp (in)

  
Interpreter that contains the target command for an alias.





  
const char *targetCmd (in)

  
Name of target command for alias in targetInterp.





  
int argc (in)

  
Count of additional arguments to pass to the alias command.





  
const char *const *argv (in)

  
Vector of strings, the additional arguments to pass to the alias command.
      This storage is owned by the caller.





  
int objc (in)

  
Count of additional object arguments to pass to the alias object
    command.





  
Tcl_Obj **objv (in)

  
Vector of Tcl_Obj structures, the additional object arguments to pass to
      the alias object command. This storage is owned by the caller.





  
Tcl_Interp **targetInterpPtr (in)

  
Pointer to location to store the address of the interpreter where a target
      command is defined for an alias.





  
const char **targetCmdPtr (out)

  
Pointer to location to store the address of the name of the target command
      for an alias.





  
int *argcPtr (out)

  
Pointer to location to store count of additional arguments to be passed to
      the alias. The location is in storage owned by the caller.





  
const char ***argvPtr (out)

  
Pointer to location to store a vector of strings, the additional arguments
      to pass to an alias. The location is in storage owned by the caller, the
      vector of strings is owned by the called function.





  
int *objcPtr (out)

  
Pointer to location to store count of additional object arguments to be
      passed to the alias. The location is in storage owned by the caller.





  
Tcl_Obj ***objvPtr (out)

  
Pointer to location to store a vector of Tcl_Obj structures, the
      additional arguments to pass to an object alias command. The location is
      in storage owned by the caller, the vector of Tcl_Obj structures is owned
      by the called function.





  
const char *cmdName (in)

  
Name of an exposed command to hide or create.





  
const char *hiddenCmdName (in)

  
Name under which a hidden command is stored and with which it can be
      exposed or invoked.
    
    

    
 

    

  




DESCRIPTION

These procedures are intended for access to the multiple interpreter facility
  from inside C programs. They enable managing multiple interpreters in a
  hierarchical relationship, and the management of aliases, commands that when
  invoked in one interpreter execute a command in another interpreter. The
  return value for those procedures that return an int is either
  TCL_OK or TCL_ERROR. If TCL_ERROR is returned then the
  result field of the interpreter contains an error message.


Tcl_CreateSlave creates a new interpreter as a slave of interp. It
  also creates a slave command named slaveName in interp which
  allows interp to manipulate the new slave. If isSafe is zero,
  the command creates a trusted slave in which Tcl code has access to all the
  Tcl commands. If it is 1, the command creates a “safe”
  slave in which Tcl code has access only to set of Tcl commands defined as
  “Safe Tcl”; see the manual entry for the Tcl interp
  command for details. If the creation of the new slave interpreter failed,
  NULL is returned.


Tcl_IsSafe returns 1 if interp is “safe” (was
  created with the TCL_SAFE_INTERPRETER flag specified), 0
  otherwise.


Tcl_MakeSafe marks interp as “safe”, so that future
  calls to Tcl_IsSafe will return 1. It also removes all known
  potentially-unsafe core functionality (both commands and variables) from
  interp. However, it cannot know what parts of an extension or
  application are safe and does not make any attempt to remove those parts, so
  safety is not guaranteed after calling Tcl_MakeSafe. Callers will want
  to take care with their use of Tcl_MakeSafe to avoid false claims of
  safety. For many situations, Tcl_CreateSlave may be a better choice,
  since it creates interpreters in a known-safe state.


Tcl_GetSlave returns a pointer to a slave interpreter of interp.
  The slave interpreter is identified by slaveName. If no such slave
  interpreter exists, NULL is returned.


Tcl_GetMaster returns a pointer to the master interpreter of
  interp. If interp has no master (it is a top-level interpreter)
  then NULL is returned.


Tcl_GetInterpPath sets the result field in askingInterp to
  the relative path between askingInterp and slaveInterp;
  slaveInterp must be a slave of askingInterp. If the computation
  of the relative path succeeds, TCL_OK is returned, else
  TCL_ERROR is returned and the result field in
  askingInterp contains the error message.


Tcl_CreateAlias creates an object command named slaveCmd in
  slaveInterp that when invoked, will cause the command targetCmd
  to be invoked in targetInterp. The arguments specified by the strings
  contained in argv are always prepended to any arguments supplied in the
  invocation of slaveCmd and passed to targetCmd. This operation
  returns TCL_OK if it succeeds, or TCL_ERROR if it fails; in that
  case, an error message is left in the object result of slaveInterp.
  Note that there are no restrictions on the ancestry relationship (as created
  by Tcl_CreateSlave) between slaveInterp and targetInterp.
  Any two interpreters can be used, without any restrictions on how they are
  related.


Tcl_CreateAliasObj is similar to Tcl_CreateAlias except that it
  takes a vector of objects to pass as additional arguments instead of a vector
  of strings.


Tcl_GetAlias returns information about an alias aliasName in
  interp. Any of the result fields can be NULL, in which case the
  corresponding datum is not returned. If a result field is non- NULL,
  the address indicated is set to the corresponding datum. For example, if
  targetNamePtr is non- NULL it is set to a pointer to the string
  containing the name of the target command.


Tcl_GetAliasObj is similar to Tcl_GetAlias except that it returns
  a pointer to a vector of Tcl_Obj structures instead of a vector of strings.


Tcl_ExposeCommand moves the command named hiddenCmdName from the
  set of hidden commands to the set of exposed commands, putting it under the
  name cmdName. HiddenCmdName must be the name of an existing
  hidden command, or the operation will return TCL_ERROR and leave an
  error message in the result field in interp. If an exposed
  command named cmdName already exists, the operation returns
  TCL_ERROR and leaves an error message in the object result of
  interp. If the operation succeeds, it returns TCL_OK. After
  executing this command, attempts to use cmdName in a call to
  Tcl_Eval or with the Tcl eval command will again succeed.


Tcl_HideCommand moves the command named cmdName from the set of
  exposed commands to the set of hidden commands, under the name
  hiddenCmdName. CmdName must be the name of an existing exposed
  command, or the operation will return TCL_ERROR and leave an error
  message in the object result of interp. Currently both cmdName
  and hiddenCmdName must not contain namespace qualifiers, or the
  operation will return TCL_ERROR and leave an error message in the
  object result of interp. The CmdName will be looked up in the
  global namespace, and not relative to the current namespace, even if the
  current namespace is not the global one. If a hidden command whose name is
  hiddenCmdName already exists, the operation also returns
  TCL_ERROR and the result field in interp contains an
  error message. If the operation succeeds, it returns TCL_OK. After
  executing this command, attempts to use cmdName in a call to
  Tcl_Eval or with the Tcl eval command will fail.


For a description of the Tcl interface to multiple interpreters, see
  interp(3tcl).

SEE ALSO

interp



KEYWORDS

alias, command, exposed commands, hidden commands, interpreter, invoke, master,
  slave



  

    7.6
    Tcl