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, Tcl_SetExitProc - end the application or
11 thread (and invoke 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 Tcl_ExitProc * │
33 Tcl_SetExitProc(proc) │
34
36 int status (in) Provides information about why
37 the application or thread exited.
38 Exact meaning may be platform-
39 specific. 0 usually means a nor‐
40 mal exit, any nonzero value usu‐
41 ally means that an error
42 occurred.
43 Tcl_ExitProc *proc (in) Procedure to invoke before exit‐
45 ing application, or (for
46 Tcl_SetExitProc) NULL to unin‐
47 stall the current application
48 exit procedure.
49 ClientData clientData (in) Arbitrary one-word value to pass
51 to proc.
52_________________________________________________________________
53
56 The procedures described here provide a graceful mechanism to end the
57 execution of a Tcl application. Exit handlers are invoked to cleanup
58 the application's state before ending the execution of Tcl code.
59 Invoke Tcl_Exit to end a Tcl application and to exit from this process.
61 This procedure is invoked by the exit command, and can be invoked any‐
62 place else to terminate the application. No-one should ever invoke the
63 exit system procedure directly; always invoke Tcl_Exit instead, so
64 that it can invoke exit handlers. Note that if other code invokes exit
65 system procedure directly, or otherwise causes the application to ter‐
66 minate without calling Tcl_Exit, the exit handlers will not be run.
67 Tcl_Exit internally invokes the exit system call, thus it never returns
68 control to its caller. If an application exit handler has been │
69 installed (see Tcl_SetExitProc), that handler is invoked with an argu‐ │
70 ment consisting of the exit status (cast to ClientData); the applica‐ │
71 tion exit handler should not return control to Tcl.
72 Tcl_Finalize is similar to Tcl_Exit except that it does not exit from
74 the current process. It is useful for cleaning up when a process is
75 finished using Tcl but wishes to continue executing, and when Tcl is
76 used in a dynamically loaded extension that is about to be unloaded.
77 On some systems Tcl is automatically notified when it is being
78 unloaded, and it calls Tcl_Finalize internally; on these systems it not
79 necessary for the caller to explicitly call Tcl_Finalize. However, to
80 ensure portability, your code should always invoke Tcl_Finalize when
81 Tcl is being unloaded, to ensure that the code will work on all plat‐
82 forms. Tcl_Finalize can be safely called more than once.
83 Tcl_ExitThread is used to terminate the current thread and invoke per-
85 thread exit handlers. This finalization is done by Tcl_FinalizeThread,
86 which you can call if you just want to clean up per-thread state and
87 invoke the thread exit handlers. Tcl_Finalize calls Tcl_FinalizeThread
88 for the current thread automatically.
89 Tcl_CreateExitHandler arranges for proc to be invoked by Tcl_Finalize
91 and Tcl_Exit. Tcl_CreateThreadExitHandler arranges for proc to be
92 invoked by Tcl_FinalizeThread and Tcl_ExitThread. This provides a hook
93 for cleanup operations such as flushing buffers and freeing global mem‐
94 ory. Proc should match the type Tcl_ExitProc:
95 typedef void Tcl_ExitProc(ClientData clientData);
96 The clientData parameter to proc is a copy of the clientData argument
97 given to Tcl_CreateExitHandler or Tcl_CreateThreadExitHandler when the
98 callback was created. Typically, clientData points to a data structure
99 containing application-specific information about what to do in proc.
100 Tcl_DeleteExitHandler and Tcl_DeleteThreadExitHandler may be called to
102 delete a previously-created exit handler. It removes the handler indi‐
103 cated by proc and clientData so that no call to proc will be made. If
104 no such handler exists then Tcl_DeleteExitHandler or Tcl_DeleteThread‐
105 ExitHandler does nothing.
106 Tcl_Finalize and Tcl_Exit execute all registered exit handlers, in
108 reverse order from the order in which they were registered. This
109 matches the natural order in which extensions are loaded and unloaded;
110 if extension A loads extension B, it usually unloads B before it itself
111 is unloaded. If extension A registers its exit handlers before loading
112 extension B, this ensures that any exit handlers for B will be executed
113 before the exit handlers for A.
114 Tcl_Finalize and Tcl_Exit call Tcl_FinalizeThread and the thread exit
116 handlers after the process-wide exit handlers. This is because thread
117 finalization shuts down the I/O channel system, so any attempt at I/O
118 by the global exit handlers will vanish into the bitbucket.
119 Tcl_SetExitProc installs an application exit handler, returning the │
121 previously-installed application exit handler or NULL if no application │
122 handler was installed. If an application exit handler is installed, │
123 that exit handler takes over complete responsibility for finalization │
124 of Tcl's subsystems via Tcl_Finalize at an appropriate time. The argu‐ │
125 ment passed to proc when it is invoked will be the exit status code (as │
126 passed to Tcl_Exit) cast to a ClientData value.
127
130 callback, cleanup, dynamic loading, end application, exit, unloading,
131 thread
132Tcl 8.5 Tcl_Exit(3)