diff options
Diffstat (limited to 'doc/Interp.3')
| -rw-r--r-- | doc/Interp.3 | 20 |
1 files changed, 11 insertions, 9 deletions
diff --git a/doc/Interp.3 b/doc/Interp.3 index 7d1f515..0b1de03 100644 --- a/doc/Interp.3 +++ b/doc/Interp.3 @@ -15,9 +15,9 @@ Tcl_Interp \- client-visible fields of interpreter structures \fB#include <tcl.h>\fR .sp typedef struct { - char *\fIresult\fR; - Tcl_FreeProc *\fIfreeProc\fR; - int \fIerrorLine\fR; + char *\fIresult\fR; + Tcl_FreeProc *\fIfreeProc\fR; + int \fIerrorLine\fR; } Tcl_Interp; typedef void Tcl_FreeProc(char *\fIblockPtr\fR); @@ -28,17 +28,23 @@ typedef void Tcl_FreeProc(char *\fIblockPtr\fR); The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp structure. This pointer is then passed into other Tcl procedures to process commands in the interpreter and perform other operations -on the interpreter. Interpreter structures contain many many fields +on the interpreter. Interpreter structures contain many fields that are used by Tcl, but only three that may be accessed by clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR. .PP +.VS 8.5 +\fBNote that access to all three fields, \fIresult\fB, \fIfreeProc\fB and +\fIerrorLine\fB is deprecated.\fR Use \fBTcl_SetResult\fR, +\fBTcl_GetResult\fR, and \fBTcl_GetReturnOptions\fR instead. +.VE 8.5 +.PP The \fIresult\fR and \fIfreeProc\fR fields are used to return results or error messages from commands. This information is returned by command procedures back to \fBTcl_Eval\fR, and by \fBTcl_Eval\fR back to its callers. The \fIresult\fR field points to the string that represents the result or error message, and the \fIfreeProc\fR field tells how -to dispose of the storage for the string when it isn't needed anymore. +to dispose of the storage for the string when it is not needed anymore. The easiest way for command procedures to manipulate these fields is to call procedures like \fBTcl_SetResult\fR or \fBTcl_AppendResult\fR; they @@ -55,7 +61,6 @@ should point to an empty string. Normally, results are assumed to be statically allocated, which means that the contents will not change before the next time \fBTcl_Eval\fR is called or some other command procedure is invoked. -.VS In this case, the \fIfreeProc\fR field must be zero. Alternatively, a command procedure may dynamically allocate its return value (e.g. using \fBTcl_Alloc\fR) @@ -64,7 +69,6 @@ In this case, the command procedure must also set \fIinterp->freeProc\fR to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR if the storage was allocated directly by Tcl or by a call to \fBTcl_Alloc\fR. -.VE If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR to free the space pointed to by \fIinterp->result\fR before it invokes the next command. @@ -76,10 +80,8 @@ macro should be used for this purpose). \fIFreeProc\fR should have arguments and result that match the \fBTcl_FreeProc\fR declaration above: it receives a single argument which is a pointer to the result value to free. -.VS In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever used for \fIfreeProc\fR. -.VE However, an application may store a different procedure address in \fIfreeProc\fR in order to use an alternate memory allocator or in order to do other cleanup when the result memory is freed. |