Tcl_CreateExitHandler(3tcl)

______________________________________________________________________________

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 nor-
                                             mal exit, any nonzero value  usu-
                                             ally    means   that   an   error
                                             occurred.

       Tcl_ExitProc   *proc        (in)      Procedure to invoke before  exit-
                                             ing 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 any-
       place 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 ter-
       minate 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  plat-
       forms. 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 mem-
       ory.  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 indi-
       cated by proc and clientData so that no call to proc will be made.   If
       no  such handler exists then Tcl_DeleteExitHandler or Tcl_DeleteThread-
       ExitHandler 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

Tcl                                   8.1                          Tcl_Exit(3)