IPC::System::Simple - Call system() commands with a minimum of fuss
use IPC::System::Simple qw(run $EXITVAL);
run("some_command"); # Run a command and check exit status
run("some_command",@args); # Run a command, avoiding the shell
my $exit_value = run([0..5], "some_command", @args);
print "some_command exited with status $EXITVAL\n";
Calling Perl's in-built system() function is easy, but checking
the results can be hard. IPC::System::Simple aims to make
life easy for the common cases of calling system.
IPC::System::Simple provides a single subroutine, called
run, that executes a command using the same semantics is
Perl's built-in system:
use IPC::System::Simple qw(run);
run("cat *.txt"); # Execute command via the shell
run("cat","/etc/motd"); # Execute command without shell
In the case where the command returns an unexpected status,
run will throw an exception, which is not caught will terminate
your program with an error.
Capturing an the exception is easy:
eval {
run("cat *.txt");
};
if ($@) {
print "Something went wrong - $@\n";
}
See the diagnostics section below for more details.
IPC::System::Simple considers the following to be unexpected,
and worthy of exception:
Failing to start entirely (eg, command not found, permission denied).
Returning an exit value other than zero (but see below).
Being killed by a signal.
You may specify a range of values which are considered acceptable return values by passing an array reference as the first argument:
run( [0..5], "cat *.txt"); # Exit values 0-5 are OK
run( [0..255], "cat *.txt"); # Any exit value is OK
The run subroutine returns the exit value of the process:
my $exit_value = run( [0..5], "cat *.txt");
print "Program exited with value $exit_value\n";
After a call to run or capture the exit value of the command
is always available in $IPC::System::Simple::EXITVAL. This will
be set to -1 if the command did not exit normally (eg,
being terminated by a signal) or did not start.
As of IPC::System::Simple v0.06, the run subroutine when
called with multiple arguments will make available the full 16-bit
return value on Win32 systems. This is different from the
previous versions of IPC::System::Simple and from Perl's
in-build system() function, which can only handle 8-bit return values.
Signals are not supported on Windows systems. Sending a signal to a Windows process will usually cause it to exit with the signal number used.
You attempted to call run but did not provide any arguments at all.
You called run with a list of acceptable exit values, but no
actual command.
The command specified did not even start. It may not exist, or
you may not have permission to use it. The reason it could not
start (as determined from $!) will be provided.
The command ran successful, but returned an exit value we did not expect. The value returned is reported.
The command was killed by a signal. The name of the signal
will be reported, or UNKNOWN if it cannot be determined. The
signal number is always reported.
You've found a bug in IPC::System::Simple. It knows your command
ran successful, but doesn't know how or why it stopped. Please
report this error using the submission mechanism described in
BUGS below.
This module depends upon the Win32::Process manpage when used on Win32
system. Win32::Process is bundled as a core module in ActivePerl 5.6
and above.
There are no non-core dependencies on non-Win32 systems.
Reporting of core-dumps is not yet implemented.
WIFSTOPPED status is not checked.
Signals are not supported under Win32 systems.
16-bit exit values are provided when run() is called with multiple
arguments under Windows, but only 8-bit values are returned when
run() is called with a single value. We should always return 16-bit
value on systems that support them.
Please report bugs to http://rt.cpan.org/Public/Dist/Display.html .
the POSIX manpage the IPC::Run::Simple manpage the perlipc manpage the perlport manpage the IPC::Run manpage the Win32::Process manpage
Paul Fenwick <pjf@cpan.org>
Copyright (C) 2006-2007 by Paul Fenwick
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.