Tcl_Exit(3)

NAME
Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler - end the application (and invoke exit handlers)

SYNOPSIS
#include <tcl.h>

Tcl_Exit(status)

Tcl_Finalize()

Tcl_CreateExitHandler(proc, clientData)

Tcl_DeleteExitHandler(proc, clientData)

ARGUMENTS
Provides information about why application exited. Exact meaning may be platform-specific. 0 usually means a normal exit, any nonzero value usually means that an error occurred. Procedure to invoke before exiting application. 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.

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_CreateExitHandler arranges for proc to be invoked by Tcl_Finalize and Tcl_Exit. 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 when the callback was created. Typically, clientData points to a data structure containing application-specific information about what to do in proc.

Tcl_DeleteExitHandler 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 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.

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