1IPC::Cmd(3) User Contributed Perl Documentation IPC::Cmd(3)
2
6 IPC::Cmd - finding and running system commands made easy
7
9 use IPC::Cmd qw[can_run run];
10 my $full_path = can_run('wget') or warn 'wget is not installed!';
12 ### commands can be arrayrefs or strings ###
14 my $cmd = "$full_path -b theregister.co.uk";
15 my $cmd = [$full_path, '-b', 'theregister.co.uk'];
16 ### in scalar context ###
18 my $buffer;
19 if( scalar run( command => $cmd,
20 verbose => 0,
21 buffer => \$buffer )
22 ) {
23 print "fetched webpage successfully: $buffer\n";
24 }
25 ### in list context ###
27 my( $success, $error_code, $full_buf, $stdout_buf, $stderr_buf ) =
28 run( command => $cmd, verbose => 0 );
29 if( $success ) {
31 print "this is what the command printed:\n";
32 print join "", @$full_buf;
33 }
34 ### check for features
36 print "IPC::Open3 available: " . IPC::Cmd->can_use_ipc_open3;
37 print "IPC::Run available: " . IPC::Cmd->can_use_ipc_run;
38 print "Can capture buffer: " . IPC::Cmd->can_capture_buffer;
39 ### don't have IPC::Cmd be verbose, ie don't print to stdout or
41 ### stderr when running commands -- default is '0'
42 $IPC::Cmd::VERBOSE = 0;
43
45 IPC::Cmd allows you to run commands, interactively if desired, platform
46 independent but have them still work.
47 The "can_run" function can tell you if a certain binary is installed
49 and if so where, whereas the "run" function can actually execute any of
50 the commands you give it and give you a clear return value, as well as
51 adhere to your verbosity settings.
52
54 $bool = IPC::Cmd->can_use_ipc_run( [VERBOSE] )
55 Utility function that tells you if "IPC::Run" is available. If the
57 verbose flag is passed, it will print diagnostic messages if "IPC::Run"
58 can not be found or loaded.
59 $bool = IPC::Cmd->can_use_ipc_open3( [VERBOSE] )
61 Utility function that tells you if "IPC::Open3" is available. If the
63 verbose flag is passed, it will print diagnostic messages if
64 "IPC::Open3" can not be found or loaded.
65 $bool = IPC::Cmd->can_capture_buffer
67 Utility function that tells you if "IPC::Cmd" is capable of capturing
69 buffers in it's current configuration.
70
72 $path = can_run( PROGRAM );
73 "can_run" takes but a single argument: the name of a binary you wish to
75 locate. "can_run" works much like the unix binary "which" or the bash
76 command "type", which scans through your path, looking for the
77 requested binary .
78 Unlike "which" and "type", this function is platform independent and
80 will also work on, for example, Win32.
81 It will return the full path to the binary you asked for if it was
83 found, or "undef" if it was not.
84 $ok ⎪ ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( command
86 => COMMAND, [verbose => BOOL, buffer => \$SCALAR] );
87 "run" takes 3 arguments:
89 command
91 This is the command to execute. It may be either a string or an
92 array reference. This is a required argument.
93 See CAVEATS for remarks on how commands are parsed and their limi‐
95 tations.
96 verbose
98 This controls whether all output of a command should also be
99 printed to STDOUT/STDERR or should only be trapped in buffers
100 (NOTE: buffers require "IPC::Run" to be installed or your system
101 able to work with "IPC::Open3").
102 It will default to the global setting of $IPC::Cmd::VERBOSE, which
104 by default is 0.
105 buffer
107 This will hold all the output of a command. It needs to be a refer‐
108 ence to a scalar. Note that this will hold both the STDOUT and
109 STDERR messages, and you have no way of telling which is which. If
110 you require this distinction, run the "run" command in list context
111 and inspect the individual buffers.
112 Of course, this requires that the underlying call supports buffers.
114 See the note on buffers right above.
115 "run" will return a simple "true" or "false" when called in scalar con‐
117 text. In list context, you will be returned a list of the following
118 items:
119 success
121 A simple boolean indicating if the command executed without errors
122 or not.
123 errorcode
125 If the first element of the return value (success) was 0, then some
126 error occurred. This second element is the error code the command
127 you requested exited with, if available.
128 full_buffer
130 This is an arrayreference containing all the output the command
131 generated. Note that buffers are only available if you have
132 "IPC::Run" installed, or if your system is able to work with
133 "IPC::Open3" -- See below). This element will be "undef" if this
134 is not the case.
135 out_buffer
137 This is an arrayreference containing all the output sent to STDOUT
138 the command generated. Note that buffers are only available if you
139 have "IPC::Run" installed, or if your system is able to work with
140 "IPC::Open3" -- See below). This element will be "undef" if this
141 is not the case.
142 error_buffer
144 This is an arrayreference containing all the output sent to STDERR
145 the command generated. Note that buffers are only available if you
146 have "IPC::Run" installed, or if your system is able to work with
147 "IPC::Open3" -- See below). This element will be "undef" if this
148 is not the case.
149 See the "HOW IT WORKS" Section below to see how "IPC::Cmd" decides what
151 modules or function calls to use when issuing a command.
152
154 "run" will try to execute your command using the following logic:
155 · If you have "IPC::Run" installed, and the variable
157 $IPC::Cmd::USE_IPC_RUN is set to true (See the "GLOBAL VARIABLES"
158 Section) use that to execute the command. You will have the full
159 output available in buffers, interactive commands are sure to work
160 and you are guaranteed to have your verbosity settings honored
161 cleanly.
162 · Otherwise, if the variable $IPC::Cmd::USE_IPC_OPEN3 is set to true
164 (See the "GLOBAL VARIABLES" Section), try to execute the command
165 using "IPC::Open3". Buffers will be available on all platforms
166 except "Win32", interactive commands will still execute cleanly,
167 and also your verbosity settings will be adhered to nicely;
168 · Otherwise, if you have the verbose argument set to true, we fall
170 back to a simple system() call. We cannot capture any buffers, but
171 interactive commands will still work.
172 · Otherwise we will try and temporarily redirect STDERR and STDOUT,
174 do a system() call with your command and then re-open STDERR and
175 STDOUT. This is the method of last resort and will still allow you
176 to execute your commands cleanly. However, no buffers will be
177 available.
178
180 The behaviour of IPC::Cmd can be altered by changing the following
181 global variables:
182 $IPC::Cmd::VERBOSE
184 This controls whether IPC::Cmd will print any output from the commands
186 to the screen or not. The default is 0;
187 $IPC::Cmd::USE_IPC_RUN
189 This variable controls whether IPC::Cmd will try to use IPC::Run when
191 available and suitable. Defaults to true if you are on "Win32".
192 $IPC::Cmd::USE_IPC_OPEN3
194 This variable controls whether IPC::Cmd will try to use IPC::Open3 when
196 available and suitable. Defaults to true.
197 $IPC::Cmd::WARN
199 This variable controls whether run time warnings should be issued, like
201 the failure to load an "IPC::*" module you explicitly requested.
202 Defaults to true. Turn this off at your own risk.
204
206 Whitespace
207 When you provide a string as this argument, the string will be
208 split on whitespace to determine the individual elements of your
209 command. Although this will usually just Do What You Mean, it may
210 break if you have files or commands with whitespace in them.
211 If you do not wish this to happen, you should provide an array ref‐
213 erence, where all parts of your command are already separated out.
214 Note however, if there's extra or spurious whitespace in these
215 parts, the parser or underlying code may not interpret it cor‐
216 rectly, and cause an error.
217 Example: The following code
219 gzip -cdf foo.tar.gz ⎪ tar -xf -
221 should either be passed as
223 "gzip -cdf foo.tar.gz ⎪ tar -xf -"
225 or as
227 ['gzip', '-cdf', 'foo.tar.gz', '⎪', 'tar', '-xf', '-']
229 But take care not to pass it as, for example
231 ['gzip -cdf foo.tar.gz', '⎪', 'tar -xf -']
233 Since this will lead to issues as described above.
235 IO Redirect
237 Currently it is too complicated to parse your command for IO Redi‐
238 rections. For capturing STDOUT or STDERR there is a work around
239 however, since you can just inspect your buffers for the contents.
240
242 "IPC::Run", "IPC::Open3"
243
245 This module by Jos Boumans <kane@cpan.org>.
246
248 Thanks to James Mastros and Martijn van der Streek for their help in
249 getting IPC::Open3 to behave nicely.
250
252 This module is copyright (c) 2002 - 2006 Jos Boumans <kane@cpan.org>.
253 All rights reserved.
254 This library is free software; you may redistribute and/or modify it
256 under the same terms as Perl itself.
257perl v5.8.8 2006-11-24 IPC::Cmd(3)