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, Tcl_SetExitProc - end the application or
thread (and invoke exit handlers)
SYNOPSIS
#include <tcl.h>
Tcl_Exit(status)Tcl_Finalize()
Tcl_CreateExitHandler(proc, clientData)
Tcl_DeleteExitHandler(proc, clientData)
Tcl_ExitThread(status)Tcl_FinalizeThread()
Tcl_CreateThreadExitHandler(proc, clientData)
Tcl_DeleteThreadExitHandler(proc, clientData)
Tcl_ExitProc * │
Tcl_SetExitProc(proc) │
ARGUMENTS
int status (in) Provides information about why
the application or thread exited.
Exact meaning may be platform-
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 exit‐
ing application, or (for
Tcl_SetExitProc) NULL to unin‐
stall the current application
exit procedure.
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. If an application exit handler has been │
installed (see Tcl_SetExitProc), that handler is invoked with an argu‐ │
ment consisting of the exit status (cast to ClientData); the applica‐ │
tion exit handler should not return control to Tcl.
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_ExitThread is used to terminate the current thread and invoke per-
thread exit handlers. This finalization is done by Tcl_FinalizeThread,
which you can call if you just want to clean up per-thread state and
invoke the thread exit handlers. Tcl_Finalize calls Tcl_FinalizeThread
for the current thread automatically.
Tcl_CreateExitHandler arranges for proc to be invoked by Tcl_Finalize
and Tcl_Exit. Tcl_CreateThreadExitHandler arranges for proc 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 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 proc.
Tcl_DeleteExitHandler and Tcl_DeleteThreadExitHandler may be called to
delete a previously-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_DeleteExitHandler or Tcl_DeleteThread‐
ExitHandler 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.
Tcl_Finalize and Tcl_Exit call Tcl_FinalizeThread and the thread exit
handlers after the process-wide exit handlers. This is because thread
finalization shuts down the I/O channel system, so any attempt at I/O
by the global exit handlers will vanish into the bitbucket.
Tcl_SetExitProc installs an application exit handler, returning the │
previously-installed application exit handler or NULL if no application │
handler was installed. If an application exit handler is installed, │
that exit handler takes over complete responsibility for finalization │
of Tcl's subsystems via Tcl_Finalize at an appropriate time. The argu‐ │
ment passed to proc when it is invoked will be the exit status code (as │
passed to Tcl_Exit) cast to a ClientData value.
KEYWORDS
callback, cleanup, dynamic loading, end application, exit, unloading,
thread
Tcl 8.5 Tcl_Exit(3)