Tcl_Exit(3)
_________________________________________________________________
NAME
Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_Delete-
ExitHandler - end the application (and invoke exit han-
dlers)
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 applica-
tion exited. Exact
meaning may be plat-
form-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 exiting
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 end-
ing 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 com-
mand, 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 explic- |
itly 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 client-
Data 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 previ-
ously-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_DeleteEx-
itHandler does nothing.
Tcl_Finalize and Tcl_Exit execute all registered exit han- |
dlers, 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