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
					      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 Tcl_SavedResult that is used to store
       enough information 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  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 it-
       self change the state of	the interpreter.   Unlike  Tcl_SaveResult,  it
       does not	reset the interpreter.

       Tcl_RestoreInterpState  accepts	a Tcl_InterpState token	previously re-
       turned 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)

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

home | help