Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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)

ARGUMENTS
       Tcl_Interp *interp (in)				 Interpreter in	 which
							 to execute the	speci-
							 fied command.

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

       int isSafe (in)					 If non-zero, a	"safe"
							 slave	that  is suit-
							 able for running  un-
							 trusted  code is cre-
							 ated,	 otherwise   a
							 trusted slave is cre-
							 ated.

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

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

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

       const char *targetCmd (in)			 Name of  target  com-
							 mand	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 argu-
							 ments 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 ob-
							 ject command.

       Tcl_Obj **objv (in)				 Vector	  of   Tcl_Obj
							 structures, the addi-
							 tional	 object	 argu-
							 ments	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 com-
							 mand 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 ad-
							 ditional 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	 addi-
							 tional	 arguments  to
							 pass to an alias. The
							 location is in	 stor-
							 age   owned   by  the
							 caller, the vector of
							 strings  is  owned by
							 the called function.

       int *objcPtr (out)				 Pointer  to  location
							 to store count	of ad-
							 ditional object argu-
							 ments 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   structures,
							 the  additional argu-
							 ments 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	inter-
       preters	in a hierarchical relationship,	and the	management of aliases,
       commands	that when invoked in one interpreter execute a command in  an-
       other 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 in-
       terp  to	manipulate the new slave.  If isSafe is	zero, the command cre-
       ates a trusted slave in which Tcl code has access to all	the  Tcl  com-
       mands.	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 cre-
       ation 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 func-
       tionality  (both	commands and variables)	from interp.  However, it can-
       not 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	situa-
       tions, Tcl_CreateSlave may be a better choice, since it creates	inter-
       preters 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	inter-
       preter 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  re-
       turned.

       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 re-
       strictions 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 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.

       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 mes-
       sage  in	 the result field in interp.  If an exposed command named cmd-
       Name already exists, the	operation returns TCL_ERROR and	leaves an  er-
       ror message in the object result	of interp.  If the operation succeeds,
       it returns TCL_OK.  After executing this	command, attempts to use  cmd-
       Name in a call to Tcl_Eval or with the Tcl eval command will again suc-
       ceed.

       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	opera-
       tion will return	TCL_ERROR and leave an error message in	the object re-
       sult of interp.	Currently both cmdName and hiddenCmdName must not con-
       tain  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 cur-
       rent namespace, even if the current namespace is	not  the  global  one.
       If a hidden command whose name is hiddenCmdName already exists, the op-
       eration 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(n).

SEE ALSO
       interp

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

Tcl				      7.6		    Tcl_CreateSlave(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_CreateAlias.tcl85&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help