| 1 |
578 |
markom |
'\"
|
| 2 |
|
|
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
|
| 3 |
|
|
'\"
|
| 4 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
| 5 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
| 6 |
|
|
'\"
|
| 7 |
|
|
'\" RCS: @(#) $Id: Exit.3,v 1.1.1.1 2002-01-16 10:25:23 markom Exp $
|
| 8 |
|
|
'\"
|
| 9 |
|
|
.so man.macros
|
| 10 |
|
|
.TH Tcl_Exit 3 7.7 Tcl "Tcl Library Procedures"
|
| 11 |
|
|
.BS
|
| 12 |
|
|
.SH NAME
|
| 13 |
|
|
Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the application (and invoke exit handlers)
|
| 14 |
|
|
.SH SYNOPSIS
|
| 15 |
|
|
.nf
|
| 16 |
|
|
\fB#include \fR
|
| 17 |
|
|
.sp
|
| 18 |
|
|
\fBTcl_Exit\fR(\fIstatus\fR)
|
| 19 |
|
|
.sp
|
| 20 |
|
|
\fBTcl_Finalize\fR()
|
| 21 |
|
|
.sp
|
| 22 |
|
|
\fBTcl_CreateExitHandler\fR(\fIproc, clientData\fR)
|
| 23 |
|
|
.sp
|
| 24 |
|
|
\fBTcl_DeleteExitHandler\fR(\fIproc, clientData\fR)
|
| 25 |
|
|
.SH ARGUMENTS
|
| 26 |
|
|
.AS Tcl_ExitProc clientData
|
| 27 |
|
|
.AP int status in
|
| 28 |
|
|
Provides information about why application exited. Exact meaning may
|
| 29 |
|
|
be platform-specific. 0 usually means a normal exit, any nonzero value
|
| 30 |
|
|
usually means that an error occurred.
|
| 31 |
|
|
.AP Tcl_ExitProc *proc in
|
| 32 |
|
|
Procedure to invoke before exiting application.
|
| 33 |
|
|
.AP ClientData clientData in
|
| 34 |
|
|
Arbitrary one-word value to pass to \fIproc\fR.
|
| 35 |
|
|
.BE
|
| 36 |
|
|
|
| 37 |
|
|
.SH DESCRIPTION
|
| 38 |
|
|
.PP
|
| 39 |
|
|
The procedures described here provide a graceful mechanism to end the
|
| 40 |
|
|
execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the
|
| 41 |
|
|
application's state before ending the execution of \fBTcl\fR code.
|
| 42 |
|
|
.PP
|
| 43 |
|
|
Invoke \fBTcl_Exit\fR to end a \fBTcl\fR application and to exit from this
|
| 44 |
|
|
process. This procedure is invoked by the \fBexit\fR command, and can be
|
| 45 |
|
|
invoked anyplace else to terminate the application.
|
| 46 |
|
|
No-one should ever invoke the \fBexit\fR system procedure directly; always
|
| 47 |
|
|
invoke \fBTcl_Exit\fR instead, so that it can invoke exit handlers.
|
| 48 |
|
|
Note that if other code invokes \fBexit\fR system procedure directly, or
|
| 49 |
|
|
otherwise causes the application to terminate without calling
|
| 50 |
|
|
\fBTcl_Exit\fR, the exit handlers will not be run.
|
| 51 |
|
|
\fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
|
| 52 |
|
|
returns control to its caller.
|
| 53 |
|
|
.PP
|
| 54 |
|
|
.VS
|
| 55 |
|
|
\fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
|
| 56 |
|
|
exit from the current process.
|
| 57 |
|
|
It is useful for cleaning up when a process is finished using \fBTcl\fR but
|
| 58 |
|
|
wishes to continue executing, and when \fBTcl\fR is used in a dynamically
|
| 59 |
|
|
loaded extension that is about to be unloaded.
|
| 60 |
|
|
On some systems \fBTcl\fR is automatically notified when it is being
|
| 61 |
|
|
unloaded, and it calls \fBTcl_Finalize\fR internally; on these systems it
|
| 62 |
|
|
not necessary for the caller to explicitly call \fBTcl_Finalize\fR.
|
| 63 |
|
|
However, to ensure portability, your code should always invoke
|
| 64 |
|
|
\fBTcl_Finalize\fR when \fBTcl\fR is being unloaded, to ensure that the
|
| 65 |
|
|
code will work on all platforms. \fBTcl_Finalize\fR can be safely called
|
| 66 |
|
|
more than once.
|
| 67 |
|
|
.VE
|
| 68 |
|
|
.PP
|
| 69 |
|
|
\fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
|
| 70 |
|
|
by \fBTcl_Finalize\fR and \fBTcl_Exit\fR.
|
| 71 |
|
|
This provides a hook for cleanup operations such as flushing buffers
|
| 72 |
|
|
and freeing global memory.
|
| 73 |
|
|
\fIProc\fR should match the type \fBTcl_ExitProc\fR:
|
| 74 |
|
|
.CS
|
| 75 |
|
|
typedef void Tcl_ExitProc(ClientData \fIclientData\fR);
|
| 76 |
|
|
.CE
|
| 77 |
|
|
The \fIclientData\fR parameter to \fIproc\fR is a
|
| 78 |
|
|
copy of the \fIclientData\fR argument given to
|
| 79 |
|
|
\fBTcl_CreateExitHandler\fR when the callback
|
| 80 |
|
|
was created. Typically, \fIclientData\fR points to a data
|
| 81 |
|
|
structure containing application-specific information about
|
| 82 |
|
|
what to do in \fIproc\fR.
|
| 83 |
|
|
.PP
|
| 84 |
|
|
\fBTcl_DeleteExitHandler\fR may be called to delete a
|
| 85 |
|
|
previously-created exit handler. It removes the handler
|
| 86 |
|
|
indicated by \fIproc\fR and \fIclientData\fR so that no call
|
| 87 |
|
|
to \fIproc\fR will be made. If no such handler exists then
|
| 88 |
|
|
\fBTcl_DeleteExitHandler\fR does nothing.
|
| 89 |
|
|
.PP
|
| 90 |
|
|
.VS
|
| 91 |
|
|
.PP
|
| 92 |
|
|
\fBTcl_Finalize\fR and \fBTcl_Exit\fR execute all registered exit handlers,
|
| 93 |
|
|
in reverse order from the order in which they were registered.
|
| 94 |
|
|
This matches the natural order in which extensions are loaded and unloaded;
|
| 95 |
|
|
if extension \fBA\fR loads extension \fBB\fR, it usually
|
| 96 |
|
|
unloads \fBB\fR before it itself is unloaded.
|
| 97 |
|
|
If extension \fBA\fR registers its exit handlers before loading extension
|
| 98 |
|
|
\fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
|
| 99 |
|
|
before the exit handlers for \fBA\fR.
|
| 100 |
|
|
.VE
|
| 101 |
|
|
|
| 102 |
|
|
.SH KEYWORDS
|
| 103 |
|
|
callback, cleanup, dynamic loading, end application, exit, unloading
|
