NAME

       Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_Delete­
       ExitHandler, Tcl_ExitThread, Tcl_FinalizeThread,  Tcl_Cre­
       ateThreadExitHandler,  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 appli­
                                             cation   or   thread
                                             exited.  Exact mean­
                                             ing 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 end­
       this  process.  This procedure is invoked by the exit com­
       mand, 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 explic­
       itly 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  opera­
       tions  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  client­
       Data  argument  given to Tcl_CreateExitHandler or Tcl_Cre­
       ateThreadExitHandler when the callback was created.  Typi­
       cally,  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_DeleteThreadEx­
       itHandler does nothing.

       dlers,  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