--- /dev/null
+'\"
+'\" Copyright 1991-1997 by Bell Labs Innovations for Lucent Technologies.
+'\"
+'\" Permission to use, copy, modify, and distribute this software and its
+'\" documentation for any purpose and without fee is hereby granted, provided
+'\" that the above copyright notice appear in all copies and that both that the
+'\" copyright notice and warranty disclaimer appear in supporting documentation,
+'\" and that the names of Lucent Technologies any of their entities not be used
+'\" in advertising or publicity pertaining to distribution of the software
+'\" without specific, written prior permission.
+'\"
+'\" Lucent Technologies disclaims all warranties with regard to this software,
+'\" including all implied warranties of merchantability and fitness. In no event
+'\" shall Lucent Technologies be liable for any special, indirect or
+'\" consequential damages or any damages whatsoever resulting from loss of use,
+'\" data or profits, whether in an action of contract, negligence or other
+'\" tortuous action, arising out of or in connection with the use or performance
+'\" of this software.
+'\"
+'\" Bgexec command created by George Howlett.
+'\"
+.so man.macros
+.TH bgexec n BLT_VERSION BLT "BLT Built-In Commands"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+bgexec \- Run programs in the background while handling Tk events.
+kill \- Terminate program or send signal.
+.SH SYNOPSIS
+\fBblt::bgexec \fIvarName\fR ?\fIswitches\fR? \fIprogram\fR ?\fIarg\fR?...
+.br
+\fBblt::kill \fIprocessid\fR ?\fIsignal\fR?
+.BE
+.SH DESCRIPTION
+.PP
+The \fBkill\fR command terminates a \fIprocessid\fR or under unix
+sends a signal.
+.PP
+The \fBbgexec\fR command executes a \fIprogram\fR pipleline using
+the \fBTcl\fR event-loop allowing other events to continue to be serviced.
+Upon completion it sets the global variable \fIvarName\fR with
+a list of 4 status values: a text token, the process-id, the exit code,
+and a text message.
+\fBBgexec\fR provides capabilities similar to the \fBexec\fR command,
+but with added support for callbacks, output to variables and termination.
+.PP
+When used with no options,
+the returned value from \fBbgexec\fR is the output from the \fIprogram\fR.
+But when the last \fIarg\fR is an ampersand (&)
+the \fIprogram\fR runs detached, and
+\fBbgexec\fR immediately returns with a list of the process ids
+created in the command pipeline.
+Detached processes can be interrupted and terminated simply by setting
+\fIvarName\fR.
+.PP
+The valid \fIswitches\fR are as follows:
+.TP
+\fB\-check \fInum\fR
+Interval in ms to poll for the exiting processes.
+The default is 1000.
+.TP
+\fB\-closeonkill \fImillisecs\fR
+Force close of stdin/stdout on kill after the given interval.
+This lets kill finalize processes, even
+uninterruptably sleeping ones unable to receive signals.
+The default is \fB0\fR for do not force close.
+.TP
+\fB\-command \fIscript\fR
+Specifies a command to call upon command completion/termination.
+Two extra arguments are appended before the call.
+The data output from the command, and the status info as set
+into \fIvarName\fR.
+.TP
+\fB\-decodeerror \fIencodingName\fR
+Specifies the encoding of the stderr channel.
+This affects only data returned to the Tcl interpreter. No translation
+is done on file redirection.
+For example if data is to be converted from Unicode for use in Tcl,
+you would use the "unicode" encoding. The default is that no
+tranlation is performed.
+.TP
+\fB\-decodeoutput \fIencodingName\fR
+Specifies the encoding of the stdout channels.
+This affects only data returned to the Tcl interpreter. No translation
+is done on file redirection.
+For example if data is to be converted from Unicode for use in Tcl,
+you would use the "unicode" encoding. The default is that no
+tranlation is performed.
+.TP
+\fB\-echo \fIboolean\fR
+Indicates if the pipeline's stderr stream should be echoed.
+\fINote: this option is deprecated.\fR
+.TP
+\fB\-error \fIvarName\fR
+Specifies that a global variable \fIvarName\fR is to be set with the
+contents of stderr after the program has completed.
+.TP
+\fB\-keepnewline \fIboolean\fR
+Specifies that a trailing newline should be retained in the
+output. If \fIboolean\fR is true, the trailing newline is truncated
+from the output of the \fB\-onoutput\fR and \fB\-output\fR variables.
+The default value is \fBtrue\fR.
+.TP
+\fB\-killsignal \fIsignal\fR
+Specifies the signal to be sent to the program when
+terminating. This option is available only on Unix.
+\fISignal\fR can either be a number (typically 1-32) or
+a mnemonic (such as SIGINT). If \fIsignal\fR is the empty string,
+then no signal is sent. The default signal is \fB9\fR (SIGKILL).
+.TP
+\fB\-lasterror \fIvarName\fR
+Specifies a variable \fIvarName\fR that is updated whenever data
+becomes available from standard error of the program.
+\fIVarName\fR is a global variable. Unlike the \fB\-error\fR option,
+data is available as soon as it arrives.
+.TP
+\fB\-lastoutput \fIvarName\fR
+Specifies a variable \fIvarName\fR that is updated whenever data
+becomes available from standard output of the program.
+\fIVarName\fR is a global variable. Unlike the \fB\-output\fR option,
+data is available as soon as it arrives.
+.TP
+\fB\-limit \fInumBytes\fR
+Limit the size of the returned data to \fInumBytes\fR,
+terminating the program if exceeded.
+The limit applies to both stdout and stderr.
+.TP
+\fB\-linebuffered \fIboolean\fR
+Specifies that updates should be made on a line-by-line basis.
+Normally when new data is available \fBbgexec\fR will set the variable
+(\fB\-lastoutput\fR and \fB\-lasterror\fR options) or invoke the
+command (\fB\-onoutput\fR and \fB\-onerror\fR options) delivering all
+the new data currently available. If \fIboolean\fR is true, only one
+line at a time will be delivered. This can be useful when you want to
+process the output on a line-by-line basis.
+The default value is
+\fBfalse\fR.
+.TP
+\fB\-local \fIboolean\fR
+When \fIboolean\fR is true, any unqualified variables or command options
+are treated as local to the current namespace.
+This is mostly useful for non-detaching (no ampersand) commands.
+Note that using this flag with a detached command will
+use variables from the current namespace, not from the
+current proc stack-frame.
+.TP
+\fB\-onerror \fIcommand\fR
+Specifies the start of a Tcl command that will be executed
+whenever new data is available from standard error. The data
+is appended to the command as an extra argument before it is
+executed.
+.TP
+\fB\-onoutput \fIcommand\fR
+Specifies the start of a Tcl command that will be executed
+whenever new data is available from standard output. The data
+is appended to the command as an extra argument before it is
+executed.
+.TP
+\fB\-output \fIvarName\fR
+Specifies a global variable \fIvarName\fR to be set with the
+output of the program, upon completion.
+.TP
+\fB\-raise \fIboolean\fR
+When \fIboolean\fR is \fBtrue\fR, a non-zero return code from a
+non-detached command will raise an error (.ie emulates \fBexec\fR).
+The default is \fBfalse\fR an error is generated only if
+one of the following occurs: invalid
+options are given, a redirection error,
+or process creation failure (eg. executable program not found).
+Detached commands, of course, never raise an error
+on a non-zero return code.
+.TP
+\fB\-\|\-\fR
+This marks the end of the options. The following argument will
+be considered the name of a program even if it starts with
+a dash (\fB\-\fR).
+.SH USAGE
+Invoking \fBbgexec\fR without a trailing ampersand
+will block and wait for result. However, other Tcl
+events continue to be serviced. This prevents Tcl from hanging, eg:
+.PP
+.CS
+pack [text .t]
+set val [blt::bgexec myStatus du -s]
+.CE
+.PP
+Note that text widget .t continues to respond to events.
+.SH CALLBACKS
+Here is an example that invokes the Unix \fBdu\fR program
+with a \fB-command\fR callback.
+.PP
+.CS
+proc Done {data status} { puts "Done($status)\\n$data" }
+
+blt::bgexec myStatus -command Done du -s $dir &
+.CE
+.PP
+When \fBdu\fR has completed,
+the handler \fBDone\fR is called with data and status.
+Also, the global variable \fImyStatus\fR is set
+to contain the program's exit status, eg:
+.PP
+.CS
+EXITED 26811 0 {child completed normally}
+.CE
+.PP
+If \fImyStatus\fR is set before \fBdu\fR has
+completed, the process will be killed. Under Unix, this sends
+a signal (SIGKILL by default). Under Win32,
+\fBTerminateProcess\fR is called.
+.PP
+.SH VARIABLE
+Here is another example, this time using the \fB-output\fR option
+to direct output to a variable.
+.PP
+.CS
+global myStatus myOutput
+blt::bgexec myStatus -output myOutput du -s $dir
+puts "Disk usage for $dir is $myOutput"
+.CE
+.PP
+Upon completion, \fBMyOutput\fR will contain the output of the program.
+.SH STDERR
+Various \fBbgexec\fR options can be used
+to capture \fBstderr\fR separately from \fBstdout\fR.
+.PP
+.CS
+global myStatus myOutput myErrs
+blt::bgexec myStatus -output myOutput -error myErrs du -s $dir
+.CE
+.PP
+The \fB\-error\fR option is similar to \fB\-output\fR in that it sets a
+variable when the program completes with data written to stderr.
+.PP
+.SH LOCAL
+By default, \fBbgexec\fR treats variable or command options
+as being in the global namespace.
+The \fB-local\fR option can change this to use the current namespace.
+Thus data can be collected to namespace-local variables even those
+inside of procs, eg.
+.CS
+proc Work {} {
+ blt::bgexec myStatus -local 1 -output val -error err du -s
+ puts "VAL=$val"
+ puts "ERR=$err"
+}
+.CE
+which collects data to local variables.
+.PP
+For detached processes, \fB-local\fR will cause
+data to aggregate to namespace variables, ie. outside the proc, eg.
+.CS
+namespace eval ::Ns {
+ set pval {}
+ set perr {}
+ proc Work {} {
+ blt::bgexec myStatus -local 1 -output pval -error perr du -s &
+ }
+}
+.CE
+This collects data to \fB::Ns::pval\fR and stderr to \fB::Ns::perr\fR.
+Similarly, proc names (eg \fB-onoutput\fR) will be relative to the current namespace.
+.PP
+.SH PROGRESS
+The \fB\-output\fR and \fB\-error\fR variables are set only
+after the program completes. But if a program runs for a long time,
+you can gather data
+as it becomes available using the \fB\-onoutput\fR option.
+As new data becomes available, this
+command is executed, with data appended as an argument.
+.PP
+.CS
+proc GetInfo { data } { puts $data }
+
+blt::bgexec myStatus -onoutput GetInfo du -s $dir
+.CE
+.PP
+The \fB\-onerror\fR option performs a similar function for the stderr
+data stream.
+.PP
+.SH ERROR HANDLING
+Like \fBexec\fR, \fBbgexec\fR returns an error if the exit code of the
+program is non-zero. To handle this
+invoke \fBbgexec\fR from within a \fBcatch\fR.
+.PP
+.CS
+catch { blt::bgexec myStatus -output myOutput du -s $dir }
+.CE
+.PP
+Detached jobs will generate an error only if the program startup
+failed. Otherwise the only indication is
+the status code set in \fImyStatus\fR.
+.SH TKWAIT
+By default, \fBbgexec\fR waits for a program to finish and
+returns the resulting output.
+To detach a program simply append an ampersand (&) as the last
+argument on the command line, eg.
+.PP
+.CS
+global myStatus myOutput
+blt::bgexec myStatus -output myOutput du -s $dir &
+.CE
+.PP
+\fBBgexec\fR will then return immediately with
+the spawned process ids as the result. If needed
+\fBtkwait\fR can be used to wait for the program to finish:
+.PP
+.CS
+global myStatus myOutput
+blt::bgexec myStatus -output myOutput du -s $dir &
+ ...
+tkwait variable myStatus
+.CE
+.PP
+Note however that using \fBtkwait\fR can be dangerous.
+Multiple \fBtkwait\fR/\fBvwait\fR calls must complete
+in the reverse order called.
+The BLT \fBbusy\fR command can be used to try and enforce this,
+but a better alternative is to just use \fB-command\fR instead.
+.SH DIFFERENCES WITH EXEC
+Using \fBbgexec\fR without an ampersand will not hang Tcl: events
+continue to be serviced by the event handler while the call blocks.
+Also unlike \fBexec\fR, an error will not be generated if output is
+appears on \fBstderr\fR. And output from \fBstderr\fR can be separately
+managed and collected (without having to redirect to files).
+Finally, \fBbgexec\fR ensures that invoked processes get properly
+cleaned up at termination.
+.SH DIFFERENCES WITH FILEEVENT
+Since Tk 4.0, a subset of \fBbgexec\fR can be achieved using the
+\fBfileevent\fR command. The steps for running a program in the
+background are:
+.PP
+Execute the program with the \fBopen\fR command (using the "|"
+syntax) and save the file handle.
+.CS
+ global fileId
+ set fileId [open "|du -s $dir" r]
+.CE
+Next register a Tcl code snippet with \fBfileevent\fR to be run
+whenever output is available on the file handle. The code snippet
+will read from the file handle and save the output in a variable.
+.CS
+fileevent fileId readable {
+ if { [gets $fileId line] < 0 } {
+ close $fileId
+ set output $temp
+ unset fileId temp
+ } else {
+ append temp $line
+ }
+}
+.CE
+.PP
+However,
+\fBBgexec\fR is simpler and less error prone than using
+\fBopen\fR + \fBfileevent\fR.
+You don't have to worry about non-blocking I/O.
+Everything is handled for you automatically.
+.PP
+Moreover, \fBbgexec\fR can run programs that \fBfileevent\fR can not.
+\fBFileevent\fR assumes that the when stdout is closed the program has
+completed. But some programs, like the Unix \fBcompress\fR program,
+reopen stdout, fooling \fBfileevent\fR into thinking the program has
+terminated. In the example above, we assume that the program will
+write and flush its output line-by-line. However when running another
+program, your application can block in the \fBgets\fR command reading
+a partial line.
+.PP
+\fBBgexec\fR gives you get back the exit status of the program.
+It also lets you reliably kill detached processes and
+allows you to collect data from both stdout and stderr individually.
+Finally, since data collection is handled in C code, \fBbgexec\fR is
+faster and more efficient.
+.SH SEE ALSO
+busy, exec, tkwait, vwait
+.SH KEYWORDS
+exec, background, busy
OSDN Git Service
