URIS

  http://rubyforge.org/frs/?group_id=1024
  http://www.codeforpeople.com/lib/ruby/

SYNOPSIS

  open child process with handles on pid, stdin, stdout, and stderr: manage
  child processes and their io handles easily.

HISTORY

  0.5.1:
    - fixes a __critical__ but in ThreadEnsemble class that had a race
      condition that could cause thread deadlock.  sorry bout that folks.

  0.5.0:
    - on the suggestion of tim pease (thanks tim!), i added timeout features
      to open4.  the command run may have an overall timeout and individual
      timeouts set for each of the io handles.  for example

        cmd = 'command_that_produce_out_at_one_second_intervals'

        open4.spawn cmd, :stdout_timeout => 2 

      or 

        cmd = 'command_that_should_complete_in_about_one_minute'

        open4.spawn cmd, :timeout => 60

      or

        cmd = 'consumes_input_at_one_line_per_second_rate'

        input = %w( 42 forty-two 42.0 )

        open4.spawn cmd, :stdin=>input, :stdin_timeout=>1

    - added 'open4' alias so one can write

        open4.spawn  vs Open4.spawn

      or even

        open4(cmd) do |pid,i,o,e|
        end

    - added signal info to SpawnError

  0.4.0:
    - improved error handling contributed by jordan breeding.
    - introduction of background/bg method

  0.3.0 :
    - bug fix from jordan breeding.  general clean up.  added spawn method.

  0.2.0 :
    - added exception marshaled from child -> parent when exec fails.  thanks
      to jordan breeding for a patch (yay!) and paul brannan for this most
      excellent idea.

  0.1.0 :
    - fixed docs to correctly show return value of popen4 (pid first not last).
      thanks Stefanie Tellex <stefie10@alum.mit.edu> for catching this. 
  0.0.0 :
    - initial version

INSTALL

  ~> gem install open4

SAMPLES

  ----------------------------------------------------------------------------
  simple usage
  ----------------------------------------------------------------------------

    harp: > cat sample/simple.rb
    require "open4"

    pid, stdin, stdout, stderr = Open4::popen4 "sh"

    stdin.puts "echo 42.out"
    stdin.puts "echo 42.err 1>&2"
    stdin.close

    ignored, status = Process::waitpid2 pid

    puts "pid        : #{ pid }"
    puts "stdout     : #{ st