[25] | 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 |
---|