Initial revision

1 files changed, 166 insertions, 0 deletions

diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3
new file mode 100644
index 0000000..91708b8
--- /dev/null
+++ b/doc/AddErrInfo.3
@@ -0,0 +1,166 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" 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.28 97/06/12 13:39:53
+'\" 
+.so man.macros
+.TH Tcl_AddErrorInfo 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+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_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR)
+.sp
+\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR)
+.sp
+char *
+\fBTcl_PosixError\fR(\fIinterp\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *message
+.AP Tcl_Interp *interp in
+Interpreter in which to record information.
+.AP char *message in
+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.
+.BE
+
+.SH DESCRIPTION
+.PP
+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.
+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
+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_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
+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
+\fBerrorInfo\fR beyond what can be supplied automatically
+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_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_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
+\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
+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.
+The caller must previously have called \fBTcl_SetErrno\fR to set
+\fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl
+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 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
+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_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_AddObjErrorInfo\fR is called
+for an error, it clears the existing value of \fBerrorInfo\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\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
+(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_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
+
+.SH KEYWORDS
+error, object, object result, stack, trace, variable