lib/IPC/Cmd.pm

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