NAME¶

Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult - Save and restore the state of an an interpreter.

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)

The interpreter for the operation.

int status (in)

The return code for the state.

Tcl_InterpState state (in)

A token for saved state.

Tcl_SavedResult *savedPtr (in)

A pointer to storage for saved state.

DESCRIPTION¶

These routines save the state of an interpreter before a call to a routine such as Tcl_Eval, and restore the state afterwards.

Tcl_SaveInterpState saves the parts of interp that comprise the result of a script, including the resulting value, the return code passed as status, and any options such as -errorinfo and -errorcode. It returns a token for the saved state. The interpreter result is not reset and no interpreter state is changed.

Tcl_RestoreInterpState restores the state indicated by state and returns the status originally passed in the corresponding call to Tcl_SaveInterpState.

If a saved state is not restored, Tcl_DiscardInterpState must be called to release it. A token used to discard or restore state must not be used again.

Tcl_SaveResult, Tcl_RestoreResult, and Tcl_DiscardResult are deprecated. Instead use Tcl_SaveInterpState, Tcl_RestoreInterpState, and Tcl_DiscardInterpState, which are more capable.

Tcl_SaveResult moves the result of interp to the location statePtr points to and returns the interpreter result to its initial state. It does not save options such as -errorcode or -errorinfo.

Tcl_RestoreResult clears any existing result or error in interp and moves the result from statePtr back to interp. statePtr is then in an undefined state and must not be used until passed again to Tcl_SaveResult.

Tcl_DiscardResult releases the state stored at statePtr, which is then in an undefined state and must not be used until passed again to Tcl_SaveResult.

If a saved result is not restored, Tcl_DiscardResult must be called to release it.

KEYWORDS¶

result, state, interp