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 as 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 succeeds 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       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
251       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
255       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
259       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
268       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
275       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

DIAGNOSTICS

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
285       "%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
289       "%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
295       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
300       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
304       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
311       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
318       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
324           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
328       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
334       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

DEPENDENCIES

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

COMPARISON TO OTHER APIs

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
351       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
357           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
363       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
370       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
375       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

BUGS

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
389       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
393       "WIFSTOPPED" status is not checked, as perl never spawns processes with
394       the "WUNTRACED" option.
395
396       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
400   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
405       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
410       Submitting a patch and/or failing test case will greatly expedite the
411       fixing of bugs.
412

FEEDBACK

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

SEE ALSO

423       autodie uses "IPC::System::Simple" to provide succeed-or-die
424       replacements to "system" (and other built-ins) with lexical scope.
425
426       POSIX, IPC::Run::Simple, perlipc, perlport, IPC::Run, IPC::Run3,
427       Win32::Process
428

AUTHOR

430       Paul Fenwick <pjf@cpan.org>
431
433       Copyright (C) 2006-2008 by Paul Fenwick
434
435       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.
438
439
440
441perl v5.36.0                      2022-07-22            IPC::System::Simple(3)
Impressum