2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 '\" SCCS: @(#) Exit.3 1.8 96/12/10 07:37:23
9 '\" The definitions below are for supplemental macros used in Tcl/Tk
12 '\" .AP type name in/out ?indent?
13 '\" Start paragraph describing an argument to a library procedure.
14 '\" type is type of argument (int, etc.), in/out is either "in", "out",
15 '\" or "in/out" to describe whether procedure reads or modifies arg,
16 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 '\" needed; use .AS below instead)
20 '\" Give maximum sizes of arguments for setting tab stops. Type and
21 '\" name are examples of largest possible arguments that will be passed
22 '\" to .AP later. If args are omitted, default tab stops are used.
25 '\" Start box enclosure. From here until next .BE, everything will be
26 '\" enclosed in one large box.
29 '\" End of box enclosure.
32 '\" Begin code excerpt.
37 '\" .VS ?version? ?br?
38 '\" Begin vertical sidebar, for use in marking newly-changed parts
39 '\" of man pages. The first argument is ignored and used for recording
40 '\" the version when the .VS was added, so that the sidebars can be
41 '\" found and removed when they reach a certain age. If another argument
42 '\" is present, then a line break is forced before starting the sidebar.
45 '\" End of vertical sidebar.
48 '\" Begin an indented unfilled display.
51 '\" End of indented unfilled display.
54 '\" Start of list of standard options for a Tk widget. The
55 '\" options follow on successive lines, in four columns separated
59 '\" End of list of standard options for a Tk widget.
61 '\" .OP cmdName dbName dbClass
62 '\" Start of description of a specific option. cmdName gives the
63 '\" option's name as specified in the class command, dbName gives
64 '\" the option's name in the option database, and dbClass gives
65 '\" the option's class in the option database.
68 '\" Print arg1 underlined, then print arg2 normally.
70 '\" SCCS: @(#) man.macros 1.9 97/08/22 18:50:59
72 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
76 '\" # Start an argument description
80 . ie !"\\$2"" .TP \\n()Cu
85 \&\\$1 \\fI\\$2\\fP (\\$3)
98 '\" # define tabbing values for .AP
101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
107 .AS Tcl_Interp Tcl_CreateInterp in/out
108 '\" # BS - start boxed text
109 '\" # ^y = starting y location
117 .if n \l'\\n(.lu\(ul'
120 '\" # BE - end boxed text (draw box now)
125 .ie n \l'\\n(^lu\(ul'
127 .\" Draw four-sided box normally, but don't draw top of
128 .\" box if the box started on an earlier page.
130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
140 '\" # VS - start vertical sidebar
141 '\" # ^Y = starting y location
142 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
146 .ie n 'mc \s12\(br\s0
149 '\" # VE - end of vertical sidebar
157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
164 '\" # Special macro to handle page bottom: finish off current
165 '\" # box/sidebar if in box/sidebar mode, then invoked standard
166 '\" # page bottom macro.
173 .\" Draw three-sided box if this is the box's first page,
174 .\" draw two sides but no top otherwise.
175 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
176 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
179 .nr ^x \\n(^tu+1v-\\n(^Yu
180 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
193 '\" # DS - begin display
199 '\" # DE - end display
205 '\" # SO - start of list of standard options
207 .SH "STANDARD OPTIONS"
213 '\" # SE - end of list of standard options
218 See the \\fBoptions\\fR manual entry for details on the standard options.
220 '\" # OP - start of full description for a single option
225 Command-Line Name: \\fB\\$1\\fR
226 Database Name: \\fB\\$2\\fR
227 Database Class: \\fB\\$3\\fR
231 '\" # CS - begin code excerpt
237 '\" # CE - end code excerpt
245 .TH Tcl_Exit 3 7.7 Tcl "Tcl Library Procedures"
248 Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the application (and invoke exit handlers)
251 \fB#include <tcl.h>\fR
253 \fBTcl_Exit\fR(\fIstatus\fR)
257 \fBTcl_CreateExitHandler\fR(\fIproc, clientData\fR)
259 \fBTcl_DeleteExitHandler\fR(\fIproc, clientData\fR)
261 .AS Tcl_ExitProc clientData
263 Provides information about why application exited. Exact meaning may
264 be platform-specific. 0 usually means a normal exit, any nonzero value
265 usually means that an error occurred.
266 .AP Tcl_ExitProc *proc in
267 Procedure to invoke before exiting application.
268 .AP ClientData clientData in
269 Arbitrary one-word value to pass to \fIproc\fR.
274 The procedures described here provide a graceful mechanism to end the
275 execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the
276 application's state before ending the execution of \fBTcl\fR code.
278 Invoke \fBTcl_Exit\fR to end a \fBTcl\fR application and to exit from this
279 process. This procedure is invoked by the \fBexit\fR command, and can be
280 invoked anyplace else to terminate the application.
281 No-one should ever invoke the \fBexit\fR system procedure directly; always
282 invoke \fBTcl_Exit\fR instead, so that it can invoke exit handlers.
283 Note that if other code invokes \fBexit\fR system procedure directly, or
284 otherwise causes the application to terminate without calling
285 \fBTcl_Exit\fR, the exit handlers will not be run.
286 \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
287 returns control to its caller.
290 \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
291 exit from the current process.
292 It is useful for cleaning up when a process is finished using \fBTcl\fR but
293 wishes to continue executing, and when \fBTcl\fR is used in a dynamically
294 loaded extension that is about to be unloaded.
295 On some systems \fBTcl\fR is automatically notified when it is being
296 unloaded, and it calls \fBTcl_Finalize\fR internally; on these systems it
297 not necessary for the caller to explicitly call \fBTcl_Finalize\fR.
298 However, to ensure portability, your code should always invoke
299 \fBTcl_Finalize\fR when \fBTcl\fR is being unloaded, to ensure that the
300 code will work on all platforms. \fBTcl_Finalize\fR can be safely called
304 \fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
305 by \fBTcl_Finalize\fR and \fBTcl_Exit\fR.
306 This provides a hook for cleanup operations such as flushing buffers
307 and freeing global memory.
308 \fIProc\fR should match the type \fBTcl_ExitProc\fR:
310 typedef void Tcl_ExitProc(ClientData \fIclientData\fR);
312 The \fIclientData\fR parameter to \fIproc\fR is a
313 copy of the \fIclientData\fR argument given to
314 \fBTcl_CreateExitHandler\fR when the callback
315 was created. Typically, \fIclientData\fR points to a data
316 structure containing application-specific information about
317 what to do in \fIproc\fR.
319 \fBTcl_DeleteExitHandler\fR may be called to delete a
320 previously-created exit handler. It removes the handler
321 indicated by \fIproc\fR and \fIclientData\fR so that no call
322 to \fIproc\fR will be made. If no such handler exists then
323 \fBTcl_DeleteExitHandler\fR does nothing.
327 \fBTcl_Finalize\fR and \fBTcl_Exit\fR execute all registered exit handlers,
328 in reverse order from the order in which they were registered.
329 This matches the natural order in which extensions are loaded and unloaded;
330 if extension \fBA\fR loads extension \fBB\fR, it usually
331 unloads \fBB\fR before it itself is unloaded.
332 If extension \fBA\fR registers its exit handlers before loading extension
333 \fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
334 before the exit handlers for \fBA\fR.
338 callback, cleanup, dynamic loading, end application, exit, unloading