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 interpreter 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 |
       routines 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 powerful routines.	The older, weaker routines Tcl_SaveResult, |
       Tcl_RestoreResult, 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 argument, and any return options, including -errorinfo and -error- |
       code 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_RestoreInterpState 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 eventually 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  can-
       not 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)