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_01';
  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                      File::Spec->curdir()
 191         ) {
 192             my $abs = File::Spec->catfile($dir, $command);
 193             return $abs if $abs = MM->maybe_command($abs);
 194         }
 195     }
 196 }
 197
 198 =head2 $ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( command => COMMAND, [verbose => BOOL, buffer => \$SCALAR] );
 199
 200 C<run> takes 3 arguments:
 201
 202 =over 4
 203
 204 =item command
 205
 206 This is the command to execute. It may be either a string or an array
 207 reference.
 208 This is a required argument.
 209
 210 See L<CAVEATS> for remarks on how commands are parsed and their
 211 limitations.
 212
 213 =item verbose
 214
 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
 218 C<IPC::Open3>).
 219
 220 It will default to the global setting of C<$IPC::Cmd::VERBOSE>,
 221 which by default is 0.
 222
 223 =item buffer
 224
 225 This will hold all the output of a command. It needs to be a reference
 226 to a scalar.
 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.
 231
 232 Of course, this requires that the underlying call supports buffers. See
 233 the note on buffers right above.
 234
 235 =back
 236
 237 C<run> will return a simple C<true> or C<false> when called in scalar
 238 context.
 239 In list context, you will be returned a list of the following items:
 240
 241 =over 4
 242
 243 =item success
 244
 245 A simple boolean indicating if the command executed without errors or
 246 not.
 247
 248 =item errorcode
 249
 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.
 253
 254 =item full_buffer
 255
 256 This is an arrayreference containing all the output the command
 257 generated.
 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.
 261
 262 =item out_buffer
 263
 264 This is an arrayreference containing all the output sent to STDOUT the
 265 command generated.
 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.
 269
 270 =item error_buffer
 271
 272 This is an arrayreference containing all the output sent to STDERR the
 273 command generated.
 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.
 277
 278 =back
 279
 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.
 282
 283 =cut
 284
 285 sub run {
 286     my %hash = @_;
 287
 288     ### if the user didn't provide a buffer, we'll store it here.
 289     my $def_buf = '';
 290
 291     my($verbose,$cmd,$buffer);
 292     my $tmpl = {
 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' }
 297         },
 298     };
 299
 300     unless( check( $tmpl, \%hash, $VERBOSE ) ) {
 301         Carp::carp(loc("Could not validate input: %1", Params::Check->last_error));
 302         return;
 303     };
 304
 305     print loc("Running [%1]...\n", (ref $cmd ? "@$cmd" : $cmd)) if $verbose;
 306
 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;
 312
 313     ### buffers that are to be captured
 314     my( @buffer, @buff_err, @buff_out );
 315
 316     ### capture STDOUT
 317     my $_out_handler = sub {
 318         my $buf = shift;
 319         return unless defined $buf;
 320
 321         print STDOUT $buf if $verbose;
 322         push @buffer,   $buf;
 323         push @buff_out, $buf;
 324     };
 325
 326     ### capture STDERR
 327     my $_err_handler = sub {
 328         my $buf = shift;
 329         return unless defined $buf;
 330
 331         print STDERR $buf if $verbose;
 332         push @buffer,   $buf;
 333         push @buff_err, $buf;
 334     };
 335
 336
 337     ### flag to indicate we have a buffer captured
 338     my $have_buffer = __PACKAGE__->can_capture_buffer ? 1 : 0;
 339
 340     ### flag indicating if the subcall went ok
 341     my $ok;
 342
 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
 346
 347         __PACKAGE__->_debug( "# Using IPC::Run. Have buffer: $have_buffer" )
 348             if $DEBUG;
 349
 350         $ok = __PACKAGE__->_ipc_run( $cmd, $_out_handler, $_err_handler );
 351
 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 ) ) {
 355
 356         __PACKAGE__->_debug( "# Using IPC::Open3. Have buffer: $have_buffer" )
 357             if $DEBUG;
 358
 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
 364                             );
 365
 366     ### if we are allowed to run verbose, just dispatch the system command
 367     } else {
 368         __PACKAGE__->_debug( "# Using system(). Have buffer: $have_buffer" )
 369             if $DEBUG;
 370         $ok = __PACKAGE__->_system_run( (ref $cmd ? "@$cmd" : $cmd), $verbose );
 371     }
 372
 373     ### fill the buffer;
 374     $$buffer = join '', @buffer if @buffer;
 375
 376     ### return a list of flags and buffers (if available) in list
 377     ### context, or just a simple 'ok' in scalar
 378     return wantarray
 379                 ? $have_buffer
 380                     ? ($ok, $?, \@buffer, \@buff_out, \@buff_err)
 381                     : ($ok, $? )
 382                 : $ok
 383
 384
 385 }
 386
 387 sub _open3_run {
 388     my $self            = shift;
 389     my $cmd             = shift;
 390     my $_out_handler    = shift;
 391     my $_err_handler    = shift;
 392     my $verbose         = shift || 0;
 393
 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
 398
 399     ### define them beforehand, so we always have defined FH's
 400     ### to read from.
 401     use Symbol;
 402     my $kidout      = Symbol::gensym();
 403     my $kiderror    = Symbol::gensym();
 404
 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]
 413                             : qw[STDIN]
 414                         );
 415     __PACKAGE__->__dup_fds( @fds_to_dup );
 416
 417
 418     my $pid = IPC::Open3::open3(
 419                     '<&STDIN',
 420                     (IS_WIN32 ? '>&STDOUT' : $kidout),
 421                     (IS_WIN32 ? '>&STDERR' : $kiderror),
 422                     $cmd
 423                 );
 424
 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),
 430                         \*STDIN,
 431                         (IS_WIN32 ? \*STDOUT : $kidout)
 432                     );
 433
 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');
 437
 438     ### add an epxlicit break statement
 439     ### code courtesy of theorbtwo from #london.pm
 440     OUTER: while ( my @ready = $selector->can_read ) {
 441
 442         for my $h ( @ready ) {
 443             my $buf;
 444
 445             ### $len is the amount of bytes read
 446             my $len = sysread( $h, $buf, 4096 );    # try to read 4096 bytes
 447
 448             ### see perldoc -f sysread: it returns undef on error,
 449             ### so bail out.
 450             if( not defined $len ) {
 451                 warn(loc("Error reading from process: %1", $!));
 452                 last OUTER;
 453             }
 454
 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;
 460
 461             ### child process is done printing.
 462             last OUTER if $h == $kidout and $len == 0
 463         }
 464     }
 465
 466     waitpid $pid, 0; # wait for it to die
 467
 468     ### restore STDIN after duping, or STDIN will be closed for
 469     ### this current perl process!
 470     __PACKAGE__->__reopen_fds( @fds_to_dup );
 471
 472     return if $?;   # some error occurred
 473     return 1;
 474 }
 475
 476
 477 sub _ipc_run {
 478     my $self            = shift;
 479     my $cmd             = shift;
 480     my $_out_handler    = shift;
 481     my $_err_handler    = shift;
 482
 483     STDOUT->autoflush(1); STDERR->autoflush(1);
 484
 485     ### a command like:
 486     # [
 487     #     '/usr/bin/gzip',
 488     #     '-cdf',
 489     #     '/Users/kane/sources/p4/other/archive-extract/t/src/x.tgz',
 490     #     '|',
 491     #     '/usr/bin/tar',
 492     #     '-tf -'
 493     # ]
 494     ### needs to become:
 495     # [
 496     #     ['/usr/bin/gzip', '-cdf',
 497     #       '/Users/kane/sources/p4/other/archive-extract/t/src/x.tgz']
 498     #     '|',
 499     #     ['/usr/bin/tar', '-tf -']
 500     # ]
 501
 502
 503     my @command; my $special_chars;
 504     if( ref $cmd ) {
 505         my $aref = [];
 506         for my $item (@$cmd) {
 507             if( $item =~ /([<>|&])/ ) {
 508                 push @command, $aref, $item;
 509                 $aref = [];
 510                 $special_chars .= $1;
 511             } else {
 512                 push @$aref, $item;
 513             }
 514         }
 515         push @command, $aref;
 516     } else {
 517         @command = map { if( /([<>|&])/ ) {
 518                             $special_chars .= $1; $_;
 519                          } else {
 520                             [ split / +/ ]
 521                          }
 522                     } split( /\s*([<>|&])\s*/, $cmd );
 523     }
 524
 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..
 535     #         my $i;
 536     #         @command = map { ($_ eq '|' && not $i++)
 537     #                             ? ( \*STDIN, $_ )
 538     #                             : $_
 539     #                         } @command;
 540     #     } else {
 541     #         push @command, \*STDIN;
 542     #     }
 543
 544
 545     # \*STDIN is already included in the @command, see a few lines up
 546     return IPC::Run::run(   @command,
 547                             fileno(STDOUT).'>',
 548                             $_out_handler,
 549                             fileno(STDERR).'>',
 550                             $_err_handler
 551                         );
 552 }
 553
 554 sub _system_run {
 555     my $self    = shift;
 556     my $cmd     = shift;
 557     my $verbose = shift || 0;
 558
 559     my @fds_to_dup = $verbose ? () : qw[STDOUT STDERR];
 560     __PACKAGE__->__dup_fds( @fds_to_dup );
 561
 562     ### system returns 'true' on failure -- the exit code of the cmd
 563     system( $cmd );
 564
 565     __PACKAGE__->__reopen_fds( @fds_to_dup );
 566
 567     return if $?;
 568     return 1;
 569 }
 570
 571 {   use File::Spec;
 572     use Symbol;
 573
 574     my %Map = (
 575         STDOUT => [qw|>&|, \*STDOUT, Symbol::gensym() ],
 576         STDERR => [qw|>&|, \*STDERR, Symbol::gensym() ],
 577         STDIN  => [qw|<&|, \*STDIN,  Symbol::gensym() ],
 578     );
 579
 580     ### dups FDs and stores them in a cache
 581     sub __dup_fds {
 582         my $self    = shift;
 583         my @fds     = @_;
 584
 585         __PACKAGE__->_debug( "# Closing the following fds: @fds" ) if $DEBUG;
 586
 587         for my $name ( @fds ) {
 588             my($redir, $fh, $glob) = @{$Map{$name}} or (
 589                 Carp::carp(loc("No such FD: '%1'", $name)), next );
 590
 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", $!)),
 596                         return
 597                     );
 598
 599             ### we should re-open this filehandle right now, not
 600             ### just dup it
 601             if( $redir eq '>&' ) {
 602                 open( $fh, '>', File::Spec->devnull ) or (
 603                     Carp::carp(loc("Could not reopen '$name': %1", $!)),
 604                     return
 605                 );
 606             }
 607         }
 608
 609         return 1;
 610     }
 611
 612     ### reopens FDs from the cache
 613     sub __reopen_fds {
 614         my $self    = shift;
 615         my @fds     = @_;
 616
 617         __PACKAGE__->_debug( "# Reopening the following fds: @fds" ) if $DEBUG;
 618
 619         for my $name ( @fds ) {
 620             my($redir, $fh, $glob) = @{$Map{$name}} or (
 621                 Carp::carp(loc("No such FD: '%1'", $name)), next );
 622
 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", $!)),
 628                     return
 629                 );
 630
 631             ### close this FD, we're not using it anymore
 632             close $glob;
 633         }
 634         return 1;
 635
 636     }
 637 }
 638
 639 sub _debug {
 640     my $self    = shift;
 641     my $msg     = shift or return;
 642     my $level   = shift || 0;
 643
 644     local $Carp::CarpLevel += $level;
 645     Carp::carp($msg);
 646
 647     return 1;
 648 }
 649
 650
 651 1;
 652
 653
 654 __END__
 655
 656 =head1 HOW IT WORKS
 657
 658 C<run> will try to execute your command using the following logic:
 659
 660 =over 4
 661
 662 =item *
 663
 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.
 668
 669 =item *
 670
 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;
 676
 677 =item *
 678
 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.
 682
 683 =item *
 684
 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.
 689
 690 =back
 691
 692 =head1 Global Variables
 693
 694 The behaviour of IPC::Cmd can be altered by changing the following
 695 global variables:
 696
 697 =head2 $IPC::Cmd::VERBOSE
 698
 699 This controls whether IPC::Cmd will print any output from the
 700 commands to the screen or not. The default is 0;
 701
 702 =head2 $IPC::Cmd::USE_IPC_RUN
 703
 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>.
 706
 707 =head2 $IPC::Cmd::USE_IPC_OPEN3
 708
 709 This variable controls whether IPC::Cmd will try to use L<IPC::Open3>
 710 when available and suitable. Defaults to true.
 711
 712 =head2 $IPC::Cmd::WARN
 713
 714 This variable controls whether run time warnings should be issued, like
 715 the failure to load an C<IPC::*> module you explicitly requested.
 716
 717 Defaults to true. Turn this off at your own risk.
 718
 719 =head1 Caveats
 720
 721 =over 4
 722
 723 =item Whitespace
 724
 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.
 729
 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
 734 cause an error.
 735
 736 Example:
 737 The following code
 738
 739     gzip -cdf foo.tar.gz | tar -xf -
 740
 741 should either be passed as
 742
 743     "gzip -cdf foo.tar.gz | tar -xf -"
 744
 745 or as
 746
 747     ['gzip', '-cdf', 'foo.tar.gz', '|', 'tar', '-xf', '-']
 748
 749 But take care not to pass it as, for example
 750
 751     ['gzip -cdf foo.tar.gz', '|', 'tar -xf -']
 752
 753 Since this will lead to issues as described above.
 754
 755 =item IO Redirect
 756
 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.
 760
 761 =back
 762
 763 =head1 See Also
 764
 765 C<IPC::Run>, C<IPC::Open3>
 766
 767 =head1 AUTHOR
 768
 769 This module by
 770 Jos Boumans E<lt>kane@cpan.orgE<gt>.
 771
 772 =head1 ACKNOWLEDGEMENTS
 773
 774 Thanks to James Mastros and Martijn van der Streek for their
 775 help in getting IPC::Open3 to behave nicely.
 776
 777 =head1 COPYRIGHT
 778
 779 This module is
 780 copyright (c) 2002 - 2006 Jos Boumans E<lt>kane@cpan.orgE<gt>.
 781 All rights reserved.
 782
 783 This library is free software;
 784 you may redistribute and/or modify it under the same
 785 terms as Perl itself.