URIS

  http://rubyforge.org/projects/codeforpeople/
  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.9.5:
    - another patch from Corey Jewett, this time dealing with ruby's handling
      of chdir and threads.  basically the 'cwd' keyword to open4 cannot work
      with multiple threads (aka background) because ruby cannot cause green
      threads to have an actuall different working dir.  the moral is that the
      :cwd/'cwd' keyword to spawn will work with 0 or 1 threads in effect.
  
  0.9.4:
    - patch to #background from Corey Jewett


  0.9.3:
    - removed some debugging output accidentally left in 0.9.2.  arggh!

  0.9.2:
    - fixed a descriptor leak.  thanks Andre Nathan.

  0.9.1:
    - fixed warning with '-w' : @cid not initialized.  thanks blaise tarr.

  0.9.0:
    - added the ability for open4.spawn to take either an array of arguments
      or multiple arguments in order to specify the argv for the command run.
      for example

        open4.spawn ['touch', 'difficult to "quote"'], :stdout=>STDOUT

      same thing

        open4.spawn 'touch', 'difficult to "quote"', :stdout=>STDOUT

      thanks to jordan breeding for this suggestion


    - added 'cwd'/:cwd keyword.  usage is pretty obivous

        open4.spawn 'pwd', 1=>STDOUT, :cwd=>'/tmp'   #=> /tmp

      this one also from jordan

  0.8.0:

    - fixed a critical bug whereby a process producing tons of stdout, but for
      which the stdout was not handled, would cause the child process to
      become blocked/hung writing to the pipe.  eg, this command would cause a
      hang

        include Open4

        spawn 'ruby -e"  puts Array.new(65536){ 42 }  "'

      whereas this one would not

        include Open4

        spawn 'ruby -e"  puts Array.new(65536){ 42 }  "', :stdout=>StringIO.new

      this version handles the former by spawning a 'null' thread which reads,
      but does not process stdout/stderr.  that way commands which generate
      tons of output will never become blocked.

  0.7.0:
    - merged functionality of exitstatus/status keywords:

        include Open4

        spawn 'ruby -e "exit 42"'                 # raises 
        spawn 'ruby -e "exit 42"', :status=>true  # ok, returns status
        spawn 'ruby -e "exit 42"', :status=>42    # raises if status != 42
        spawn 'ruby -e "exit 42"', :status=>0,42  # raises if status != 0||42

    - the 0.6.0 was broken on rubyforge... this release fixes that (somehow!?)

  0.6.0:
    - added feature for exitstatus to be list of acceptable exit statuses

        Open4.spawn 'ruby -e "exit 42"'                      # raises
        Open4.spawn 'ruby -e "exit 42"', :exitstatus=>[0,42] # ok

    - added :status switch, which will always simply return the status (no
      error thrown for failure)

        Open4.spawn 'ruby -e "exit 42"'                          # raises 
        status = Open4.spawn 'ruby -e "exit 42"', :status=>true  # ok 

      note, however, that any SpawnError does in fact contain the failed
      status so, even when they are thrown, error status can be retrieved:

        include Open4

        status =
          begin
            spawn 'ruby -e "exit 42"'
          rescue Spa