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 normal exit, any
nonzero value usually means
that an error occurred.

Tcl_ExitProc *proc (in) Procedure to invoke before
exiting application, or (for
Tcl_SetExitProc) NULL to
uninstall 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 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. If an
application exit handler has been installed (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
invoked by Tcl_FinalizeThread and Tcl_ExitThread. 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 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
indicated by proc and clientData so that no call to proc will be
made. If no such handler exists then Tcl_DeleteExitHandler or
Tcl_DeleteThreadExitHandler 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 argument 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(n)

KEYWORDS

abort, callback, cleanup, dynamic loading, end application, exit,
unloading, thread

Tcl 8.5 Tcl_Exit(3)