I686LINUX/util/I686LINUX/man/man3/Tcl_DeleteExitHandler.3

   1 '\"
   2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" RCS: @(#) $Id: Exit.3,v 1.4 2000/07/24 00:03:02 jenglish Exp $
   8 '\"
   9 '\" The definitions below are for supplemental macros used in Tcl/Tk
  10 '\" manual entries.
  11 '\"
  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)
  18 '\"
  19 '\" .AS ?type? ?name?
  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.
  23 '\"
  24 '\" .BS
  25 '\"     Start box enclosure.  From here until next .BE, everything will be
  26 '\"     enclosed in one large box.
  27 '\"
  28 '\" .BE
  29 '\"     End of box enclosure.
  30 '\"
  31 '\" .CS
  32 '\"     Begin code excerpt.
  33 '\"
  34 '\" .CE
  35 '\"     End code excerpt.
  36 '\"
  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.
  43 '\"
  44 '\" .VE
  45 '\"     End of vertical sidebar.
  46 '\"
  47 '\" .DS
  48 '\"     Begin an indented unfilled display.
  49 '\"
  50 '\" .DE
  51 '\"     End of indented unfilled display.
  52 '\"
  53 '\" .SO
  54 '\"     Start of list of standard options for a Tk widget.  The
  55 '\"     options follow on successive lines, in four columns separated
  56 '\"     by tabs.
  57 '\"
  58 '\" .SE
  59 '\"     End of list of standard options for a Tk widget.
  60 '\"
  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.
  66 '\"
  67 '\" .UL arg1 arg2
  68 '\"     Print arg1 underlined, then print arg2 normally.
  69 '\"
  70 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
  71 '\"
  72 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  73 .if t .wh -1.3i ^B
  74 .nr ^l \n(.l
  75 .ad b
  76 '\"     # Start an argument description
  77 .de AP
  78 .ie !"\\$4"" .TP \\$4
  79 .el \{\
  80 .   ie !"\\$2"" .TP \\n()Cu
  81 .   el          .TP 15
  82 .\}
  83 .ta \\n()Au \\n()Bu
  84 .ie !"\\$3"" \{\
  85 \&\\$1  \\fI\\$2\\fP    (\\$3)
  86 .\".b
  87 .\}
  88 .el \{\
  89 .br
  90 .ie !"\\$2"" \{\
  91 \&\\$1  \\fI\\$2\\fP
  92 .\}
  93 .el \{\
  94 \&\\fI\\$1\\fP
  95 .\}
  96 .\}
  97 ..
  98 '\"     # define tabbing values for .AP
  99 .de AS
 100 .nr )A 10n
 101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 102 .nr )B \\n()Au+15n
 103 .\"
 104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 106 ..
 107 .AS Tcl_Interp Tcl_CreateInterp in/out
 108 '\"     # BS - start boxed text
 109 '\"     # ^y = starting y location
 110 '\"     # ^b = 1
 111 .de BS
 112 .br
 113 .mk ^y
 114 .nr ^b 1u
 115 .if n .nf
 116 .if n .ti 0
 117 .if n \l'\\n(.lu\(ul'
 118 .if n .fi
 119 ..
 120 '\"     # BE - end boxed text (draw box now)
 121 .de BE
 122 .nf
 123 .ti 0
 124 .mk ^t
 125 .ie n \l'\\n(^lu\(ul'
 126 .el \{\
 127 .\"     Draw four-sided box normally, but don't draw top of
 128 .\"     box if the box started on an earlier page.
 129 .ie !\\n(^b-1 \{\
 130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 131 .\}
 132 .el \}\
 133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 134 .\}
 135 .\}
 136 .fi
 137 .br
 138 .nr ^b 0
 139 ..
 140 '\"     # VS - start vertical sidebar
 141 '\"     # ^Y = starting y location
 142 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 143 .de VS
 144 .if !"\\$2"" .br
 145 .mk ^Y
 146 .ie n 'mc \s12\(br\s0
 147 .el .nr ^v 1u
 148 ..
 149 '\"     # VE - end of vertical sidebar
 150 .de VE
 151 .ie n 'mc
 152 .el \{\
 153 .ev 2
 154 .nf
 155 .ti 0
 156 .mk ^t
 157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 158 .sp -1
 159 .fi
 160 .ev
 161 .\}
 162 .nr ^v 0
 163 ..
 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.
 167 .de ^B
 168 .ev 2
 169 'ti 0
 170 'nf
 171 .mk ^t
 172 .if \\n(^b \{\
 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
 177 .\}
 178 .if \\n(^v \{\
 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
 181 .\}
 182 .bp
 183 'fi
 184 .ev
 185 .if \\n(^b \{\
 186 .mk ^y
 187 .nr ^b 2
 188 .\}
 189 .if \\n(^v \{\
 190 .mk ^Y
 191 .\}
 192 ..
 193 '\"     # DS - begin display
 194 .de DS
 195 .RS
 196 .nf
 197 .sp
 198 ..
 199 '\"     # DE - end display
 200 .de DE
 201 .fi
 202 .RE
 203 .sp
 204 ..
 205 '\"     # SO - start of list of standard options
 206 .de SO
 207 .SH "STANDARD OPTIONS"
 208 .LP
 209 .nf
 210 .ta 5.5c 11c
 211 .ft B
 212 ..
 213 '\"     # SE - end of list of standard options
 214 .de SE
 215 .fi
 216 .ft R
 217 .LP
 218 See the \\fBoptions\\fR manual entry for details on the standard options.
 219 ..
 220 '\"     # OP - start of full description for a single option
 221 .de OP
 222 .LP
 223 .nf
 224 .ta 4c
 225 Command-Line Name:      \\fB\\$1\\fR
 226 Database Name:  \\fB\\$2\\fR
 227 Database Class: \\fB\\$3\\fR
 228 .fi
 229 .IP
 230 ..
 231 '\"     # CS - begin code excerpt
 232 .de CS
 233 .RS
 234 .nf
 235 .ta .25i .5i .75i 1i
 236 ..
 237 '\"     # CE - end code excerpt
 238 .de CE
 239 .fi
 240 .RE
 241 ..
 242 .de UL
 243 \\$1\l'|0\(ul'\\$2
 244 ..
 245 .TH Tcl_Exit 3 8.1 Tcl "Tcl Library Procedures"
 246 .BS
 247 .SH NAME
 248 Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler, Tcl_ExitThread, Tcl_FinalizeThread, Tcl_CreateThreadExitHandler, Tcl_DeleteThreadExitHandler \- end the application or thread (and invoke exit handlers)
 249 .SH SYNOPSIS
 250 .nf
 251 \fB#include <tcl.h>\fR
 252 .sp
 253 \fBTcl_Exit\fR(\fIstatus\fR)
 254 .sp
 255 \fBTcl_Finalize\fR()
 256 .sp
 257 \fBTcl_CreateExitHandler\fR(\fIproc, clientData\fR)
 258 .sp
 259 \fBTcl_DeleteExitHandler\fR(\fIproc, clientData\fR)
 260 .sp
 261 \fBTcl_ExitThread\fR(\fIstatus\fR)
 262 .sp
 263 \fBTcl_FinalizeThread\fR()
 264 .sp
 265 \fBTcl_CreateThreadExitHandler\fR(\fIproc, clientData\fR)
 266 .sp
 267 \fBTcl_DeleteThreadExitHandler\fR(\fIproc, clientData\fR)
 268 .SH ARGUMENTS
 269 .AS Tcl_ExitProc clientData
 270 .AP int status  in
 271 Provides information about why the application or thread exited.
 272 Exact meaning may
 273 be platform-specific.  0 usually means a normal exit, any nonzero value
 274 usually means that an error occurred.
 275 .AP Tcl_ExitProc *proc in
 276 Procedure to invoke before exiting application.
 277 .AP ClientData clientData in
 278 Arbitrary one-word value to pass to \fIproc\fR.
 279 .BE
 280
 281 .SH DESCRIPTION
 282 .PP
 283 The procedures described here provide a graceful mechanism to end the
 284 execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the
 285 application's state before ending the execution of \fBTcl\fR code.
 286 .PP
 287 Invoke \fBTcl_Exit\fR to end a \fBTcl\fR application and to exit from this
 288 process. This procedure is invoked by the \fBexit\fR command, and can be
 289 invoked anyplace else to terminate the application.
 290 No-one should ever invoke the \fBexit\fR system procedure directly;  always
 291 invoke \fBTcl_Exit\fR instead, so that it can invoke exit handlers.
 292 Note that if other code invokes \fBexit\fR system procedure directly, or
 293 otherwise causes the application to terminate without calling
 294 \fBTcl_Exit\fR, the exit handlers will not be run.
 295 \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
 296 returns control to its caller.
 297 .PP
 298 \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
 299 exit from the current process.
 300 It is useful for cleaning up when a process is finished using \fBTcl\fR but
 301 wishes to continue executing, and when \fBTcl\fR is used in a dynamically
 302 loaded extension that is about to be unloaded.
 303 On some systems \fBTcl\fR is automatically notified when it is being
 304 unloaded, and it calls \fBTcl_Finalize\fR internally; on these systems it
 305 not necessary for the caller to explicitly call \fBTcl_Finalize\fR.
 306 However, to ensure portability, your code should always invoke
 307 \fBTcl_Finalize\fR when \fBTcl\fR is being unloaded, to ensure that the
 308 code will work on all platforms. \fBTcl_Finalize\fR can be safely called
 309 more than once.
 310 .PP
 311 .VS
 312 \fBTcl_ExitThread\fR is used to terminate the current thread and invoke
 313 per-thread exit handlers.  This finalization is done by
 314 \fBTcl_FinalizeThread\fR, which you can call if you just want to clean
 315 up per-thread state and invoke the thread exit handlers.
 316 \fBTcl_Finalize\fR calls \fBTcl_FinalizeThread\fR for the current
 317 thread automatically.
 318 .VE
 319 .PP
 320 \fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
 321 by \fBTcl_Finalize\fR and \fBTcl_Exit\fR.
 322 \fBTcl_CreateThreadExitHandler\fR arranges for \fIproc\fR to be invoked
 323 by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR.
 324 This provides a hook for cleanup operations such as flushing buffers
 325 and freeing global memory.
 326 \fIProc\fR should match the type \fBTcl_ExitProc\fR:
 327 .CS
 328 typedef void Tcl_ExitProc(ClientData \fIclientData\fR);
 329 .CE
 330 The \fIclientData\fR parameter to \fIproc\fR is a
 331 copy of the \fIclientData\fR argument given to
 332 \fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\fR when
 333 the callback
 334 was created.  Typically, \fIclientData\fR points to a data
 335 structure containing application-specific information about
 336 what to do in \fIproc\fR.
 337 .PP
 338 \fBTcl_DeleteExitHandler\fR and \fBTcl_DeleteThreadExitHandler\fR may be
 339 called to delete a
 340 previously-created exit handler.  It removes the handler
 341 indicated by \fIproc\fR and \fIclientData\fR so that no call
 342 to \fIproc\fR will be made.  If no such handler exists then
 343 \fBTcl_DeleteExitHandler\fR or \fBTcl_DeleteThreadExitHandler\fR does nothing.
 344 .PP
 345 .VS
 346 .PP
 347 \fBTcl_Finalize\fR and \fBTcl_Exit\fR execute all registered exit handlers,
 348 in reverse order from the order in which they were registered.
 349 This matches the natural order in which extensions are loaded and unloaded;
 350 if extension \fBA\fR loads extension \fBB\fR, it usually
 351 unloads \fBB\fR before it itself is unloaded.
 352 If extension \fBA\fR registers its exit handlers before loading extension
 353 \fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
 354 before the exit handlers for \fBA\fR.
 355 .VE
 356 .VS
 357 .PP
 358 \fBTcl_Finalize\fR and \fBTcl_Exit\fR call \fBTcl_FinalizeThread\fR
 359 and the thread exit handlers \fIafter\fR
 360 the process-wide exit handlers.  This is because thread finalization shuts
 361 down the I/O channel system, so any attempt at I/O by the global exit
 362 handlers will vanish into the bitbucket.
 363 .VE
 364
 365 .SH KEYWORDS
 366 callback, cleanup, dynamic loading, end application, exit, unloading, thread