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
       -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_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_DiscardInterpState 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 value 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 value results from statePtr back into interp.  Any
       result or error that was already in the interpreter 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