**runcmd for system calls**

This call is a robust tool for passing requests not to
"system" from Perl but to "IPC::Open3::open3";

Everything you need to use it is in CondorUtils.pm
and a sample usage script is in condor_tests/run_cmd.pl.
It is used in all the key testing Perl modules and batch_test.pl

Calling it in its basic form is only different from "system"
in spelling:

system("ps -ef"); {linebreak}
runcmd("ps -ef"); {linebreak}

However the behavior is quite different as is the return. Runcmd
takes an optional hash after the string allowing you to control
its default behaviors. Additionally it returns a reference to a hash
containing an assortment of things.

There is an alternate calling method. For places already expecting
to check the return code you can still use it by calling:

my $ret = verbose_system("ps -ef");

Both of these function accept an optional hash of args.

The four default behaviors and their defaults are:

expect_result                      PASS {linebreak}
die_on_failed_expectation          TRUE {linebreak}
emit_output                        TRUE  {linebreak}
use_system                         FALSE {linebreak}

There are a number of predefined results which you can pass in
in this form:

runcmd("ls",{expect_result=>\&FAIL});

PASS, FAIL, ANY, SIGNALED or SIGNAL.

If you'd like it quiet unless there is a failed expectation....

runcmd("ls",{expect_result=>\&FAIL,emit_output=>0});

Returns a reference to a hash filled as follows:

$returnthings{"signal"} = $signal; {linebreak}
$returnthings{"success"} = $rc; {linebreak}
$returnthings{"exitcode"} = $rc; {linebreak}
$returnthings{"stdout"} = \@outlines; {linebreak}
$returnthings{"stderr"} = \@errlines; {linebreak}
$returnthings{"expectation"} = $expected; {linebreak}