Tcl_RestoreInterpState man page on Mageia

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

Tcl_SaveResult(3)	    Tcl Library Procedures	     Tcl_SaveResult(3)

______________________________________________________________________________

NAME
       Tcl_SaveInterpState,   Tcl_RestoreInterpState,  Tcl_DiscardInterpState,
       Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult - save and restore
       an interpreter's state

SYNOPSIS
       #include <tcl.h>

       Tcl_InterpState
       Tcl_SaveInterpState(interp, status)

       int
       Tcl_RestoreInterpState(interp, state)

       Tcl_DiscardInterpState(state)

       Tcl_SaveResult(interp, savedPtr)

       Tcl_RestoreResult(interp, savedPtr)

       Tcl_DiscardResult(savedPtr)

ARGUMENTS
       Tcl_Interp *interp (in)		      Interpreter   for	  which	 state
					      should be saved.

       int status (in)			      Return code  value  to  save  as
					      part of interpreter state.

       Tcl_InterpState state (in)	      Saved state token to be restored
					      or discarded.

       Tcl_SavedResult *savedPtr (in)	      Pointer to location where inter‐
					      preter result should be saved or
					      restored.
_________________________________________________________________

DESCRIPTION
       These routines allows a C procedure to take a snapshot of  the  current │
       state  of  an  interpreter  so  that it can be restored after a call to │
       Tcl_Eval or some other routine that  modifies  the  interpreter	state. │
       There are two triplets of routines meant to work together.	       │

       The first triplet stores the snapshot of interpreter state in an opaque │
       token returned by Tcl_SaveInterpState.  That token value	 may  then  be │
       passed back to one of Tcl_RestoreInterpState or Tcl_DiscardInterpState, │
       depending on whether the interp state is to be restored.	  So  long  as │
       one  of the latter two routines is called, Tcl will take care of memory │
       management.							       │

       The second triplet stores the snapshot of only the  interpreter	result │
       (not its complete state) in memory allocated by the caller.  These rou‐ │
       tines are passed a pointer to a Tcl_SavedResult structure that is  used │
       to  store  enough  information to restore the interpreter result.  This │
       structure can be allocated on  the  stack  of  the  calling  procedure. │
       These  routines	do  not save the state of any error information in the │
       interpreter (e.g. the -errorcode or -errorinfo return options, when  an │
       error is in progress).						       │

       Because	the  routines Tcl_SaveInterpState, Tcl_RestoreInterpState, and │
       Tcl_DiscardInterpState perform a superset of the functions provided  by │
       the  other routines, any new code should only make use of the more pow‐ │
       erful routines.	The older, weaker routines Tcl_SaveResult, Tcl_Restor‐ │
       eResult,	 and  Tcl_DiscardResult continue to exist only for the sake of │
       existing programs that may already be using them.		       │

       Tcl_SaveInterpState takes a snapshot of those portions  of  interpreter │
       state  that make up the full result of script evaluation.  This include │
       the interpreter result, the return code (passed in as the status	 argu‐ │
       ment,  and any return options, including -errorinfo and -errorcode when │
       an error is in progress.	 This snapshot is returned as an opaque	 token │
       of  type	 Tcl_InterpState.   The	 call  to Tcl_SaveInterpState does not │
       itself change the state of the interpreter.  Unlike Tcl_SaveResult,  it │
       does not reset the interpreter.					       │

       Tcl_RestoreInterpState	accepts	 a  Tcl_InterpState  token  previously │
       returned by Tcl_SaveInterpState and restores the state of the interp to │
       the  state  held	 in that snapshot.  The return value of Tcl_RestoreIn‐ │
       terpState is the status value originally passed to  Tcl_SaveInterpState │
       when the snapshot token was created.				       │

       Tcl_DiscardInterpState  is  called  to  release a Tcl_InterpState token │
       previously returned by Tcl_SaveInterpState when that snapshot is not to │
       be restored to an interp.					       │

       The  Tcl_InterpState token returned by Tcl_SaveInterpState must eventu‐ │
       ally be passed to either Tcl_RestoreInterpState	or  Tcl_DiscardInterp‐ │
       State to avoid a memory leak.  Once the Tcl_InterpState token is passed │
       to one of them, the token is no longer valid and	 should	 not  be  used │
       anymore.

       Tcl_SaveResult  moves  the string and object results of interp into the
       location specified by statePtr.	Tcl_SaveResult clears the  result  for
       interp and leaves the result in its normal empty initialized state.

       Tcl_RestoreResult  moves	 the  string  and object results from statePtr
       back into interp.  Any result or error that was already in  the	inter‐
       preter will be cleared.	The statePtr is left in an uninitialized state
       and cannot be used until another call to Tcl_SaveResult.

       Tcl_DiscardResult  releases  the	 saved	interpreter  state  stored  at
       statePtr.   The	state  structure is left in an uninitialized state and
       cannot be used until another call to Tcl_SaveResult.

       Once Tcl_SaveResult is called to save the  interpreter  result,	either
       Tcl_RestoreResult or Tcl_DiscardResult must be called to properly clean
       up the memory associated with the saved state.

KEYWORDS
       result, state, interp

Tcl				      8.1		     Tcl_SaveResult(3)
[top]

List of man pages available for Mageia

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