Tcl Source Code

Check-in [0ef72df401]
Login
☰Core Home Timeline Branches Tags Tickets Download Wiki

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Tighten up SaveResult.3, make installManPage more robust against newlines.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | core-8-branch
Files: files | file ages | folders
SHA3-256: 0ef72df401df22168cfbb7fd980e71dae96997dbabcb49ae2bfc5ce076f67c02
User & Date: pooryorick 2018-08-10 15:03:14.684
References
2024-06-11
09:06
Backout [0ef72df401df2216]: "Tighten up SaveResult.3". Will be put in a separate review for 9.0 check-in: d51f727d41 user: jan.nijtmans tags: trunk, main
08:14
Backout [0ef72df401df2216]: "Tighten up SaveResult.3". Will be put in a separate review for 9.0 check-in: e264ba6b23 user: jan.nijtmans tags: core-8-branch
Context
2024-06-10
15:25
Make installManPage more robust against newlines. Backported from 8.7 check-in: d3890a5258 user: jan.nijtmans tags: core-8-6-branch
2024-06-04
12:44
Let's review the SaveInterpState.3 changes in 8.7/trunk (which were never backported to 8.6) Closed-Leaf check-in: df24abc91a user: jan.nijtmans tags: backout-saveinterpstate-doc
2018-08-10
18:44
minor changes to documentation check-in: 33f87b52fa user: pooryorick tags: core-8-branch
15:03
Tighten up SaveResult.3, make installManPage more robust against newlines. check-in: 0ef72df401 user: pooryorick tags: core-8-branch
2018-08-08
06:46
Merge 8.6 check-in: 2f74349eb2 user: jan.nijtmans tags: core-8-branch
Changes
Unified Diff Ignore Whitespace Patch
Changes to doc/SaveResult.3. 
1
2
3

4
5
6
7
8
9
10
11
12


13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70


71
72
73
74
75
76
77
78
79
80

81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

119
120

'\"
'\" Copyright (c) 1997 by Sun Microsystems, Inc.
'\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright)

'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's state


.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_InterpState
\fBTcl_SaveInterpState\fR(\fIinterp, status\fR)
.sp
int
\fBTcl_RestoreInterpState\fR(\fIinterp, state\fR)
.sp
\fBTcl_DiscardInterpState\fR(\fIstate\fR)
.sp
\fBTcl_SaveResult\fR(\fIinterp, savedPtr\fR)
.sp
\fBTcl_RestoreResult\fR(\fIinterp, savedPtr\fR)
.sp
\fBTcl_DiscardResult\fR(\fIsavedPtr\fR)
.SH ARGUMENTS
.AS Tcl_InterpState savedPtr
.AP Tcl_Interp *interp in
Interpreter for which state should be saved.
.AP int status in
Return code value to save as part of interpreter state.
.AP Tcl_InterpState state in
Saved state token to be restored or discarded.
.AP Tcl_SavedResult *savedPtr in
Pointer to location where interpreter result should be saved or restored.
.BE
.SH DESCRIPTION
.PP
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 \fBTcl_Eval\fR or some other routine that modifies the interpreter
state.  There are two triplets of routines meant to work together.
.PP
The first triplet stores the snapshot of interpreter state in
an opaque token returned by \fBTcl_SaveInterpState\fR.  That token
value may then be passed back to one of \fBTcl_RestoreInterpState\fR


or \fBTcl_DiscardInterpState\fR, 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.
.PP
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 \fBTcl_SavedResult\fR
that is used to store enough information to restore the interpreter result.
\fBTcl_SavedResult\fR 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 \fB\-errorcode\fR or
\fB\-errorinfo\fR return options, when an error is in progress).
.PP
Because the routines \fBTcl_SaveInterpState\fR,
\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR 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 \fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR,
and \fBTcl_DiscardResult\fR continue to exist only for the sake
of existing programs that may already be using them.


.PP
\fBTcl_SaveInterpState\fR 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 \fIstatus\fR argument, and any return options, including
\fB\-errorinfo\fR and \fB\-errorcode\fR when an error is in progress.
This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR.
The call to \fBTcl_SaveInterpState\fR does not itself change the
state of the interpreter.  Unlike \fBTcl_SaveResult\fR, it does
not reset the interpreter.

.PP
\fBTcl_RestoreInterpState\fR accepts a \fBTcl_InterpState\fR token
previously returned by \fBTcl_SaveInterpState\fR and restores the
state of the interp to the state held in that snapshot.  The return
value of \fBTcl_RestoreInterpState\fR is the status value originally
passed to \fBTcl_SaveInterpState\fR when the snapshot token was
created.
.PP
\fBTcl_DiscardInterpState\fR is called to release a \fBTcl_InterpState\fR
token previously returned by \fBTcl_SaveInterpState\fR when that
snapshot is not to be restored to an interp.
.PP
The \fBTcl_InterpState\fR token returned by \fBTcl_SaveInterpState\fR
must eventually be passed to either \fBTcl_RestoreInterpState\fR
or \fBTcl_DiscardInterpState\fR to avoid a memory leak.  Once
the \fBTcl_InterpState\fR token is passed to one of them, the
token is no longer valid and should not be used anymore.
.PP
\fBTcl_SaveResult\fR moves the string and value results
of \fIinterp\fR into the location specified by \fIstatePtr\fR.
\fBTcl_SaveResult\fR clears the result for \fIinterp\fR and
leaves the result in its normal empty initialized state.

.PP
\fBTcl_RestoreResult\fR moves the string and value results from
\fIstatePtr\fR back into \fIinterp\fR.  Any result or error that was
already in the interpreter will be cleared.  The \fIstatePtr\fR is left
in an uninitialized state and cannot be used until another call to
\fBTcl_SaveResult\fR.
.PP
\fBTcl_DiscardResult\fR releases the saved interpreter state
stored at \fBstatePtr\fR.  The state structure is left in an
uninitialized state and cannot be used until another call to
\fBTcl_SaveResult\fR.
.PP
Once \fBTcl_SaveResult\fR is called to save the interpreter
result, either \fBTcl_RestoreResult\fR or
\fBTcl_DiscardResult\fR must be called to properly clean up the
memory associated with the saved state.

.SH KEYWORDS
result, state, interp




>








|
>
>




















|

|

|

|



<
|
|
<

<
|
<
>
>
|
|
<

|
<
|
<
|
<
<
<

<
|
<
<
<
<
<
>
>

|
<
<
<
<
<
|
|
<
>

<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
|
|
|
<
>

|
|
|
<
|

|
<
|


<
<
|
<
>



1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

46
47

48

49

50
51
52
53

54
55

56

57



58

59





60
61
62
63





64
65

66
67

















68
69
70

71
72
73
74
75

76
77
78

79
80
81


82

83
84
85

'\"
'\" Copyright (c) 1997 by Sun Microsystems, Inc.
'\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright)
'\" Copyright (c) 2018 Nathan Coulter. 
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState,
Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- Save and restore the
state of an an interpreter.
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_InterpState
\fBTcl_SaveInterpState\fR(\fIinterp, status\fR)
.sp
int
\fBTcl_RestoreInterpState\fR(\fIinterp, state\fR)
.sp
\fBTcl_DiscardInterpState\fR(\fIstate\fR)
.sp
\fBTcl_SaveResult\fR(\fIinterp, savedPtr\fR)
.sp
\fBTcl_RestoreResult\fR(\fIinterp, savedPtr\fR)
.sp
\fBTcl_DiscardResult\fR(\fIsavedPtr\fR)
.SH ARGUMENTS
.AS Tcl_InterpState savedPtr
.AP Tcl_Interp *interp in
The current interpreter.
.AP int status in
The return code for the state.
.AP Tcl_InterpState state in
A token for saved state.
.AP Tcl_SavedResult *savedPtr in
A pointer to storage for saved state.
.BE
.SH DESCRIPTION
.PP

These routines save the state of an interpreter before a call to a routine such
as \fBTcl_Eval\fR, and restore the state afterwards.

.PP

\fBTcl_SaveInterpState\fR saves the parts of \fIinterp\fR that comprise the

result of a script, including the resulting value, the return code passed as
\fIstatus\fR, and any options such as \fB\-errorinfo\fR and \fB\-errorcode\fR.
It returns a token for the saved state.  The interpreter result is not reset
and no interpreter state is changed.

.PP
\fBTcl_RestoreInterpState\fR restores the state indicated by \fIstate\fR and

returns the \fIstatus\fR originally passed in the corresponding call to

\fBTcl_SaveInterpState\fR.



.PP

If a saved state is not restored, \fBTcl_DiscardInterpState\fR must be called





to release it.  A token used to discard or restore state must not be used
again.
.PP
\fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR, and \fBTcl_DiscardResult\fR are





deprecated.  Instead use \fBTcl_SaveInterpState\fR,
\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR, which are more

capable.
.PP

















\fBTcl_SaveResult\fR moves the string result and structured result of
\fIinterp\fR to the location \fIstatePtr\fR points to and returns the
interpreter result to its initial state.  It does not save options such as

\fB\-errorcode\fR or \fB\-errorinfo\fR.
.PP
\fBTcl_RestoreResult\fR clears any existing result or error in \fIinterp\fR and
moves the string result and structured result from \fIstatePtr\fR back to
\fIinterp\fR.  \fIstatePtr\fR is then in an undefined state and cannot be used

until passed again to \fBTcl_SaveResult\fR.
.PP
\fBTcl_DiscardResult\fR releases the state stored at \fBstatePtr\fR, which is

then in an undefined state and cannot be used until passed again to
\fBTcl_SaveResult\fR.
.PP


If a saved result is not restored, \fBTcl_DiscardResult\fR must be called to

release it.
.SH KEYWORDS
result, state, interp
Changes to unix/installManPage.
︙︙
56
57
58
59
60
61
62
63
64
65


66
67

68
69


70
71





72
73
74






75
76
77
78
79
80
81
82
83

# A sed script to parse the alternative names out of a man page.
#
# Backslashes are trippled in the sed script, because it is in
# backticks which doesn't pass backslashes literally.
#
Names=`sed -n '
#                               Look for a line that starts with .SH NAME
    /^\.SH NAME/{
#                               Read next line
	n


#                               Remove all commas ...
	s/,//g

#                               ... and backslash-escaped spaces.
	s/\\\ //g


#                               Delete from \- to the end of line
	s/ \\\-.*//





#                               Convert all non-space non-alphanum sequences
#                               to single underscores.
	s/[^ A-Za-z0-9][^ A-Za-z0-9]*/_/g






#                               print the result and exit
	p;q
    }' $ManPage`

if test -z "$Names" ; then
    echo "warning: no target names found in $ManPage"
fi

########################################################################








|
|
|
>
>
|
|
>
|
|
>
>
|
|
>
>
>
>
>
|
|
|
>
>
>
>
>
>
|
<








56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

92
93
94
95
96
97
98

# A sed script to parse the alternative names out of a man page.
#
# Backslashes are trippled in the sed script, because it is in
# backticks which doesn't pass backslashes literally.
#
Names=`sed -n '
#                               Look for a line that starts with .SH NAME
    /^\.SH NAME/,/^\./{


	/^\./!{

	    # Remove all commas...
	    s/,//g

	    # ... and backslash-escaped spaces.
	    s/\\\ //g

	    /\\\-.*/{
		# Delete from \- to the end of line
		s/ \\\-.*//
		h
		s/.*/./
		x
	    }

	    # Convert all non-space non-alphanum sequences
	    # to single underscores.
	    s/[^ A-Za-z0-9][^ A-Za-z0-9]*/_/g
	    p
	    g
	    /^\./{
		q
	    }
    }


    }' $ManPage`

if test -z "$Names" ; then
    echo "warning: no target names found in $ManPage"
fi

########################################################################
︙︙
This page was generated in about 0.017s by Fossil 2.26 [54cfac8c84] 2025-03-21 15:26:53