[Summary view] [Print] [Text view]

   1  package IPC::Cmd;
   2  
   3  use strict;
   4  
   5  BEGIN {
   6  
   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;
  10  
  11      use Exporter    ();
  12      use vars        qw[ @ISA $VERSION @EXPORT_OK $VERBOSE $DEBUG
  13                          $USE_IPC_RUN $USE_IPC_OPEN3 $WARN
  14                      ];
  15  
  16      $VERSION        = '0.40_1';
  17      $VERBOSE        = 0;
  18      $DEBUG          = 0;
  19      $WARN           = 1;
  20      $USE_IPC_RUN    = IS_WIN32 && !IS_WIN98;
  21      $USE_IPC_OPEN3  = not IS_VMS;
  22  
  23      @ISA            = qw[Exporter];
  24      @EXPORT_OK      = qw[can_run run];
  25  }
  26  
  27  require Carp;
  28  use File::Spec;
  29  use Params::Check               qw[check];
  30  use Module::Load::Conditional   qw[can_load];
  31  use Locale::Maketext::Simple    Style => 'gettext';
  32  
  33  =pod
  34  
  35  =head1 NAME
  36  
  37  IPC::Cmd - finding and running system commands made easy
  38  
  39  =head1 SYNOPSIS
  40  
  41      use IPC::Cmd qw[can_run run];
  42  
  43      my $full_path = can_run('wget') or warn 'wget is not installed!';
  44  
  45      ### commands can be arrayrefs or strings ###
  46      my $cmd = "$full_path -b theregister.co.uk";
  47      my $cmd = [$full_path, '-b', 'theregister.co.uk'];
  48  
  49      ### in scalar context ###
  50      my $buffer;
  51      if( scalar run( command => $cmd,
  52                      verbose => 0,
  53                      buffer  => \$buffer )
  54      ) {
  55          print "fetched webpage successfully: $buffer\n";
  56      }
  57  
  58  
  59      ### in list context ###
  60      my( $success, $error_code, $full_buf, $stdout_buf, $stderr_buf ) =
  61              run( command => $cmd, verbose => 0 );
  62  
  63      if( $success ) {
  64          print "this is what the command printed:\n";
  65          print join "", @$full_buf;
  66      }
  67  
  68      ### check for features
  69      print "IPC::Open3 available: "  . IPC::Cmd->can_use_ipc_open3;      
  70      print "IPC::Run available: "    . IPC::Cmd->can_use_ipc_run;      
  71      print "Can capture buffer: "    . IPC::Cmd->can_capture_buffer;     
  72  
  73      ### don't have IPC::Cmd be verbose, ie don't print to stdout or
  74      ### stderr when running commands -- default is '0'
  75      $IPC::Cmd::VERBOSE = 0;
  76  
  77  =head1 DESCRIPTION
  78  
  79  IPC::Cmd allows you to run commands, interactively if desired,
  80  platform independent but have them still work.
  81  
  82  The C<can_run> function can tell you if a certain binary is installed
  83  and if so where, whereas the C<run> function can actually execute any
  84  of the commands you give it and give you a clear return value, as well
  85  as adhere to your verbosity settings.
  86  
  87  =head1 CLASS METHODS 
  88  
  89  =head2 $bool = IPC::Cmd->can_use_ipc_run( [VERBOSE] )
  90  
  91  Utility function that tells you if C<IPC::Run> is available. 
  92  If the verbose flag is passed, it will print diagnostic messages
  93  if C<IPC::Run> can not be found or loaded.
  94  
  95  =cut
  96  
  97  
  98  sub can_use_ipc_run     { 
  99      my $self    = shift;
 100      my $verbose = shift || 0;
 101      
 102      ### ipc::run doesn't run on win98    
 103      return if IS_WIN98;
 104  
 105      ### if we dont have ipc::run, we obviously can't use it.
 106      return unless can_load(
 107                          modules => { 'IPC::Run' => '0.55' },        
 108                          verbose => ($WARN && $verbose),
 109                      );
 110                      
 111      ### otherwise, we're good to go
 112      return 1;                    
 113  }
 114  
 115  =head2 $bool = IPC::Cmd->can_use_ipc_open3( [VERBOSE] )
 116  
 117  Utility function that tells you if C<IPC::Open3> is available. 
 118  If the verbose flag is passed, it will print diagnostic messages
 119  if C<IPC::Open3> can not be found or loaded.
 120  
 121  =cut
 122  
 123  
 124  sub can_use_ipc_open3   { 
 125      my $self    = shift;
 126      my $verbose = shift || 0;
 127  
 128      ### ipc::open3 is not working on VMS becasue of a lack of fork.
 129      ### todo, win32 also does not have fork, so need to do more research.
 130      return 0 if IS_VMS;
 131  
 132      ### ipc::open3 works on every platform, but it can't capture buffers
 133      ### on win32 :(
 134      return unless can_load(
 135          modules => { map {$_ => '0.0'} qw|IPC::Open3 IO::Select Symbol| },
 136          verbose => ($WARN && $verbose),
 137      );
 138      
 139      return 1;
 140  }
 141  
 142  =head2 $bool = IPC::Cmd->can_capture_buffer
 143  
 144  Utility function that tells you if C<IPC::Cmd> is capable of
 145  capturing buffers in it's current configuration.
 146  
 147  =cut
 148  
 149  sub can_capture_buffer {
 150      my $self    = shift;
 151  
 152      return 1 if $USE_IPC_RUN    && $self->can_use_ipc_run; 
 153      return 1 if $USE_IPC_OPEN3  && $self->can_use_ipc_open3 && !IS_WIN32; 
 154      return;
 155  }
 156  
 157  
 158  =head1 FUNCTIONS
 159  
 160  =head2 $path = can_run( PROGRAM );
 161  
 162  C<can_run> takes but a single argument: the name of a binary you wish
 163  to locate. C<can_run> works much like the unix binary C<which> or the bash
 164  command C<type>, which scans through your path, looking for the requested
 165  binary .
 166  
 167  Unlike C<which> and C<type>, this function is platform independent and
 168  will also work on, for example, Win32.
 169  
 170  It will return the full path to the binary you asked for if it was
 171  found, or C<undef> if it was not.
 172  
 173  =cut
 174  
 175  sub can_run {
 176      my $command = shift;
 177  
 178      # a lot of VMS executables have a symbol defined
 179      # check those first
 180      if ( $^O eq 'VMS' ) {
 181          require VMS::DCLsym;
 182          my $syms = VMS::DCLsym->new;
 183          return $command if scalar $syms->getsym( uc $command );
 184      }
 185  
 186      require Config;
 187      require File::Spec;
 188      require ExtUtils::MakeMaker;
 189  
 190      if( File::Spec->file_name_is_absolute($command) ) {
 191          return MM->maybe_command($command);
 192  
 193      } else {
 194          for my $dir (
 195              (split /\Q$Config::Config{path_sep}\E/, $ENV{PATH}),
 196              File::Spec->curdir
 197          ) {           
 198              my $abs = File::Spec->catfile($dir, $command);
 199              return $abs if $abs = MM->maybe_command($abs);
 200          }
 201      }
 202  }
 203  
 204  =head2 $ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( command => COMMAND, [verbose => BOOL, buffer => \$SCALAR] );
 205  
 206  C<run> takes 3 arguments:
 207  
 208  =over 4
 209  
 210  =item command
 211  
 212  This is the command to execute. It may be either a string or an array
 213  reference.
 214  This is a required argument.
 215  
 216  See L<CAVEATS> for remarks on how commands are parsed and their
 217  limitations.
 218  
 219  =item verbose
 220  
 221  This controls whether all output of a command should also be printed
 222  to STDOUT/STDERR or should only be trapped in buffers (NOTE: buffers
 223  require C<IPC::Run> to be installed or your system able to work with
 224  C<IPC::Open3>).
 225  
 226  It will default to the global setting of C<$IPC::Cmd::VERBOSE>,
 227  which by default is 0.
 228  
 229  =item buffer
 230  
 231  This will hold all the output of a command. It needs to be a reference
 232  to a scalar.
 233  Note that this will hold both the STDOUT and STDERR messages, and you
 234  have no way of telling which is which.
 235  If you require this distinction, run the C<run> command in list context
 236  and inspect the individual buffers.
 237  
 238  Of course, this requires that the underlying call supports buffers. See
 239  the note on buffers right above.
 240  
 241  =back
 242  
 243  C<run> will return a simple C<true> or C<false> when called in scalar
 244  context.
 245  In list context, you will be returned a list of the following items:
 246  
 247  =over 4
 248  
 249  =item success
 250  
 251  A simple boolean indicating if the command executed without errors or
 252  not.
 253  
 254  =item errorcode
 255  
 256  If the first element of the return value (success) was 0, then some
 257  error occurred. This second element is the error code the command
 258  you requested exited with, if available.
 259  
 260  =item full_buffer
 261  
 262  This is an arrayreference containing all the output the command
 263  generated.
 264  Note that buffers are only available if you have C<IPC::Run> installed,
 265  or if your system is able to work with C<IPC::Open3> -- See below).
 266  This element will be C<undef> if this is not the case.
 267  
 268  =item out_buffer
 269  
 270  This is an arrayreference containing all the output sent to STDOUT the
 271  command generated.
 272  Note that buffers are only available if you have C<IPC::Run> installed,
 273  or if your system is able to work with C<IPC::Open3> -- See below).
 274  This element will be C<undef> if this is not the case.
 275  
 276  =item error_buffer
 277  
 278  This is an arrayreference containing all the output sent to STDERR the
 279  command generated.
 280  Note that buffers are only available if you have C<IPC::Run> installed,
 281  or if your system is able to work with C<IPC::Open3> -- See below).
 282  This element will be C<undef> if this is not the case.
 283  
 284  =back
 285  
 286  See the C<HOW IT WORKS> Section below to see how C<IPC::Cmd> decides
 287  what modules or function calls to use when issuing a command.
 288  
 289  =cut
 290  
 291  sub run {
 292      my %hash = @_;
 293      
 294      ### if the user didn't provide a buffer, we'll store it here.
 295      my $def_buf = '';
 296      
 297      my($verbose,$cmd,$buffer);
 298      my $tmpl = {
 299          verbose => { default  => $VERBOSE,  store => \$verbose },
 300          buffer  => { default  => \$def_buf, store => \$buffer },
 301          command => { required => 1,         store => \$cmd,
 302                       allow    => sub { !ref($_[0]) or ref($_[0]) eq 'ARRAY' } 
 303          },
 304      };
 305  
 306      unless( check( $tmpl, \%hash, $VERBOSE ) ) {
 307          Carp::carp(loc("Could not validate input: %1", Params::Check->last_error));
 308          return;
 309      };        
 310  
 311      print loc("Running [%1]...\n", (ref $cmd ? "@$cmd" : $cmd)) if $verbose;
 312  
 313      ### did the user pass us a buffer to fill or not? if so, set this
 314      ### flag so we know what is expected of us
 315      ### XXX this is now being ignored. in the future, we could add diagnostic
 316      ### messages based on this logic
 317      #my $user_provided_buffer = $buffer == \$def_buf ? 0 : 1;
 318      
 319      ### buffers that are to be captured
 320      my( @buffer, @buff_err, @buff_out );
 321  
 322      ### capture STDOUT
 323      my $_out_handler = sub {
 324          my $buf = shift;
 325          return unless defined $buf;
 326          
 327          print STDOUT $buf if $verbose;
 328          push @buffer,   $buf;
 329          push @buff_out, $buf;
 330      };
 331      
 332      ### capture STDERR
 333      my $_err_handler = sub {
 334          my $buf = shift;
 335          return unless defined $buf;
 336          
 337          print STDERR $buf if $verbose;
 338          push @buffer,   $buf;
 339          push @buff_err, $buf;
 340      };
 341      
 342  
 343      ### flag to indicate we have a buffer captured
 344      my $have_buffer = __PACKAGE__->can_capture_buffer ? 1 : 0;
 345      
 346      ### flag indicating if the subcall went ok
 347      my $ok;
 348      
 349      ### IPC::Run is first choice if $USE_IPC_RUN is set.
 350      if( $USE_IPC_RUN and __PACKAGE__->can_use_ipc_run( 1 ) ) {
 351          ### ipc::run handlers needs the command as a string or an array ref
 352  
 353          __PACKAGE__->_debug( "# Using IPC::Run. Have buffer: $have_buffer" )
 354              if $DEBUG;
 355              
 356          $ok = __PACKAGE__->_ipc_run( $cmd, $_out_handler, $_err_handler );
 357  
 358      ### since IPC::Open3 works on all platforms, and just fails on
 359      ### win32 for capturing buffers, do that ideally
 360      } elsif ( $USE_IPC_OPEN3 and __PACKAGE__->can_use_ipc_open3( 1 ) ) {
 361  
 362          __PACKAGE__->_debug( "# Using IPC::Open3. Have buffer: $have_buffer" )
 363              if $DEBUG;
 364  
 365          ### in case there are pipes in there;
 366          ### IPC::Open3 will call exec and exec will do the right thing 
 367          $ok = __PACKAGE__->_open3_run( 
 368                                  ( ref $cmd ? "@$cmd" : $cmd ),
 369                                  $_out_handler, $_err_handler, $verbose 
 370                              );
 371          
 372      ### if we are allowed to run verbose, just dispatch the system command
 373      } else {
 374          __PACKAGE__->_debug( "# Using system(). Have buffer: $have_buffer" )
 375              if $DEBUG;
 376          $ok = __PACKAGE__->_system_run( (ref $cmd ? "@$cmd" : $cmd), $verbose );
 377      }
 378      
 379      ### fill the buffer;
 380      $$buffer = join '', @buffer if @buffer;
 381      
 382      ### return a list of flags and buffers (if available) in list
 383      ### context, or just a simple 'ok' in scalar
 384      return wantarray
 385                  ? $have_buffer
 386                      ? ($ok, $?, \@buffer, \@buff_out, \@buff_err)
 387                      : ($ok, $? )
 388                  : $ok
 389      
 390      
 391  }
 392  
 393  sub _open3_run { 
 394      my $self            = shift;
 395      my $cmd             = shift;
 396      my $_out_handler    = shift;
 397      my $_err_handler    = shift;
 398      my $verbose         = shift || 0;
 399  
 400      ### Following code are adapted from Friar 'abstracts' in the
 401      ### Perl Monastery (http://www.perlmonks.org/index.pl?node_id=151886).
 402      ### XXX that code didn't work.
 403      ### we now use the following code, thanks to theorbtwo
 404  
 405      ### define them beforehand, so we always have defined FH's
 406      ### to read from.
 407      use Symbol;    
 408      my $kidout      = Symbol::gensym();
 409      my $kiderror    = Symbol::gensym();
 410  
 411      ### Dup the filehandle so we can pass 'our' STDIN to the
 412      ### child process. This stops us from having to pump input
 413      ### from ourselves to the childprocess. However, we will need
 414      ### to revive the FH afterwards, as IPC::Open3 closes it.
 415      ### We'll do the same for STDOUT and STDERR. It works without
 416      ### duping them on non-unix derivatives, but not on win32.
 417      my @fds_to_dup = ( IS_WIN32 && !$verbose 
 418                              ? qw[STDIN STDOUT STDERR] 
 419                              : qw[STDIN]
 420                          );
 421      __PACKAGE__->__dup_fds( @fds_to_dup );
 422      
 423  
 424      my $pid = IPC::Open3::open3(
 425                      '<&STDIN',
 426                      (IS_WIN32 ? '>&STDOUT' : $kidout),
 427                      (IS_WIN32 ? '>&STDERR' : $kiderror),
 428                      $cmd
 429                  );
 430  
 431      ### use OUR stdin, not $kidin. Somehow,
 432      ### we never get the input.. so jump through
 433      ### some hoops to do it :(
 434      my $selector = IO::Select->new(
 435                          (IS_WIN32 ? \*STDERR : $kiderror), 
 436                          \*STDIN,   
 437                          (IS_WIN32 ? \*STDOUT : $kidout)     
 438                      );              
 439  
 440      STDOUT->autoflush(1);   STDERR->autoflush(1);   STDIN->autoflush(1);
 441      $kidout->autoflush(1)   if UNIVERSAL::can($kidout,   'autoflush');
 442      $kiderror->autoflush(1) if UNIVERSAL::can($kiderror, 'autoflush');
 443  
 444      ### add an epxlicit break statement
 445      ### code courtesy of theorbtwo from #london.pm
 446      my $stdout_done = 0;
 447      my $stderr_done = 0;
 448      OUTER: while ( my @ready = $selector->can_read ) {
 449  
 450          for my $h ( @ready ) {
 451              my $buf;
 452              
 453              ### $len is the amount of bytes read
 454              my $len = sysread( $h, $buf, 4096 );    # try to read 4096 bytes
 455              
 456              ### see perldoc -f sysread: it returns undef on error,
 457              ### so bail out.
 458              if( not defined $len ) {
 459                  warn(loc("Error reading from process: %1", $!));
 460                  last OUTER;
 461              }
 462              
 463              ### check for $len. it may be 0, at which point we're
 464              ### done reading, so don't try to process it.
 465              ### if we would print anyway, we'd provide bogus information
 466              $_out_handler->( "$buf" ) if $len && $h == $kidout;
 467              $_err_handler->( "$buf" ) if $len && $h == $kiderror;
 468  
 469              ### Wait till child process is done printing to both
 470              ### stdout and stderr.
 471              $stdout_done = 1 if $h == $kidout   and $len == 0;
 472              $stderr_done = 1 if $h == $kiderror and $len == 0;
 473              last OUTER if ($stdout_done && $stderr_done);
 474          }
 475      }
 476  
 477      waitpid $pid, 0; # wait for it to die
 478  
 479      ### restore STDIN after duping, or STDIN will be closed for
 480      ### this current perl process!
 481      __PACKAGE__->__reopen_fds( @fds_to_dup );
 482      
 483      return if $?;   # some error occurred
 484      return 1;
 485  }
 486  
 487  
 488  sub _ipc_run {  
 489      my $self            = shift;
 490      my $cmd             = shift;
 491      my $_out_handler    = shift;
 492      my $_err_handler    = shift;
 493      
 494      STDOUT->autoflush(1); STDERR->autoflush(1);
 495  
 496      ### a command like:
 497      # [
 498      #     '/usr/bin/gzip',
 499      #     '-cdf',
 500      #     '/Users/kane/sources/p4/other/archive-extract/t/src/x.tgz',
 501      #     '|',
 502      #     '/usr/bin/tar',
 503      #     '-tf -'
 504      # ]
 505      ### needs to become:
 506      # [
 507      #     ['/usr/bin/gzip', '-cdf',
 508      #       '/Users/kane/sources/p4/other/archive-extract/t/src/x.tgz']
 509      #     '|',
 510      #     ['/usr/bin/tar', '-tf -']
 511      # ]
 512  
 513      
 514      my @command; my $special_chars;
 515      if( ref $cmd ) {
 516          my $aref = [];
 517          for my $item (@$cmd) {
 518              if( $item =~ /([<>|&])/ ) {
 519                  push @command, $aref, $item;
 520                  $aref = [];
 521                  $special_chars .= $1;
 522              } else {
 523                  push @$aref, $item;
 524              }
 525          }
 526          push @command, $aref;
 527      } else {
 528          @command = map { if( /([<>|&])/ ) {
 529                              $special_chars .= $1; $_;
 530                           } else {
 531                              [ split / +/ ]
 532                           }
 533                      } split( /\s*([<>|&])\s*/, $cmd );
 534      }
 535   
 536      ### if there's a pipe in the command, *STDIN needs to 
 537      ### be inserted *BEFORE* the pipe, to work on win32
 538      ### this also works on *nix, so we should do it when possible
 539      ### this should *also* work on multiple pipes in the command
 540      ### if there's no pipe in the command, append STDIN to the back
 541      ### of the command instead.
 542      ### XXX seems IPC::Run works it out for itself if you just
 543      ### dont pass STDIN at all.
 544      #     if( $special_chars and $special_chars =~ /\|/ ) {
 545      #         ### only add STDIN the first time..
 546      #         my $i;
 547      #         @command = map { ($_ eq '|' && not $i++) 
 548      #                             ? ( \*STDIN, $_ ) 
 549      #                             : $_ 
 550      #                         } @command; 
 551      #     } else {
 552      #         push @command, \*STDIN;
 553      #     }
 554    
 555   
 556      # \*STDIN is already included in the @command, see a few lines up
 557      return IPC::Run::run(   @command, 
 558                              fileno(STDOUT).'>',
 559                              $_out_handler,
 560                              fileno(STDERR).'>',
 561                              $_err_handler
 562                          );
 563  }
 564  
 565  sub _system_run { 
 566      my $self    = shift;
 567      my $cmd     = shift;
 568      my $verbose = shift || 0;
 569  
 570      my @fds_to_dup = $verbose ? () : qw[STDOUT STDERR];
 571      __PACKAGE__->__dup_fds( @fds_to_dup );
 572      
 573      ### system returns 'true' on failure -- the exit code of the cmd
 574      system( $cmd );
 575      
 576      __PACKAGE__->__reopen_fds( @fds_to_dup );
 577      
 578      return if $?;
 579      return 1;
 580  }
 581  
 582  {   use File::Spec;
 583      use Symbol;
 584  
 585      my %Map = (
 586          STDOUT => [qw|>&|, \*STDOUT, Symbol::gensym() ],
 587          STDERR => [qw|>&|, \*STDERR, Symbol::gensym() ],
 588          STDIN  => [qw|<&|, \*STDIN,  Symbol::gensym() ],
 589      );
 590  
 591      ### dups FDs and stores them in a cache
 592      sub __dup_fds {
 593          my $self    = shift;
 594          my @fds     = @_;
 595  
 596          __PACKAGE__->_debug( "# Closing the following fds: @fds" ) if $DEBUG;
 597  
 598          for my $name ( @fds ) {
 599              my($redir, $fh, $glob) = @{$Map{$name}} or (
 600                  Carp::carp(loc("No such FD: '%1'", $name)), next );
 601              
 602              ### MUST use the 2-arg version of open for dup'ing for 
 603              ### 5.6.x compatibilty. 5.8.x can use 3-arg open
 604              ### see perldoc5.6.2 -f open for details            
 605              open $glob, $redir . fileno($fh) or (
 606                          Carp::carp(loc("Could not dup '$name': %1", $!)),
 607                          return
 608                      );        
 609                  
 610              ### we should re-open this filehandle right now, not
 611              ### just dup it
 612              ### Use 2-arg version of open, as 5.5.x doesn't support
 613              ### 3-arg version =/
 614              if( $redir eq '>&' ) {
 615                  open( $fh, '>' . File::Spec->devnull ) or (
 616                      Carp::carp(loc("Could not reopen '$name': %1", $!)),
 617                      return
 618                  );
 619              }
 620          }
 621          
 622          return 1;
 623      }
 624  
 625      ### reopens FDs from the cache    
 626      sub __reopen_fds {
 627          my $self    = shift;
 628          my @fds     = @_;
 629  
 630          __PACKAGE__->_debug( "# Reopening the following fds: @fds" ) if $DEBUG;
 631  
 632          for my $name ( @fds ) {
 633              my($redir, $fh, $glob) = @{$Map{$name}} or (
 634                  Carp::carp(loc("No such FD: '%1'", $name)), next );
 635  
 636              ### MUST use the 2-arg version of open for dup'ing for 
 637              ### 5.6.x compatibilty. 5.8.x can use 3-arg open
 638              ### see perldoc5.6.2 -f open for details
 639              open( $fh, $redir . fileno($glob) ) or (
 640                      Carp::carp(loc("Could not restore '$name': %1", $!)),
 641                      return
 642                  ); 
 643             
 644              ### close this FD, we're not using it anymore
 645              close $glob;                
 646          }                
 647          return 1;                
 648      
 649      }
 650  }    
 651  
 652  sub _debug {
 653      my $self    = shift;
 654      my $msg     = shift or return;
 655      my $level   = shift || 0;
 656      
 657      local $Carp::CarpLevel += $level;
 658      Carp::carp($msg);
 659      
 660      return 1;
 661  }
 662  
 663  
 664  1;
 665  
 666  
 667  __END__
 668  
 669  =head1 HOW IT WORKS
 670  
 671  C<run> will try to execute your command using the following logic:
 672  
 673  =over 4
 674  
 675  =item *
 676  
 677  If you have C<IPC::Run> installed, and the variable C<$IPC::Cmd::USE_IPC_RUN>
 678  is set to true (See the C<GLOBAL VARIABLES> Section) use that to execute 
 679  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
 680  settings honored cleanly.
 681  
 682  =item *
 683  
 684  Otherwise, if the variable C<$IPC::Cmd::USE_IPC_OPEN3> is set to true 
 685  (See the C<GLOBAL VARIABLES> Section), try to execute the command using
 686  C<IPC::Open3>. Buffers will be available on all platforms except C<Win32>,
 687  interactive commands will still execute cleanly, and also your verbosity
 688  settings will be adhered to nicely;
 689  
 690  =item *
 691  
 692  Otherwise, if you have the verbose argument set to true, we fall back
 693  to a simple system() call. We cannot capture any buffers, but
 694  interactive commands will still work.
 695  
 696  =item *
 697  
 698  Otherwise we will try and temporarily redirect STDERR and STDOUT, do a
 699  system() call with your command and then re-open STDERR and STDOUT.
 700  This is the method of last resort and will still allow you to execute
 701  your commands cleanly. However, no buffers will be available.
 702  
 703  =back
 704  
 705  =head1 Global Variables
 706  
 707  The behaviour of IPC::Cmd can be altered by changing the following
 708  global variables:
 709  
 710  =head2 $IPC::Cmd::VERBOSE
 711  
 712  This controls whether IPC::Cmd will print any output from the
 713  commands to the screen or not. The default is 0;
 714  
 715  =head2 $IPC::Cmd::USE_IPC_RUN
 716  
 717  This variable controls whether IPC::Cmd will try to use L<IPC::Run>
 718  when available and suitable. Defaults to true if you are on C<Win32>.
 719  
 720  =head2 $IPC::Cmd::USE_IPC_OPEN3
 721  
 722  This variable controls whether IPC::Cmd will try to use L<IPC::Open3>
 723  when available and suitable. Defaults to true.
 724  
 725  =head2 $IPC::Cmd::WARN
 726  
 727  This variable controls whether run time warnings should be issued, like
 728  the failure to load an C<IPC::*> module you explicitly requested.
 729  
 730  Defaults to true. Turn this off at your own risk.
 731  
 732  =head1 Caveats
 733  
 734  =over 4
 735  
 736  =item Whitespace
 737  
 738  When you provide a string as this argument, the string will be
 739  split on whitespace to determine the individual elements of your
 740  command. Although this will usually just Do What You Mean, it may
 741  break if you have files or commands with whitespace in them.
 742  
 743  If you do not wish this to happen, you should provide an array
 744  reference, where all parts of your command are already separated out.
 745  Note however, if there's extra or spurious whitespace in these parts,
 746  the parser or underlying code may not interpret it correctly, and
 747  cause an error.
 748  
 749  Example:
 750  The following code
 751  
 752      gzip -cdf foo.tar.gz | tar -xf -
 753  
 754  should either be passed as
 755  
 756      "gzip -cdf foo.tar.gz | tar -xf -"
 757  
 758  or as
 759  
 760      ['gzip', '-cdf', 'foo.tar.gz', '|', 'tar', '-xf', '-']
 761  
 762  But take care not to pass it as, for example
 763  
 764      ['gzip -cdf foo.tar.gz', '|', 'tar -xf -']
 765  
 766  Since this will lead to issues as described above.
 767  
 768  =item IO Redirect
 769  
 770  Currently it is too complicated to parse your command for IO
 771  Redirections. For capturing STDOUT or STDERR there is a work around
 772  however, since you can just inspect your buffers for the contents.
 773  
 774  =back
 775  
 776  =head1 See Also
 777  
 778  C<IPC::Run>, C<IPC::Open3>
 779  
 780  =head1 ACKNOWLEDGEMENTS
 781  
 782  Thanks to James Mastros and Martijn van der Streek for their
 783  help in getting IPC::Open3 to behave nicely.
 784  
 785  =head1 BUG REPORTS
 786  
 787  Please report bugs or other issues to E<lt>bug-ipc-cmd@rt.cpan.orgE<gt>.
 788  
 789  =head1 AUTHOR
 790  
 791  This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
 792  
 793  =head1 COPYRIGHT
 794  
 795  This library is free software; you may redistribute and/or modify it 
 796  under the same terms as Perl itself.
 797  
 798  =cut