diff options
Diffstat (limited to 'tcl8.6/doc/Panic.3')
-rw-r--r-- | tcl8.6/doc/Panic.3 | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/tcl8.6/doc/Panic.3 b/tcl8.6/doc/Panic.3 new file mode 100644 index 0000000..af86665 --- /dev/null +++ b/tcl8.6/doc/Panic.3 @@ -0,0 +1,89 @@ +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH Tcl_Panic 3 8.4 Tcl "Tcl Library Procedures" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc \- report fatal error and abort +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +void +\fBTcl_Panic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR) +.sp +void +\fBTcl_PanicVA\fR(\fIformat\fR, \fIargList\fR) +.sp +void +\fBTcl_SetPanicProc\fR(\fIpanicProc\fR) +.sp +.SH ARGUMENTS +.AS Tcl_PanicProc *panicProc +.AP "const char*" format in +A printf-style format string. +.AP "" arg in +Arguments matching the format string. +.AP va_list argList in +An argument list of arguments matching the format string. +Must have been initialized using \fBva_start\fR, +and cleared using \fBva_end\fR. +.AP Tcl_PanicProc *panicProc in +Procedure to report fatal error message and abort. +.BE +.SH DESCRIPTION +.PP +When the Tcl library detects that its internal data structures are in an +inconsistent state, or that its C procedures have been called in a +manner inconsistent with their documentation, it calls \fBTcl_Panic\fR +to display a message describing the error and abort the process. The +\fIformat\fR argument is a format string describing how to format the +remaining arguments \fIarg\fR into an error message, according to the +same formatting rules used by the \fBprintf\fR family of functions. The +same formatting rules are also used by the built-in Tcl command +\fBformat\fR. +.PP +In a freshly loaded Tcl library, \fBTcl_Panic\fR prints the formatted +error message to the standard error file of the process, and then +calls \fBabort\fR to terminate the process. \fBTcl_Panic\fR does not +return. On Windows, when a debugger is running, the formatted error +message is sent to the debugger in stead. If the windows executable +does not have a stderr channel (e.g. \fBwish.exe\fR), then a +system dialog box is used to display the panic message. +.PP +\fBTcl_SetPanicProc\fR may be used to modify the behavior of +\fBTcl_Panic\fR. The \fIpanicProc\fR argument should match the +type \fBTcl_PanicProc\fR: +.PP +.CS +typedef void \fBTcl_PanicProc\fR( + const char *\fBformat\fR, + \fBarg\fR, \fBarg\fR,...); +.CE +.PP +After \fBTcl_SetPanicProc\fR returns, any future calls to +\fBTcl_Panic\fR will call \fIpanicProc\fR, passing along the +\fIformat\fR and \fIarg\fR arguments. \fIpanicProc\fR should avoid +making calls into the Tcl library, or into other libraries that may +call the Tcl library, since the original call to \fBTcl_Panic\fR +indicates the Tcl library is not in a state of reliable operation. +.PP +The typical use of \fBTcl_SetPanicProc\fR arranges for the error message +to be displayed or reported in a manner more suitable for the +application or the platform. +.PP +Although the primary callers of \fBTcl_Panic\fR are the procedures of +the Tcl library, \fBTcl_Panic\fR is a public function and may be called +by any extension or application that wishes to abort the process and +have a panic message displayed the same way that panic messages from Tcl +will be displayed. +.PP +\fBTcl_PanicVA\fR is the same as \fBTcl_Panic\fR except that instead of +taking a variable number of arguments it takes an argument list. +.SH "SEE ALSO" +abort(3), printf(3), exec(n), format(n) +.SH KEYWORDS +abort, fatal, error |