TclPanic(3) Tcl Library Procedures TclPanic(3)

NAME
       TclPanic, TclPanicVA, TclSetPanicProc, panic, panicVA - report fatal
       error and abort

SYNOPSIS
       ##iinncclluuddee <>

       void
       TTccllPPaanniicc(format, arg, arg, ...)

       void
       TTccllPPaanniiccVVAA(format, argList)

       void
       TTccllSSeettPPaanniiccPPrroocc(panicProc)

       void
       ppaanniicc(format, arg, arg, ...)

       void
       ppaanniiccVVAA(format, argList)


AARRGGUUMMEENNTTSS
       CONST char*     format       (in)      A printf-style format string.

                       arg          (in)      Arguments  matching  the  format
                                              string.

       valist         argList      (in)      An  argument  list  of arguments
                                              matching  the   format   string.
                                              Must have been initialized using
                                              TTCCLLVVAARRAARRGGSSSSTTAARRTT,  and  cleared
                                              using vvaaeenndd.

       TclPanicProc   *panicProc   (in)      Procedure  to report fatal error
                                              message and abort.




DESCRIPTION
       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  TTccllPPaanniicc  to
       display a message describing the error and abort the process.  The for-
       mat argument is a format string describing how to format the  remaining
       arguments  arg  into an error message, according to the same formatting
       rules used by the pprriinnttff family  of  functions.   The  same  formatting
       rules are also used by the builtin Tcl command ffoorrmmaatt.

       In  a  freshly loaded Tcl library, TTccllPPaanniicc prints the formatted error
       message to the standard error file of the process, and then calls aabboorrtt
       to terminate the process.  TTccllPPaanniicc does not return.

       TTccllSSeettPPaanniiccPPrroocc  may be used to modify the behavior of TTccllPPaanniicc.  The
       panicProc argument should match the type TTccllPPaanniiccPPrroocc:

              typedef void TclPanicProc(
                CONST char *ffoorrmmaatt,
                aarrgg, aarrgg,...);

       After TTccllSSeettPPaanniiccPPrroocc returns, any future calls to TTccllPPaanniicc will call
       panicProc,  passing  along  the  format and arg arguments.  To maintain
       consistency with the callers of TTccllPPaanniicc, panicProc must  not  return;
       it  must  call aabboorrtt.  panicProc should avoid making calls into the Tcl
       library, or into other libraries that may call the Tcl  library,  since
       the  original  call  to TTccllPPaanniicc indicates the Tcl library is not in a
       state of reliable operation.

       The typical use of TTccllSSeettPPaanniiccPPrroocc 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  wwiisshh
       calls TTccllSSeettPPaanniiccPPrroocc 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).

       Although the primary callers of TTccllPPaanniicc are the procedures of the Tcl
       library, TTccllPPaanniicc is a public function and may be called by any exten-
       sion  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.

       TTccllPPaanniiccVVAA  is  the  same as TTccllPPaanniicc except that instead of taking a
       variable number of arguments it takes an argument list.  The procedures
       ppaanniicc  and  ppaanniiccVVAA  are synonyms (implemented as macros) for TTccllPPaanniicc
       and TTccllPPaanniiccVVAA, respectively.  They exist to  support  old  code;  new
       code should use direct calls to TTccllPPaanniicc or TTccllPPaanniiccVVAA.


SEE ALSO
       abort(3), printf(3), exec(n), format(n)


KKEEYYWWOORRDDSS
       abort, fatal, error




Tcl                                   8.4                         TclPanic(3)