Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

CentOS 7.0 - man page for tcl_restoreinterpstate (centos section 3)

Tcl_SaveResult(3)					      Tcl Library Procedures						 Tcl_SaveResult(3)


Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult - save and restore an interpreter's state
#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)
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. _________________________________________________________________
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.
result, state, interp Tcl 8.1 Tcl_SaveResult(3)