Tcl_Exit(3) Tcl (7.7) 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 meaning
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 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 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
Page 1 (printed 2/19/99)
Tcl_Exit(3) Tcl (7.7) Tcl_Exit(3)
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
Page 2 (printed 2/19/99)
