* generic/tcl.h:

	* generic/tcl.decls:
	* generic/tclPanic.c: Added CONST to Tcl_*Panic* public interfaces.
	  [Patch 415648, TIP 27]

	* generic/tclInt.decls:
	* mac/tclMacAppInit.c (main):
	* mac/tclMacBOAAppInit.c (main):
	* mac/tclMacPanic.c: Modified special Mac implementations of
	  Tcl_*Panic* to be exact copies of the generic implementations.
	  Added TclMacSetPanic.  The generic implementations should be
	  used directly, rather than copies, but that requires further
	  changes by someone familiar with the Mac build systems.
	  [Patch 415648]

	* generic/tclDecls.h:
	* generic/tclIntPlatDecls.h:
	*`generic/tclStubInit.c: `make gentubs` after above changes.

	* doc/Panic.3:
	* unix/mkLinks:  New file documenting Tcl_*Panic* public interfaces,
	  followed by `make mklinks`.  [Patch 415648, Bug 219170, Bug 414936]

1 files changed, 102 insertions, 0 deletions

diff --git a/doc/Panic.3 b/doc/Panic.3
new file mode 100644
index 0000000..c7b0f8c
--- /dev/null
+++ b/doc/Panic.3
@@ -0,0 +1,102 @@
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: Panic.3,v 1.1 2001/06/08 20:06:11 dgp Exp $
+'\" 
+.so man.macros
+.TH Tcl_Panic 3 8.4 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc, panic, panicVA \- 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
+void
+\fBpanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
+.sp
+void
+\fBpanicVA\fR(\fIformat\fR, \fIargList\fR)
+.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 \fBTCL_VARARGS_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\fB 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 builtin 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.
+.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:
+.CS
+typedef void Tcl_PanicProc( CONST char *\fBformat\fR,
+	\fBarg\fR, \fBarg\fR,...);
+.CE
+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.  To maintain consistency with the
+callers of \fBTcl_Panic\fR, \fIpanicProc\fB 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.  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
+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.  The
+procedures \fBpanic\fR and \fBpanicVA\fR are synonyms (implemented as
+macros) for \fBTcl_Panic\fR and \fBTcl_PanicVA\fR, respectively.  They
+exist to support old code; new code should use direct calls to
+\fBTcl_Panic\fR or \fBTcl_PanicVA\fR.
+
+.SH "SEE ALSO"
+abort(3), printf(3), exec(n), format(n)
+
+.SH KEYWORDS
+abort, fatal, error
+