1IPC::System::Simple(3)User Contributed Perl DocumentationIPC::System::Simple(3)
2
3
4

NAME

6       IPC::System::Simple - Run commands simply, with detailed diagnostics
7

SYNOPSIS

9         use IPC::System::Simple qw(system systemx capture capturex);
10
11         system("some_command");        # Command succeeds or dies!
12
13         system("some_command",@args);  # Succeeds or dies, avoids shell if @args
14
15         systemx("some_command",@args); # Succeeds or dies, NEVER uses the shell
16
17
18         # Capture the output of a command (just like backticks). Dies on error.
19         my $output = capture("some_command");
20
21         # Just like backticks in list context.  Dies on error.
22         my @output = capture("some_command");
23
24         # As above, but avoids the shell if @args is non-empty
25         my $output = capture("some_command", @args);
26
27         # As above, but NEVER invokes the shell.
28         my $output = capturex("some_command", @args);
29         my @output = capturex("some_command", @args);
30

DESCRIPTION

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
37       "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
40           use IPC::System::Simple qw(system);
41
42       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
46       The "IPC::System::Simple" module also provides a simple replacement to
47       Perl's backticks operator.  Simply write:
48
49           use IPC::System::Simple qw(capture);
50
51       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
56           use IPC::System::Simple qw(capturex);
57
58           my $result = capturex($command, @args);
59
60       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

ADVANCED SYNOPSIS

65         use IPC::System::Simple qw(
66           capture capturex system systemx run runx $EXITVAL EXIT_ANY
67         );
68
69         # Run a command, throwing exception on failure
70
71         run("some_command");
72
73         runx("some_command",@args);  # Run a command, avoiding the shell
74
75         # Do the same thing, but with the drop-in system replacement.
76
77         system("some_command");
78
79         systemx("some_command", @args);
80
81         # Run a command which must return 0..5, avoid the shell, and get the
82         # exit value (we could also look at $EXITVAL)
83
84         my $exit_value = runx([0..5], "some_command", @args);
85
86         # The same, but any exit value will do.
87
88         my $exit_value = runx(EXIT_ANY, "some_command", @args);
89
90         # Capture output into $result and throw exception on failure
91
92         my $result = capture("some_command");
93
94         # Check exit value from captured command
95
96         print "some_command exited with status $EXITVAL\n";
97
98         # Captures into @lines, splitting on $/
99         my @lines = capture("some_command");
100
101         # Run a command which must return 0..5, capture the output into
102         # @lines, and avoid the shell.
103
104         my @lines  = capturex([0..5], "some_command", @args);
105

ADVANCED USAGE

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
111           use IPC::System::Simple qw(run);
112
113           run("cat *.txt");           # Execute command via the shell
114           run("cat","/etc/motd");     # Execute command without shell
115
116       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
121       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
124           use IPC::System::Simple qw(system);
125
126           system("cat *.txt");  # system now suceeds or dies!
127
128       "system" and "run" are aliases to each other.
129
130       See also "runx(), systemx() and capturex()" for variants of "system()"
131       and "run()" that never invoke the shell, even with a single argument.
132
133   capture()
134       A second subroutine, named "capture" executes a command with the same
135       semantics as Perl's built-in backticks (and "qx()"):
136
137           use IPC::System::Simple qw(capture);
138
139           # Capture text while invoking the shell.
140           my $file  = capture("cat /etc/motd");
141           my @lines = capture("cat /etc/passwd");
142
143       However unlike regular backticks, which always use the shell, "capture"
144       will bypass the shell when called with multiple arguments:
145
146           # Capture text while avoiding the shell.
147           my $file  = capture("cat", "/etc/motd");
148           my @lines = capture("cat", "/etc/passwd");
149
150       See also "runx(), systemx() and capturex()" for a variant of
151       "capture()" that never invokes the shell, even with a single argument.
152
153   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
160           systemx($cmd, @args);
161
162       The use of "systemx()" here guarantees that the shell will never be
163       invoked, even if @args is empty.
164
165   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
170       Capturing the exception is easy:
171
172           eval {
173               run("cat *.txt");
174           };
175
176           if ($@) {
177               print "Something went wrong - $@\n";
178           }
179
180       See the diagnostics section below for more details.
181
182       Exception cases
183
184       "IPC::System::Simple" considers the following to be unexpected, and
185       worthy of exception:
186
187       ·   Failing to start entirely (eg, command not found, permission
188           denied).
189
190       ·   Returning an exit value other than zero (but see below).
191
192       ·   Being killed by a signal.
193
194       ·   Being passed tainted data (in taint mode).
195
196   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
201       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
206               use IPC::System::Simple qw(run system capture EXIT_ANY);
207
208               run( [0..5], "cat *.txt");             # Exit values 0-5 are OK
209
210               system( [0..5], "cat *.txt");          # This works the same way
211
212               my @lines = capture( EXIT_ANY, "cat *.txt"); # Any exit is fine.
213
214       The "run" and replacement "system" subroutines returns the exit value
215       of the process:
216
217               my $exit_value = run( [0..5], "cat *.txt");
218
219               # OR:
220
221               my $exit_value = system( [0..5] "cat *.txt");
222
223               print "Program exited with value $exit_value\n";
224
225       $EXITVAL
226
227       The exit value of any command executed by "IPC::System::Simple" can
228       always be retrieved from the $IPC::System::Simple::EXITVAL variable:
229
230       This is particularly useful when inspecting results from "capture",
231       which returns the captured text from the command.
232
233               use IPC::System::Simple qw(capture $EXITVAL EXIT_ANY);
234
235               my @enemies_defeated = capture(EXIT_ANY, "defeat_evil", "/dev/mordor");
236
237               print "Program exited with value $EXITVAL\n";
238
239       $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
243   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
250       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
254       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
261       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

DIAGNOSTICS

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
271       "%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
275       "%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
281       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
286       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
290       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
297       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
304       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
310           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
314       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
320       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

DEPENDENCIES

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
330       There are no non-core dependencies on non-Win32 systems.
331

COMPARISON TO OTHER APIs

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
337       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
343           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
348       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
355       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
360       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

BUGS

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
374       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
378       "WIFSTOPPED" status is not checked, as perl never spawns processes with
379       the "WUNTRACED" option.
380
381       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
385       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
390   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
395       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
400       Submitting a patch and/or failing test case will greatly expedite the
401       fixing of bugs.
402

FEEDBACK

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
408       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

SEE ALSO

413       autodie uses "IPC::System::Simple" to provide succeed-or-die
414       replacements to "system" (and other built-ins) with lexical scope.
415
416       POSIX, IPC::Run::Simple, perlipc, perlport, IPC::Run, IPC::Run3,
417       Win32::Process
418

AUTHOR

420       Paul Fenwick <pjf@cpan.org>
421
423       Copyright (C) 2006-2008 by Paul Fenwick
424
425       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.
428
429
430
431perl v5.28.1                      2013-10-20            IPC::System::Simple(3)
Impressum