Tcl_DeleteInterp man page on UnixWare

Man page or keyword search:  
man Server   3616 pages
apropos Keyword Search (all sections)
Output format
UnixWare logo
[printable version]

Tcl_CreateInterp(3)	    Tcl Library Procedures	   Tcl_CreateInterp(3)

______________________________________________________________________________

NAME
       Tcl_CreateInterp,  Tcl_DeleteInterp,  Tcl_InterpDeleted	-  create  and
       delete Tcl command interpreters

SYNOPSIS
       #include <tcl.h>

       Tcl_Interp *
       Tcl_CreateInterp()

       Tcl_DeleteInterp(interp)

       int
       Tcl_InterpDeleted(interp)

ARGUMENTS
       Tcl_Interp   *interp   (in)	Token for interpreter to be destroyed.
_________________________________________________________________

DESCRIPTION
       Tcl_CreateInterp creates a new  interpreter  structure  and  returns  a
       token  for it.  The token is required in calls to most other Tcl proce‐
       dures,  such  as	 Tcl_CreateCommand,  Tcl_Eval,	and  Tcl_DeleteInterp.
       Clients	are  only  allowed to access a few of the fields of Tcl_Interp
       structures;  see the Tcl_Interp and  Tcl_CreateCommand  man  pages  for
       details.	  The new interpreter is initialized with no defined variables
       and only the built-in Tcl commands.  To bind  in	 additional  commands,
       call Tcl_CreateCommand.

       Tcl_DeleteInterp	 marks an interpreter as deleted; the interpreter will
       eventually be deleted when all calls to Tcl_Preserve for it  have  been
       matched	by  calls  to  Tcl_Release. At that time, all of the resources
       associated with it, including variables, procedures,  and  application-
       specific	 command  bindings,  will  be deleted.	After Tcl_DeleteInterp
       returns any attempt to use Tcl_Eval on the interpreter  will  fail  and
       return  TCL_ERROR.  After  the  call  to Tcl_DeleteInterp it is safe to
       examine interp->result, query or set the values of  variables,  define,
       undefine	 or  retrieve  procedures,  and examine the runtime evaluation
       stack. See below, in the section INTERPRETERS AND MEMORY MANAGEMENT for
       details.

       Tcl_InterpDeleted  returns  nonzero if Tcl_DeleteInterp was called with
       interp as its argument; this indicates that the interpreter will	 even‐
       tually be deleted, when the last call to Tcl_Preserve for it is matched
       by a call to Tcl_Release. If nonzero  is	 returned,  further  calls  to
       Tcl_Eval in this interpreter will return TCL_ERROR.

       Tcl_InterpDeleted  is  useful  in  deletion  callbacks  to  distinguish
       between when only the memory the callback is responsible for  is	 being
       deleted	and when the whole interpreter is being deleted. In the former
       case the callback may recreate the data being deleted, but  this	 would
       lead to an infinite loop if the interpreter were being deleted.

INTERPRETERS AND MEMORY MANAGEMENT
       Tcl_DeleteInterp	 can  be called at any time on an interpreter that may
       be used by nested evaluations and C code	 in  various  extensions.  Tcl
       implements  a  simple mechanism that allows callers to use interpreters
       without worrying about the interpreter being deleted in a nested	 call,
       and  without requiring special code to protect the interpreter, in most
       cases.  This mechanism ensures that nested uses of an  interpreter  can
       safely continue using it even after Tcl_DeleteInterp is called.

       The mechanism relies on matching up calls to Tcl_Preserve with calls to
       Tcl_Release. If Tcl_DeleteInterp has been called, only  when  the  last
       call  to	 Tcl_Preserve  is  matched  by a call to Tcl_Release, will the
       interpreter be freed. See the  manual  entry  for  Tcl_Preserve	for  a
       description of these functions.

       The  rules  for	when the user of an interpreter must call Tcl_Preserve
       and Tcl_Release are simple:

       Interpreters Passed As Arguments
	      Functions that are passed an  interpreter	 as  an	 argument  can
	      safely use the interpreter without any special protection. Thus,
	      when you write an extension consisting of new Tcl	 commands,  no
	      special code is needed to protect interpreters received as argu‐
	      ments. This covers the majority of all uses.

       Interpreter Creation And Deletion
	      When a new  interpreter  is  created  and	 used  in  a  call  to
	      Tcl_Eval,	 Tcl_VarEval,  Tcl_GlobalEval, Tcl_SetVar, or Tcl_Get‐
	      Var, a pair of calls to Tcl_Preserve and Tcl_Release  should  be
	      wrapped around all uses of the interpreter.  Remember that it is
	      unsafe to use the interpreter once Tcl_Release has been  called.
	      To ensure that the interpreter is properly deleted when it is no
	      longer needed, call Tcl_InterpDeleted to test if some other code
	      already  called  Tcl_DeleteInterp; if not, call Tcl_DeleteInterp
	      before calling Tcl_Release  in  your  own	 code.	 Do  not  call
	      Tcl_DeleteInterp	on  an interpreter for which Tcl_InterpDeleted
	      returns nonzero.

       Retrieving An Interpreter From A Data Structure
	      When an interpreter is retrieved from a data structure (e.g. the
	      client  data  of	a  callback) for use in Tcl_Eval, Tcl_VarEval,
	      Tcl_GlobalEval, Tcl_SetVar, or Tcl_GetVar, a pair	 of  calls  to
	      Tcl_Preserve  and	 Tcl_Release should be wrapped around all uses
	      of the interpreter; it is unsafe to reuse the  interpreter  once
	      Tcl_Release has been called.  If an interpreter is stored inside
	      a callback data structure, an appropriate deletion cleanup mech‐
	      anism  should be set up by the code that creates the data struc‐
	      ture so that the interpreter is removed from the data  structure
	      (e.g.  by	 setting  the  field  to NULL) when the interpreter is
	      deleted. Otherwise, you may be using  an	interpreter  that  has
	      been freed and whose memory may already have been reused.

       All  uses  of  interpreters  in Tcl and Tk have already been protected.
       Extension writers should ensure that their code also properly  protects
       any additional interpreters used, as described above.

KEYWORDS
       command, create, delete, interpreter

SEE ALSO
       Tcl_Preserve(3), Tcl_Release(3)

Tcl				      7.5		   Tcl_CreateInterp(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server UnixWare

List of man pages available for UnixWare

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net