FreeBSD Manual Pages
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 appli- cation 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 exe- cution of a Tcl application. Exit handlers are invoked to cleanup the ap- plication'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 sys- tem procedure directly; always invoke Tcl_Exit instead, so that it can in- voke 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 dy- namically 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 nat- ural 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 han- dlers for A. Tcl_Finalize and Tcl_Exit call Tcl_FinalizeThread and the thread exit han- dlers after the process-wide exit handlers. This is because thread final- ization 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 previ- ously-installed application exit handler or NULL if no application handler was installed. If an application exit handler is installed, that exit han- dler takes over complete responsibility for finalization of Tcl's subsys- tems 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, unload- ing, thread Tcl 8.5 Tcl_Exit(3)
NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_FinalizeThread.tcl86&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>