1IPC::System::Simple(3)User Contributed Perl DocumentationIPC::System::Simple(3)
2
6 IPC::System::Simple - Run commands simply, with detailed diagnostics
7
9 use IPC::System::Simple qw(system systemx capture capturex);
10 system("some_command"); # Command succeeds or dies!
12 system("some_command",@args); # Succeeds or dies, avoids shell if @args
14 systemx("some_command",@args); # Succeeds or dies, NEVER uses the shell
16 # Capture the output of a command (just like backticks). Dies on error.
19 my $output = capture("some_command");
20 # Just like backticks in list context. Dies on error.
22 my @output = capture("some_command");
23 # As above, but avoids the shell if @args is non-empty
25 my $output = capture("some_command", @args);
26 # As above, but NEVER invokes the shell.
28 my $output = capturex("some_command", @args);
29 my @output = capturex("some_command", @args);
30
32 Calling Perl's in-built "system()" function is easy, determining if it
33 was successful is hard. Let's face it, $? isn't the nicest variable in
34 the world to play with, and even if you do check it, producing a well-
35 formatted error string takes a lot of work.
36 "IPC::System::Simple" takes the hard work out of calling external
38 commands. In fact, if you want to be really lazy, you can just write:
39 use IPC::System::Simple qw(system);
41 and all of your "system" commands will either succeed (run to
43 completion and return a zero exit value), or die with rich diagnostic
44 messages.
45 The "IPC::System::Simple" module also provides a simple replacement to
47 Perl's backticks operator. Simply write:
48 use IPC::System::Simple qw(capture);
50 and then use the "capture()" command just like you'd use backticks. If
52 there's an error, it will die with a detailed description of what went
53 wrong. Better still, you can even use "capturex()" to run the
54 equivalent of backticks, but without the shell:
55 use IPC::System::Simple qw(capturex);
57 my $result = capturex($command, @args);
59 If you want more power than the basic interface, including the ability
61 to specify which exit values are acceptable, trap errors, or process
62 diagnostics, then read on!
63
65 use IPC::System::Simple qw(
66 capture capturex system systemx run runx $EXITVAL EXIT_ANY
67 );
68 # Run a command, throwing exception on failure
70 run("some_command");
72 runx("some_command",@args); # Run a command, avoiding the shell
74 # Do the same thing, but with the drop-in system replacement.
76 system("some_command");
78 systemx("some_command", @args);
80 # Run a command which must return 0..5, avoid the shell, and get the
82 # exit value (we could also look at $EXITVAL)
83 my $exit_value = runx([0..5], "some_command", @args);
85 # The same, but any exit value will do.
87 my $exit_value = runx(EXIT_ANY, "some_command", @args);
89 # Capture output into $result and throw exception on failure
91 my $result = capture("some_command");
93 # Check exit value from captured command
95 print "some_command exited with status $EXITVAL\n";
97 # Captures into @lines, splitting on $/
99 my @lines = capture("some_command");
100 # Run a command which must return 0..5, capture the output into
102 # @lines, and avoid the shell.
103 my @lines = capturex([0..5], "some_command", @args);
105
107 run() and system()
108 "IPC::System::Simple" provides a subroutine called "run", that executes
109 a command using the same semantics is Perl's built-in "system":
110 use IPC::System::Simple qw(run);
112 run("cat *.txt"); # Execute command via the shell
114 run("cat","/etc/motd"); # Execute command without shell
115 The primary difference between Perl's in-built system and the "run"
117 command is that "run" will throw an exception on failure, and allows a
118 list of acceptable exit values to be set. See "Exit values" for
119 further information.
120 In fact, you can even have "IPC::System::Simple" replace the default
122 "system" function for your package so it has the same behaviour:
123 use IPC::System::Simple qw(system);
125 system("cat *.txt"); # system now suceeds or dies!
127 "system" and "run" are aliases to each other.
129 See also "runx(), systemx() and capturex()" for variants of "system()"
131 and "run()" that never invoke the shell, even with a single argument.
132 capture()
134 A second subroutine, named "capture" executes a command with the same
135 semantics as Perl's built-in backticks (and "qx()"):
136 use IPC::System::Simple qw(capture);
138 # Capture text while invoking the shell.
140 my $file = capture("cat /etc/motd");
141 my @lines = capture("cat /etc/passwd");
142 However unlike regular backticks, which always use the shell, "capture"
144 will bypass the shell when called with multiple arguments:
145 # Capture text while avoiding the shell.
147 my $file = capture("cat", "/etc/motd");
148 my @lines = capture("cat", "/etc/passwd");
149 See also "runx(), systemx() and capturex()" for a variant of
151 "capture()" that never invokes the shell, even with a single argument.
152 runx(), systemx() and capturex()
154 The "runx()", "systemx()" and "capturex()" commands are identical to
155 the multi-argument forms of "run()", "system()" and "capture()"
156 respectively, but never invoke the shell, even when called with a
157 single argument. These forms are particularly useful when a command's
158 argument list might be empty, for example:
159 systemx($cmd, @args);
161 The use of "systemx()" here guarantees that the shell will never be
163 invoked, even if @args is empty.
164 Exception handling
166 In the case where the command returns an unexpected status, both "run"
167 and "capture" will throw an exception, which if not caught will
168 terminate your program with an error.
169 Capturing the exception is easy:
171 eval {
173 run("cat *.txt");
174 };
175 if ($@) {
177 print "Something went wrong - $@\n";
178 }
179 See the diagnostics section below for more details.
181 Exception cases
183 "IPC::System::Simple" considers the following to be unexpected, and
185 worthy of exception:
186 · Failing to start entirely (eg, command not found, permission
188 denied).
189 · Returning an exit value other than zero (but see below).
191 · Being killed by a signal.
193 · Being passed tainted data (in taint mode).
195 Exit values
197 Traditionally, system commands return a zero status for success and a
198 non-zero status for failure. "IPC::System::Simple" will default to
199 throwing an exception if a non-zero exit value is returned.
200 You may specify a range of values which are considered acceptable exit
202 values by passing an array reference as the first argument. The
203 special constant "EXIT_ANY" can be used to allow any exit value to be
204 returned.
205 use IPC::System::Simple qw(run system capture EXIT_ANY);
207 run( [0..5], "cat *.txt"); # Exit values 0-5 are OK
209 system( [0..5], "cat *.txt"); # This works the same way
211 my @lines = capture( EXIT_ANY, "cat *.txt"); # Any exit is fine.
213 The "run" and replacement "system" subroutines returns the exit value
215 of the process:
216 my $exit_value = run( [0..5], "cat *.txt");
218 # OR:
220 my $exit_value = system( [0..5] "cat *.txt");
222 print "Program exited with value $exit_value\n";
224 $EXITVAL
226 The exit value of any command executed by "IPC::System::Simple" can
228 always be retrieved from the $IPC::System::Simple::EXITVAL variable:
229 This is particularly useful when inspecting results from "capture",
231 which returns the captured text from the command.
232 use IPC::System::Simple qw(capture $EXITVAL EXIT_ANY);
234 my @enemies_defeated = capture(EXIT_ANY, "defeat_evil", "/dev/mordor");
236 print "Program exited with value $EXITVAL\n";
238 $EXITVAL will be set to "-1" if the command did not exit normally (eg,
240 being terminated by a signal) or did not start. In this situation an
241 exception will also be thrown.
242 WINDOWS-SPECIFIC NOTES
244 As of "IPC::System::Simple" v0.06, the "run" subroutine when called
245 with multiple arguments will make available the full 32-bit exit value
246 on Win32 systems. This is different from the previous versions of
247 "IPC::System::Simple" and from Perl's in-build "system()" function,
248 which can only handle 8-bit return values.
249 The "capture" subroutine always returns the 32-bit exit value under
251 Windows. The "capture" subroutine also never uses the shell, even when
252 passed a single argument.
253 Versions of "IPC::System::Simple" before v0.09 would not search the
255 "PATH" environment variable when the multi-argument form of "run()" was
256 called. Versions from v0.09 onwards correctly search the path provided
257 the command is provided including the extension (eg, "notepad.exe"
258 rather than just "notepad", or "gvim.bat" rather than just "gvim"). If
259 no extension is provided, ".exe" is assumed.
260 Signals are not supported on Windows systems. Sending a signal to a
262 Windows process will usually cause it to exit with the signal number
263 used.
264
266 "%s" failed to start: "%s"
267 The command specified did not even start. It may not exist, or you
268 may not have permission to use it. The reason it could not start
269 (as determined from $!) will be provided.
270 "%s" unexpectedly returned exit value %d
272 The command ran successfully, but returned an exit value we did not
273 expect. The value returned is reported.
274 "%s" died to signal "%s" (%d) %s
276 The command was killed by a signal. The name of the signal will be
277 reported, or "UNKNOWN" if it cannot be determined. The signal
278 number is always reported. If we detected that the process dumped
279 core, then the string "and dumped core" is appended.
280 IPC::System::Simple::%s called with no arguments
282 You attempted to call "run" or "capture" but did not provide any
283 arguments at all. At the very lease you need to supply a command
284 to run.
285 IPC::System::Simple::%s called with no command
287 You called "run" or "capture" with a list of acceptable exit
288 values, but no actual command.
289 IPC::System::Simple::%s called with tainted argument "%s"
291 You called "run" or "capture" with tainted (untrusted) arguments,
292 which is almost certainly a bad idea. To untaint your arguments
293 you'll need to pass your data through a regular expression and use
294 the resulting match variables. See "Laundering and Detecting
295 Tainted Data" in perlsec for more information.
296 IPC::System::Simple::%s called with tainted environment $ENV{%s}
298 You called "run" or "capture" but part of your environment was
299 tainted (untrusted). You should either delete the named
300 environment variable before calling "run", or set it to an
301 untainted value (usually one set inside your program). See
302 "Cleaning Up Your Path" in perlsec for more information.
303 Error in IPC::System::Simple plumbing: "%s" - "%s"
305 Implementing the "capture" command involves dark and terrible
306 magicks involving pipes, and one of them has sprung a leak. This
307 could be due to a lack of file descriptors, although there are
308 other possibilities.
309 If you are able to reproduce this error, you are encouraged to
311 submit a bug report according to the "Reporting bugs" section
312 below.
313 Internal error in IPC::System::Simple: "%s"
315 You've found a bug in "IPC::System::Simple". Please check to see
316 if an updated version of "IPC::System::Simple" is available. If
317 not, please file a bug report according to the "Reporting bugs"
318 section below.
319 IPC::System::Simple::%s called with undefined command
321 You've passed the undefined value as a command to be executed.
322 While this is a very Zen-like action, it's not supported by Perl's
323 current implementation.
324
326 This module depends upon Win32::Process when used on Win32 system.
327 "Win32::Process" is bundled as a core module in ActivePerl 5.6 and
328 above.
329 There are no non-core dependencies on non-Win32 systems.
331
333 Perl provides a range of in-built functions for handling external
334 commands, and CPAN provides even more. The "IPC::System::Simple"
335 differentiates itself from other options by providing:
336 Extremely detailed diagnostics
338 The diagnostics produced by "IPC::System::Simple" are designed to
339 provide as much information as possible. Rather than requiring the
340 developer to inspect $?, "IPC::System::Simple" does the hard work
341 for you.
342 If an odd exit status is provided, you're informed of what it is.
344 If a signal kills your process, you are informed of both its name
345 and number. If tainted data or environment prevents your command
346 from running, you are informed of exactly which datais
347 Exceptions on failure
349 "IPC::System::Simple" takes an aggressive approach to error
350 handling. Rather than allow commands to fail silently, exceptions
351 are thrown when unexpected results are seen. This allows for easy
352 development using a try/catch style, and avoids the possibility of
353 accidently continuing after a failed command.
354 Easy access to exit status
356 The "run", "system" and "capture" commands all set $EXITVAL, making
357 it easy to determine the exit status of a command. Additionally,
358 the "system" and "run" interfaces return the exit status.
359 Consistent interfaces
361 When called with multiple arguments, the "run", "system" and
362 "capture" interfaces never invoke the shell. This differs from the
363 in-built Perl "system" command which may invoke the shell under
364 Windows when called with multiple arguments. It differs from the
365 in-built Perl backticks operator which always invokes the shell.
366
368 When "system" is exported, the exotic form "system { $cmd } @args" is
369 not supported. Attemping to use the exotic form is a syntax error.
370 This affects the calling package only. Use "CORE::system" if you need
371 it, or consider using the autodie module to replace "system" with
372 lexical scope.
373 Core dumps are only checked for when a process dies due to a signal.
375 It is not believed there are any systems where processes can dump core
376 without dying to a signal.
377 "WIFSTOPPED" status is not checked, as perl never spawns processes with
379 the "WUNTRACED" option.
380 Signals are not supported under Win32 systems, since they don't work at
382 all like Unix signals. Win32 singals cause commands to exit with a
383 given exit value, which this modules does capture.
384 Only 8-bit values are returned when "run()" or "system()" is called
386 with a single value under Win32. Multi-argument calls to "run()" and
387 "system()", as well as the "runx()" and "systemx()" always return the
388 32-bit Windows return values.
389 Reporting bugs
391 Before reporting a bug, please check to ensure you are using the most
392 recent version of "IPC::System::Simple". Your problem may have already
393 been fixed in a new release.
394 You can find the "IPC::System::Simple" bug-tracker at
396 <http://rt.cpan.org/Public/Dist/Display.html?Name=IPC-System-Simple> .
397 Please check to see if your bug has already been reported; if in doubt,
398 report yours anyway.
399 Submitting a patch and/or failing test case will greatly expedite the
401 fixing of bugs.
402
404 If you find this module useful, please consider rating it on the CPAN
405 Ratings service at
406 <http://cpanratings.perl.org/rate/?distribution=IPC-System-Simple> .
407 The module author loves to hear how "IPC::System::Simple" has made your
409 life better (or worse). Feedback can be sent to
410 <pjf@perltraining.com.au>.
411
413 autodie uses "IPC::System::Simple" to provide succeed-or-die
414 replacements to "system" (and other built-ins) with lexical scope.
415 POSIX, IPC::Run::Simple, perlipc, perlport, IPC::Run, IPC::Run3,
417 Win32::Process
418
420 Paul Fenwick <pjf@cpan.org>
421
423 Copyright (C) 2006-2008 by Paul Fenwick
424 This library is free software; you can redistribute it and/or modify it
426 under the same terms as Perl itself, either Perl version 5.6.0 or, at
427 your option, any later version of Perl 5 you may have available.
428perl v5.26.3 2013-10-20 IPC::System::Simple(3)