ready to 1.5.1-rc2
[manpages-zh.git] / raw / mann / bgerror.n
blobe9842ec1dca1ad6e0474329c977b2ed4b444f55c
1 '\"
2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
4 '\"
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 '\"
8 '\" RCS: @(#) $Id: bgerror.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
9 '\"
10 '\" The definitions below are for supplemental macros used in Tcl/Tk
11 '\" manual entries.
12 '\"
13 '\" .AP type name in/out ?indent?
14 '\" Start paragraph describing an argument to a library procedure.
15 '\" type is type of argument (int, etc.), in/out is either "in", "out",
16 '\" or "in/out" to describe whether procedure reads or modifies arg,
17 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
18 '\" needed; use .AS below instead)
19 '\"
20 '\" .AS ?type? ?name?
21 '\" Give maximum sizes of arguments for setting tab stops. Type and
22 '\" name are examples of largest possible arguments that will be passed
23 '\" to .AP later. If args are omitted, default tab stops are used.
24 '\"
25 '\" .BS
26 '\" Start box enclosure. From here until next .BE, everything will be
27 '\" enclosed in one large box.
28 '\"
29 '\" .BE
30 '\" End of box enclosure.
31 '\"
32 '\" .CS
33 '\" Begin code excerpt.
34 '\"
35 '\" .CE
36 '\" End code excerpt.
37 '\"
38 '\" .VS ?version? ?br?
39 '\" Begin vertical sidebar, for use in marking newly-changed parts
40 '\" of man pages. The first argument is ignored and used for recording
41 '\" the version when the .VS was added, so that the sidebars can be
42 '\" found and removed when they reach a certain age. If another argument
43 '\" is present, then a line break is forced before starting the sidebar.
44 '\"
45 '\" .VE
46 '\" End of vertical sidebar.
47 '\"
48 '\" .DS
49 '\" Begin an indented unfilled display.
50 '\"
51 '\" .DE
52 '\" End of indented unfilled display.
53 '\"
54 '\" .SO
55 '\" Start of list of standard options for a Tk widget. The
56 '\" options follow on successive lines, in four columns separated
57 '\" by tabs.
58 '\"
59 '\" .SE
60 '\" End of list of standard options for a Tk widget.
61 '\"
62 '\" .OP cmdName dbName dbClass
63 '\" Start of description of a specific option. cmdName gives the
64 '\" option's name as specified in the class command, dbName gives
65 '\" the option's name in the option database, and dbClass gives
66 '\" the option's class in the option database.
67 '\"
68 '\" .UL arg1 arg2
69 '\" Print arg1 underlined, then print arg2 normally.
70 '\"
71 '\" RCS: @(#) $Id: bgerror.n,v 1.1 2003/12/20 03:31:54 bbbush Exp $
72 '\"
73 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
74 .if t .wh -1.3i ^B
75 .nr ^l \n(.l
76 .ad b
77 '\" # Start an argument description
78 .de AP
79 .ie !"\\$4"" .TP \\$4
80 .el \{\
81 . ie !"\\$2"" .TP \\n()Cu
82 . el .TP 15
83 .\}
84 .ta \\n()Au \\n()Bu
85 .ie !"\\$3"" \{\
86 \&\\$1 \\fI\\$2\\fP (\\$3)
87 .\".b
88 .\}
89 .el \{\
90 .br
91 .ie !"\\$2"" \{\
92 \&\\$1 \\fI\\$2\\fP
93 .\}
94 .el \{\
95 \&\\fI\\$1\\fP
96 .\}
97 .\}
99 '\" # define tabbing values for .AP
100 .de AS
101 .nr )A 10n
102 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
103 .nr )B \\n()Au+15n
105 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
108 .AS Tcl_Interp Tcl_CreateInterp in/out
109 '\" # BS - start boxed text
110 '\" # ^y = starting y location
111 '\" # ^b = 1
112 .de BS
114 .mk ^y
115 .nr ^b 1u
116 .if n .nf
117 .if n .ti 0
118 .if n \l'\\n(.lu\(ul'
119 .if n .fi
121 '\" # BE - end boxed text (draw box now)
122 .de BE
124 .ti 0
125 .mk ^t
126 .ie n \l'\\n(^lu\(ul'
127 .el \{\
128 .\" Draw four-sided box normally, but don't draw top of
129 .\" box if the box started on an earlier page.
130 .ie !\\n(^b-1 \{\
131 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
133 .el \}\
134 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 .nr ^b 0
141 '\" # VS - start vertical sidebar
142 '\" # ^Y = starting y location
143 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
144 .de VS
145 .if !"\\$2"" .br
146 .mk ^Y
147 .ie n 'mc \s12\(br\s0
148 .el .nr ^v 1u
150 '\" # VE - end of vertical sidebar
151 .de VE
152 .ie n 'mc
153 .el \{\
154 .ev 2
156 .ti 0
157 .mk ^t
158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
159 .sp -1
163 .nr ^v 0
165 '\" # Special macro to handle page bottom: finish off current
166 '\" # box/sidebar if in box/sidebar mode, then invoked standard
167 '\" # page bottom macro.
168 .de ^B
169 .ev 2
170 'ti 0
172 .mk ^t
173 .if \\n(^b \{\
174 .\" Draw three-sided box if this is the box's first page,
175 .\" draw two sides but no top otherwise.
176 .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
177 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
179 .if \\n(^v \{\
180 .nr ^x \\n(^tu+1v-\\n(^Yu
181 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
186 .if \\n(^b \{\
187 .mk ^y
188 .nr ^b 2
190 .if \\n(^v \{\
191 .mk ^Y
194 '\" # DS - begin display
195 .de DS
200 '\" # DE - end display
201 .de DE
206 '\" # SO - start of list of standard options
207 .de SO
208 .SH "STANDARD OPTIONS"
211 .ta 5.5c 11c
212 .ft B
214 '\" # SE - end of list of standard options
215 .de SE
217 .ft R
219 See the \\fBoptions\\fR manual entry for details on the standard options.
221 '\" # OP - start of full description for a single option
222 .de OP
225 .ta 4c
226 Command-Line Name: \\fB\\$1\\fR
227 Database Name: \\fB\\$2\\fR
228 Database Class: \\fB\\$3\\fR
232 '\" # CS - begin code excerpt
233 .de CS
236 .ta .25i .5i .75i 1i
238 '\" # CE - end code excerpt
239 .de CE
243 .de UL
244 \\$1\l'|0\(ul'\\$2
246 .TH bgerror n 7.5 Tcl "Tcl Built-In Commands"
248 '\" Note: do not modify the .SH NAME line immediately below!
249 .SH NAME
250 bgerror \- Command invoked to process background errors
251 .SH SYNOPSIS
252 \fBbgerror \fImessage\fR
255 .SH DESCRIPTION
257 The \fBbgerror\fR command doesn't exist as built-in part of Tcl. Instead,
258 individual applications or users can define a \fBbgerror\fR
259 command (e.g. as a Tcl procedure) if they wish to handle background
260 errors.
262 A background error is one that occurs in an event handler or some
263 other command that didn't originate with the application.
264 For example, if an error occurs while executing a command specified
265 with the \fBafter\fR command, then it is a background error.
266 For a non-background error, the error can simply be returned up
267 through nested Tcl command evaluations until it reaches the top-level
268 code in the application; then the application can report the error
269 in whatever way it wishes. When a background error occurs, the
270 unwinding ends in the Tcl library and there is no obvious way for Tcl
271 to report the error.
273 When Tcl detects a background error, it saves information about the
274 error and invokes the \fBbgerror\fR command later as an idle event
275 handler. Before invoking \fBbgerror\fR, Tcl restores the
276 \fBerrorInfo\fR and \fBerrorCode\fR variables to their values at the
277 time the error occurred, then it invokes \fBbgerror\fR with the error
278 message as its only argument. Tcl assumes that the application has
279 implemented the \fBbgerror\fR command, and that the command will
280 report the error in a way that makes sense for the application. Tcl
281 will ignore any result returned by the \fBbgerror\fR command as long
282 as no error is generated.
284 If another Tcl error occurs within the \fBbgerror\fR command (for
285 example, because no \fBbgerror\fR command has been defined) then Tcl
286 reports the error itself by writing a message to stderr.
288 If several background errors accumulate before \fBbgerror\fR is
289 invoked to process them, \fBbgerror\fR will be invoked once for each
290 error, in the order they occurred. However, if \fBbgerror\fR returns
291 with a break exception, then any remaining errors are skipped without
292 calling \fBbgerror\fR.
294 Tcl has no default implementation for \fBbgerror\fR. However, in
295 applications using Tk there is a default \fBbgerror\fR procedure which
296 posts a dialog box containing the error message and offers the user a
297 chance to see a stack trace showing where the error occurred. In
298 addition to allowing the user to view the stack trace, the dialog
299 provides an additional application configurable button which may be
300 used, for example, to save the stack trace to a file. By default,
301 this is the behavior associated with that button. This behavior can
302 be redefined by setting the option database values
303 \fB*ErrorDialog.function.text\fR, to specify the caption for the
304 function button, and \fB*ErrorDialog.function.command\fR, to specify
305 the command to be run. The text of the stack trace is appended to the
306 command when it is evaluated. If either of these options is set to
307 the empty string, then the additional button will not be displayed in
308 the dialog.
310 .SH "SEE ALSO"
311 after(n), tclvars(n)
313 .SH KEYWORDS
314 background error, reporting