diff options
Diffstat (limited to 'doc/Exit.3')
| -rw-r--r-- | doc/Exit.3 | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/doc/Exit.3 b/doc/Exit.3 new file mode 100644 index 0000000..1d3e26d --- /dev/null +++ b/doc/Exit.3 @@ -0,0 +1,103 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) Exit.3 1.8 96/12/10 07:37:23 +'\" +.so man.macros +.TH Tcl_Exit 3 7.7 Tcl "Tcl Library Procedures" +.BS +.SH NAME +Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the application (and invoke exit handlers) +.SH SYNOPSIS +.nf +\fB#include <tcl.h>\fR +.sp +\fBTcl_Exit\fR(\fIstatus\fR) +.sp +\fBTcl_Finalize\fR() +.sp +\fBTcl_CreateExitHandler\fR(\fIproc, clientData\fR) +.sp +\fBTcl_DeleteExitHandler\fR(\fIproc, clientData\fR) +.SH ARGUMENTS +.AS Tcl_ExitProc clientData +.AP int status in +Provides information about why application exited. Exact meaning may +be platform-specific. 0 usually means a normal exit, any nonzero value +usually means that an error occurred. +.AP Tcl_ExitProc *proc in +Procedure to invoke before exiting application. +.AP ClientData clientData in +Arbitrary one-word value to pass to \fIproc\fR. +.BE + +.SH DESCRIPTION +.PP +The procedures described here provide a graceful mechanism to end the +execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the +application's state before ending the execution of \fBTcl\fR code. +.PP +Invoke \fBTcl_Exit\fR to end a \fBTcl\fR application and to exit from this +process. This procedure is invoked by the \fBexit\fR command, and can be +invoked anyplace else to terminate the application. +No-one should ever invoke the \fBexit\fR system procedure directly; always +invoke \fBTcl_Exit\fR instead, so that it can invoke exit handlers. +Note that if other code invokes \fBexit\fR system procedure directly, or +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. +.PP +.VS +\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. +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. +.VE +.PP +\fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked +by \fBTcl_Finalize\fR and \fBTcl_Exit\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: +.CS +typedef void Tcl_ExitProc(ClientData \fIclientData\fR); +.CE +The \fIclientData\fR parameter to \fIproc\fR is a +copy of the \fIclientData\fR argument given to +\fBTcl_CreateExitHandler\fR when the callback +was created. Typically, \fIclientData\fR points to a data +structure containing application-specific information about +what to do in \fIproc\fR. +.PP +\fBTcl_DeleteExitHandler\fR may be called to delete a +previously-created exit handler. It removes the handler +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 does nothing. +.PP +.VS +.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; +if extension \fBA\fR loads extension \fBB\fR, it usually +unloads \fBB\fR before it itself is unloaded. +If extension \fBA\fR registers its exit handlers before loading extension +\fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed +before the exit handlers for \fBA\fR. +.VE + +.SH KEYWORDS +callback, cleanup, dynamic loading, end application, exit, unloading |