NAME

       Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitThread, Tcl_FinalizeThread,
       Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler - end the application or thread (and invoke exit
       handlers)

SYNOPSIS

       #include <tcl.h>

       Tcl_Exit(status)

       Tcl_Finalize()

       Tcl_CreateExitHandler(proc, clientData)

       Tcl_DeleteExitHandler(proc, clientData)

       Tcl_ExitThread(status)

       Tcl_FinalizeThread()

       Tcl_CreateThreadExitHandler(proc, clientData)

       Tcl_DeleteThreadExitHandler(proc, clientData)

ARGUMENTS

       int            status       (in)      Provides  information  about  why the application or thread exited.
                                             Exact meaning may be platform-specific.  0 usually means  a  normal
                                             exit, any nonzero value usually means that an error occurred.

       Tcl_ExitProc   *proc        (in)      Procedure to invoke before exiting application.

       ClientData     clientData   (in)      Arbitrary one-word value to pass to proc.
_________________________________________________________________

DESCRIPTION

       The  procedures  described  here  provide a graceful mechanism to end the execution of a Tcl application.
       Exit handlers are invoked to cleanup the application's state before ending the execution of Tcl code.

       Invoke Tcl_Exit to end a Tcl application and to exit from this process. This procedure is invoked by  the
       exit  command,  and can be invoked anyplace else to terminate the application.  No-one should ever invoke
       the exit system procedure directly;  always invoke Tcl_Exit instead, so that it can invoke exit handlers.
       Note  that  if  other code invokes exit system procedure directly, or otherwise causes the application to
       terminate without calling Tcl_Exit, the exit handlers will not be run.  Tcl_Exit internally  invokes  the
       exit system call, thus it never returns control to its caller.

       Tcl_Finalize  is similar to Tcl_Exit except that it does not exit from the current process.  It is useful
       for cleaning up when a process is finished using Tcl but wishes to continue executing, and  when  Tcl  is
       used  in  a  dynamically  loaded  extension  that  is  about  to  be  unloaded.   On  some systems Tcl is
       automatically notified when it is being unloaded, and it calls Tcl_Finalize internally; on these  systems
       it  not  necessary  for the caller to explicitly call Tcl_Finalize.  However, to ensure portability, your
       code should always invoke Tcl_Finalize when Tcl is being unloaded, to ensure that the code will  work  on
       all platforms. Tcl_Finalize can be safely called more than once.

       Tcl_ExitThread  is  used  to  terminate  the  current  thread  and invoke per-thread exit handlers.  This │
       finalization is done by Tcl_FinalizeThread, which you can call if you just want to  clean  up  per-thread │
       state  and invoke the thread exit handlers.  Tcl_Finalize calls Tcl_FinalizeThread for the current thread │
       automatically.

       Tcl_CreateExitHandler   arranges   for   proc   to   be   invoked   by   Tcl_Finalize    and    Tcl_Exit.
       Tcl_CreateThreadExitHandler  arranges  for  proc  to be invoked by Tcl_FinalizeThread and Tcl_ExitThread.
       This provides a hook for cleanup operations such as flushing buffers and  freeing  global  memory.   Proc
       should match the type Tcl_ExitProc:
              typedef void Tcl_ExitProc(ClientData clientData);
       The  clientData  parameter to proc is a copy of the clientData argument given to Tcl_CreateExitHandler or
       Tcl_CreateThreadExitHandler when the callback was  created.   Typically,  clientData  points  to  a  data
       structure containing application-specific information about what to do in proc.

       Tcl_DeleteExitHandler  and  Tcl_DeleteThreadExitHandler may be called to delete a previously-created exit
       handler.  It removes the handler indicated by proc and clientData so that no call to proc will  be  made.
       If no such handler exists then Tcl_DeleteExitHandler or Tcl_DeleteThreadExitHandler does nothing.

       Tcl_Finalize  and Tcl_Exit execute all registered exit handlers, in reverse order from the order in which │
       they were registered.  This matches the natural order in which extensions are  loaded  and  unloaded;  if │
       extension  A  loads  extension  B,  it  usually  unloads  B before it itself is unloaded.  If extension A │
       registers its exit handlers before loading extension B, this ensures that any exit handlers for B will be │
       executed before the exit handlers for A.                                                                  │

       Tcl_Finalize  and  Tcl_Exit  call  Tcl_FinalizeThread and the thread exit handlers after the process-wide │
       exit handlers.  This is because thread finalization shuts down the I/O channel system, so any attempt  at │
       I/O by the global exit handlers will vanish into the bitbucket.

KEYWORDS

       callback, cleanup, dynamic loading, end application, exit, unloading, thread