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       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
84       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
90       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
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
128

KEYWORDS

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