[[document arguments of this [BLT] command]]

Example of [stderr] capture:
        proc DisplayErrors { data } {
            puts "stderr> $data"
        }
        bgexec myVar -onerror DisplayErrors programName &

Also has -onoutput.

onerror sets up a callback so that when output appears on the stderr of programName, DisplayErrors is called with the string, and the proc can then do with it what it likes.  onoutput sets up a similar callback, watching stdout of programName .
----
[gah] writes,
"What I like about 'bgexec' is that it handles all the dumb stuff under
the hood--so you (the Tcl programmer) don't have to worry about it.
It automatically performs non-blocking I/O.  It collects data at
whatever rate, without you doing anything.  It raises the programming
problem from 'readable' events, non-blocking I/O, and buffer lengths,
to Tcl variables and procedure calls.  You don't have to be an expert
in I/O or process semantics.  If you want to kill the pipeline, all
you have to do is set a variable.  It's the same whether you're on
Windows or Unix or MacOSX."

[Vince] writes -- all wonderful reasons why this functionality really should go into Tcl's core.

[US] Ceterum censeo bgexec esse integrandam (Marcus Porcius Cato, slightly modified)

[KJN] I agree with all the above.  There's one further feature that I would like, which is the ability to open a file descriptor that is connected to the standard input of the first process in the pipeline, like "open |programName" does.  Then bgexec would combine the input-handling facilities of open, with the very convenient output-handling facilities already available in bgexec.  The new feature could be implemented as an option
  -input varName
that returns the file descriptor as $varName.

This functionality can be implemented in a roundabout way by using a pre-existing named pipe (e.g. /tmp/somepipe).  The trick mentioned below by [SLB] is also incorporated:

  proc putsout { data } {
     puts -nonewline $data
  }

  global myStatus

  set pipeID [open /tmp/somepipe r+] ;# this command does not block!
  bgexec myStatus -keepnewline 1 -onoutput putsout -onerror putsout programName <@$pipeID &

Now, the process programName runs in the background, and can be drip-fed input by writing to the file descriptor $pipeID; its output is collected one line at a time by putsout, which in this example writes to stdout, but can do whatever you like.

If you open a pipe for reading (i.e. with access option "r"), the open command will block unless the pipe is already open for writing (access option "w"); and vice versa!  The workaround used here is to open the pipe for both reading and writing (access option "r+"), and use the same file descriptor for both operations: there may be more elegant workarounds.

This code works a lot like "open |programName r+", but it's convenient not to have to deal with fileevent and output collection - bgexec does this for us, and so our program is very short: only 6 lines of code.

----
[SLB] One point about bgexec that tripped me up recently was in using a command such as this:

    ::blt::bgexec ::bgexecStatus -linebuffer 1 -onerror puts -onoutput puts cat file.txt &

This reported all lines in file.txt except for the blank lines.

If you want the blank lines to can change the command to this:

    ::blt::bgexec ::bgexecStatus -linebuffer 1 -keepnewline 1 -onerror {puts -nonewline} -onoutput {puts -nonewline} cat file.txt &


keepnewline mode has the
documented effect of adding a trailing newline to each line of output and an undocumented
effect of retaining blank lines.

bgexec.html says that keepnewline mode is the default, this seems to be incorrect.

This behaviour is present 2.4z on both Windows and Solaris.

----
For a pure tcl-implementation of bgexec, see [Matthias Hoffmann - Tcl-Code-Snippets]. Sorry, if I had known that a bgexec exists I had used a different proc name...
----