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

Linux & Unix Commands - Search Man Pages

Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 interpreter result should
					      be saved or restored.
_________________________________________________________________

DESCRIPTION
       These routines allows a C procedure to take a snapshot of the current state of  an  inter- |
       preter so that it can be restored after a call to Tcl_Eval or some other routine that mod- |
       ifies 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_RestoreIn- |
       terpState 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 mem- |
       ory 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  inter- |
       preter  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_DiscardInterp- |
       State 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 |
       -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_SaveIn- |
       terpState  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_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 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 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)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:37 AM.

Unix & Linux Forums Content Copyright©1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?