diff options
Diffstat (limited to 'doc/Interp.3')
| -rw-r--r-- | doc/Interp.3 | 22 |
1 files changed, 12 insertions, 10 deletions
diff --git a/doc/Interp.3 b/doc/Interp.3 index b6c2c0f..362c80b 100644 --- a/doc/Interp.3 +++ b/doc/Interp.3 @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: Interp.3,v 1.3 2000/04/14 23:01:51 hobbs Exp $ +'\" RCS: @(#) $Id: Interp.3,v 1.13 2007/12/13 15:22:31 dgp Exp $ '\" .so man.macros .TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures" @@ -17,9 +17,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); @@ -30,17 +30,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 @@ -57,7 +63,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) @@ -66,7 +71,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. @@ -78,10 +82,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. |