diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/AddErrInfo.3 | 23 | ||||
| -rw-r--r-- | doc/CrtCommand.3 | 8 | ||||
| -rw-r--r-- | doc/CrtInterp.3 | 10 | ||||
| -rw-r--r-- | doc/Interp.3 | 28 | ||||
| -rw-r--r-- | doc/SetResult.3 | 19 |
5 files changed, 57 insertions, 31 deletions
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 |