AddErrInfo.3
上传用户:rrhhcc
上传日期:2015-12-11
资源大小:54129k
文件大小:8k
- '"
- '" 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.
- '"
- '" RCS: @(#) $Id: AddErrInfo.3,v 1.8.2.1 2003/07/18 16:56:24 dgp Exp $
- '"
- .so man.macros
- .TH Tcl_AddErrorInfo 3 8.0 Tcl "Tcl Library Procedures"
- .BS
- .SH NAME
- Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo - record information about errors
- .SH SYNOPSIS
- .nf
- fB#include <tcl.h>fR
- .sp
- fBTcl_AddObjErrorInfofR(fIinterp, message, lengthfR)
- .sp
- fBTcl_AddErrorInfofR(fIinterp, messagefR)
- .sp
- fBTcl_SetObjErrorCodefR(fIinterp, errorObjPtrfR)
- .sp
- fBTcl_SetErrorCodefR(fIinterp, element, element, ... fB(char *) NULLfR)
- .sp
- fBTcl_SetErrorCodeVAfR(fIinterp, argListfR)
- .sp
- CONST char *
- fBTcl_PosixErrorfR(fIinterpfR)
- .sp
- void
- fBTcl_LogCommandInfofR(fIinterp, script, command, commandLengthfR)
- .SH ARGUMENTS
- .AS Tcl_Interp *message
- .AP Tcl_Interp *interp in
- Interpreter in which to record information.
- .AP char *message in
- For fBTcl_AddObjErrorInfofR,
- this points to the first byte of an array of bytes
- containing a string to record in the fBerrorInfofR variable.
- This byte array may contain embedded null bytes
- unless fIlengthfR is negative.
- For fBTcl_AddErrorInfofR,
- this is a conventional C string to record in the fBerrorInfofR variable.
- .AP int length in
- The number of bytes to copy from fImessagefR when
- setting the fBerrorInfofR variable.
- If negative, all bytes up to the first null byte are used.
- .AP Tcl_Obj *errorObjPtr in
- This variable fBerrorCodefR will be set to this value.
- .AP char *element in
- String to record as one element of fBerrorCodefR variable.
- Last fIelementfR argument must be NULL.
- .AP va_list argList in
- An argument list which must have been initialized using
- fBTCL_VARARGS_STARTfR, and cleared using fBva_endfR.
- .AP "CONST char" *script in
- Pointer to first character in script containing command (must be <= command)
- .AP "CONST char" *command in
- Pointer to first character in command that generated the error
- .AP int commandLength in
- Number of bytes in command; -1 means use all bytes up to first null byte
- .BE
- .SH DESCRIPTION
- .PP
- These procedures are used to manipulate two Tcl global variables
- that hold information about errors.
- The variable fBerrorInfofR holds a stack trace of the
- operations that were in progress when an error occurred,
- and is intended to be human-readable.
- The variable fBerrorCodefR holds a list of items that
- are intended to be machine-readable.
- The first item in fBerrorCodefR identifies the class of
- error that occurred
- (e.g. POSIX means an error occurred in a POSIX system call)
- and additional elements in fBerrorCodefR hold additional pieces
- of information that depend on the class.
- See the Tcl overview manual entry for details on the various
- formats for fBerrorCodefR.
- .PP
- The fBerrorInfofR variable is gradually built up as an
- error unwinds through the nested operations.
- Each time an error code is returned to fBTcl_EvalObjExfR
- (or fBTcl_EvalfR, which calls fBTcl_EvalObjExfR)
- it calls the procedure fBTcl_AddObjErrorInfofR to add
- additional text to fBerrorInfofR 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
- fBerrorInfofR beyond what can be supplied automatically
- by fBTcl_EvalObjExfR.
- fBTcl_AddObjErrorInfofR may be used for this purpose:
- its fImessagefR and fIlengthfR arguments describe an additional
- string to be appended to fBerrorInfofR.
- For example, the fBsourcefR command calls fBTcl_AddObjErrorInfofR
- 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_AddObjErrorInfofR is just after
- fBTcl_EvalObjExfR has returned fBTCL_ERRORfR.
- In calling fBTcl_AddObjErrorInfofR, you may find it useful to
- use the fBerrorLinefR field of the interpreter (see the
- fBTcl_InterpfR manual entry for details).
- .PP
- fBTcl_AddErrorInfofR resembles fBTcl_AddObjErrorInfofR
- but differs in initializing fBerrorInfofR 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 fImessagefR
- instead of fBTcl_AddObjErrorInfofR's counted string.
- .PP
- The procedure fBTcl_SetObjErrorCodefR is used to set the
- fBerrorCodefR variable. fIerrorObjPtrfR contains a list object
- built up by the caller. fBerrorCodefR is set to this
- value. fBTcl_SetObjErrorCodefR is typically invoked just
- before returning an error in an object command. If an error is
- returned without calling fBTcl_SetObjErrorCodefR or
- fBTcl_SetErrorCodefR the Tcl interpreter automatically sets
- fBerrorCodefR to fBNONEfR.
- .PP
- The procedure fBTcl_SetErrorCodefR is also used to set the
- fBerrorCodefR variable. However, it takes one or more strings to
- record instead of an object. Otherwise, it is similar to
- fBTcl_SetObjErrorCodefR in behavior.
- .PP
- fBTcl_SetErrorCodeVAfR is the same as fBTcl_SetErrorCodefR except that
- instead of taking a variable number of arguments it takes an argument list.
- .PP
- fBTcl_PosixErrorfR
- sets the fBerrorCodefR variable after an error in a POSIX kernel call.
- It reads the value of the fBerrnofR C variable and calls
- fBTcl_SetErrorCodefR to set fBerrorCodefR in the fBPOSIXfR format.
- The caller must previously have called fBTcl_SetErrnofR to set
- fBerrnofR; 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_SetErrnofR for more information.
- .PP
- fBTcl_PosixErrorfR returns a human-readable diagnostic message
- for the error
- (this is the same value that will appear as the third element
- in fBerrorCodefR).
- 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_LogCommandInfofR 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 fBerrorInfofR variable, and
- the line number stored internally in the interpreter is set. On the
- first call to fBTcl_LogCommandInfofR or fBTcl_AddObjErrorInfofR
- since an error occurred, the old information in fBerrorInfofR is
- deleted.
- .PP
- It is important to call the procedures described here rather than
- setting fBerrorInfofR or fBerrorCodefR directly with
- fBTcl_ObjSetVar2fR.
- The reason for this is that the Tcl interpreter keeps information
- about whether these procedures have been called.
- For example, the first time fBTcl_AddObjErrorInfofR is called
- for an error, it clears the existing value of fBerrorInfofR
- and adds the error message in the interpreter's result to the variable
- before appending fImessagefR;
- in subsequent calls, it just appends the new fImessagefR.
- When fBTcl_SetErrorCodefR is called, it sets a flag indicating
- that fBerrorCodefR has been set;
- this allows the Tcl interpreter to set fBerrorCodefR to fBNONEfR
- if it receives an error return
- when fBTcl_SetErrorCodefR hasn't been called.
- .PP
- If the procedure fBTcl_ResetResultfR is called,
- it clears all of the state associated with
- fBerrorInfofR and fBerrorCodefR
- (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