NAME

       Tcl_Exit,   Tcl_Finalize,  Tcl_CreateExitHandler,  Tcl_DeleteExitHandler,  Tcl_ExitThread,
       Tcl_FinalizeThread,       Tcl_CreateThreadExitHandler,        Tcl_DeleteThreadExitHandler,
       Tcl_SetExitProc - 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)

       Tcl_ExitProc *                                                                             │
       Tcl_SetExitProc(proc)                                                                      │

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,  or
                                             (for  Tcl_SetExitProc) NULL to uninstall the current
                                             application exit procedure.

       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.  If an application exit  handler │
       has  been  installed  (see  Tcl_SetExitProc),  that  handler  is  invoked with an argument │
       consisting of the exit status (cast to ClientData); the application  exit  handler  should │
       not return control to Tcl.

       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.

       Tcl_SetExitProc installs an application exit handler, returning  the  previously-installed │
       application  exit  handler  or  NULL  if  no  application  handler  was  installed.  If an │
       application  exit  handler  is  installed,  that  exit   handler   takes   over   complete │
       responsibility  for  finalization  of  Tcl's subsystems via Tcl_Finalize at an appropriate │
       time.  The argument passed to proc when it is invoked will be the  exit  status  code  (as │
       passed to Tcl_Exit) cast to a ClientData value.

KEYWORDS

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