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

HISTORY

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     : #{ stdout.read.strip }"
  puts "stderr     : #{ stderr.read.strip }"
  puts "status     : #{ status.inspect }"
  puts "exitstatus : #{ status.exitstatus }"

  harp: > ruby sample/simple.rb
  pid        : 17273
  stdout     : 42.out
  stderr     : 42.err
  status     : #<Process::Status: pid=17273,exited(0)>
  exitstatus : 0

----------------------------------------------------------------------------
in block form - the child process is automatically waited for
----------------------------------------------------------------------------

  harp: > cat sample/block.rb
  require 'open4'

  status =
    Open4::popen4("sh") do |pid, stdin, stdout, stderr|
      stdin.puts "echo 42.out"
      stdin.puts "echo 42.err 1>&2"
      stdin.close

      puts "pid        : #{ pid }"
      puts "stdout     : #{ stdout.read.strip }"
      puts "stderr     : #{ stderr.read.strip }"
    end

      puts "status     : #{ status.inspect }"
      puts "exitstatus : #{ status.exitstatus }"

  harp: > ruby sample/block.rb
  pid        : 17295
  stdout     : 42.out
  stderr     : 42.err
  status     : #<Process::Status: pid=17295,exited(0)>
  exitstatus : 0

----------------------------------------------------------------------------
exceptions are marshaled from child to parent if fork/exec fails
----------------------------------------------------------------------------

  harp: > cat sample/exception.rb
  require "open4"
  Open4::popen4 "noexist"

  harp: > ruby sample/exception.rb
  /dmsp/reference/ruby-1.8.1//lib/ruby/site_ruby/open4.rb:100:in `popen4': No such file or directory - noexist (Errno::ENOENT)
          from sample/exception.rb:3

----------------------------------------------------------------------------
the spawn method provides and even more convenient method of running a
process, allowing any object that supports 'each', 'read', or 'to_s' to be
given as stdin and any objects that support '<<' to be given as
stdout/stderr.  an exception is thrown if the exec'd cmd fails (nonzero
exitstatus) unless the option 'raise'=>false is given
----------------------------------------------------------------------------

  harp: > cat sample/spawn.rb
  require 'open4'
  include Open4

  cat = '  ruby -e"  ARGF.each{|line| STDOUT << line}  "  '

  stdout, stderr = '', ''
  status = spawn cat, 'stdin' => '42', 'stdout' => stdout, 'stderr' => stderr
  p status
  p stdout
  p stderr

  stdout, stderr = '', ''
  status = spawn cat, 0=>'42', 1=>stdout, 2=>stderr
  p status
  p stdout
  p stderr

  harp: > RUBYLIB=lib ruby sample/spawn.rb
  0
  "42"
  ""
  0
  "42"
  ""

----------------------------------------------------------------------------
the bg/background method is similar to spawn, but the process is
automatically set running in a thread.  the returned thread has several
methods added dynamically which return the pid and blocking calls to the
exitstatus.
----------------------------------------------------------------------------

  harp: > cat sample/bg.rb
  require 'yaml'
  require 'open4'
  include Open4

  stdin = '42'
  stdout = ''
  stderr = ''

  t = bg 'ruby -e"sleep 4; puts ARGF.read"', 0=>stdin, 1=>stdout, 2=>stderr

  waiter = Thread.new{ y t.pid => t.exitstatus } # t.exitstatus is a blocking call!

  while((status = t.status))
    y "status" => status
    sleep 1
  end

  waiter.join

  y "stdout" => stdout

  harp: > ruby sample/bg.rb
  ---
  status: run
  ---
  status: sleep
  ---
  status: sleep
  ---
  status: sleep
  ---
  21357: 0
  ---
  stdout: "42\n"

AUTHOR

ara.t.howard@noaa.gov

LICENSE

ruby's