diff options
Diffstat (limited to 'doc/Panic.3')
| -rw-r--r-- | doc/Panic.3 | 54 |
1 files changed, 21 insertions, 33 deletions
diff --git a/doc/Panic.3 b/doc/Panic.3 index 5abe1dd..454d313 100644 --- a/doc/Panic.3 +++ b/doc/Panic.3 @@ -1,13 +1,13 @@ '\" '\" 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, Tcl_ConsolePanic \- report fatal error and abort +Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc \- report fatal error and abort .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -18,11 +18,8 @@ void void \fBTcl_PanicVA\fR(\fIformat\fR, \fIargList\fR) .sp -const char * -\fBTcl_SetPanicProc\fR(\fIpanicProc\fR) -.sp void -\fBTcl_ConsolePanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR) +\fBTcl_SetPanicProc\fR(\fIpanicProc\fR) .sp .SH ARGUMENTS .AS Tcl_PanicProc *panicProc @@ -36,7 +33,9 @@ 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 @@ -52,45 +51,33 @@ same formatting rules are also used by the built-in Tcl command 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 instead. 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 -If your application doesn't use \fBTcl_Main\fR or \fBTk_Main\fR -and you want to implicitly use the stderr channel of your -application's C runtime (instead of the stderr channel of the -C runtime used by Tcl), you can call \fBTcl_SetPanicProc\fR -with \fBTcl_ConsolePanic\fR as its argument. On platforms which -only have one C runtime (almost all platforms except Windows) -\fBTcl_ConsolePanic\fR is equivalent to NULL. +return. .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( +typedef void Tcl_PanicProc( 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 result of \fBTcl_SetPanicProc\fR is the full Tcl version with build -information (e.g., \fB8.7.0+abcdef...abcdef.gcc-1002\fR). +\fIformat\fR and \fIarg\fR arguments. To maintain consistency with the +callers of \fBTcl_Panic\fR, \fIpanicProc\fR must not return; it must +call \fBabort\fR. \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 -\fBTcl_SetPanicProc\fR can not be used in stub-enabled extensions. Its symbol -entry in the stub table is deprecated and it will be removed in Tcl 9.0. +application or the platform. As an example, the Windows implementation +of \fBwish\fR calls \fBTcl_SetPanicProc\fR to force all panic messages +to be displayed in a system dialog box, rather than to be printed to the +standard error file (usually not visible under Windows). .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 @@ -99,10 +86,11 @@ 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. Interfaces -using argument lists have been found to be nonportable in practice. This -function is deprecated and will be removed in Tcl 9.0. +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 + |
