tcl7.6 C API - CrtSlave






NAME

     Tcl_IsSafe,  Tcl_MakeSafe,  Tcl_CreateSlave,   Tcl_GetSlave,
     Tcl_GetSlaves, Tcl_GetMaster, Tcl_CreateAlias, Tcl_GetAlias,
     Tcl_GetAliases  -  manage  multiple  Tcl  interpreters   and
     aliases.


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, srcCmd, targetInterp, targetCmd, argc, argv)

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


ARGUMENTS

     Tcl_Interp             *interp        (in)      Interpreter
                                                     in  which to
                                                     execute  the
                                                     specified
                                                     command.

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

     int                    isSafe         (in)      Zero   means
                                                     the   inter-
                                                     preter   may
                                                     have all Tcl
                                                     functions.
                                                     Non-zero
                                                     means    the
                                                     new
                                                     interpreter's
                                                     functional-
                                                     ity   should
                                                     be   limited
                                                     to  make  it
                                                     safe.

     Tcl_Interp             *slaveInterp   (in)      Interpreter
                                                     to  use  for
                                                     creating the
                                                     source  com-
                                                     mand for  an
                                                     alias   (see
                                                     below).

     char                   *srcCmd        (in)      Name      of
                                                     source  com-
                                                     mand     for
                                                     alias.

     Tcl_Interp             *targetInterp  (in)      Interpreter
                                                     that    con-
                                                     tains    the
                                                     target  com-
                                                     mand for  an
                                                     alias.

     char                   *targetCmd     (in)      Name of tar-
                                                     get  command
                                                     for alias in
                                                     targetIn-
                                                     terp.

     int                    argc           (in)      Count     of
                                                     additional
                                                     arguments to
                                                     pass  to the
                                                     alias   com-
                                                     mand.

     char                   **argv         (in)      Vector    of
                                                     strings, the
                                                     additional
                                                     arguments to
                                                     pass to  the
                                                     alias   com-
                                                     mand.   This
                                                     storage   is
                                                     owned by the
                                                     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.

     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     addi-
                                                     tional argu-
                                                     ments  to be
                                                     passed    to
                                                     the   alias.
                                                     The location
                                                     is        in
                                                     storage
                                                     owned by the
                                                     caller.

     char                   ***argvPtr     (out)     Pointer   to
                                                     location  to
                                                     store a vec-
                                                     tor       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 func-
                                                     tion.





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  the
     given  interpreter.  It  also creates a slave command in the
     given interpreter which allows  the  master  interpreter  to
     manipulate  the  slave.  The slave interpreter and the slave
     command have the specified name. If isSafe  is  1,  the  new
     slave  interpreter  is  made ``safe'' by removing all unsafe
     functionality. If the creation failed, NULL is returned.

     Tcl_IsSafe returns 1 if the given interpreter is ``safe'', 0
     otherwise.

     Tcl_MakeSafe makes the given interpreter ``safe'' by  remov-
     ing all non-core and core unsafe functionality. Note that if
     you call this after adding some extension to an interpreter,
     all traces of that extension will be removed from the inter-
     preter. This operation always succeeds and returns TCL_OK.

     Tcl_GetSlave returns a pointer to a slave interpreter of the
     given  interpreter.  The  slave interpreter is identified by
     the name specified.  If no such  slave  interpreter  exists,
     NULL is returned.

     Tcl_GetMaster returns a pointer to the master interpreter of
     the  given interpreter. If the given interpreter has no mas-
     ter (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 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_GetAlias returns information about an alias of a  speci-
     fied  name  in a given interpreter. 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 indi-
     cated 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.

     In order to map over all slave  interpreters,  use  Tcl_Eval
     with  the  command  interp  slaves  and use the value (a Tcl
     list) deposited in the  result  field  of  the  interpreter.
     Similarly, to map over all aliases whose source commands are
     defined in an interpreter, use  Tcl_Eval  with  the  command
     interp  aliases  and use the value (a Tcl list) deposited in
     the result field. Note that the storage of this list belongs
     to  Tcl, so you should copy it before invoking any other Tcl
     commands in that interpreter.


SEE ALSO

     For a description of the Tcl interface  to  multiple  inter-
     preters, see interp(n).



KEYWORDS

     alias, command, interpreter, master, slave