1Tcl_Exit(3) Tcl Library Procedures Tcl_Exit(3)
2______________________________________________________________________________
6
8 Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler,
9 Tcl_ExitThread, Tcl_FinalizeThread, Tcl_CreateThreadExitHandler,
10 Tcl_DeleteThreadExitHandler - end the application or thread (and invoke
11 exit handlers)
12
14 #include <tcl.h>
15 Tcl_Exit(status)
17 Tcl_Finalize()
19 Tcl_CreateExitHandler(proc, clientData)
21 Tcl_DeleteExitHandler(proc, clientData)
23 Tcl_ExitThread(status)
25 Tcl_FinalizeThread()
27 Tcl_CreateThreadExitHandler(proc, clientData)
29 Tcl_DeleteThreadExitHandler(proc, clientData)
31
33 int status (in) Provides information about why
34 the application or thread exited.
35 Exact meaning may be platform-
36 specific. 0 usually means a nor‐
37 mal exit, any nonzero value usu‐
38 ally means that an error
39 occurred.
40 Tcl_ExitProc *proc (in) Procedure to invoke before exit‐
42 ing application.
43 ClientData clientData (in) Arbitrary one-word value to pass
45 to proc.
46_________________________________________________________________
47
50 The procedures described here provide a graceful mechanism to end the
51 execution of a Tcl application. Exit handlers are invoked to cleanup
52 the application's state before ending the execution of Tcl code.
53 Invoke Tcl_Exit to end a Tcl application and to exit from this process.
55 This procedure is invoked by the exit command, and can be invoked any‐
56 place else to terminate the application. No-one should ever invoke the
57 exit system procedure directly; always invoke Tcl_Exit instead, so
58 that it can invoke exit handlers. Note that if other code invokes exit
59 system procedure directly, or otherwise causes the application to ter‐
60 minate without calling Tcl_Exit, the exit handlers will not be run.
61 Tcl_Exit internally invokes the exit system call, thus it never returns
62 control to its caller.
63 Tcl_Finalize is similar to Tcl_Exit except that it does not exit from
65 the current process. It is useful for cleaning up when a process is
66 finished using Tcl but wishes to continue executing, and when Tcl is
67 used in a dynamically loaded extension that is about to be unloaded.
68 On some systems Tcl is automatically notified when it is being
69 unloaded, and it calls Tcl_Finalize internally; on these systems it not
70 necessary for the caller to explicitly call Tcl_Finalize. However, to
71 ensure portability, your code should always invoke Tcl_Finalize when
72 Tcl is being unloaded, to ensure that the code will work on all plat‐
73 forms. Tcl_Finalize can be safely called more than once.
74 Tcl_ExitThread is used to terminate the current thread and invoke per- │
76 thread exit handlers. This finalization is done by Tcl_FinalizeThread, │
77 which you can call if you just want to clean up per-thread state and │
78 invoke the thread exit handlers. Tcl_Finalize calls Tcl_FinalizeThread │
79 for the current thread automatically.
80 Tcl_CreateExitHandler arranges for proc to be invoked by Tcl_Finalize
82 and Tcl_Exit. Tcl_CreateThreadExitHandler arranges for proc to be
83 invoked by Tcl_FinalizeThread and Tcl_ExitThread. This provides a hook
84 for cleanup operations such as flushing buffers and freeing global mem‐
85 ory. Proc should match the type Tcl_ExitProc:
86 typedef void Tcl_ExitProc(ClientData clientData);
87 The clientData parameter to proc is a copy of the clientData argument
88 given to Tcl_CreateExitHandler or Tcl_CreateThreadExitHandler when the
89 callback was created. Typically, clientData points to a data structure
90 containing application-specific information about what to do in proc.
91 Tcl_DeleteExitHandler and Tcl_DeleteThreadExitHandler may be called to
93 delete a previously-created exit handler. It removes the handler indi‐
94 cated by proc and clientData so that no call to proc will be made. If
95 no such handler exists then Tcl_DeleteExitHandler or Tcl_DeleteThread‐
96 ExitHandler does nothing.
97 Tcl_Finalize and Tcl_Exit execute all registered exit handlers, in │
99 reverse order from the order in which they were registered. This │
100 matches the natural order in which extensions are loaded and unloaded; │
101 if extension A loads extension B, it usually unloads B before it itself │
102 is unloaded. If extension A registers its exit handlers before loading │
103 extension B, this ensures that any exit handlers for B will be executed │
104 before the exit handlers for A. │
105 Tcl_Finalize and Tcl_Exit call Tcl_FinalizeThread and the thread exit │
107 handlers after the process-wide exit handlers. This is because thread │
108 finalization shuts down the I/O channel system, so any attempt at I/O │
109 by the global exit handlers will vanish into the bitbucket.
110
113 callback, cleanup, dynamic loading, end application, exit, unloading,
114 thread
115Tcl 8.1 Tcl_Exit(3)