Tcl_Exit(3tcl) Tcl Library Procedures Tcl_Exit(3tcl)
______________________________________________________________________________
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 oc-
curred.
Tcl_ExitProc *proc (in) Procedure to invoke before exit-
ing application, or (for Tcl_Se-
tExitProc) NULL to uninstall the
current application exit proce-
dure.
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 in-
stalled (see Tcl_SetExitProc), that handler is invoked with an argument
consisting of the exit status (cast to ClientData); the application
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.
Your code should always invoke Tcl_Finalize when Tcl is being unloaded,
to ensure proper cleanup. 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 in-
voked 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 re-
verse order from the order in which they were registered. This matches
the natural order in which extensions are loaded and unloaded; if ex-
tension 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.
SEE ALSO
exit(3tcl)
KEYWORDS
abort, callback, cleanup, dynamic loading, end application, exit, un-
loading, thread
Tcl 8.5 Tcl_Exit(3tcl)
Generated by dwww version 1.14 on Mon Oct 28 11:26:35 CET 2024.