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

DESCRIPTION

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

KEYWORDS

116       result, state, interp
117
118
119
120Tcl                                   8.1                    Tcl_SaveResult(3)
Impressum