2 '\" Copyright 1991-1997 by Bell Labs Innovations for Lucent Technologies.
4 '\" Permission to use, copy, modify, and distribute this software and its
5 '\" documentation for any purpose and without fee is hereby granted, provided
6 '\" that the above copyright notice appear in all copies and that both that the
7 '\" copyright notice and warranty disclaimer appear in supporting documentation,
8 '\" and that the names of Lucent Technologies any of their entities not be used
9 '\" in advertising or publicity pertaining to distribution of the software
10 '\" without specific, written prior permission.
12 '\" Lucent Technologies disclaims all warranties with regard to this software,
13 '\" including all implied warranties of merchantability and fitness. In no event
14 '\" shall Lucent Technologies be liable for any special, indirect or
15 '\" consequential damages or any damages whatsoever resulting from loss of use,
16 '\" data or profits, whether in an action of contract, negligence or other
17 '\" tortuous action, arising out of or in connection with the use or performance
20 '\" Bgexec command created by George Howlett.
22 '\" The definitions below are for supplemental macros used in Tcl/Tk
25 '\" .AP type name in/out ?indent?
26 '\" Start paragraph describing an argument to a library procedure.
27 '\" type is type of argument (int, etc.), in/out is either "in", "out",
28 '\" or "in/out" to describe whether procedure reads or modifies arg,
29 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
30 '\" needed; use .AS below instead)
33 '\" Give maximum sizes of arguments for setting tab stops. Type and
34 '\" name are examples of largest possible arguments that will be passed
35 '\" to .AP later. If args are omitted, default tab stops are used.
38 '\" Start box enclosure. From here until next .BE, everything will be
39 '\" enclosed in one large box.
42 '\" End of box enclosure.
45 '\" Begin code excerpt.
50 '\" .VS ?version? ?br?
51 '\" Begin vertical sidebar, for use in marking newly-changed parts
52 '\" of man pages. The first argument is ignored and used for recording
53 '\" the version when the .VS was added, so that the sidebars can be
54 '\" found and removed when they reach a certain age. If another argument
55 '\" is present, then a line break is forced before starting the sidebar.
58 '\" End of vertical sidebar.
61 '\" Begin an indented unfilled display.
64 '\" End of indented unfilled display.
67 '\" Start of list of standard options for a Tk widget. The
68 '\" options follow on successive lines, in four columns separated
72 '\" End of list of standard options for a Tk widget.
74 '\" .OP cmdName dbName dbClass
75 '\" Start of description of a specific option. cmdName gives the
76 '\" option's name as specified in the class command, dbName gives
77 '\" the option's name in the option database, and dbClass gives
78 '\" the option's class in the option database.
81 '\" Print arg1 underlined, then print arg2 normally.
83 '\" RCS: @(#) $Id: man.macros,v 1.3 2001/02/17 07:46:19 ghowlett Exp $
85 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
89 '\" # Start an argument description
93 . ie !"\\$2"" .TP \\n()Cu
98 \&\\$1 \\fI\\$2\\fP (\\$3)
111 '\" # define tabbing values for .AP
114 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
117 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
118 .nr )C \\n()Bu+\\w'(in/out)'u+2n
120 .AS Tcl_Interp Tcl_CreateInterp in/out
121 '\" # BS - start boxed text
122 '\" # ^y = starting y location
130 .if n \l'\\n(.lu\(ul'
133 '\" # BE - end boxed text (draw box now)
138 .ie n \l'\\n(^lu\(ul'
140 .\" Draw four-sided box normally, but don't draw top of
141 .\" box if the box started on an earlier page.
143 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
153 '\" # VS - start vertical sidebar
154 '\" # ^Y = starting y location
155 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
159 .ie n 'mc \s12\(br\s0
162 '\" # VE - end of vertical sidebar
170 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
177 '\" # Special macro to handle page bottom: finish off current
178 '\" # box/sidebar if in box/sidebar mode, then invoked standard
179 '\" # page bottom macro.
186 .\" Draw three-sided box if this is the box's first page,
187 .\" draw two sides but no top otherwise.
188 .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
189 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
192 .nr ^x \\n(^tu+1v-\\n(^Yu
193 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
206 '\" # DS - begin display
212 '\" # DE - end display
218 '\" # SO - start of list of standard options
220 .SH "STANDARD OPTIONS"
226 '\" # SE - end of list of standard options
231 See the \\fBoptions\\fR manual entry for details on the standard options.
233 '\" # OP - start of full description for a single option
238 Command-Line Name: \\fB\\$1\\fR
239 Database Name: \\fB\\$2\\fR
240 Database Class: \\fB\\$3\\fR
244 '\" # CS - begin code excerpt
252 '\" # CE - end code excerpt
262 .TH bgexec n 2.4 BLT "BLT Built-In Commands"
264 '\" Note: do not modify the .SH NAME line immediately below!
266 bgexec \- Run programs in the background while handling Tk events.
268 \fBblt::bgexec \fIvarName\fR ?\fIoption value\fR?... \fIprogram\fR ?\fIarg\fR?...
272 The \fBbgexec\fR command executes programs in the background,
273 allowing Tk to handle events. A global Tcl variable \fIvarName\fR is
274 set when the program has completed.
276 Tcl's \fBexec\fR command is very useful for gathering information from
277 the operating system. It runs a program and returns the output as its
278 result. This works well for Tcl-only applications. But
279 for Tk applications, a problem occurs when the program takes time to
280 process. Let's say we want the get the disk usage of a
281 directory. We'll use the Unix program \f(CWdu\fR to get the summary.
283 set out [exec du -s $dir]
284 puts "Disk usage for $dir is $out"
286 While \f(CWdu\fR is running, scrollbars won't respond. None of the Tk
287 widgets will be redrawn properly. The \fBsend\fR command won't work.
288 And the worst part is that the application appears hung up or dead.
289 The problem is that while \fBexec\fR is waiting for \fIdu\fR to
290 finish, Tk is not able to handle X events.
292 The \fBbgexec\fR command performs the same functions as \fBexec\fR,
293 but also allows Tk to handle events. You can execute a long-running
294 program and the Tk widgets will behave normally. When the
295 program finishes, its output and the exit status are written to Tcl
296 variables. This makes it easy to monitor and save the output of a
299 Here is the disk usage example again, this time using \fBbgexec\fR.
300 The syntax to invoke "du" is exactly the same as the previous
301 example, when we used \fBexec\fR.
303 global myStatus myOutput
304 blt::bgexec myStatus -output myOutput du -s $dir
305 puts "Disk usage for $dir is $myOutput"
307 Two global variables, \f(CWmyStatus\fR and \f(CWmyOutput\fR, will be set by
308 \fBbgexec\fR when \f(CWdu\fR has completed. \f(CWMyStatus\fR
309 will contain the program's exit status. \f(CWMyOutput\fR, specified by the
310 \fB\-output\fR option, will store the output of the program.
312 You can also terminate the program by setting the variable
313 \f(CWmyStatus\fR. If \f(CWmyStatus\fR is set before \f(CWdu\fR has
314 completed, the process is killed. Under Unix, this is done sending by
315 a configurable signal (by default it's SIGKILL). Under Win32, this
316 is done by calling \fBTerminateProcess\fR. It makes no
317 difference what \f(CWmyStatus\fR is set to.
321 There are several \fBbgexec\fR options to collect different types of
324 global myStatus myOutput myErrs
325 blt::bgexec myStatus -output myOutput -error myErrs du -s $dir
327 The \fB\-error\fR option is similar to \fB\-output\fR. It sets a global
328 variable when the program completes. The variable will contain
329 any data written to stderr by the program.
331 The \fB\-output\fR and \fB\-error\fR variables are set only
332 after the program completes. But if the program takes a long time, to
333 run you may want to receive its partial output. You can gather data
334 as it becomes available using the \fB\-onoutput\fR option. It
335 specifies a Tcl command prefix. Whenever new data is available, this
336 command is executed, with the data appended as an argument to the
339 proc GetInfo { data } {
342 blt::bgexec myStatus -onoutput GetInfo du -s $dir
344 When output is available, the procedure \f(CWGetInfo\fR is called.
345 The \fB\-onerror\fR option performs a similar function for the stderr
348 Like \fBexec\fR, \fBbgexec\fR returns an error if the exit code of the
349 program is not zero. If you think you may get a non-zero exit
350 code, you might want to invoke \fBbgexec\fR from within a \fBcatch\fR.
352 catch { blt::bgexec myStatus -output myOutput du -s $dir }
354 By default, \fBbgexec\fR will wait for the program to finish.
355 But you can detach the program making ampersand (&) the last
356 argument on the command line.
358 global myStatus myOutput
359 blt::bgexec myStatus -output myOutput du -s $dir &
361 \fBBgexec\fR will return immediately and its result will be a list of
362 the spawned process ids. If at some point you need to wait for the
363 program to finish up, you can use \fBtkwait\fR. When the program
364 finishes, the variable \f(CWmyStatus\fR will be written to, breaking
365 out the \fBtkwait\fR command.
367 global myStatus myOutput
368 blt::bgexec myStatus -output myOutput du -s $dir &
370 tkwait variable myStatus
373 The \fBbgexec\fR command takes the following form:
375 \fB blt::bgexec \fIvarName\fR ?\fIoption value\fR?... \fIprogram\fR ?\fIarg\fR?...
377 \fIVarName\fR is the name of a global variable which is set when
378 \fIprogram\fR has finished executing. The exit status of
379 will be stored in \fIvarName\fR. The exit status is a
380 list of a status token, the process-id of the program, the exit code,
381 and a status message. You can also prematurely terminate the program
382 by setting \fIvarName\fR. Under Unix, the program will be sent a signal to
383 terminate it (by default the signal is a SIGKILL; see the
384 \fB\-killsignal\fR option).
386 \fIProgram\fR is the name of the program to be executed and \fIargs\fR
387 are any extra arguments for \fIprogram\fR. The syntax of
388 \fIprogram\fR and \fIargs\fR is the same as the \fBexec\fR command. So
389 you can redirect I/O, execute pipelines, etc. (see the \fBexec\fR
390 manual for further information) just like \fBexec\fR. If the last
391 argument is an ampersand (&), the program will be run detached, and
392 \fBbgexec\fR will return immediately. \fIVarName\fR will still be set
393 with the return status when \fIprogram\fR completes.
395 \fIOption\fR refers to the switch name always beginning with a dash (\-).
396 \fIValue\fR is the value of the option. Option-value pairs are
397 terminated either by the program name, or double dashes (\-\-).
398 The following options are available for \fBbgexec\fR:
400 \fB\-decodeerror \fIencodingName\fR
402 Specifies the encoding of the stderr channel.
403 This affects only data returned to the Tcl interpreter. No translation
404 is done on file redirection.
406 For example if data is to be converted from Unicode for use in Tcl,
407 you would use the "unicode" encoding. The default is that no
408 tranlation is performed.
410 \fB\-decodeoutput \fIencodingName\fR
412 Specifies the encoding of the stdout channels.
413 This affects only data returned to the Tcl interpreter. No translation
414 is done on file redirection.
416 For example if data is to be converted from Unicode for use in Tcl,
417 you would use the "unicode" encoding. The default is that no
418 tranlation is performed.
420 \fB\-error \fIvarName\fR
422 Specifies that a global variable \fIvarName\fR is to be set with the
423 contents of stderr after the program has completed.
425 \fB\-keepnewline \fIboolean\fR
426 Specifies that a trailing newline should be retained in the
427 output. If \fIboolean\fR is true, the trailing newline is truncated
428 from the output of the \fB\-onoutput\fR and \fB\-output\fR variables.
429 The default value is \f(CWtrue\fR.
431 \fB\-killsignal \fIsignal\fR
432 Specifies the signal to be sent to the program when
433 terminating. This is available only under Unix.
434 \fISignal\fR can either be a number (typically 1-32) or
435 a mnemonic (such as SIGINT). If \fIsignal\fR is the empty string,
436 then no signal is sent. The default signal is \f(CW9\fR (SIGKILL).
438 \fB\-lasterror \fIvarName\fR
439 Specifies a variable \fIvarName\fR that is updated whenever data
440 becomes available from standard error of the program.
441 \fIVarName\fR is a global variable. Unlike the \fB\-error\fR option,
442 data is available as soon as it arrives.
444 \fB\-lastoutput \fIvarName\fR
445 Specifies a variable \fIvarName\fR that is updated whenever data
446 becomes available from standard output of the program.
447 \fIVarName\fR is a global variable. Unlike the \fB\-output\fR option,
448 data is available as soon as it arrives.
450 \fB\-linebuffered \fIboolean\fR
451 Specifies that updates should be made on a line-by-line basis.
452 Normally when new data is available \fBbgexec\fR will set the variable
453 (\fB\-lastoutput\fR and \fB\-lasterror\fR options) or invoke the
454 command (\fB\-onoutput\fR and \fB\-onerror\fR options) delivering all
455 the new data currently available. If \fIboolean\fR is true, only one
456 line at a time will be delivered. This can be useful when you want to
457 process the output on a line-by-line basis.
461 \fB\-output \fIvarName\fR
463 Specifies that a global variable \fIvarName\fR is to be set with the
464 output of the program, once it has completed. If this option
465 is not set, no output will be accumulated.
467 \fB\-onerror \fIcommand\fR
468 Specifies the start of a Tcl command that will be executed
469 whenever new data is available from standard error. The data
470 is appended to the command as an extra argument before it is
473 \fB\-onoutput \fIcommand\fR
474 Specifies the start of a Tcl command that will be executed
475 whenever new data is available from standard output. The data
476 is appended to the command as an extra argument before it is
479 \fB\-update \fIvarName\fR
480 Deprecated. This option is replaced by \fB\-lasterror\fR.
483 This marks the end of the options. The following argument will
484 be considered the name of a program even if it starts with
487 Because \fBbgexec\fR allows Tk to handle events while a program is
488 running, it's possible for an application to preempt itself with
489 further user-interactions. Let's say your application has a button
490 that runs the disk usage example. And while the \f(CWdu\fR program is
491 running, the user accidently presses the button again. A second
492 \fBbgexec\fR program will preempt the first. What this means is that
493 the first program can not finish until the second program has
496 Care must be taken to prevent an application from preempting itself by
497 blocking further user-interactions (such as button clicks). The BLT
498 \fBbusy\fR command is very useful for just these situations.
499 See the \fBbusy\fR manual for details.
500 .SH DIFFERENCES WITH FILEEVENT
501 Since Tk 4.0, a subset of \fBbgexec\fR can be also achieved using the
502 \fBfileevent\fR command. The steps for running a program in the
505 Execute the program with the \fBopen\fR command (using the "|"
506 syntax) and save the file handle.
509 set fileId [open "|du -s $dir" r]
511 Next register a Tcl code snippet with \fBfileevent\fR to be run
512 whenever output is available on the file handle. The code snippet
513 will read from the file handle and save the output in a variable.
515 fileevent fileId readable {
516 if { [gets $fileId line] < 0 } {
526 The biggest advantage of \fBbgexec\fR is that, unlike \fBfileevent\fR,
527 it requires no additional Tcl code to run a program. It's simpler and
528 less error prone. You don't have to worry about non-blocking I/O.
529 It's handled tranparently for you.
531 \fBBgexec\fR runs programs that \fBfileevent\fR can not.
532 \fBFileevent\fR assumes that the when stdout is closed the program has
533 completed. But some programs, like the Unix \f(CWcompress\fR program,
534 reopen stdout, fooling \fBfileevent\fR into thinking the program has
535 terminated. In the example above, we assume that the program will
536 write and flush its output line-by-line. However running another
537 program, your application may block in the \fBgets\fR command reading
540 \fBBgexec\fR lets you get back the exit status of the program. It also
541 allows you to collect data from both stdout and stderr simultaneously.
542 Finally, since data collection is handled in C code, \fBbgexec\fR is
543 faster. You get back to the Tk event loop more quickly, making your
544 application seem more responsive.
548 exec, background, busy
OSDN Git Service
