util/src/TclTk/tcl8.6.12/doc/Exit.3

   1 '\"
   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 .TH Tcl_Exit 3 8.5 Tcl "Tcl Library Procedures"
   8 .so man.macros
   9 .BS
  10 .SH NAME
  11 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)
  12 .SH SYNOPSIS
  13 .nf
  14 \fB#include <tcl.h>\fR
  15 .sp
  16 \fBTcl_Exit\fR(\fIstatus\fR)
  17 .sp
  18 \fBTcl_Finalize\fR()
  19 .sp
  20 \fBTcl_CreateExitHandler\fR(\fIproc, clientData\fR)
  21 .sp
  22 \fBTcl_DeleteExitHandler\fR(\fIproc, clientData\fR)
  23 .sp
  24 \fBTcl_ExitThread\fR(\fIstatus\fR)
  25 .sp
  26 \fBTcl_FinalizeThread\fR()
  27 .sp
  28 \fBTcl_CreateThreadExitHandler\fR(\fIproc, clientData\fR)
  29 .sp
  30 \fBTcl_DeleteThreadExitHandler\fR(\fIproc, clientData\fR)
  31 .sp
  32 Tcl_ExitProc *
  33 \fBTcl_SetExitProc\fR(\fIproc\fR)
  34 .SH ARGUMENTS
  35 .AS Tcl_ExitProc clientData
  36 .AP int status  in
  37 Provides information about why the application or thread exited.
  38 Exact meaning may
  39 be platform-specific.  0 usually means a normal exit, any nonzero value
  40 usually means that an error occurred.
  41 .AP Tcl_ExitProc *proc in
  42 Procedure to invoke before exiting application, or (for
  43 \fBTcl_SetExitProc\fR) NULL to uninstall the current application exit
  44 procedure.
  45 .AP ClientData clientData in
  46 Arbitrary one-word value to pass to \fIproc\fR.
  47 .BE
  48
  49 .SH DESCRIPTION
  50 .PP
  51 The procedures described here provide a graceful mechanism to end the
  52 execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the
  53 application's state before ending the execution of \fBTcl\fR code.
  54 .PP
  55 Invoke \fBTcl_Exit\fR to end a \fBTcl\fR application and to exit from this
  56 process. This procedure is invoked by the \fBexit\fR command, and can be
  57 invoked anyplace else to terminate the application.
  58 No-one should ever invoke the \fBexit\fR system procedure directly;  always
  59 invoke \fBTcl_Exit\fR instead, so that it can invoke exit handlers.
  60 Note that if other code invokes \fBexit\fR system procedure directly, or
  61 otherwise causes the application to terminate without calling
  62 \fBTcl_Exit\fR, the exit handlers will not be run.
  63 \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
  64 returns control to its caller.
  65 If an application exit handler has been installed (see
  66 \fBTcl_SetExitProc\fR), that handler is invoked with an argument
  67 consisting of the exit status (cast to ClientData); the application
  68 exit handler should not return control to Tcl.
  69 .PP
  70 \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
  71 exit from the current process.
  72 It is useful for cleaning up when a process is finished using \fBTcl\fR but
  73 wishes to continue executing, and when \fBTcl\fR is used in a dynamically
  74 loaded extension that is about to be unloaded.
  75 Your code should always invoke \fBTcl_Finalize\fR when \fBTcl\fR is being
  76 unloaded, to ensure proper cleanup. \fBTcl_Finalize\fR can be safely called
  77 more than once.
  78 .PP
  79 \fBTcl_ExitThread\fR is used to terminate the current thread and invoke
  80 per-thread exit handlers.  This finalization is done by
  81 \fBTcl_FinalizeThread\fR, which you can call if you just want to clean
  82 up per-thread state and invoke the thread exit handlers.
  83 \fBTcl_Finalize\fR calls \fBTcl_FinalizeThread\fR for the current
  84 thread automatically.
  85 .PP
  86 \fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
  87 by \fBTcl_Finalize\fR and \fBTcl_Exit\fR.
  88 \fBTcl_CreateThreadExitHandler\fR arranges for \fIproc\fR to be invoked
  89 by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR.
  90 This provides a hook for cleanup operations such as flushing buffers
  91 and freeing global memory.
  92 \fIProc\fR should match the type \fBTcl_ExitProc\fR:
  93 .PP
  94 .CS
  95 typedef void \fBTcl_ExitProc\fR(
  96         ClientData \fIclientData\fR);
  97 .CE
  98 .PP
  99 The \fIclientData\fR parameter to \fIproc\fR is a
 100 copy of the \fIclientData\fR argument given to
 101 \fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\fR when
 102 the callback
 103 was created.  Typically, \fIclientData\fR points to a data
 104 structure containing application-specific information about
 105 what to do in \fIproc\fR.
 106 .PP
 107 \fBTcl_DeleteExitHandler\fR and \fBTcl_DeleteThreadExitHandler\fR may be
 108 called to delete a
 109 previously-created exit handler.  It removes the handler
 110 indicated by \fIproc\fR and \fIclientData\fR so that no call
 111 to \fIproc\fR will be made.  If no such handler exists then
 112 \fBTcl_DeleteExitHandler\fR or \fBTcl_DeleteThreadExitHandler\fR does nothing.
 113 .PP
 114 \fBTcl_Finalize\fR and \fBTcl_Exit\fR execute all registered exit handlers,
 115 in reverse order from the order in which they were registered.
 116 This matches the natural order in which extensions are loaded and unloaded;
 117 if extension \fBA\fR loads extension \fBB\fR, it usually
 118 unloads \fBB\fR before it itself is unloaded.
 119 If extension \fBA\fR registers its exit handlers before loading extension
 120 \fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
 121 before the exit handlers for \fBA\fR.
 122 .PP
 123 \fBTcl_Finalize\fR and \fBTcl_Exit\fR call \fBTcl_FinalizeThread\fR
 124 and the thread exit handlers \fIafter\fR
 125 the process-wide exit handlers.  This is because thread finalization shuts
 126 down the I/O channel system, so any attempt at I/O by the global exit
 127 handlers will vanish into the bitbucket.
 128 .PP
 129 \fBTcl_SetExitProc\fR installs an application exit handler, returning
 130 the previously-installed application exit handler or NULL if no
 131 application handler was installed.  If an application exit handler is
 132 installed, that exit handler takes over complete responsibility for
 133 finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an
 134 appropriate time.  The argument passed to \fIproc\fR when it is
 135 invoked will be the exit status code (as passed to \fBTcl_Exit\fR)
 136 cast to a ClientData value.
 137 .SH "SEE ALSO"
 138 exit(n)
 139 .SH KEYWORDS
 140 abort, callback, cleanup, dynamic loading, end application, exit, unloading, thread