DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_GetMaster(3tcl)




Tcl_CreateSlave(3)   Tcl Library Procedures    Tcl_CreateSlave(3)

_________________________________________________________________


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)

Tcl                     Last change: 7.6                        1

Tcl_CreateSlave(3)   Tcl Library Procedures    Tcl_CreateSlave(3)


ARGUMENTS

     Tcl_Interp *interp (in)                           Interpreter
                                                       in   which
                                                       to execute
                                                       the speci-
                                                       fied  com-
                                                       mand.

     const char *slaveName (in)                        Name    of
                                                       slave
                                                       inter-
                                                       preter  to
                                                       create  or
                                                       manipu-
                                                       late.

     int isSafe (in)                                   If    non-
                                                       zero,    a
                                                       "safe"
                                                       slave that
                                                       is   suit-
                                                       able   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  con-
                                                       tains  the
                                                       target
                                                       command
                                                       for     an
                                                       alias.

Tcl                     Last change: 7.6                        2

Tcl_CreateSlave(3)   Tcl Library Procedures    Tcl_CreateSlave(3)

     const char *targetCmd (in)                        Name    of
                                                       target
                                                       command
                                                       for  alias
                                                       in    tar-
                                                       getInterp.

     int argc (in)                                     Count   of
                                                       additional
                                                       arguments
                                                       to pass to
                                                       the  alias
                                                       command.

     const char *const *argv (in)                      Vector  of
                                                       strings,
                                                       the  addi-
                                                       tional
                                                       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
                                                       struc-
                                                       tures, the
                                                       additional
                                                       object
                                                       arguments
                                                       to pass to
                                                       the  alias
                                                       object
                                                       command.
                                                       This
                                                       storage is
                                                       owned   by
                                                       the

Tcl                     Last change: 7.6                        3

Tcl_CreateSlave(3)   Tcl Library Procedures    Tcl_CreateSlave(3)

                                                       caller.

     Tcl_Interp **targetInterpPtr (in)                 Pointer to
                                                       location
                                                       to   store
                                                       the
                                                       address of
                                                       the inter-
                                                       preter
                                                       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  loca-
                                                       tion is in
                                                       storage
                                                       owned   by
                                                       the
                                                       caller.

     const char ***argvPtr (out)                       Pointer to
                                                       location
                                                       to store a
                                                       vector  of
                                                       strings,
                                                       the  addi-
                                                       tional
                                                       arguments

Tcl                     Last change: 7.6                        4

Tcl_CreateSlave(3)   Tcl Library Procedures    Tcl_CreateSlave(3)

                                                       to pass to
                                                       an  alias.
                                                       The  loca-
                                                       tion 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  loca-
                                                       tion is in
                                                       storage
                                                       owned   by
                                                       the
                                                       caller.

     Tcl_Obj ***objvPtr (out)                          Pointer to
                                                       location
                                                       to store a
                                                       vector  of
                                                       Tcl_Obj
                                                       struc-
                                                       tures, the
                                                       additional
                                                       arguments
                                                       to pass to
                                                       an  object
                                                       alias com-
                                                       mand.  The
                                                       location
                                                       is      in
                                                       storage
                                                       owned   by
                                                       the
                                                       caller,
                                                       the vector

Tcl                     Last change: 7.6                        5

Tcl_CreateSlave(3)   Tcl Library Procedures    Tcl_CreateSlave(3)

                                                       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  relation-
     ship,  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

Tcl                     Last change: 7.6                        6

Tcl_CreateSlave(3)   Tcl Library Procedures    Tcl_CreateSlave(3)

     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 inter-
     preter) 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 computa-
     tion 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 tar-
     getCmd to be invoked in targetInterp. The  arguments  speci-
     fied  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 tar-
     getInterp. 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 correspond-
     ing 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

Tcl                     Last change: 7.6                        7

Tcl_CreateSlave(3)   Tcl Library Procedures    Tcl_CreateSlave(3)

     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  inter-
     preters, see interp(n).


SEE ALSO

     interp


KEYWORDS

     alias, command, exposed commands,  hidden  commands,  inter-
     preter, invoke, master, slave

Tcl                     Last change: 7.6                        8


Man(1) output converted with man2html