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 as 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 succeeds 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 The "run" subroutine make available the full 32-bit exit value on Win32
245 systems. This has been true since "IPC::System::Simple" v0.06 when
246 called with multiple arguments, and since v1.25 when called with a
247 single argument. This is different from the previous versions of
248 "IPC::System::Simple" and from Perl's in-build "system()" function,
249 which can only handle 8-bit return values.
250 The "capture" subroutine always returns the 32-bit exit value under
252 Windows. The "capture" subroutine also never uses the shell, even when
253 passed a single argument.
254 The "run" subroutine always uses a shell when passed a single argument.
256 On NT systems, it uses "cmd.exe" in the system root, and on non-NT
257 systems it uses "command.com" in the system root.
258 As of "IPC::System::Simple" v1.25, the "runx" and "capturex"
260 subroutines, as well as multiple-argument calls to the "run" and
261 "capture" subroutines, have their arguments properly quoted, so that
262 arugments with spaces and the like work properly. Unfortunately, this
263 breaks any attempt to invoke the shell itself. If you really need to
264 execute "cmd.exe" or "command.com", use the single-argument form. For
265 single-argument calls to "run" and "capture", the argument must be
266 properly shell-quoted in advance of the call.
267 Versions of "IPC::System::Simple" before v0.09 would not search the
269 "PATH" environment variable when the multi-argument form of "run()" was
270 called. Versions from v0.09 onwards correctly search the path provided
271 the command is provided including the extension (eg, "notepad.exe"
272 rather than just "notepad", or "gvim.bat" rather than just "gvim"). If
273 no extension is provided, ".exe" is assumed.
274 Signals are not supported on Windows systems. Sending a signal to a
276 Windows process will usually cause it to exit with the signal number
277 used.
278
280 "%s" failed to start: "%s"
281 The command specified did not even start. It may not exist, or you
282 may not have permission to use it. The reason it could not start
283 (as determined from $!) will be provided.
284 "%s" unexpectedly returned exit value %d
286 The command ran successfully, but returned an exit value we did not
287 expect. The value returned is reported.
288 "%s" died to signal "%s" (%d) %s
290 The command was killed by a signal. The name of the signal will be
291 reported, or "UNKNOWN" if it cannot be determined. The signal
292 number is always reported. If we detected that the process dumped
293 core, then the string "and dumped core" is appended.
294 IPC::System::Simple::%s called with no arguments
296 You attempted to call "run" or "capture" but did not provide any
297 arguments at all. At the very lease you need to supply a command
298 to run.
299 IPC::System::Simple::%s called with no command
301 You called "run" or "capture" with a list of acceptable exit
302 values, but no actual command.
303 IPC::System::Simple::%s called with tainted argument "%s"
305 You called "run" or "capture" with tainted (untrusted) arguments,
306 which is almost certainly a bad idea. To untaint your arguments
307 you'll need to pass your data through a regular expression and use
308 the resulting match variables. See "Laundering and Detecting
309 Tainted Data" in perlsec for more information.
310 IPC::System::Simple::%s called with tainted environment $ENV{%s}
312 You called "run" or "capture" but part of your environment was
313 tainted (untrusted). You should either delete the named
314 environment variable before calling "run", or set it to an
315 untainted value (usually one set inside your program). See
316 "Cleaning Up Your Path" in perlsec for more information.
317 Error in IPC::System::Simple plumbing: "%s" - "%s"
319 Implementing the "capture" command involves dark and terrible
320 magicks involving pipes, and one of them has sprung a leak. This
321 could be due to a lack of file descriptors, although there are
322 other possibilities.
323 If you are able to reproduce this error, you are encouraged to
325 submit a bug report according to the "Reporting bugs" section
326 below.
327 Internal error in IPC::System::Simple: "%s"
329 You've found a bug in "IPC::System::Simple". Please check to see
330 if an updated version of "IPC::System::Simple" is available. If
331 not, please file a bug report according to the "Reporting bugs"
332 section below.
333 IPC::System::Simple::%s called with undefined command
335 You've passed the undefined value as a command to be executed.
336 While this is a very Zen-like action, it's not supported by Perl's
337 current implementation.
338
340 This module depends upon Win32::Process when used on Win32 system.
341 "Win32::Process" is bundled as a core module in ActivePerl 5.6 and
342 above.
343 There are no non-core dependencies on non-Win32 systems.
345
347 Perl provides a range of in-built functions for handling external
348 commands, and CPAN provides even more. The "IPC::System::Simple"
349 differentiates itself from other options by providing:
350 Extremely detailed diagnostics
352 The diagnostics produced by "IPC::System::Simple" are designed to
353 provide as much information as possible. Rather than requiring the
354 developer to inspect $?, "IPC::System::Simple" does the hard work
355 for you.
356 If an odd exit status is provided, you're informed of what it is.
358 If a signal kills your process, you are informed of both its name
359 and number. If tainted data or environment prevents your command
360 from running, you are informed of exactly which data or
361 environmental variable is tainted.
362 Exceptions on failure
364 "IPC::System::Simple" takes an aggressive approach to error
365 handling. Rather than allow commands to fail silently, exceptions
366 are thrown when unexpected results are seen. This allows for easy
367 development using a try/catch style, and avoids the possibility of
368 accidentally continuing after a failed command.
369 Easy access to exit status
371 The "run", "system" and "capture" commands all set $EXITVAL, making
372 it easy to determine the exit status of a command. Additionally,
373 the "system" and "run" interfaces return the exit status.
374 Consistent interfaces
376 When called with multiple arguments, the "run", "system" and
377 "capture" interfaces never invoke the shell. This differs from the
378 in-built Perl "system" command which may invoke the shell under
379 Windows when called with multiple arguments. It differs from the
380 in-built Perl backticks operator which always invokes the shell.
381
383 When "system" is exported, the exotic form "system { $cmd } @args" is
384 not supported. Attemping to use the exotic form is a syntax error.
385 This affects the calling package only. Use "CORE::system" if you need
386 it, or consider using the autodie module to replace "system" with
387 lexical scope.
388 Core dumps are only checked for when a process dies due to a signal.
390 It is not believed there are any systems where processes can dump core
391 without dying to a signal.
392 "WIFSTOPPED" status is not checked, as perl never spawns processes with
394 the "WUNTRACED" option.
395 Signals are not supported under Win32 systems, since they don't work at
397 all like Unix signals. Win32 signals cause commands to exit with a
398 given exit value, which this modules does capture.
399 Reporting bugs
401 Before reporting a bug, please check to ensure you are using the most
402 recent version of "IPC::System::Simple". Your problem may have already
403 been fixed in a new release.
404 You can find the "IPC::System::Simple" bug-tracker at
406 <http://rt.cpan.org/Public/Dist/Display.html?Name=IPC-System-Simple> .
407 Please check to see if your bug has already been reported; if in doubt,
408 report yours anyway.
409 Submitting a patch and/or failing test case will greatly expedite the
411 fixing of bugs.
412
414 If you find this module useful, please consider rating it on the CPAN
415 Ratings service at
416 <http://cpanratings.perl.org/rate/?distribution=IPC-System-Simple> .
417 The module author loves to hear how "IPC::System::Simple" has made your
419 life better (or worse). Feedback can be sent to
420 <pjf@perltraining.com.au>.
421
423 autodie uses "IPC::System::Simple" to provide succeed-or-die
424 replacements to "system" (and other built-ins) with lexical scope.
425 POSIX, IPC::Run::Simple, perlipc, perlport, IPC::Run, IPC::Run3,
427 Win32::Process
428
430 Paul Fenwick <pjf@cpan.org>
431
433 Copyright (C) 2006-2008 by Paul Fenwick
434 This library is free software; you can redistribute it and/or modify it
436 under the same terms as Perl itself, either Perl version 5.6.0 or, at
437 your option, any later version of Perl 5 you may have available.
438perl v5.34.0 2021-07-22 IPC::System::Simple(3)