[eos/base.git] / util / src / TclTk / blt2.5 / man / bgexec.mann

'\"
'\" 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