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");
runcmd("ps -ef");
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
die_on_failed_expectation TRUE
emit_output TRUE
use_system FALSE
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;
$returnthings{"success"} = $rc;
$returnthings{"exitcode"} = $rc;
$returnthings{"stdout"} = \@outlines;
$returnthings{"stderr"} = \@errlines;
$returnthings{"expectation"} = $expected;