Tcl_Exit(3) Tcl Library Procedures 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
int status (in) Provides information about why
application 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 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_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. Typi‐
cally, 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
Tcl 7.7 Tcl_Exit(3)