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_SaveInterpState(interp, status)

     Tcl_RestoreInterpState(interp, state)


     Tcl_SaveResult(interp, savedPtr)

     Tcl_RestoreResult(interp, savedPtr)



     Tcl_Interp *interp (in)                Interpreter for which
                                            state    should    be

     int status (in)                        Return code value  to
                                            save   as   part   of
                                            interpreter state.

     Tcl_InterpState state (in)             Saved state token  to
                                            be  restored  or dis-

     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.                              |

Tcl                     Last change: 8.1                        1

Tcl_SaveResult(3)    Tcl Library Procedures     Tcl_SaveResult(3)

     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  inter-  |
     preter  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  struc-  |
     ture can be allocated on the stack of the calling procedure.  |
     These routines do not save the state of any  error  informa-  |
     tion  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 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  pre-  |
     viously  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  |

Tcl                     Last change: 8.1                        2

Tcl_SaveResult(3)    Tcl Library Procedures     Tcl_SaveResult(3)

     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 unin-
     itialized state and cannot be used  until  another  call  to

     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                     Last change: 8.1                        3

Man(1) output converted with man2html