NAME

       Tcl_SaveInterpState,  Tcl_RestoreInterpState,  Tcl_DiscardInterpState - 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)

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

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.

       Tcl_SaveInterpState  stores  a  snapshot  of  the  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.

       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.

       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.

KEYWORDS

       result, state, interp

Tcl                                                    8.1                             Tcl_SaveInterpState(3tcl)