7 use constant IS_VMS => $^O eq 'VMS' ? 1 : 0;
8 use constant IS_WIN32 => $^O eq 'MSWin32' ? 1 : 0;
9 use constant IS_WIN98 => (IS_WIN32 and !Win32::IsWinNT()) ? 1 : 0;
12 use vars qw[ @ISA $VERSION @EXPORT_OK $VERBOSE $DEBUG
13 $USE_IPC_RUN $USE_IPC_OPEN3 $WARN
20 $USE_IPC_RUN = IS_WIN32 && !IS_WIN98;
21 $USE_IPC_OPEN3 = not IS_VMS;
24 @EXPORT_OK = qw[can_run run];
28 use Params::Check qw[check];
29 use Module::Load::Conditional qw[can_load];
30 use Locale::Maketext::Simple Style => 'gettext';
36 IPC::Cmd - finding and running system commands made easy
40 use IPC::Cmd qw[can_run run];
42 my $full_path = can_run('wget') or warn 'wget is not installed!';
44 ### commands can be arrayrefs or strings ###
45 my $cmd = "$full_path -b theregister.co.uk";
46 my $cmd = [$full_path, '-b', 'theregister.co.uk'];
48 ### in scalar context ###
50 if( scalar run( command => $cmd,
54 print "fetched webpage successfully: $buffer\n";
58 ### in list context ###
59 my( $success, $error_code, $full_buf, $stdout_buf, $stderr_buf ) =
60 run( command => $cmd, verbose => 0 );
63 print "this is what the command printed:\n";
64 print join "", @$full_buf;
67 ### check for features
68 print "IPC::Open3 available: " . IPC::Cmd->can_use_ipc_open3;
69 print "IPC::Run available: " . IPC::Cmd->can_use_ipc_run;
70 print "Can capture buffer: " . IPC::Cmd->can_capture_buffer;
72 ### don't have IPC::Cmd be verbose, ie don't print to stdout or
73 ### stderr when running commands -- default is '0'
74 $IPC::Cmd::VERBOSE = 0;
78 IPC::Cmd allows you to run commands, interactively if desired,
79 platform independent but have them still work.
81 The C<can_run> function can tell you if a certain binary is installed
82 and if so where, whereas the C<run> function can actually execute any
83 of the commands you give it and give you a clear return value, as well
84 as adhere to your verbosity settings.
88 =head2 $bool = IPC::Cmd->can_use_ipc_run( [VERBOSE] )
90 Utility function that tells you if C<IPC::Run> is available.
91 If the verbose flag is passed, it will print diagnostic messages
92 if C<IPC::Run> can not be found or loaded.
99 my $verbose = shift || 0;
101 ### ipc::run doesn't run on win98
104 ### if we dont have ipc::run, we obviously can't use it.
105 return unless can_load(
106 modules => { 'IPC::Run' => '0.55' },
107 verbose => ($WARN && $verbose),
110 ### otherwise, we're good to go
114 =head2 $bool = IPC::Cmd->can_use_ipc_open3( [VERBOSE] )
116 Utility function that tells you if C<IPC::Open3> is available.
117 If the verbose flag is passed, it will print diagnostic messages
118 if C<IPC::Open3> can not be found or loaded.
123 sub can_use_ipc_open3 {
125 my $verbose = shift || 0;
127 ### ipc::open3 works on every platform, but it can't capture buffers
129 return unless can_load(
130 modules => { map {$_ => '0.0'} qw|IPC::Open3 IO::Select Symbol| },
131 verbose => ($WARN && $verbose),
137 =head2 $bool = IPC::Cmd->can_capture_buffer
139 Utility function that tells you if C<IPC::Cmd> is capable of
140 capturing buffers in it's current configuration.
144 sub can_capture_buffer {
147 return 1 if $USE_IPC_RUN && $self->can_use_ipc_run;
148 return 1 if $USE_IPC_OPEN3 && $self->can_use_ipc_open3 && !IS_WIN32;
155 =head2 $path = can_run( PROGRAM );
157 C<can_run> takes but a single argument: the name of a binary you wish
158 to locate. C<can_run> works much like the unix binary C<which> or the bash
159 command C<type>, which scans through your path, looking for the requested
162 Unlike C<which> and C<type>, this function is platform independent and
163 will also work on, for example, Win32.
165 It will return the full path to the binary you asked for if it was
166 found, or C<undef> if it was not.
173 # a lot of VMS executables have a symbol defined
175 if ( $^O eq 'VMS' ) {
177 my $syms = VMS::DCLsym->new;
178 return $command if scalar $syms->getsym( uc $command );
183 require ExtUtils::MakeMaker;
185 if( File::Spec->file_name_is_absolute($command) ) {
186 return MM->maybe_command($command);
189 for my $dir ((split /\Q$Config::Config{path_sep}\E/, $ENV{PATH}),
192 my $abs = File::Spec->catfile($dir, $command);
193 return $abs if $abs = MM->maybe_command($abs);
198 =head2 $ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( command => COMMAND, [verbose => BOOL, buffer => \$SCALAR] );
200 C<run> takes 3 arguments:
206 This is the command to execute. It may be either a string or an array
208 This is a required argument.
210 See L<CAVEATS> for remarks on how commands are parsed and their
215 This controls whether all output of a command should also be printed
216 to STDOUT/STDERR or should only be trapped in buffers (NOTE: buffers
217 require C<IPC::Run> to be installed or your system able to work with
220 It will default to the global setting of C<$IPC::Cmd::VERBOSE>,
221 which by default is 0.
225 This will hold all the output of a command. It needs to be a reference
227 Note that this will hold both the STDOUT and STDERR messages, and you
228 have no way of telling which is which.
229 If you require this distinction, run the C<run> command in list context
230 and inspect the individual buffers.
232 Of course, this requires that the underlying call supports buffers. See
233 the note on buffers right above.
237 C<run> will return a simple C<true> or C<false> when called in scalar
239 In list context, you will be returned a list of the following items:
245 A simple boolean indicating if the command executed without errors or
250 If the first element of the return value (success) was 0, then some
251 error occurred. This second element is the error code the command
252 you requested exited with, if available.
256 This is an arrayreference containing all the output the command
258 Note that buffers are only available if you have C<IPC::Run> installed,
259 or if your system is able to work with C<IPC::Open3> -- See below).
260 This element will be C<undef> if this is not the case.
264 This is an arrayreference containing all the output sent to STDOUT the
266 Note that buffers are only available if you have C<IPC::Run> installed,
267 or if your system is able to work with C<IPC::Open3> -- See below).
268 This element will be C<undef> if this is not the case.
272 This is an arrayreference containing all the output sent to STDERR the
274 Note that buffers are only available if you have C<IPC::Run> installed,
275 or if your system is able to work with C<IPC::Open3> -- See below).
276 This element will be C<undef> if this is not the case.
280 See the C<HOW IT WORKS> Section below to see how C<IPC::Cmd> decides
281 what modules or function calls to use when issuing a command.
288 ### if the user didn't provide a buffer, we'll store it here.
291 my($verbose,$cmd,$buffer);
293 verbose => { default => $VERBOSE, store => \$verbose },
294 buffer => { default => \$def_buf, store => \$buffer },
295 command => { required => 1, store => \$cmd,
296 allow => sub { !ref($_[0]) or ref($_[0]) eq 'ARRAY' }
300 unless( check( $tmpl, \%hash, $VERBOSE ) ) {
301 Carp::carp(loc("Could not validate input: %1", Params::Check->last_error));
305 print loc("Running [%1]...\n", (ref $cmd ? "@$cmd" : $cmd)) if $verbose;
307 ### did the user pass us a buffer to fill or not? if so, set this
308 ### flag so we know what is expected of us
309 ### XXX this is now being ignored. in the future, we could add diagnostic
310 ### messages based on this logic
311 #my $user_provided_buffer = $buffer == \$def_buf ? 0 : 1;
313 ### buffers that are to be captured
314 my( @buffer, @buff_err, @buff_out );
317 my $_out_handler = sub {
319 return unless defined $buf;
321 print STDOUT $buf if $verbose;
323 push @buff_out, $buf;
327 my $_err_handler = sub {
329 return unless defined $buf;
331 print STDERR $buf if $verbose;
333 push @buff_err, $buf;
337 ### flag to indicate we have a buffer captured
338 my $have_buffer = __PACKAGE__->can_capture_buffer ? 1 : 0;
340 ### flag indicating if the subcall went ok
343 ### IPC::Run is first choice if $USE_IPC_RUN is set.
344 if( $USE_IPC_RUN and __PACKAGE__->can_use_ipc_run( 1 ) ) {
345 ### ipc::run handlers needs the command as a string or an array ref
347 __PACKAGE__->_debug( "# Using IPC::Run. Have buffer: $have_buffer" )
350 $ok = __PACKAGE__->_ipc_run( $cmd, $_out_handler, $_err_handler );
352 ### since IPC::Open3 works on all platforms, and just fails on
353 ### win32 for capturing buffers, do that ideally
354 } elsif ( $USE_IPC_OPEN3 and __PACKAGE__->can_use_ipc_open3( 1 ) ) {
356 __PACKAGE__->_debug( "# Using IPC::Open3. Have buffer: $have_buffer" )
359 ### in case there are pipes in there;
360 ### IPC::Open3 will call exec and exec will do the right thing
361 $ok = __PACKAGE__->_open3_run(
362 ( ref $cmd ? "@$cmd" : $cmd ),
363 $_out_handler, $_err_handler, $verbose
366 ### if we are allowed to run verbose, just dispatch the system command
368 __PACKAGE__->_debug( "# Using system(). Have buffer: $have_buffer" )
370 $ok = __PACKAGE__->_system_run( (ref $cmd ? "@$cmd" : $cmd), $verbose );
374 $$buffer = join '', @buffer if @buffer;
376 ### return a list of flags and buffers (if available) in list
377 ### context, or just a simple 'ok' in scalar
380 ? ($ok, $?, \@buffer, \@buff_out, \@buff_err)
390 my $_out_handler = shift;
391 my $_err_handler = shift;
392 my $verbose = shift || 0;
394 ### Following code are adapted from Friar 'abstracts' in the
395 ### Perl Monastery (http://www.perlmonks.org/index.pl?node_id=151886).
396 ### XXX that code didn't work.
397 ### we now use the following code, thanks to theorbtwo
399 ### define them beforehand, so we always have defined FH's
402 my $kidout = Symbol::gensym();
403 my $kiderror = Symbol::gensym();
405 ### Dup the filehandle so we can pass 'our' STDIN to the
406 ### child process. This stops us from having to pump input
407 ### from ourselves to the childprocess. However, we will need
408 ### to revive the FH afterwards, as IPC::Open3 closes it.
409 ### We'll do the same for STDOUT and STDERR. It works without
410 ### duping them on non-unix derivatives, but not on win32.
411 my @fds_to_dup = ( IS_WIN32 && !$verbose
412 ? qw[STDIN STDOUT STDERR]
415 __PACKAGE__->__dup_fds( @fds_to_dup );
418 my $pid = IPC::Open3::open3(
420 (IS_WIN32 ? '>&STDOUT' : $kidout),
421 (IS_WIN32 ? '>&STDERR' : $kiderror),
425 ### use OUR stdin, not $kidin. Somehow,
426 ### we never get the input.. so jump through
427 ### some hoops to do it :(
428 my $selector = IO::Select->new(
429 (IS_WIN32 ? \*STDERR : $kiderror),
431 (IS_WIN32 ? \*STDOUT : $kidout)
434 STDOUT->autoflush(1); STDERR->autoflush(1); STDIN->autoflush(1);
435 $kidout->autoflush(1) if UNIVERSAL::can($kidout, 'autoflush');
436 $kiderror->autoflush(1) if UNIVERSAL::can($kiderror, 'autoflush');
438 ### add an epxlicit break statement
439 ### code courtesy of theorbtwo from #london.pm
440 OUTER: while ( my @ready = $selector->can_read ) {
442 for my $h ( @ready ) {
445 ### $len is the amount of bytes read
446 my $len = sysread( $h, $buf, 4096 ); # try to read 4096 bytes
448 ### see perldoc -f sysread: it returns undef on error,
450 if( not defined $len ) {
451 warn(loc("Error reading from process: %1", $!));
455 ### check for $len. it may be 0, at which point we're
456 ### done reading, so don't try to process it.
457 ### if we would print anyway, we'd provide bogus information
458 $_out_handler->( "$buf" ) if $len && $h == $kidout;
459 $_err_handler->( "$buf" ) if $len && $h == $kiderror;
461 ### child process is done printing.
462 last OUTER if $h == $kidout and $len == 0
466 waitpid $pid, 0; # wait for it to die
468 ### restore STDIN after duping, or STDIN will be closed for
469 ### this current perl process!
470 __PACKAGE__->__reopen_fds( @fds_to_dup );
472 return if $?; # some error occurred
480 my $_out_handler = shift;
481 my $_err_handler = shift;
483 STDOUT->autoflush(1); STDERR->autoflush(1);
489 # '/Users/kane/sources/p4/other/archive-extract/t/src/x.tgz',
496 # ['/usr/bin/gzip', '-cdf',
497 # '/Users/kane/sources/p4/other/archive-extract/t/src/x.tgz']
499 # ['/usr/bin/tar', '-tf -']
503 my @command; my $special_chars;
506 for my $item (@$cmd) {
507 if( $item =~ /([<>|&])/ ) {
508 push @command, $aref, $item;
510 $special_chars .= $1;
515 push @command, $aref;
517 @command = map { if( /([<>|&])/ ) {
518 $special_chars .= $1; $_;
522 } split( /\s*([<>|&])\s*/, $cmd );
525 ### if there's a pipe in the command, *STDIN needs to
526 ### be inserted *BEFORE* the pipe, to work on win32
527 ### this also works on *nix, so we should do it when possible
528 ### this should *also* work on multiple pipes in the command
529 ### if there's no pipe in the command, append STDIN to the back
530 ### of the command instead.
531 ### XXX seems IPC::Run works it out for itself if you just
532 ### dont pass STDIN at all.
533 # if( $special_chars and $special_chars =~ /\|/ ) {
534 # ### only add STDIN the first time..
536 # @command = map { ($_ eq '|' && not $i++)
541 # push @command, \*STDIN;
545 # \*STDIN is already included in the @command, see a few lines up
546 return IPC::Run::run( @command,
557 my $verbose = shift || 0;
559 my @fds_to_dup = $verbose ? () : qw[STDOUT STDERR];
560 __PACKAGE__->__dup_fds( @fds_to_dup );
562 ### system returns 'true' on failure -- the exit code of the cmd
565 __PACKAGE__->__reopen_fds( @fds_to_dup );
575 STDOUT => [qw|>&|, \*STDOUT, Symbol::gensym() ],
576 STDERR => [qw|>&|, \*STDERR, Symbol::gensym() ],
577 STDIN => [qw|<&|, \*STDIN, Symbol::gensym() ],
580 ### dups FDs and stores them in a cache
585 __PACKAGE__->_debug( "# Closing the following fds: @fds" ) if $DEBUG;
587 for my $name ( @fds ) {
588 my($redir, $fh, $glob) = @{$Map{$name}} or (
589 Carp::carp(loc("No such FD: '%1'", $name)), next );
591 ### MUST use the 2-arg version of open for dup'ing for
592 ### 5.6.x compatibilty. 5.8.x can use 3-arg open
593 ### see perldoc5.6.2 -f open for details
594 open $glob, $redir . fileno($fh) or (
595 Carp::carp(loc("Could not dup '$name': %1", $!)),
599 ### we should re-open this filehandle right now, not
601 if( $redir eq '>&' ) {
602 open( $fh, '>', File::Spec->devnull ) or (
603 Carp::carp(loc("Could not reopen '$name': %1", $!)),
612 ### reopens FDs from the cache
617 __PACKAGE__->_debug( "# Reopening the following fds: @fds" ) if $DEBUG;
619 for my $name ( @fds ) {
620 my($redir, $fh, $glob) = @{$Map{$name}} or (
621 Carp::carp(loc("No such FD: '%1'", $name)), next );
623 ### MUST use the 2-arg version of open for dup'ing for
624 ### 5.6.x compatibilty. 5.8.x can use 3-arg open
625 ### see perldoc5.6.2 -f open for details
626 open( $fh, $redir . fileno($glob) ) or (
627 Carp::carp(loc("Could not restore '$name': %1", $!)),
631 ### close this FD, we're not using it anymore
641 my $msg = shift or return;
642 my $level = shift || 0;
644 local $Carp::CarpLevel += $level;
658 C<run> will try to execute your command using the following logic:
664 If you have C<IPC::Run> installed, and the variable C<$IPC::Cmd::USE_IPC_RUN>
665 is set to true (See the C<GLOBAL VARIABLES> Section) use that to execute
666 the command. You will have the full output available in buffers, interactive commands are sure to work and you are guaranteed to have your verbosity
667 settings honored cleanly.
671 Otherwise, if the variable C<$IPC::Cmd::USE_IPC_OPEN3> is set to true
672 (See the C<GLOBAL VARIABLES> Section), try to execute the command using
673 C<IPC::Open3>. Buffers will be available on all platforms except C<Win32>,
674 interactive commands will still execute cleanly, and also your verbosity
675 settings will be adhered to nicely;
679 Otherwise, if you have the verbose argument set to true, we fall back
680 to a simple system() call. We cannot capture any buffers, but
681 interactive commands will still work.
685 Otherwise we will try and temporarily redirect STDERR and STDOUT, do a
686 system() call with your command and then re-open STDERR and STDOUT.
687 This is the method of last resort and will still allow you to execute
688 your commands cleanly. However, no buffers will be available.
692 =head1 Global Variables
694 The behaviour of IPC::Cmd can be altered by changing the following
697 =head2 $IPC::Cmd::VERBOSE
699 This controls whether IPC::Cmd will print any output from the
700 commands to the screen or not. The default is 0;
702 =head2 $IPC::Cmd::USE_IPC_RUN
704 This variable controls whether IPC::Cmd will try to use L<IPC::Run>
705 when available and suitable. Defaults to true if you are on C<Win32>.
707 =head2 $IPC::Cmd::USE_IPC_OPEN3
709 This variable controls whether IPC::Cmd will try to use L<IPC::Open3>
710 when available and suitable. Defaults to true.
712 =head2 $IPC::Cmd::WARN
714 This variable controls whether run time warnings should be issued, like
715 the failure to load an C<IPC::*> module you explicitly requested.
717 Defaults to true. Turn this off at your own risk.
725 When you provide a string as this argument, the string will be
726 split on whitespace to determine the individual elements of your
727 command. Although this will usually just Do What You Mean, it may
728 break if you have files or commands with whitespace in them.
730 If you do not wish this to happen, you should provide an array
731 reference, where all parts of your command are already separated out.
732 Note however, if there's extra or spurious whitespace in these parts,
733 the parser or underlying code may not interpret it correctly, and
739 gzip -cdf foo.tar.gz | tar -xf -
741 should either be passed as
743 "gzip -cdf foo.tar.gz | tar -xf -"
747 ['gzip', '-cdf', 'foo.tar.gz', '|', 'tar', '-xf', '-']
749 But take care not to pass it as, for example
751 ['gzip -cdf foo.tar.gz', '|', 'tar -xf -']
753 Since this will lead to issues as described above.
757 Currently it is too complicated to parse your command for IO
758 Redirections. For capturing STDOUT or STDERR there is a work around
759 however, since you can just inspect your buffers for the contents.
765 C<IPC::Run>, C<IPC::Open3>
770 Jos Boumans E<lt>kane@cpan.orgE<gt>.
772 =head1 ACKNOWLEDGEMENTS
774 Thanks to James Mastros and Martijn van der Streek for their
775 help in getting IPC::Open3 to behave nicely.
780 copyright (c) 2002 - 2006 Jos Boumans E<lt>kane@cpan.orgE<gt>.
783 This library is free software;
784 you may redistribute and/or modify it under the same
785 terms as Perl itself.