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

NAME

8       Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult,
9       Tcl_AppendResult, Tcl_AppendResultVA,  Tcl_AppendElement,  Tcl_ResetRe‐
10       sult, Tcl_TransferResult, Tcl_FreeResult - manipulate Tcl result
11

SYNOPSIS

13       #include <tcl.h>
14
15       Tcl_SetObjResult(interp, objPtr)
16
17       Tcl_Obj *
18       Tcl_GetObjResult(interp)
19
20       Tcl_SetResult(interp, result, freeProc)
21
22       const char *
23       Tcl_GetStringResult(interp)
24
25       Tcl_AppendResult(interp, result, result, ... , (char *) NULL)
26
27       Tcl_AppendResultVA(interp, argList)
28
29       Tcl_ResetResult(interp)
30
31       Tcl_TransferResult(sourceInterp, code, targetInterp)                    │
32
33       Tcl_AppendElement(interp, element)
34
35       Tcl_FreeResult(interp)
36

ARGUMENTS

38       Tcl_Interp *interp (out)                Interpreter  whose result is to
39                                               be modified or read.
40
41       Tcl_Obj *objPtr (in)                    Tcl value to become result  for
42                                               interp.
43
44       char *result (in)                       String  value  to become result
45                                               for interp or to be appended to
46                                               the existing result.
47
48       const char *element (in)                String  value  to  append  as a
49                                               list element  to  the  existing
50                                               result of interp.
51
52       Tcl_FreeProc *freeProc (in)             Address of procedure to call to
53                                               release storage at  result,  or
54                                               TCL_STATIC,   TCL_DYNAMIC,   or
55                                               TCL_VOLATILE.
56
57       va_list argList (in)                    An  argument  list  which  must
58                                               have   been  initialized  using
59                                               va_start,  and  cleared   using
60                                               va_end.
61
62       Tcl_Interp *sourceInterp (in)           Interpreter that the result and │
63                                               return options should be trans‐ │
64                                               ferred from.
65
66       Tcl_Interp *targetInterp (in)           Interpreter that the result and │
67                                               return options should be trans‐ │
68                                               ferred to.
69
70       int code (in)                           Return code value that controls │
71                                               transfer of return options.
72______________________________________________________________________________
73

DESCRIPTION

75       The procedures described here are utilities for manipulating the result
76       value in a Tcl interpreter.  The interpreter result may be either a Tcl
77       value or a string.  For example, Tcl_SetObjResult and Tcl_SetResult set
78       the  interpreter  result to, respectively, a value and a string.  Simi‐
79       larly, Tcl_GetObjResult and Tcl_GetStringResult return the  interpreter
80       result  as  a  value  and  as a string.  The procedures always keep the
81       string and value forms of the interpreter result consistent.  For exam‐
82       ple,  if  Tcl_SetObjResult is called to set the result to a value, then
83       Tcl_GetStringResult is called, it will return the value's string repre‐
84       sentation.
85
86       Tcl_SetObjResult  arranges  for objPtr to be the result for interp, re‐
87       placing any existing result.  The result is left pointing to the  value
88       referenced  by  objPtr.   objPtr's reference count is incremented since
89       there is now a new reference to it from interp.   The  reference  count
90       for  any  old  result  value is decremented and the old result value is
91       freed if no references to it remain.
92
93       Tcl_GetObjResult returns the result for interp as a value.  The value's
94       reference  count  is  not  incremented; if the caller needs to retain a
95       long-term pointer to the value they should use Tcl_IncrRefCount to  in‐
96       crement  its  reference  count in order to keep it from being freed too
97       early or accidentally changed.
98
99       Tcl_SetResult arranges for result to be the result for the current  Tcl
100       command  in  interp, replacing any existing result.  The freeProc argu‐
101       ment specifies how to manage the storage for the result argument; it is
102       discussed in the section THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT be‐
103       low.  If result is NULL, then freeProc is ignored and Tcl_SetResult re-
104       initializes interp's result to point to an empty string.
105
106       Tcl_GetStringResult  returns the result for interp as a string.  If the
107       result was set to a value by a Tcl_SetObjResult call,  the  value  form
108       will be converted to a string and returned.  If the value's string rep‐
109       resentation contains null bytes, this conversion will lose information.
110       For  this reason, programmers are encouraged to write their code to use
111       the new value API procedures and to call Tcl_GetObjResult instead.
112
113       Tcl_ResetResult clears the result for interp and leaves the  result  in
114       its normal empty initialized state.  If the result is a value, its ref‐
115       erence count is decremented and the result is left pointing to  an  un‐
116       shared  value representing an empty string.  If the result is a dynami‐
117       cally allocated string, its memory is free*d and the result is left  as
118       a empty string.  Tcl_ResetResult also clears the error state managed by
119       Tcl_AddErrorInfo, Tcl_AddObjErrorInfo, and Tcl_SetErrorCode.
120
121       Tcl_AppendResult makes it easy to build up Tcl results in  pieces.   It
122       takes  each  of  its  result arguments and appends them in order to the
123       current result associated with interp.  If the result is  in  its  ini‐
124       tialized  empty  state  (e.g.  a  command procedure was just invoked or
125       Tcl_ResetResult was just called), then Tcl_AppendResult sets the result
126       to  the concatenation of its result arguments.  Tcl_AppendResult may be
127       called repeatedly as additional pieces  of  the  result  are  produced.
128       Tcl_AppendResult  takes care of all the storage management issues asso‐
129       ciated with managing interp's result, such as allocating a  larger  re‐
130       sult area if necessary.  It also manages conversion to and from the re‐
131       sult field of the interp so as to  handle  backward-compatibility  with
132       old-style  extensions.  Any number of result arguments may be passed in
133       a single call; the last argument in the list must be a NULL pointer.
134
135       Tcl_AppendResultVA is the same as Tcl_AppendResult except that  instead
136       of taking a variable number of arguments it takes an argument list.
137
138       Tcl_TransferResult  transfers  interpreter  state  from sourceInterp to │
139       targetInterp. The two interpreters must have been created in  the  same │
140       thread.   If  sourceInterp  and  targetInterp  are the same, nothing is │
141       done. Otherwise, Tcl_TransferResult moves the result from  sourceInterp
142       to  targetInterp,  and resets the result in sourceInterp. It also moves │
143       the return options dictionary as controlled by the  return  code  value │
144       code in the same manner as Tcl_GetReturnOptions.
145

DEPRECATED INTERFACES

147   OLD STRING PROCEDURES
148       Use of the following procedures is deprecated since they manipulate the
149       Tcl result as a string.  Procedures such as Tcl_SetObjResult  that  ma‐
150       nipulate the result as a value can be significantly more efficient.
151
152       Tcl_AppendElement  is similar to Tcl_AppendResult in that it allows re‐
153       sults to be built up in pieces.  However, Tcl_AppendElement takes  only
154       a  single  element argument and it appends that argument to the current
155       result as a proper Tcl  list  element.   Tcl_AppendElement  adds  back‐
156       slashes  or  braces  if necessary to ensure that interp's result can be
157       parsed as a list and that element will be extracted as  a  single  ele‐
158       ment.   Under  normal  conditions,  Tcl_AppendElement  will add a space
159       character to interp's result just before adding the new  list  element,
160       so  that  the list elements in the result are properly separated.  How‐
161       ever if the new list element is the first in a list or  sub-list  (i.e.
162       interp's  current  result is empty, or consists of the single character
163       “{”, or ends in the characters “ {”) then no space is added.
164
165       Tcl_FreeResult performs part of the work of Tcl_ResetResult.  It  frees
166       up  the  memory  associated  with  interp's  result.   It also sets in‐
167       terp->freeProc to zero, but does not change interp->result or clear er‐
168       ror  state.   Tcl_FreeResult  is most commonly used when a procedure is
169       about to replace one result value with another.
170
171   DIRECT ACCESS TO INTERP->RESULT
172       It used to be legal for programs to directly read and write interp->re‐
173       sult  to  manipulate the interpreter result.  The Tcl headers no longer
174       permit this access by default, and C code still doing this must be  up‐
175       dated  to use supported routines Tcl_GetObjResult, Tcl_GetStringResult,
176       Tcl_SetObjResult, and Tcl_SetResult.  As a migration aid, access can be
177       restored with the compiler directive
178              #define USE_INTERP_RESULT
179       but this is meant only to offer life support to otherwise dead code.
180

THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT

182       Tcl_SetResult's  freeProc  argument  specifies how the Tcl system is to
183       manage the storage  for  the  result  argument.   If  Tcl_SetResult  or
184       Tcl_SetObjResult  are  called  at a time when interp holds a string re‐
185       sult, they do whatever is necessary to dispose of the old string result
186       (see the Tcl_Interp manual entry for details on this).
187
188       If  freeProc  is  TCL_STATIC  it means that result refers to an area of
189       static storage that is guaranteed not to be modified until at least the
190       next call to Tcl_Eval.  If freeProc is TCL_DYNAMIC it means that result
191       was allocated with a call to Tcl_Alloc and is now the property  of  the
192       Tcl  system.  Tcl_SetResult will arrange for the string's storage to be
193       released by calling Tcl_Free when it is no longer needed.  If  freeProc
194       is  TCL_VOLATILE  it means that result points to an area of memory that
195       is likely to be overwritten when Tcl_SetResult returns (e.g. it  points
196       to something in a stack frame).  In this case Tcl_SetResult will make a
197       copy of the string in dynamically allocated storage and arrange for the
198       copy to be the result for the current Tcl command.
199
200       If  freeProc  is  not  one  of  the values TCL_STATIC, TCL_DYNAMIC, and
201       TCL_VOLATILE, then it is the address of a  procedure  that  Tcl  should
202       call  to free the string.  This allows applications to use non-standard
203       storage allocators.  When Tcl no  longer  needs  the  storage  for  the
204       string,  it  will call freeProc. FreeProc should have arguments and re‐
205       sult that match the type Tcl_FreeProc:
206
207              typedef void Tcl_FreeProc(
208                      char *blockPtr);
209
210       When freeProc is called, its blockPtr will be set to the value  of  re‐
211       sult passed to Tcl_SetResult.
212

SEE ALSO

214       Tcl_AddErrorInfo,  Tcl_CreateObjCommand,  Tcl_SetErrorCode, Tcl_Interp,
215       Tcl_GetReturnOptions
216

KEYWORDS

218       append, command, element, list, value,  result,  return  value,  inter‐
219       preter
220
221
222
223Tcl                                   8.6                     Tcl_SetResult(3)
Impressum