HTCondorWiki: Run Cmd

 **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:
 
-Returns a reference to a hash
+system("ps -ef"); {linebreak}
+runcmd("ps -ef"); {linebreak}
 
-  $returnthings{"signal"} = $signal;
-  $returnthings{"success"} = $rc;
-  $returnthings{"exitcode"} = $rc;
-  $returnthings{"stdout"} = \@outlines;
-  $returnthings{"stderr"} = \@errlines;
-  $returnthings{"expectation"} = $expected;
+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}