summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authordgp <dgp@users.sourceforge.net>2008-12-15 18:33:24 (GMT)
committerdgp <dgp@users.sourceforge.net>2008-12-15 18:33:24 (GMT)
commit4a44a570aada5b04e9ffdee9b9f82f7fa34cfe6c (patch)
treed0ed3407fd1898930f5bc28d45d09c610c8775cb
parentfc8e6478bfb02d60c1dc8c861dd80af63e036481 (diff)
downloadtcl-4a44a570aada5b04e9ffdee9b9f82f7fa34cfe6c.zip
tcl-4a44a570aada5b04e9ffdee9b9f82f7fa34cfe6c.tar.gz
tcl-4a44a570aada5b04e9ffdee9b9f82f7fa34cfe6c.tar.bz2
* doc/AddErrInfo.3: Documented Tcl_(Set|Get)ErrorLine (TIP 336).
* doc/CrtCommand.3: Various other documentation updates to * doc/CrtInterp.3: reflect the lack of access to Tcl_Interp fields * doc/Interp.3: by default. * doc/SetResult.3: * doc/tcl.decls:
-rw-r--r--ChangeLog8
-rw-r--r--doc/AddErrInfo.323
-rw-r--r--doc/CrtCommand.38
-rw-r--r--doc/CrtInterp.310
-rw-r--r--doc/Interp.328
-rw-r--r--doc/SetResult.319
-rw-r--r--generic/tcl.decls4
-rw-r--r--generic/tclDecls.h6
8 files changed, 70 insertions, 36 deletions
diff --git a/ChangeLog b/ChangeLog
index 0454c6e..40fcd76 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -6,6 +6,13 @@
2008-12-15 Don Porter <dgp@users.sourceforge.net>
+ * doc/AddErrInfo.3: Documented Tcl_(Set|Get)ErrorLine (TIP 336).
+ * doc/CrtCommand.3: Various other documentation updates to
+ * doc/CrtInterp.3: reflect the lack of access to Tcl_Interp fields
+ * doc/Interp.3: by default.
+ * doc/SetResult.3:
+ * doc/tcl.decls:
+
TIP #338 IMPLEMENTATION
* doc/AppInit.c: Made routines Tcl_SetStartupScript and
@@ -19,6 +26,7 @@
* generic/tclIntDecls.h: make genstubs
* generic/tclStubInit.c:
+ * generic/tclDecls.h:
2008-12-14 Donal K. Fellows <dkf@users.sf.net>
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3
index 0de0a0f..ae136ce 100644
--- a/doc/AddErrInfo.3
+++ b/doc/AddErrInfo.3
@@ -5,13 +5,13 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: AddErrInfo.3,v 1.23 2008/10/17 10:22:25 dkf Exp $
+'\" RCS: @(#) $Id: AddErrInfo.3,v 1.24 2008/12/15 18:33:24 dgp Exp $
'\"
.so man.macros
.TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
+Tcl_GetReturnOptions, Tcl_SetReturnOptions, Tcl_AddErrorInfo, Tcl_AppendObjToErrorInfo, Tcl_AddObjErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_SetErrorLine, Tcl_GetErrorLine, Tcl_PosixError, Tcl_LogCommandInfo \- retrieve or record information about errors and other return options
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -34,6 +34,10 @@ int
.sp
\fBTcl_SetErrorCodeVA\fR(\fIinterp, argList\fR)
.sp
+\fBTcl_GetErrorLine\fR(\fIinterp\fR)
+.sp
+\fBTcl_SetErrorLine\fR(\fIinterp, lineNum\fR)
+.sp
const char *
\fBTcl_PosixError\fR(\fIinterp\fR)
.sp
@@ -70,6 +74,8 @@ Last \fIelement\fR argument must be NULL.
.AP va_list argList in
An argument list which must have been initialized using
\fBva_start\fR, and cleared using \fBva_end\fR.
+.AP int lineNum
+The line number of a script where an error occurred.
.AP "const char" *script in
Pointer to first character in script containing command (must be <= command)
.AP "const char" *command in
@@ -157,8 +163,12 @@ to set any collection of return options, there are a handful
of return options that are very frequently used. Most
notably the \fB\-errorinfo\fR and \fB\-errorcode\fR return
options should be set properly when the command procedure
-of a command returns \fBTCL_ERROR\fR. Tcl provides several
-simpler interfaces to more directly set these return options.
+of a command returns \fBTCL_ERROR\fR. The \fB\-errorline\fR
+return option is also read by commands that evaluate scripts
+and wish to supply detailed error location information in
+the stack trace text they append to the \fB\-errorinfo\fR option.
+Tcl provides several simpler interfaces to more directly set
+these return options.
.PP
The \fB\-errorinfo\fR option holds a stack trace of the
operations that were in progress when an error occurred,
@@ -235,6 +245,11 @@ record instead of an object. Otherwise, it is similar to
\fBTcl_SetErrorCodeVA\fR is the same as \fBTcl_SetErrorCode\fR except that
instead of taking a variable number of arguments it takes an argument list.
.PP
+The procedure \fBTcl_GetErrorLine\fR is used to read the integer value
+of the \fB\-errorline\fR return option without the overhead of a full
+call to \fBTcl_GetReturnOptions\fR. Likewise, \fBTcl_SetErrorLine\fR
+sets the \fB\-errorline\fR return option value.
+.PP
\fBTcl_PosixError\fR
sets the \fB\-errorcode\fR variable after an error in a POSIX kernel call.
It reads the value of the \fBerrno\fR C variable and calls
diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3
index 02081bf..4e8daaf 100644
--- a/doc/CrtCommand.3
+++ b/doc/CrtCommand.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: CrtCommand.3,v 1.16 2008/10/15 10:43:37 dkf Exp $
+'\" RCS: @(#) $Id: CrtCommand.3,v 1.17 2008/12/15 18:33:25 dgp Exp $
'\"
.so man.macros
.TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
@@ -54,9 +54,7 @@ Also, Tcl's interpreter now uses objects internally.
In order to invoke a string-based command procedure
registered by \fBTcl_CreateCommand\fR,
it must generate and fetch a string representation
-from each argument object before the call
-and create a new Tcl object to hold the string result returned by the
-string-based command procedure.
+from each argument object before the call.
New commands should be defined using \fBTcl_CreateObjCommand\fR.
We support \fBTcl_CreateCommand\fR for backwards compatibility.
.PP
@@ -108,7 +106,7 @@ version 8.1 of Tcl.
\fBTCL_CONTINUE\fR. See the Tcl overview man page
for details on what these codes mean. Most normal commands will only
return \fBTCL_OK\fR or \fBTCL_ERROR\fR. In addition, \fIproc\fR must set
-the interpreter result to point to a string value;
+the interpreter result;
in the case of a \fBTCL_OK\fR return code this gives the result
of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
The \fBTcl_SetResult\fR procedure provides an easy interface for setting
diff --git a/doc/CrtInterp.3 b/doc/CrtInterp.3
index d751f75..158b3b8 100644
--- a/doc/CrtInterp.3
+++ b/doc/CrtInterp.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: CrtInterp.3,v 1.9 2008/12/05 21:38:47 dkf Exp $
+'\" RCS: @(#) $Id: CrtInterp.3,v 1.10 2008/12/15 18:33:25 dgp Exp $
'\"
.so man.macros
.TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
@@ -38,10 +38,10 @@ Token for interpreter to be destroyed or queried.
\fBTcl_CreateInterp\fR creates a new interpreter structure and returns
a token for it. The token is required in calls to most other Tcl
procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and
-\fBTcl_DeleteInterp\fR.
-Clients are only allowed to access a few of the fields of
-Tcl_Interp structures; see the \fBTcl_Interp\fR
-and \fBTcl_CreateCommand\fR man pages for details.
+\fBTcl_DeleteInterp\fR. The token returned by \fBTcl_CreateInterp\fR
+may only be passed to Tcl routines called from the same thread as
+the original \fBTcl_CreateInterp\fR call. It is not safe for multiple
+threads to pass the same token to Tcl's routines.
The new interpreter is initialized with the built-in Tcl commands
and with the variables documented in tclvars(n). To bind in
additional commands, call \fBTcl_CreateCommand\fR.
diff --git a/doc/Interp.3 b/doc/Interp.3
index 29c2c65..4f0a250 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.14 2008/06/29 22:28:24 dkf Exp $
+'\" RCS: @(#) $Id: Interp.3,v 1.15 2008/12/15 18:33:25 dgp Exp $
'\"
.so man.macros
.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
@@ -28,15 +28,25 @@ typedef void \fBTcl_FreeProc\fR(
.SH DESCRIPTION
.PP
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 fields
-that are used by Tcl, but only three that may be accessed by
-clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\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
-\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.
+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.
diff --git a/doc/SetResult.3 b/doc/SetResult.3
index d19bd998..12ccc90 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.
'\"
-'\" RCS: @(#) $Id: SetResult.3,v 1.23 2008/12/05 16:01:01 nijtmans Exp $
+'\" RCS: @(#) $Id: SetResult.3,v 1.24 2008/12/15 18:33:25 dgp Exp $
'\"
.so man.macros
.TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures"
@@ -199,16 +199,19 @@ It also sets \fIinterp->freeProc\fR to zero, but does not
change \fIinterp->result\fR or clear error state.
\fBTcl_FreeResult\fR is most commonly used when a procedure
is about to replace one result value with another.
-.SS "DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED"
+.SS "DIRECT ACCESS TO INTERP->RESULT"
.PP
It used to be legal for programs to
directly read and write \fIinterp->result\fR
-to manipulate the interpreter result.
-Direct access to \fIinterp->result\fR is now strongly deprecated
-because it can make the result's string and object forms inconsistent.
-Programs should always read the result
-using the procedures \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR,
-and write the result using \fBTcl_SetObjResult\fR or \fBTcl_SetResult\fR.
+to manipulate the interpreter result. The Tcl headers no longer
+permit this access by default, and 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
diff --git a/generic/tcl.decls b/generic/tcl.decls
index 9cd8da6..334f004 100644
--- a/generic/tcl.decls
+++ b/generic/tcl.decls
@@ -12,7 +12,7 @@
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
-# RCS: @(#) $Id: tcl.decls,v 1.160 2008/12/11 14:16:41 dkf Exp $
+# RCS: @(#) $Id: tcl.decls,v 1.161 2008/12/15 18:33:25 dgp Exp $
library tcl
@@ -2203,7 +2203,7 @@ declare 605 generic {
int Tcl_GetErrorLine(Tcl_Interp *interp)
}
declare 606 generic {
- void Tcl_SetErrorLine(Tcl_Interp *interp, int value)
+ void Tcl_SetErrorLine(Tcl_Interp *interp, int lineNum)
}
# TIP#307 (move results between interpreters)
diff --git a/generic/tclDecls.h b/generic/tclDecls.h
index 45805f2..8c58b9c 100644
--- a/generic/tclDecls.h
+++ b/generic/tclDecls.h
@@ -8,7 +8,7 @@
* See the file "license.terms" for information on usage and redistribution
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
*
- * RCS: @(#) $Id: tclDecls.h,v 1.161 2008/12/11 14:17:23 dkf Exp $
+ * RCS: @(#) $Id: tclDecls.h,v 1.162 2008/12/15 18:33:25 dgp Exp $
*/
#ifndef _TCLDECLS
@@ -3668,7 +3668,7 @@ EXTERN int Tcl_GetErrorLine (Tcl_Interp * interp);
#ifndef Tcl_SetErrorLine_TCL_DECLARED
#define Tcl_SetErrorLine_TCL_DECLARED
/* 606 */
-EXTERN void Tcl_SetErrorLine (Tcl_Interp * interp, int value);
+EXTERN void Tcl_SetErrorLine (Tcl_Interp * interp, int lineNum);
#endif
#ifndef Tcl_TransferResult_TCL_DECLARED
#define Tcl_TransferResult_TCL_DECLARED
@@ -4423,7 +4423,7 @@ typedef struct TclStubs {
int (*tcl_GetEnsembleParameterList) (Tcl_Interp * interp, Tcl_Command token, Tcl_Obj ** paramListPtr); /* 603 */
int (*tcl_ParseArgsObjv) (Tcl_Interp * interp, const Tcl_ArgvInfo * argTable, int * objcPtr, Tcl_Obj *const * objv, Tcl_Obj *** remObjv); /* 604 */
int (*tcl_GetErrorLine) (Tcl_Interp * interp); /* 605 */
- void (*tcl_SetErrorLine) (Tcl_Interp * interp, int value); /* 606 */
+ void (*tcl_SetErrorLine) (Tcl_Interp * interp, int lineNum); /* 606 */
void (*tcl_TransferResult) (Tcl_Interp * sourceInterp, int result, Tcl_Interp * targetInterp); /* 607 */
int (*tcl_InterpActive) (Tcl_Interp * interp); /* 608 */
void (*tcl_BackgroundException) (Tcl_Interp * interp, int code); /* 609 */