1Tcl_SaveResult(3)           Tcl Library Procedures           Tcl_SaveResult(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_SaveInterpState,   Tcl_RestoreInterpState,  Tcl_DiscardInterpState,
9       Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult - save and restore
10       an interpreter's state
11

SYNOPSIS

13       #include <tcl.h>
14
15       Tcl_InterpState
16       Tcl_SaveInterpState(interp, status)
17
18       int
19       Tcl_RestoreInterpState(interp, state)
20
21       Tcl_DiscardInterpState(state)
22
23       Tcl_SaveResult(interp, savedPtr)
24
25       Tcl_RestoreResult(interp, savedPtr)
26
27       Tcl_DiscardResult(savedPtr)
28

ARGUMENTS

30       Tcl_Interp *interp (in)                Interpreter   for   which  state
31                                              should be saved.
32
33       int status (in)                        Return code  value  to  save  as
34                                              part of interpreter state.
35
36       Tcl_InterpState state (in)             Saved state token to be restored
37                                              or discarded.
38
39       Tcl_SavedResult *savedPtr (in)         Pointer to location where inter‐
40                                              preter result should be saved or
41                                              restored.
42_________________________________________________________________
43
44

DESCRIPTION

46       These routines allows a C procedure to take a snapshot of  the  current │
47       state  of  an  interpreter  so  that it can be restored after a call to │
48       Tcl_Eval or some other routine that  modifies  the  interpreter  state. │
49       There are two triplets of routines meant to work together.              │
50
51       The first triplet stores the snapshot of interpreter state in an opaque │
52       token returned by Tcl_SaveInterpState.  That token value  may  then  be │
53       passed back to one of Tcl_RestoreInterpState or Tcl_DiscardInterpState, │
54       depending on whether the interp state is to be restored.   So  long  as │
55       one  of the latter two routines is called, Tcl will take care of memory │
56       management.                                                             │
57
58       The second triplet stores the snapshot of only the  interpreter  result │
59       (not its complete state) in memory allocated by the caller.  These rou‐ │
60       tines are passed a pointer to a Tcl_SavedResult structure that is  used │
61       to  store  enough  information to restore the interpreter result.  This │
62       structure can be allocated on  the  stack  of  the  calling  procedure. │
63       These  routines  do  not save the state of any error information in the │
64       interpreter (e.g. the -errorcode or -errorinfo return options, when  an │
65       error is in progress).                                                  │
66
67       Because  the  routines Tcl_SaveInterpState, Tcl_RestoreInterpState, and │
68       Tcl_DiscardInterpState perform a superset of the functions provided  by │
69       the  other routines, any new code should only make use of the more pow‐ │
70       erful routines.  The older, weaker routines Tcl_SaveResult, Tcl_Restor‐ 
71       eResult,  and  Tcl_DiscardResult continue to exist only for the sake of │
72       existing programs that may already be using them.                       │
73
74       Tcl_SaveInterpState takes a snapshot of those portions  of  interpreter │
75       state  that make up the full result of script evaluation.  This include │
76       the interpreter result, the return code (passed in as the status  argu‐ │
77       ment,  and any return options, including -errorinfo and -errorcode when │
78       an error is in progress.  This snapshot is returned as an opaque  token │
79       of  type  Tcl_InterpState.   The  call  to Tcl_SaveInterpState does not │
80       itself change the state of the interpreter.  Unlike Tcl_SaveResult,  it │
81       does not reset the interpreter.                                         │
82
83       Tcl_RestoreInterpState   accepts  a  Tcl_InterpState  token  previously │
84       returned by Tcl_SaveInterpState and restores the state of the interp to │
85       the  state  held  in that snapshot.  The return value of Tcl_RestoreIn‐ 
86       terpState is the status value originally passed to  Tcl_SaveInterpState 
87       when the snapshot token was created.                                    │
88
89       Tcl_DiscardInterpState  is  called  to  release a Tcl_InterpState token │
90       previously returned by Tcl_SaveInterpState when that snapshot is not to │
91       be restored to an interp.                                               │
92
93       The  Tcl_InterpState token returned by Tcl_SaveInterpState must eventu‐ │
94       ally be passed to either Tcl_RestoreInterpState  or  Tcl_DiscardInterp‐ 
95       State to avoid a memory leak.  Once the Tcl_InterpState token is passed │
96       to one of them, the token is no longer valid and  should  not  be  used │
97       anymore.
98
99       Tcl_SaveResult  moves  the string and object results of interp into the
100       location specified by statePtr.  Tcl_SaveResult clears the  result  for
101       interp and leaves the result in its normal empty initialized state.
102
103       Tcl_RestoreResult  moves  the  string  and object results from statePtr
104       back into interp.  Any result or error that was already in  the  inter‐
105       preter will be cleared.  The statePtr is left in an uninitialized state
106       and cannot be used until another call to Tcl_SaveResult.
107
108       Tcl_DiscardResult  releases  the  saved  interpreter  state  stored  at
109       statePtr.   The  state  structure is left in an uninitialized state and
110       cannot be used until another call to Tcl_SaveResult.
111
112       Once Tcl_SaveResult is called to save the  interpreter  result,  either
113       Tcl_RestoreResult or Tcl_DiscardResult must be called to properly clean
114       up the memory associated with the saved state.
115
116

KEYWORDS

118       result, state, interp
119
120
121
122Tcl                                   8.1                    Tcl_SaveResult(3)
Impressum