Tcl_RestoreResult man page on OpenMandriva

Man page or keyword search:  
man Server   8135 pages
apropos Keyword Search (all sections)
Output format
OpenMandriva logo
[printable version]

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
					      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 rou‐
       tines 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 pow‐
       erful routines.	The older, weaker routines Tcl_SaveResult, Tcl_Restor‐
       eResult,	 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	 argu‐
       ment,  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_RestoreIn‐
       terpState 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 eventu‐
       ally 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 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

Tcl				      8.1		     Tcl_SaveResult(3)
[top]

List of man pages available for OpenMandriva

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net