trusty (3) panic.3tcl.gz

NAME

       Tcl_Panic, Tcl_PanicVA, Tcl_SetPanicProc, panic, panicVA - report fatal error and abort

SYNOPSIS

       #include <tcl.h>

       void
       Tcl_Panic(format, arg, arg, ...)

       void
       Tcl_PanicVA(format, argList)

       void
       Tcl_SetPanicProc(panicProc)

       void
       panic(format, arg, arg, ...)

       void
       panicVA(format, argList)

ARGUMENTS

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

                       arg          (in)      Arguments matching the format string.

       va_list         argList      (in)      An  argument  list  of arguments matching the format string.  Must
                                              have been initialized using TCL_VARARGS_START, and  cleared  using
                                              va_end.

       Tcl_PanicProc   *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  Tcl_Panic  to
       display  a  message  describing  the error and abort the process.  The format 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 printf family of functions.  The same formatting rules are also used by the
       builtin Tcl command format.

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

       Tcl_SetPanicProc  may  be  used to modify the behavior of Tcl_Panic.  The panicProc argument should match
       the type Tcl_PanicProc:

              typedef void Tcl_PanicProc(
                CONST char *format,
                arg, arg,...);

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

       The typical use of Tcl_SetPanicProc 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
       wish calls Tcl_SetPanicProc 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 Tcl_Panic are the procedures of the Tcl library, Tcl_Panic 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.

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

SEE ALSO

       abort(3), printf(3), exec(3tcl), format(3tcl)

KEYWORDS

       abort, fatal, error