summaryrefslogtreecommitdiffstats
path: root/doc/AddErrInfo.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/AddErrInfo.3')
-rw-r--r--doc/AddErrInfo.358
1 files changed, 29 insertions, 29 deletions
diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3
index d5f6b5f..6fa5851 100644
--- a/doc/AddErrInfo.3
+++ b/doc/AddErrInfo.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: AddErrInfo.3,v 1.17 2007/10/28 14:17:38 dkf Exp $
+'\" RCS: @(#) $Id: AddErrInfo.3,v 1.18 2007/10/29 11:28:49 dkf Exp $
'\"
.so man.macros
.TH Tcl_AddErrorInfo 3 8.5 Tcl "Tcl Library Procedures"
@@ -49,20 +49,20 @@ The code returned from script evaluation.
A dictionary of return options.
.AP char *message in
For \fBTcl_AddErrorInfo\fR,
-this is a conventional C string to append to the \fB-errorinfo\fR return option.
+this is a conventional C string to append to the \fB\-errorinfo\fR return option.
For \fBTcl_AddObjErrorInfo\fR,
this points to the first byte of an array of \fIlength\fR bytes
-containing a string to append to the \fB-errorinfo\fR return option.
+containing a string to append to the \fB\-errorinfo\fR return option.
This byte array may contain embedded null bytes
unless \fIlength\fR is negative.
.AP int length in
The number of bytes to copy from \fImessage\fR when
-appending to the \fB-errorinfo\fR return option.
+appending to the \fB\-errorinfo\fR return option.
If negative, all bytes up to the first null byte are used.
.AP Tcl_Obj *errorObjPtr in
-The \fB-errorcode\fR return option will be set to this value.
+The \fB\-errorcode\fR return option will be set to this value.
.AP char *element in
-String to record as one element of the \fB-errorcode\fR return option.
+String to record as one element of the \fB\-errorcode\fR return option.
Last \fIelement\fR argument must be NULL.
.AP va_list argList in
An argument list which must have been initialized using
@@ -94,10 +94,10 @@ of return options. The integer completion code should be
passed as the \fIcode\fR argument to \fBTcl_GetReturnOptions\fR
so that all required options will be present in the dictionary.
Specifically, a \fIcode\fR value of \fBTCL_ERROR\fR will
-ensure that entries for the keys \fB-errorinfo\fR,
-\fB-errorcode\fR, and \fB-errorline\fR will appear in the
-dictionary. Also, the entries for the keys \fB-code\fR
-and \fB-level\fR will be adjusted if necessary to agree
+ensure that entries for the keys \fB\-errorinfo\fR,
+\fB\-errorcode\fR, and \fB\-errorline\fR will appear in the
+dictionary. Also, the entries for the keys \fB\-code\fR
+and \fB\-level\fR will be adjusted if necessary to agree
with the value of \fIcode\fR. The \fB(Tcl_Obj *)\fR returned
by \fBTcl_GetReturnOptions\fR points to an unshared
\fBTcl_Obj\fR with reference count of zero. The dictionary
@@ -125,7 +125,7 @@ of \fIinterp\fR to be \fIoptions\fR. If \fIoptions\fR
contains any invalid value for any key, TCL_ERROR will
be returned, and the interp result will be set to an
appropriate error message. Otherwise, a completion code
-in agreement with the \fB-code\fR and \fB-level\fR
+in agreement with the \fB\-code\fR and \fB\-level\fR
keys in \fIoptions\fR will be returned.
.PP
As an example, Tcl's \fBreturn\fR command itself could
@@ -150,43 +150,43 @@ to any reference counting. This is analogous to
While \fBTcl_SetReturnOptions\fR provides a general interface
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
+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.
.VE 8.5
.PP
-The \fB-errorinfo\fR option holds a stack trace of the
+The \fB\-errorinfo\fR option holds a stack trace of the
operations that were in progress when an error occurred,
and is intended to be human-readable.
-The \fB-errorcode\fR option holds a list of items that
+The \fB\-errorcode\fR option holds a list of items that
are intended to be machine-readable.
-The first item in the \fB-errorcode\fR value identifies the class of
+The first item in the \fB\-errorcode\fR value identifies the class of
error that occurred
(e.g. POSIX means an error occurred in a POSIX system call)
and additional elements hold additional pieces
of information that depend on the class.
See the tclvars manual entry for details on the various
-formats for the \fB-errorcode\fR option used by
+formats for the \fB\-errorcode\fR option used by
Tcl's built-in commands.
.PP
-The \fB-errorinfo\fR option value is gradually built up as an
+The \fB\-errorinfo\fR option value is gradually built up as an
error unwinds through the nested operations.
Each time an error code is returned to \fBTcl_Eval\fR, or
any of the routines that performs script evaluation,
the procedure \fBTcl_AddErrorInfo\fR is called to add
-additional text to the \fB-errorinfo\fR value describing the
+additional text to the \fB\-errorinfo\fR value describing the
command that was being executed when the error occurred.
By the time the error has been passed all the way back
to the application, it will contain a complete trace
of the activity in progress when the error occurred.
.PP
It is sometimes useful to add additional information to
-the \fB-errorinfo\fR value beyond what can be supplied automatically
+the \fB\-errorinfo\fR value beyond what can be supplied automatically
by the script evaluation routines.
\fBTcl_AddErrorInfo\fR may be used for this purpose:
its \fImessage\fR argument is an additional
-string to be appended to the \fB-errorinfo\fR option.
+string to be appended to the \fB\-errorinfo\fR option.
For example, when an error arises during the \fBsource\fR command,
the procedure \fBTcl_AddErrorInfo\fR is called to
record the name of the file being processed and the
@@ -196,7 +196,7 @@ Tcl procedures, the procedure name and line number
within the procedure are recorded, and so on.
The best time to call \fBTcl_AddErrorInfo\fR is just after
a script evaluation routine has returned \fBTCL_ERROR\fR.
-The value of the \fB-errorline\fR return option (retrieved
+The value of the \fB\-errorline\fR return option (retrieved
via a call to \fBTcl_GetReturnOptions\fR) often makes up
a useful part of the \fImessage\fR passed to \fBTcl_AddErrorInfo\fR.
.PP
@@ -210,16 +210,16 @@ the need for a null byte. If the \fBTcl_AddObjErrorInfo\fR
interface is used at all, it should be with a negative \fIlength\fR value.
.PP
The procedure \fBTcl_SetObjErrorCode\fR is used to set the
-\fB-errorcode\fR return option to the list object \fIerrorObjPtr\fR
+\fB\-errorcode\fR return option to the list object \fIerrorObjPtr\fR
built up by the caller.
\fBTcl_SetObjErrorCode\fR is typically invoked just
before returning an error. If an error is
returned without calling \fBTcl_SetObjErrorCode\fR or
\fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets
-the \fB-errorcode\fR return option to \fBNONE\fR.
+the \fB\-errorcode\fR return option to \fBNONE\fR.
.PP
The procedure \fBTcl_SetErrorCode\fR is also used to set the
-\fB-errorcode\fR return option. However, it takes one or more strings to
+\fB\-errorcode\fR return option. However, it takes one or more strings to
record instead of an object. Otherwise, it is similar to
\fBTcl_SetObjErrorCode\fR in behavior.
.PP
@@ -227,9 +227,9 @@ record instead of an object. Otherwise, it is similar to
instead of taking a variable number of arguments it takes an argument list.
.PP
\fBTcl_PosixError\fR
-sets the \fB-errorcode\fR variable after an error in a POSIX kernel call.
+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
-\fBTcl_SetErrorCode\fR to set the \fB-errorcode\fR return
+\fBTcl_SetErrorCode\fR to set the \fB\-errorcode\fR return
option in the \fBPOSIX\fR format.
The caller must previously have called \fBTcl_SetErrno\fR to set
\fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl
@@ -240,14 +240,14 @@ occurs in a dynamically loaded extension. See the manual entry for
\fBTcl_PosixError\fR returns a human-readable diagnostic message
for the error
(this is the same value that will appear as the third element
-in the \fB-errorcode\fR value).
+in the \fB\-errorcode\fR value).
It may be convenient to include this string as part of the
error message returned to the application in
the interpreter's result.
.PP
\fBTcl_LogCommandInfo\fR is invoked after an error occurs in an
interpreter. It adds information about the command that was being
-executed when the error occurred to the \fB-errorinfo\fR value, and
+executed when the error occurred to the \fB\-errorinfo\fR value, and
the line number stored internally in the interpreter is set.
.PP
In older releases of Tcl, there was no \fBTcl_GetReturnOptions\fR
@@ -269,7 +269,7 @@ setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
If the procedure \fBTcl_ResetResult\fR is called,
it clears all of the state of the interpreter associated with
script evaluation, including the entire return options dictionary.
-In particular, the \fB-errorinfo\fR and \fB-errorcode\fR options
+In particular, the \fB\-errorinfo\fR and \fB\-errorcode\fR options
are reset.
If an error had occurred, the \fBTcl_ResetResult\fR call will
clear the error state to make it appear as if no error had