From c187695b61274eb7742b87d19a2794bd25f1a22d Mon Sep 17 00:00:00 2001 From: dgp Date: Mon, 6 Jan 2020 20:12:32 +0000 Subject: Bring docs up to date with TIP 330 and TIP 336 changes already in Tcl 8.7 --- doc/Interp.3 | 121 +++++++------------------------------------------------- doc/SetResult.3 | 9 +---- 2 files changed, 16 insertions(+), 114 deletions(-) diff --git a/doc/Interp.3 b/doc/Interp.3 index 4ccff21..c1b9803 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. '\" -.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures" +.TH Tcl_Interp 3 8.7 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -15,9 +15,9 @@ Tcl_Interp \- client-visible fields of interpreter structures \fB#include \fR .sp typedef struct { - char *\fIresult\fR; - Tcl_FreeProc *\fIfreeProc\fR; - int \fIerrorLine\fR; + char *\fIresult\fR; /* NO LONGER AVAILABLE */ + Tcl_FreeProc *\fIfreeProc\fR; /* NO LONGER AVAILABLE */ + int \fIerrorLine\fR; /* NO LONGER AVAILABLE */ } \fBTcl_Interp\fR; typedef void \fBTcl_FreeProc\fR( @@ -25,110 +25,17 @@ typedef void \fBTcl_FreeProc\fR( .BE .SH DESCRIPTION .PP -The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp +The \fBTcl_CreateInterp\fR procedure returns a pointer to a \fBTcl_Interp\fR structure. Callers of \fBTcl_CreateInterp\fR should use this pointer as an opaque token, suitable for nothing other than passing back to -other routines in the Tcl interface. Accessing fields directly through -the pointer as described below is no longer supported. The supported -public routines \fBTcl_SetResult\fR, \fBTcl_GetResult\fR, -\fBTcl_SetErrorLine\fR, \fBTcl_GetErrorLine\fR must be used instead. -.PP -For legacy programs and extensions no longer being maintained, compiles -against the Tcl 8.6 header files are only possible with the compiler -directives -.CS -#define USE_INTERP_RESULT -.CE -and/or -.CS -#define USE_INTERP_ERRORLINE -.CE -depending on which fields of the \fBTcl_Interp\fR struct are accessed. -These directives may be embedded in code or supplied via compiler options. -.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 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 -will hide all the details of managing the fields. -The description below is for those procedures that manipulate the -fields directly. -.PP -Whenever a command procedure returns, it must ensure -that the \fIresult\fR field of its interpreter points to the string -being returned by the command. -The \fIresult\fR field must always point to a valid string. -If a command wishes to return no result then \fIinterp->result\fR -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. -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) -and store a pointer to it in \fIinterp->result\fR. -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. -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. -If a client procedure overwrites \fIinterp->result\fR when -\fIinterp->freeProc\fR is non-zero, then it is responsible for calling -\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR -macro should be used for this purpose). -.PP -\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. -In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever -used for \fIfreeProc\fR. -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. -.PP -As part of processing each command, \fBTcl_Eval\fR initializes -\fIinterp->result\fR -and \fIinterp->freeProc\fR just before calling the command procedure for -the command. The \fIfreeProc\fR field will be initialized to zero, -and \fIinterp->result\fR will point to an empty string. Commands that -do not return any value can simply leave the fields alone. -Furthermore, the empty string pointed to by \fIresult\fR is actually -part of an array of approximately 200 characters. -If a command wishes to return a short string, it can simply copy -it to the area pointed to by \fIinterp->result\fR. Or, it can use -the sprintf procedure to generate a short result string at the location -pointed to by \fIinterp->result\fR. -.PP -It is a general convention in Tcl-based applications that the result -of an interpreter is normally in the initialized state described -in the previous paragraph. -Procedures that manipulate an interpreter's result (e.g. by -returning an error) will generally assume that the result -has been initialized when the procedure is called. -If such a procedure is to be called after the result has been -changed, then \fBTcl_ResetResult\fR should be called first to -reset the result to its initialized state. The direct use of -\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR). -.PP -The \fIerrorLine\fR -field is valid only after \fBTcl_Eval\fR returns -a \fBTCL_ERROR\fR return code. In this situation the \fIerrorLine\fR -field identifies the line number of the command being executed when -the error occurred. The line numbers are relative to the command -being executed: 1 means the first line of the command passed to -\fBTcl_Eval\fR, 2 means the second line, and so on. -The \fIerrorLine\fR field is typically used in conjunction with -\fBTcl_AddErrorInfo\fR to report information about where an error -occurred. -\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR. +other routines in the Tcl interface from the same thread that called +\fBTcl_CreateInterp\fR. The \fBTcl_Interp\fR struct no longer has any +supported client-visible fields. Supported public routines such as +\fBTcl_SetResult\fR, \fBTcl_GetResult\fR, \fBTcl_SetErrorLine\fR, +\fBTcl_GetErrorLine\fR must be used instead. +.PP +Any legacy programs and extensions trying to access the fields above +in their source code will need conversion to compile for Tcl 8.7 and later. .SH KEYWORDS -free, initialized, interpreter, malloc, result +interpreter, result diff --git a/doc/SetResult.3 b/doc/SetResult.3 index c5ed78a..a640956 100644 --- a/doc/SetResult.3 +++ b/doc/SetResult.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. '\" -.TH Tcl_SetResult 3 8.6 Tcl "Tcl Library Procedures" +.TH Tcl_SetResult 3 8.7 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME @@ -195,14 +195,9 @@ is about to replace one result value with another. It used to be legal for programs to directly read and write \fIinterp->result\fR to manipulate the interpreter result. The Tcl headers no longer -permit this access by default, and C code still doing this must +permit this access. C code still doing this must be updated to use supported routines \fBTcl_GetObjResult\fR, \fBTcl_GetStringResult\fR, \fBTcl_SetObjResult\fR, and \fBTcl_SetResult\fR. -As a migration aid, access can be restored with the compiler directive -.CS -#define USE_INTERP_RESULT -.CE -but this is meant only to offer life support to otherwise dead code. .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT" .PP \fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how -- cgit v0.12 From 1923110631cdc3460af116549af89e47ec5a0139 Mon Sep 17 00:00:00 2001 From: dgp Date: Mon, 6 Jan 2020 20:24:25 +0000 Subject: one more --- doc/Eval.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Eval.3 b/doc/Eval.3 index e241794..f7c6976 100644 --- a/doc/Eval.3 +++ b/doc/Eval.3 @@ -150,7 +150,7 @@ equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below). of any length, concatenates them into a single string, then calls \fBTcl_Eval\fR to execute that string as a Tcl command. It returns the result of the command and also modifies -\fIinterp->result\fR in the same way as \fBTcl_Eval\fR. +the interpreter result in the same way as \fBTcl_Eval\fR. The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end of arguments. \fBTcl_VarEval\fR is now deprecated. .PP -- cgit v0.12