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

FreeBSD Manual Pages

  
 
  

home | help
Tcl_CreateAlias(3)	    Tcl	Library	Procedures	    Tcl_CreateAlias(3)

______________________________________________________________________________

NAME
       Tcl_IsSafe,   Tcl_CreateChild,  Tcl_GetChild,  Tcl_GetParent,  Tcl_Get-
       InterpPath,   Tcl_CreateAlias,	Tcl_CreateAliasObj,   Tcl_GetAliasObj,
       Tcl_ExposeCommand,  Tcl_HideCommand - manage multiple Tcl interpreters,
       aliases and hidden commands

SYNOPSIS
       #include	<tcl.h>

       int
       Tcl_IsSafe(interp)

       Tcl_Interp *
       Tcl_CreateChild(interp, name, isSafe)

       Tcl_Interp *
       Tcl_GetChild(interp, name)

       Tcl_Interp *
       Tcl_GetParent(interp)

       int
       Tcl_GetInterpPath(interp, childInterp)

       int
       Tcl_CreateAlias(childInterp, childCmd, targetInterp, targetCmd,
		       argc, argv)

       int
       Tcl_CreateAliasObj(childInterp, childCmd, targetInterp, targetCmd,
			  objc,	objv)

       int
       Tcl_GetAliasObj(interp, childCmd, 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 *name	(in)				 Name  of child	inter-
							 preter	to  create  or
							 manipulate.

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

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

       const char *childCmd (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.

       Tcl_Size	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.

       Tcl_Size	objc (in)				 Count	of  additional
							 value	arguments   to
							 pass  to  the aliased
							 command.

       Tcl_Obj **objv (in)				 Vector	  of   Tcl_Obj
							 structures, the addi-
							 tional	  value	 argu-
							 ments to pass to  the
							 aliased      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.

       Tcl_Size	| int *objcPtr (out)			 Pointer  to  location
							 to store count	of ad-
							 ditional  value argu-
							 ments to be passed to
							 the alias. The	 loca-
							 tion  is  in  storage
							 owned by the  caller.
							 If  it	 points	 to  a
							 variable  which  type
							 is  not  Tcl_Size,  a
							 compiler warning will
							 be generated. If your
							 extensions  is	  com-
							 piled		  with
							 -DTCL_8_API,	  this
							 function  will	return
							 TCL_ERROR for aliases
							 with	 more	  than
							 INT_MAX  value	 argu-
							 ments,	otherwise  ex-
							 pect it to crash

       Tcl_Obj ***objvPtr (out)				 Pointer  to  location
							 to store a vector  of
							 Tcl_Obj   structures,
							 the additional	 argu-
							 ments	to  pass to an
							 alias	command.   The
							 location  is in stor-
							 age  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
       interpreter's result contains an	error message.

       Tcl_CreateChild creates a new interpreter as a  child  of  interp.   It
       also  creates  a	child command named name in interp which allows	interp
       to manipulate the new child.  If	isSafe is zero,	the command creates  a
       trusted child in	which Tcl code has access to all the Tcl commands.  If
       it  is  1, the command creates a	"safe" child in	which Tcl code has ac-
       cess 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 child 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_GetChild  returns  a	 pointer to a child interpreter	of interp. The
       child interpreter is identified by name.	 If no such child  interpreter
       exists, NULL is returned.

       Tcl_GetParent returns a pointer to the parent interpreter of interp. If
       interp  has  no parent (it is a top-level interpreter) then NULL	is re-
       turned.

       Tcl_GetInterpPath stores	in the result of interp	the relative path  be-
       tween interp and	childInterp; childInterp must be a child of interp. If
       the computation of the relative path succeeds, TCL_OK is	returned, else
       TCL_ERROR  is  returned and an error message is stored as the result of
       interp.

       Tcl_CreateAlias creates a command named childCmd	 in  childInterp  that
       when invoked, will cause	the command targetCmd to be invoked in target-
       Interp.	The  arguments	specified by the strings contained in argv are
       always prepended	to any arguments supplied in the invocation of	child-
       Cmd  and	passed to targetCmd.  This operation returns TCL_OK if it suc-
       ceeds, or TCL_ERROR if it fails;	in that	case, an error message is left
       in the value result of childInterp.  Note that there  are  no  restric-
       tions  on the ancestry relationship (as created by Tcl_CreateChild) be-
       tween childInterp 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 values	to pass	as additional arguments	instead	of a vector of
       strings.

       Tcl_GetAliasObj	returns	information in the form	of a pointer to	a vec-
       tor of Tcl_Obj structures 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  targetCmdPtr  is
       non-NULL	 it  is	 set to	a pointer to the string	containing the name of
       the target command.

       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 as the result of interp.  If an exposed command named cmdName  al-
       ready  exists, the operation returns TCL_ERROR and leaves an error mes-
       sage as the result of interp.  If the operation	succeeds,  it  returns
       TCL_OK.	 After	executing this command,	attempts to use	cmdName	in any
       script evaluation mechanism 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	opera-
       tion will return	TCL_ERROR and leave an error message as	the 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 as the 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 com-
       mand whose name is hiddenCmdName	already	exists,	the operation also re-
       turns TCL_ERROR and an error message is left as the result  of  interp.
       If  the	operation  succeeds,  it returns TCL_OK.  After	executing this
       command,	attempts to use	cmdName	in  any	 script	 evaluation  mechanism
       will fail.

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

REFERENCE COUNT	MANAGEMENT
       Tcl_CreateAliasObj increments the reference counts of the values	in its
       objv argument. (That reference lasts the	same length  of	 time  as  the
       owning alias.)

       Tcl_GetAliasObj	returns	(via its objvPtr argument) a pointer to	values
       that it holds a reference to.

SEE ALSO
       interp(n)

KEYWORDS
       alias, command, exposed commands, hidden	commands, interpreter, invoke,
       parent, child

Tcl				      7.6		    Tcl_CreateAlias(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_GetInterpPath.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help