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.  Your code should always invoke Tcl_Finalize when  Tcl  is  being  unloaded,  to
       ensure proper cleanup. 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.

SEE ALSO

       exit(3tcl)

KEYWORDS

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