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 - end the application or thread (and invoke exit(3,n,1 builtins) handlers) SYNOPSIS #include <tcl.h> Tcl_Exit(status) Tcl_Finalize() Tcl_CreateExitHandler(proc(5,n), clientData) Tcl_DeleteExitHandler(proc(5,n), clientData) Tcl_ExitThread(status) Tcl_FinalizeThread() Tcl_CreateThreadExitHandler(proc(5,n), clientData) Tcl_DeleteThreadExitHandler(proc(5,n), clientData) ARGUMENTS int status (in(1,8)) Provides information about why the application or thread exited. Exact meaning may be platform- specific. 0 usually means a nor- mal exit(3,n,1 builtins), any nonzero value usu- ally means that an error(8,n) occurred. Tcl_ExitProc *proc(5,n) (in(1,8)) Procedure to invoke before exit- ing application. ClientData clientData (in(1,8)) Arbitrary one-word value to pass to proc(5,n). _________________________________________________________________ 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(3,n,1 builtins) from this process. This procedure is invoked by the exit(3,n,1 builtins) command, and can be invoked any- place else to terminate the application. No-one should ever invoke the exit(3,n,1 builtins) system procedure directly; always invoke Tcl_Exit instead, so that it can invoke exit(3,n,1 builtins) handlers. Note that if(3,n) other code invokes exit(3,n,1 builtins) system procedure directly, or otherwise causes the application to ter- minate without calling Tcl_Exit, the exit(3,n,1 builtins) handlers will not be run. Tcl_Exit internally invokes the exit(3,n,1 builtins) system call, thus it never returns control to its caller. Tcl_Finalize is similar to Tcl_Exit except that it does not exit(3,n,1 builtins) 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(1,8) 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(3,n,1 builtins) handlers. This finalization is done by Tcl_FinalizeThread, | which you can call if(3,n) you just want to clean up per-thread state and | invoke the thread exit(3,n,1 builtins) handlers. Tcl_Finalize calls Tcl_FinalizeThread | for the current thread automatically. Tcl_CreateExitHandler arranges for proc(5,n) to be invoked by Tcl_Finalize and Tcl_Exit. Tcl_CreateThreadExitHandler arranges for proc(5,n) 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(5,n) 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(1,8) proc(5,n). Tcl_DeleteExitHandler and Tcl_DeleteThreadExitHandler may be called to delete a previously-created exit(3,n,1 builtins) handler. It removes the handler indi- cated by proc(5,n) and clientData so that no call to proc(5,n) 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(3,n,1 builtins) handlers, in(1,8) | reverse order from the order in(1,8) which they were registered. This | matches the natural order in(1,8) which extensions are loaded and unloaded; | if(3,n) extension A loads extension B, it usually unloads B before it itself | is unloaded. If extension A registers its exit(3,n,1 builtins) handlers before loading | extension B, this ensures that any exit(3,n,1 builtins) handlers for B will be executed | before the exit(3,n,1 builtins) handlers for A. | Tcl_Finalize and Tcl_Exit call Tcl_FinalizeThread and the thread exit(3,n,1 builtins) | handlers after the process-wide exit(3,n,1 builtins) handlers. This is because thread | finalization shuts down the I/O channel system, so any attempt at I/O | by the global exit(3,n,1 builtins) handlers will vanish into the bitbucket. KEYWORDS callback, cleanup, dynamic loading, end application, exit(3,n,1 builtins), unloading, thread Tcl 8.1 Tcl_Exit(3)