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 *                                                                                            2
       Tcl_SetExitProc(proc)                                                                                     2

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 2
       installed  (see  Tcl_SetExitProc), that handler is invoked with an argument consisting of the exit status 2
       (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 2
       handler  or  NULL  if no application handler was installed.  If an application exit handler is installed, 2
       that  exit  handler  takes  over  complete  responsibility  for  finalization  of  Tcl's  subsystems  via 2
       Tcl_Finalize  at  an  appropriate  time.  The argument passed to proc when it is invoked will be the exit 2
       status code (as passed to Tcl_Exit) cast to a ClientData value.

KEYWORDS

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

Tcl                                                    8.5                                        Tcl_Exit(3tcl)