1Tcl_Exit(3)                 Tcl Library Procedures                 Tcl_Exit(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

14       #include <tcl.h>
15
16       Tcl_Exit(status)
17
18       Tcl_Finalize()
19
20       Tcl_CreateExitHandler(proc, clientData)
21
22       Tcl_DeleteExitHandler(proc, clientData)
23
24       Tcl_ExitThread(status)
25
26       Tcl_FinalizeThread()
27
28       Tcl_CreateThreadExitHandler(proc, clientData)
29
30       Tcl_DeleteThreadExitHandler(proc, clientData)
31
32       Tcl_ExitProc *
33       Tcl_SetExitProc(proc)
34

ARGUMENTS

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
44       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
50       ClientData clientData (in)            Arbitrary one-word value to  pass
51                                             to proc.
52______________________________________________________________________________
53
54

DESCRIPTION

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
60       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
73       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       Your code should always invoke Tcl_Finalize when Tcl is being unloaded,
78       to  ensure  proper cleanup. Tcl_Finalize can be safely called more than
79       once.
80
81       Tcl_ExitThread is used to terminate the current thread and invoke  per-
82       thread exit handlers.  This finalization is done by Tcl_FinalizeThread,
83       which you can call if you just want to clean up  per-thread  state  and
84       invoke the thread exit handlers.  Tcl_Finalize calls Tcl_FinalizeThread
85       for the current thread automatically.
86
87       Tcl_CreateExitHandler arranges for proc to be invoked  by  Tcl_Finalize
88       and  Tcl_Exit.   Tcl_CreateThreadExitHandler  arranges  for  proc to be
89       invoked by Tcl_FinalizeThread and Tcl_ExitThread.  This provides a hook
90       for cleanup operations such as flushing buffers and freeing global mem‐
91       ory.  Proc should match the type Tcl_ExitProc:
92
93              typedef void Tcl_ExitProc(
94                      ClientData clientData);
95
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
101       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
107       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
115       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
120       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

SEE ALSO

129       exit(n)
130

KEYWORDS

132       abort, callback,  cleanup,  dynamic  loading,  end  application,  exit,
133       unloading, thread
134
135
136
137Tcl                                   8.5                          Tcl_Exit(3)
Impressum