diff options
Diffstat (limited to 'doc/AddErrInfo.3')
| -rw-r--r-- | doc/AddErrInfo.3 | 58 |
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 |