1 | '\" |
---|
2 | '\" Copyright (c) 1989-1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1997 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: SetResult.3,v 1.18 2007/12/13 15:22:31 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures" |
---|
12 | .BS |
---|
13 | .SH NAME |
---|
14 | Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_FreeResult \- manipulate Tcl result |
---|
15 | .SH SYNOPSIS |
---|
16 | .nf |
---|
17 | \fB#include <tcl.h>\fR |
---|
18 | .sp |
---|
19 | \fBTcl_SetObjResult\fR(\fIinterp, objPtr\fR) |
---|
20 | .sp |
---|
21 | Tcl_Obj * |
---|
22 | \fBTcl_GetObjResult\fR(\fIinterp\fR) |
---|
23 | .sp |
---|
24 | \fBTcl_SetResult\fR(\fIinterp, result, freeProc\fR) |
---|
25 | .sp |
---|
26 | const char * |
---|
27 | \fBTcl_GetStringResult\fR(\fIinterp\fR) |
---|
28 | .sp |
---|
29 | \fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fB(char *) NULL\fR) |
---|
30 | .sp |
---|
31 | \fBTcl_AppendResultVA\fR(\fIinterp, argList\fR) |
---|
32 | .sp |
---|
33 | \fBTcl_AppendElement\fR(\fIinterp, element\fR) |
---|
34 | .sp |
---|
35 | \fBTcl_ResetResult\fR(\fIinterp\fR) |
---|
36 | .sp |
---|
37 | \fBTcl_FreeResult\fR(\fIinterp\fR) |
---|
38 | .SH ARGUMENTS |
---|
39 | .AS Tcl_FreeProc freeProc out |
---|
40 | .AP Tcl_Interp *interp out |
---|
41 | Interpreter whose result is to be modified or read. |
---|
42 | .AP Tcl_Obj *objPtr in |
---|
43 | Object value to become result for \fIinterp\fR. |
---|
44 | .AP char *result in |
---|
45 | String value to become result for \fIinterp\fR or to be |
---|
46 | appended to the existing result. |
---|
47 | .AP char *element in |
---|
48 | String value to append as a list element |
---|
49 | to the existing result of \fIinterp\fR. |
---|
50 | .AP Tcl_FreeProc *freeProc in |
---|
51 | Address of procedure to call to release storage at |
---|
52 | \fIresult\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or |
---|
53 | \fBTCL_VOLATILE\fR. |
---|
54 | .AP va_list argList in |
---|
55 | An argument list which must have been initialized using |
---|
56 | \fBva_start\fR, and cleared using \fBva_end\fR. |
---|
57 | .BE |
---|
58 | .SH DESCRIPTION |
---|
59 | .PP |
---|
60 | The procedures described here are utilities for manipulating the |
---|
61 | result value in a Tcl interpreter. |
---|
62 | The interpreter result may be either a Tcl object or a string. |
---|
63 | For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR |
---|
64 | set the interpreter result to, respectively, an object and a string. |
---|
65 | Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR |
---|
66 | return the interpreter result as an object and as a string. |
---|
67 | The procedures always keep the string and object forms |
---|
68 | of the interpreter result consistent. |
---|
69 | For example, if \fBTcl_SetObjResult\fR is called to set |
---|
70 | the result to an object, |
---|
71 | then \fBTcl_GetStringResult\fR is called, |
---|
72 | it will return the object's string value. |
---|
73 | .PP |
---|
74 | \fBTcl_SetObjResult\fR |
---|
75 | arranges for \fIobjPtr\fR to be the result for \fIinterp\fR, |
---|
76 | replacing any existing result. |
---|
77 | The result is left pointing to the object |
---|
78 | referenced by \fIobjPtr\fR. |
---|
79 | \fIobjPtr\fR's reference count is incremented |
---|
80 | since there is now a new reference to it from \fIinterp\fR. |
---|
81 | The reference count for any old result object |
---|
82 | is decremented and the old result object is freed if no |
---|
83 | references to it remain. |
---|
84 | .PP |
---|
85 | \fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as an object. |
---|
86 | The object's reference count is not incremented; |
---|
87 | if the caller needs to retain a long-term pointer to the object |
---|
88 | they should use \fBTcl_IncrRefCount\fR to increment its reference count |
---|
89 | in order to keep it from being freed too early or accidentally changed. |
---|
90 | .PP |
---|
91 | \fBTcl_SetResult\fR |
---|
92 | arranges for \fIresult\fR to be the result for the current Tcl |
---|
93 | command in \fIinterp\fR, replacing any existing result. |
---|
94 | The \fIfreeProc\fR argument specifies how to manage the storage |
---|
95 | for the \fIresult\fR argument; |
---|
96 | it is discussed in the section |
---|
97 | \fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below. |
---|
98 | If \fIresult\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored |
---|
99 | and \fBTcl_SetResult\fR |
---|
100 | re-initializes \fIinterp\fR's result to point to an empty string. |
---|
101 | .PP |
---|
102 | \fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string. |
---|
103 | If the result was set to an object by a \fBTcl_SetObjResult\fR call, |
---|
104 | the object form will be converted to a string and returned. |
---|
105 | If the object's string representation contains null bytes, |
---|
106 | this conversion will lose information. |
---|
107 | For this reason, programmers are encouraged to |
---|
108 | write their code to use the new object API procedures |
---|
109 | and to call \fBTcl_GetObjResult\fR instead. |
---|
110 | .PP |
---|
111 | \fBTcl_ResetResult\fR clears the result for \fIinterp\fR |
---|
112 | and leaves the result in its normal empty initialized state. |
---|
113 | If the result is an object, |
---|
114 | its reference count is decremented and the result is left |
---|
115 | pointing to an unshared object representing an empty string. |
---|
116 | If the result is a dynamically allocated string, its memory is free*d |
---|
117 | and the result is left as a empty string. |
---|
118 | \fBTcl_ResetResult\fR also clears the error state managed by |
---|
119 | \fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR, |
---|
120 | and \fBTcl_SetErrorCode\fR. |
---|
121 | .PP |
---|
122 | \fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces. |
---|
123 | It takes each of its \fIresult\fR arguments and appends them in order |
---|
124 | to the current result associated with \fIinterp\fR. |
---|
125 | If the result is in its initialized empty state (e.g. a command procedure |
---|
126 | was just invoked or \fBTcl_ResetResult\fR was just called), |
---|
127 | then \fBTcl_AppendResult\fR sets the result to the concatenation of |
---|
128 | its \fIresult\fR arguments. |
---|
129 | \fBTcl_AppendResult\fR may be called repeatedly as additional pieces |
---|
130 | of the result are produced. |
---|
131 | \fBTcl_AppendResult\fR takes care of all the |
---|
132 | storage management issues associated with managing \fIinterp\fR's |
---|
133 | result, such as allocating a larger result area if necessary. |
---|
134 | It also manages conversion to and from the \fIresult\fR field of the |
---|
135 | \fIinterp\fR so as to handle backward-compatability with old-style |
---|
136 | extensions. |
---|
137 | Any number of \fIresult\fR arguments may be passed in a single |
---|
138 | call; the last argument in the list must be a NULL pointer. |
---|
139 | .PP |
---|
140 | \fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that |
---|
141 | instead of taking a variable number of arguments it takes an argument list. |
---|
142 | .SH "OLD STRING PROCEDURES" |
---|
143 | .PP |
---|
144 | Use of the following procedures (is deprecated |
---|
145 | since they manipulate the Tcl result as a string. |
---|
146 | Procedures such as \fBTcl_SetObjResult\fR |
---|
147 | that manipulate the result as an object |
---|
148 | can be significantly more efficient. |
---|
149 | .PP |
---|
150 | \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in |
---|
151 | that it allows results to be built up in pieces. |
---|
152 | However, \fBTcl_AppendElement\fR takes only a single \fIelement\fR |
---|
153 | argument and it appends that argument to the current result |
---|
154 | as a proper Tcl list element. |
---|
155 | \fBTcl_AppendElement\fR adds backslashes or braces if necessary |
---|
156 | to ensure that \fIinterp\fR's result can be parsed as a list and that |
---|
157 | \fIelement\fR will be extracted as a single element. |
---|
158 | Under normal conditions, \fBTcl_AppendElement\fR will add a space |
---|
159 | character to \fIinterp\fR's result just before adding the new |
---|
160 | list element, so that the list elements in the result are properly |
---|
161 | separated. |
---|
162 | However if the new list element is the first in a list or sub-list |
---|
163 | (i.e. \fIinterp\fR's current result is empty, or consists of the |
---|
164 | single character |
---|
165 | .QW { , |
---|
166 | or ends in the characters |
---|
167 | .QW " {" ) |
---|
168 | then no space is added. |
---|
169 | .PP |
---|
170 | \fBTcl_FreeResult\fR performs part of the work |
---|
171 | of \fBTcl_ResetResult\fR. |
---|
172 | It frees up the memory associated with \fIinterp\fR's result. |
---|
173 | It also sets \fIinterp->freeProc\fR to zero, but does not |
---|
174 | change \fIinterp->result\fR or clear error state. |
---|
175 | \fBTcl_FreeResult\fR is most commonly used when a procedure |
---|
176 | is about to replace one result value with another. |
---|
177 | .SH "DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED" |
---|
178 | .PP |
---|
179 | It used to be legal for programs to |
---|
180 | directly read and write \fIinterp->result\fR |
---|
181 | to manipulate the interpreter result. |
---|
182 | Direct access to \fIinterp->result\fR is now strongly deprecated |
---|
183 | because it can make the result's string and object forms inconsistent. |
---|
184 | Programs should always read the result |
---|
185 | using the procedures \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR, |
---|
186 | and write the result using \fBTcl_SetObjResult\fR or \fBTcl_SetResult\fR. |
---|
187 | .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT" |
---|
188 | .PP |
---|
189 | \fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how |
---|
190 | the Tcl system is to manage the storage for the \fIresult\fR argument. |
---|
191 | If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called |
---|
192 | at a time when \fIinterp\fR holds a string result, |
---|
193 | they do whatever is necessary to dispose of the old string result |
---|
194 | (see the \fBTcl_Interp\fR manual entry for details on this). |
---|
195 | .PP |
---|
196 | If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIresult\fR |
---|
197 | refers to an area of static storage that is guaranteed not to be |
---|
198 | modified until at least the next call to \fBTcl_Eval\fR. |
---|
199 | If \fIfreeProc\fR |
---|
200 | is \fBTCL_DYNAMIC\fR it means that \fIresult\fR was allocated with a call |
---|
201 | to \fBTcl_Alloc\fR and is now the property of the Tcl system. |
---|
202 | \fBTcl_SetResult\fR will arrange for the string's storage to be |
---|
203 | released by calling \fBTcl_Free\fR when it is no longer needed. |
---|
204 | If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIresult\fR |
---|
205 | points to an area of memory that is likely to be overwritten when |
---|
206 | \fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame). |
---|
207 | In this case \fBTcl_SetResult\fR will make a copy of the string in |
---|
208 | dynamically allocated storage and arrange for the copy to be the |
---|
209 | result for the current Tcl command. |
---|
210 | .PP |
---|
211 | If \fIfreeProc\fR is not one of the values \fBTCL_STATIC\fR, |
---|
212 | \fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address |
---|
213 | of a procedure that Tcl should call to free the string. |
---|
214 | This allows applications to use non-standard storage allocators. |
---|
215 | When Tcl no longer needs the storage for the string, it will |
---|
216 | call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and |
---|
217 | result that match the type \fBTcl_FreeProc\fR: |
---|
218 | .CS |
---|
219 | typedef void Tcl_FreeProc(char *\fIblockPtr\fR); |
---|
220 | .CE |
---|
221 | When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to |
---|
222 | the value of \fIresult\fR passed to \fBTcl_SetResult\fR. |
---|
223 | .SH "SEE ALSO" |
---|
224 | Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp |
---|
225 | .SH KEYWORDS |
---|
226 | append, command, element, list, object, result, return value, interpreter |
---|