Tcl_Exit(3)						      Tcl Library Procedures						       Tcl_Exit(3)

__________________________________________________________________________________________________________________________________________________

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-spe-
					     cific.  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 cur-
					     rent 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 nec-
       essary  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_Final-
       izeThread,  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

Tcl									8.5							       Tcl_Exit(3)