summaryrefslogtreecommitdiffstats
path: root/doc/Panic.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/Panic.3')
-rw-r--r--doc/Panic.354
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
+