* 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:

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 */