diff options
Diffstat (limited to 'contrib/tcl/doc/AddErrInfo.3')
| -rw-r--r-- | contrib/tcl/doc/AddErrInfo.3 | 133 |
1 files changed, 82 insertions, 51 deletions
diff --git a/contrib/tcl/doc/AddErrInfo.3 b/contrib/tcl/doc/AddErrInfo.3 index 51e75c219b00..91708b81b6ce 100644 --- a/contrib/tcl/doc/AddErrInfo.3 +++ b/contrib/tcl/doc/AddErrInfo.3 @@ -1,24 +1,28 @@ '\" '\" Copyright (c) 1989-1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" SCCS: @(#) AddErrInfo.3 1.21 96/03/25 19:55:32 +'\" SCCS: @(#) AddErrInfo.3 1.28 97/06/12 13:39:53 '\" .so man.macros .TH Tcl_AddErrorInfo 3 7.5 Tcl "Tcl Library Procedures" .BS .SH NAME -Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors +Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors .SH SYNOPSIS .nf \fB#include <tcl.h>\fR .sp +\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR) +.sp \fBTcl_AddErrorInfo\fR(\fIinterp, message\fR) .sp -\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ...\fB (char *) NULL\fR) +\fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR) +.sp +\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR) .sp char * \fBTcl_PosixError\fR(\fIinterp\fR) @@ -27,7 +31,19 @@ char * .AP Tcl_Interp *interp in Interpreter in which to record information. .AP char *message in -Identifying string to record in \fBerrorInfo\fR variable. +For \fBTcl_AddObjErrorInfo\fR, +this points to the first byte of an array of bytes +containing a string to record in the \fBerrorInfo\fR variable. +This byte array may contain embedded null bytes +unless \fIlength\fR is negative. +For \fBTcl_AddErrorInfo\fR, +this is a conventional C string to record in the \fBerrorInfo\fR variable. +.AP int length in +The number of bytes to copy from \fImessage\fR when +setting the \fBerrorInfo\fR variable. +If negative, all bytes up to the first null byte are used. +.AP Tcl_Obj *errorObjPtr in +This variable \fBerrorCode\fR will be set to this value. .AP char *element in String to record as one element of \fBerrorCode\fR variable. Last \fIelement\fR argument must be NULL. @@ -38,23 +54,23 @@ Last \fIelement\fR argument must be NULL. These procedures are used to manipulate two Tcl global variables that hold information about errors. The variable \fBerrorInfo\fR holds a stack trace of the -operations that were in progress when an error occurred, and -is intended to be human-readable. +operations that were in progress when an error occurred, +and is intended to be human-readable. The variable \fBerrorCode\fR holds a list of items that are intended to be machine-readable. The first item in \fBerrorCode\fR identifies the class of -.VS -error that occurred (e.g. POSIX means an error occurred in -.VE -a POSIX system call) and additional elements in \fBerrorCode\fR -hold additional pieces of information that depend on the class. +error that occurred +(e.g. POSIX means an error occurred in a POSIX system call) +and additional elements in \fBerrorCode\fR hold additional pieces +of information that depend on the class. See the Tcl overview manual entry for details on the various formats for \fBerrorCode\fR. .PP The \fBerrorInfo\fR variable is gradually built up as an error unwinds through the nested operations. -Each time an error code is returned to \fBTcl_Eval\fR -it calls the procedure \fBTcl_AddErrorInfo\fR to add +Each time an error code is returned to \fBTcl_EvalObj\fR +(or \fBTcl_Eval\fR, which calls \fBTcl_EvalObj\fR) +it calls the procedure \fBTcl_AddObjErrorInfo\fR to add additional text to \fBerrorInfo\fR describing the command that was being executed when the error occurred. By the time the error has been passed all the way back @@ -63,34 +79,46 @@ of the activity in progress when the error occurred. .PP It is sometimes useful to add additional information to \fBerrorInfo\fR beyond what can be supplied automatically -by \fBTcl_Eval\fR. -\fBTcl_AddErrorInfo\fR may be used for this purpose: -its \fImessage\fR argument contains an additional +by \fBTcl_EvalObj\fR. +\fBTcl_AddObjErrorInfo\fR may be used for this purpose: +its \fImessage\fR and \fIlength\fR arguments describe an additional string to be appended to \fBerrorInfo\fR. -For example, the \fBsource\fR command calls \fBTcl_AddErrorInfo\fR +For example, the \fBsource\fR command calls \fBTcl_AddObjErrorInfo\fR to record the name of the file being processed and the -line number on which the error occurred; for 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 -\fBTcl_Eval\fR has returned \fBTCL_ERROR\fR. -In calling \fBTcl_AddErrorInfo\fR, you may find it useful to +line number on which the error occurred; +for Tcl procedures, the procedure name and line number +within the procedure are recorded, and so on. +The best time to call \fBTcl_AddObjErrorInfo\fR is just after +\fBTcl_EvalObj\fR has returned \fBTCL_ERROR\fR. +In calling \fBTcl_AddObjErrorInfo\fR, you may find it useful to use the \fBerrorLine\fR field of the interpreter (see the \fBTcl_Interp\fR manual entry for details). .PP -The procedure \fBTcl_SetErrorCode\fR is used to set the -\fBerrorCode\fR variable. -Its \fIelement\fR arguments give one or more strings to record -in \fBerrorCode\fR: each \fIelement\fR will become one item -of a properly-formed Tcl list stored in \fBerrorCode\fR. -\fBTcl_SetErrorCode\fR is typically invoked just before returning -an error. -If an error is returned without calling \fBTcl_SetErrorCode\fR -then the Tcl interpreter automatically sets \fBerrorCode\fR -to \fBNONE\fR. +\fBTcl_AddErrorInfo\fR resembles \fBTcl_AddObjErrorInfo\fR +but differs in initializing \fBerrorInfo\fR from the string +value of the interpreter's result +if the error is just starting to be logged. +It does not use the result as a Tcl object +so any embedded null characters in the result +will cause information to be lost. +It also takes a conventional C string in \fImessage\fR +instead of \fBTcl_AddObjErrorInfo\fR's counted string. +.PP +The procedure \fBTcl_SetObjErrorCode\fR is used to set the +\fBerrorCode\fR variable. \fIerrorObjPtr\fR contains a list object +built up by the caller. \fBerrorCode\fR is set to this +value. \fBTcl_SetObjErrorCode\fR is typically invoked just +before returning an error in an object command. If an error is +returned without calling \fBTcl_SetObjErrorCode\fR or +\fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets +\fBerrorCode\fR to \fBNONE\fR. +.PP +The procedure \fBTcl_SetErrorCode\fR is also used to set the +\fBerrorCode\fR variable. However, it takes one or more strings to +record instead of an object. Otherwise, it is similar to +\fBTcl_SetObjErrorCode\fR in behavior. .PP \fBTcl_PosixError\fR -.VS sets the \fBerrorCode\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 \fBerrorCode\fR in the \fBPOSIX\fR format. @@ -100,36 +128,39 @@ is linked into an application as a shared library, or when the error occurs in a dynamically loaded extension. See the manual entry for \fBTcl_SetErrno\fR for more information. .PP -\fBTcl_PosixError\fR returns a human-readable -.VE -diagnostic message for the error (this is the same value that -will appear as the third element in \fBerrorCode\fR). +\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 \fBerrorCode\fR). It may be convenient to include this string as part of the -error message returned to the application in \fIinterp->result\fR. +error message returned to the application in +the interpreter's result. .PP It is important to call the procedures described here rather than setting \fBerrorInfo\fR or \fBerrorCode\fR directly with -\fBTcl_SetVar\fR. +\fBTcl_ObjSetVar2\fR. The reason for this is that the Tcl interpreter keeps information about whether these procedures have been called. -For example, the first time \fBTcl_AppendResult\fR is called +For example, the first time \fBTcl_AddObjErrorInfo\fR is called for an error, it clears the existing value of \fBerrorInfo\fR -and adds the error message in \fIinterp->result\fR to the variable -before appending \fImessage\fR; in subsequent calls, it just -appends the new \fImessage\fR. +and adds the error message in the interpreter's result to the variable +before appending \fImessage\fR; +in subsequent calls, it just appends the new \fImessage\fR. When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating -that \fBerrorCode\fR has been set; this allows the Tcl interpreter -to set \fBerrorCode\fR to \fBNONE\fB if it receives an error return +that \fBerrorCode\fR has been set; +this allows the Tcl interpreter to set \fBerrorCode\fR to \fBNONE\fR +if it receives an error return when \fBTcl_SetErrorCode\fR hasn't been called. .PP -If the procedure \fBTcl_ResetResult\fR is called, it clears all -of the state associated with \fBerrorInfo\fR and \fBerrorCode\fR +If the procedure \fBTcl_ResetResult\fR is called, +it clears all of the state associated with +\fBerrorInfo\fR and \fBerrorCode\fR (but it doesn't actually modify the variables). If an error had occurred, this will clear the error state to make it appear as if no error had occurred after all. .SH "SEE ALSO" -Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno +Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno .SH KEYWORDS -error, stack, trace, variable +error, object, object result, stack, trace, variable |