diff options
Diffstat (limited to 'doc/Exit.3')
| -rw-r--r-- | doc/Exit.3 | 25 |
1 files changed, 16 insertions, 9 deletions
@@ -29,8 +29,10 @@ Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitTh .sp \fBTcl_DeleteThreadExitHandler\fR(\fIproc, clientData\fR) .sp +.VS 8.5 Tcl_ExitProc * \fBTcl_SetExitProc\fR(\fIproc\fR) +.VE 8.5 .SH ARGUMENTS .AS Tcl_ExitProc clientData .AP int status in @@ -62,18 +64,24 @@ otherwise causes the application to terminate without calling \fBTcl_Exit\fR, the exit handlers will not be run. \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never returns control to its caller. +.VS 8.5 If an application exit handler has been installed (see \fBTcl_SetExitProc\fR), 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. +.VE 8.5 .PP \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not exit from the current process. It is useful for cleaning up when a process is finished using \fBTcl\fR but wishes to continue executing, and when \fBTcl\fR is used in a dynamically loaded extension that is about to be unloaded. -Your code should always invoke \fBTcl_Finalize\fR when \fBTcl\fR is being -unloaded, to ensure proper cleanup. \fBTcl_Finalize\fR can be safely called +On some systems \fBTcl\fR is automatically notified when it is being +unloaded, and it calls \fBTcl_Finalize\fR internally; on these systems it +not necessary for the caller to explicitly call \fBTcl_Finalize\fR. +However, to ensure portability, your code should always invoke +\fBTcl_Finalize\fR when \fBTcl\fR is being unloaded, to ensure that the +code will work on all platforms. \fBTcl_Finalize\fR can be safely called more than once. .PP \fBTcl_ExitThread\fR is used to terminate the current thread and invoke @@ -90,12 +98,9 @@ by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR. This provides a hook for cleanup operations such as flushing buffers and freeing global memory. \fIProc\fR should match the type \fBTcl_ExitProc\fR: -.PP .CS -typedef void \fBTcl_ExitProc\fR( - ClientData \fIclientData\fR); +typedef void Tcl_ExitProc(ClientData \fIclientData\fR); .CE -.PP The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR argument given to \fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\fR when @@ -111,6 +116,7 @@ indicated by \fIproc\fR and \fIclientData\fR so that no call to \fIproc\fR will be made. If no such handler exists then \fBTcl_DeleteExitHandler\fR or \fBTcl_DeleteThreadExitHandler\fR does nothing. .PP +.PP \fBTcl_Finalize\fR and \fBTcl_Exit\fR 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; @@ -126,6 +132,7 @@ 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. .PP +.VS 8.5 \fBTcl_SetExitProc\fR 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 @@ -134,7 +141,7 @@ finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an appropriate time. The argument passed to \fIproc\fR when it is invoked will be the exit status code (as passed to \fBTcl_Exit\fR) cast to a ClientData value. -.SH "SEE ALSO" -exit(n) +.VE 8.5 + .SH KEYWORDS -abort, callback, cleanup, dynamic loading, end application, exit, unloading, thread +callback, cleanup, dynamic loading, end application, exit, unloading, thread |