Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
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  inter-
					    preter result should be saved or re-
					    stored.
________________________________________________________________________________

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 to-
     ken 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  lat-
     ter 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 Tcl_SavedResult that is used to store enough informa-
     tion to restore the interpreter result.  Tcl_SavedResult 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 rou-
     tines.   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 inter-
     preter  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_Interp-
     State.  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 to-
     ken was created.

     Tcl_DiscardInterpState is called to release a Tcl_InterpState token  previ-
     ously  returned  by Tcl_SaveInterpState when that snapshot is not to be re-
     stored 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 loca-
     tion 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

Tcl				       8.1		       Tcl_SaveResult(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_RestoreResult.tcl86&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help