local-lib5/lib/perl5/IPC/Run3.pm

   1 package IPC::Run3;
   2 BEGIN { require 5.006_000; } # i.e. 5.6.0
   3 use strict;
   4
   5 =head1 NAME
   6
   7 IPC::Run3 - run a subprocess with input/ouput redirection
   8
   9 =head1 VERSION
  10
  11 version 0.043
  12
  13 =cut
  14
  15 our $VERSION = '0.043';
  16
  17 =head1 SYNOPSIS
  18
  19     use IPC::Run3;    # Exports run3() by default
  20
  21     run3 \@cmd, \$in, \$out, \$err;
  22
  23 =head1 DESCRIPTION
  24
  25 This module allows you to run a subprocess and redirect stdin, stdout,
  26 and/or stderr to files and perl data structures.  It aims to satisfy 99% of the
  27 need for using C<system>, C<qx>, and C<open3>
  28 with a simple, extremely Perlish API.
  29
  30 Speed, simplicity, and portability are paramount.  (That's speed of Perl code;
  31 which is often much slower than the kind of buffered I/O that this module uses
  32 to spool input to and output from the child command.)
  33
  34 =cut
  35
  36 use Exporter;
  37 our @ISA = qw(Exporter);
  38 our @EXPORT = qw( run3 );
  39 our %EXPORT_TAGS = ( all => \@EXPORT );
  40
  41 use constant debugging => $ENV{IPCRUN3DEBUG} || $ENV{IPCRUNDEBUG} || 0;
  42 use constant profiling => $ENV{IPCRUN3PROFILE} || $ENV{IPCRUNPROFILE} || 0;
  43 use constant is_win32  => 0 <= index $^O, "Win32";
  44
  45 BEGIN {
  46    if ( is_win32 ) {
  47       eval "use Win32 qw( GetOSName ); 1" or die $@;
  48    }
  49 }
  50
  51 #use constant is_win2k => is_win32 && GetOSName() =~ /Win2000/i;
  52 #use constant is_winXP => is_win32 && GetOSName() =~ /WinXP/i;
  53
  54 use Carp qw( croak );
  55 use File::Temp qw( tempfile );
  56 use POSIX qw( dup dup2 );
  57
  58 # We cache the handles of our temp files in order to
  59 # keep from having to incur the (largish) overhead of File::Temp
  60 my %fh_cache;
  61 my $fh_cache_pid = $$;
  62
  63 my $profiler;
  64
  65 sub _profiler { $profiler } # test suite access
  66
  67 BEGIN {
  68     if ( profiling ) {
  69         eval "use Time::HiRes qw( gettimeofday ); 1" or die $@;
  70         if ( $ENV{IPCRUN3PROFILE} =~ /\A\d+\z/ ) {
  71             require IPC::Run3::ProfPP;
  72             IPC::Run3::ProfPP->import;
  73             $profiler = IPC::Run3::ProfPP->new(Level => $ENV{IPCRUN3PROFILE});
  74         } else {
  75             my ( $dest, undef, $class ) =
  76                reverse split /(=)/, $ENV{IPCRUN3PROFILE}, 2;
  77             $class = "IPC::Run3::ProfLogger"
  78                 unless defined $class && length $class;
  79             if ( not eval "require $class" ) {
  80                 my $e = $@;
  81                 $class = "IPC::Run3::$class";
  82                 eval "require IPC::Run3::$class" or die $e;
  83             }
  84             $profiler = $class->new( Destination => $dest );
  85         }
  86         $profiler->app_call( [ $0, @ARGV ], scalar gettimeofday() );
  87     }
  88 }
  89
  90
  91 END {
  92     $profiler->app_exit( scalar gettimeofday() ) if profiling;
  93 }
  94
  95 sub _binmode {
  96     my ( $fh, $mode, $what ) = @_;
  97     # if $mode is not given, then default to ":raw", except on Windows,
  98     # where we default to ":crlf";
  99     # otherwise if a proper layer string was given, use that,
 100     # else use ":raw"
 101     my $layer = !$mode
 102         ? (is_win32 ? ":crlf" : ":raw")
 103         : ($mode =~ /^:/ ? $mode : ":raw");
 104     warn "binmode $what, $layer\n" if debugging >= 2;
 105
 106     binmode $fh, ":raw" unless $layer eq ":raw";      # remove all layers first
 107     binmode $fh, $layer or croak "binmode $layer failed: $!";
 108 }
 109
 110 sub _spool_data_to_child {
 111     my ( $type, $source, $binmode_it ) = @_;
 112
 113     # If undef (not \undef) passed, they want the child to inherit
 114     # the parent's STDIN.
 115     return undef unless defined $source;
 116
 117     my $fh;
 118     if ( ! $type ) {
 119         open $fh, "<", $source or croak "$!: $source";
 120         _binmode($fh, $binmode_it, "STDIN");
 121         warn "run3(): feeding file '$source' to child STDIN\n"
 122             if debugging >= 2;
 123     } elsif ( $type eq "FH" ) {
 124         $fh = $source;
 125         warn "run3(): feeding filehandle '$source' to child STDIN\n"
 126             if debugging >= 2;
 127     } else {
 128         $fh = $fh_cache{in} ||= tempfile;
 129         truncate $fh, 0;
 130         seek $fh, 0, 0;
 131         _binmode($fh, $binmode_it, "STDIN");
 132         my $seekit;
 133         if ( $type eq "SCALAR" ) {
 134
 135             # When the run3()'s caller asks to feed an empty file
 136             # to the child's stdin, we want to pass a live file
 137             # descriptor to an empty file (like /dev/null) so that
 138             # they don't get surprised by invalid fd errors and get
 139             # normal EOF behaviors.
 140             return $fh unless defined $$source;  # \undef passed
 141
 142             warn "run3(): feeding SCALAR to child STDIN",
 143                 debugging >= 3
 144                    ? ( ": '", $$source, "' (", length $$source, " chars)" )
 145                    : (),
 146                 "\n"
 147                 if debugging >= 2;
 148
 149             $seekit = length $$source;
 150             print $fh $$source or die "$! writing to temp file";
 151
 152         } elsif ( $type eq "ARRAY" ) {
 153             warn "run3(): feeding ARRAY to child STDIN",
 154                 debugging >= 3 ? ( ": '", @$source, "'" ) : (),
 155                 "\n"
 156             if debugging >= 2;
 157
 158             print $fh @$source or die "$! writing to temp file";
 159             $seekit = grep length, @$source;
 160         } elsif ( $type eq "CODE" ) {
 161             warn "run3(): feeding output of CODE ref '$source' to child STDIN\n"
 162                 if debugging >= 2;
 163             my $parms = [];  # TODO: get these from $options
 164             while (1) {
 165                 my $data = $source->( @$parms );
 166                 last unless defined $data;
 167                 print $fh $data or die "$! writing to temp file";
 168                 $seekit = length $data;
 169             }
 170         }
 171
 172         seek $fh, 0, 0 or croak "$! seeking on temp file for child's stdin"
 173             if $seekit;
 174     }
 175
 176     croak "run3() can't redirect $type to child stdin"
 177         unless defined $fh;
 178
 179     return $fh;
 180 }
 181
 182 sub _fh_for_child_output {
 183     my ( $what, $type, $dest, $options ) = @_;
 184
 185     my $fh;
 186     if ( $type eq "SCALAR" && $dest == \undef ) {
 187         warn "run3(): redirecting child $what to oblivion\n"
 188             if debugging >= 2;
 189
 190         $fh = $fh_cache{nul} ||= do {
 191             open $fh, ">", File::Spec->devnull;
 192             $fh;
 193         };
 194     } elsif ( $type eq "FH" ) {
 195         $fh = $dest;
 196         warn "run3(): redirecting $what to filehandle '$dest'\n"
 197             if debugging >= 3;
 198     } elsif ( !$type ) {
 199         warn "run3(): feeding child $what to file '$dest'\n"
 200             if debugging >= 2;
 201
 202         open $fh, $options->{"append_$what"} ? ">>" : ">", $dest
 203             or croak "$!: $dest";
 204     } else {
 205         warn "run3(): capturing child $what\n"
 206             if debugging >= 2;
 207
 208         $fh = $fh_cache{$what} ||= tempfile;
 209         seek $fh, 0, 0;
 210         truncate $fh, 0;
 211     }
 212
 213     my $binmode_it = $options->{"binmode_$what"};
 214     _binmode($fh, $binmode_it, uc $what);
 215
 216     return $fh;
 217 }
 218
 219 sub _read_child_output_fh {
 220     my ( $what, $type, $dest, $fh, $options ) = @_;
 221
 222     return if $type eq "SCALAR" && $dest == \undef;
 223
 224     seek $fh, 0, 0 or croak "$! seeking on temp file for child $what";
 225
 226     if ( $type eq "SCALAR" ) {
 227         warn "run3(): reading child $what to SCALAR\n"
 228             if debugging >= 3;
 229
 230         # two read()s are used instead of 1 so that the first will be
 231         # logged even it reads 0 bytes; the second won't.
 232         my $count = read $fh, $$dest, 10_000,
 233             $options->{"append_$what"} ? length $$dest : 0;
 234         while (1) {
 235             croak "$! reading child $what from temp file"
 236                 unless defined $count;
 237
 238             last unless $count;
 239
 240             warn "run3(): read $count bytes from child $what",
 241                 debugging >= 3 ? ( ": '", substr( $$dest, -$count ), "'" ) : (),
 242                 "\n"
 243                 if debugging >= 2;
 244
 245             $count = read $fh, $$dest, 10_000, length $$dest;
 246         }
 247     } elsif ( $type eq "ARRAY" ) {
 248         if ($options->{"append_$what"}) {
 249             push @$dest, <$fh>;
 250         } else {
 251             @$dest = <$fh>;
 252         }
 253         if ( debugging >= 2 ) {
 254             my $count = 0;
 255             $count += length for @$dest;
 256             warn
 257                 "run3(): read ",
 258                 scalar @$dest,
 259                 " records, $count bytes from child $what",
 260                 debugging >= 3 ? ( ": '", @$dest, "'" ) : (),
 261                 "\n";
 262         }
 263     } elsif ( $type eq "CODE" ) {
 264         warn "run3(): capturing child $what to CODE ref\n"
 265             if debugging >= 3;
 266
 267         local $_;
 268         while ( <$fh> ) {
 269             warn
 270                 "run3(): read ",
 271                 length,
 272                 " bytes from child $what",
 273                 debugging >= 3 ? ( ": '", $_, "'" ) : (),
 274                 "\n"
 275                 if debugging >= 2;
 276
 277             $dest->( $_ );
 278         }
 279     } else {
 280         croak "run3() can't redirect child $what to a $type";
 281     }
 282
 283 }
 284
 285 sub _type {
 286     my ( $redir ) = @_;
 287     return "FH" if eval { $redir->isa("IO::Handle") };
 288     my $type = ref $redir;
 289     return $type eq "GLOB" ? "FH" : $type;
 290 }
 291
 292 sub _max_fd {
 293     my $fd = dup(0);
 294     POSIX::close $fd;
 295     return $fd;
 296 }
 297
 298 my $run_call_time;
 299 my $sys_call_time;
 300 my $sys_exit_time;
 301
 302 sub run3 {
 303     $run_call_time = gettimeofday() if profiling;
 304
 305     my $options = @_ && ref $_[-1] eq "HASH" ? pop : {};
 306
 307     my ( $cmd, $stdin, $stdout, $stderr ) = @_;
 308
 309     print STDERR "run3(): running ",
 310        join( " ", map "'$_'", ref $cmd ? @$cmd : $cmd ),
 311        "\n"
 312        if debugging;
 313
 314     if ( ref $cmd ) {
 315         croak "run3(): empty command"     unless @$cmd;
 316         croak "run3(): undefined command" unless defined $cmd->[0];
 317         croak "run3(): command name ('')" unless length  $cmd->[0];
 318     } else {
 319         croak "run3(): missing command" unless @_;
 320         croak "run3(): undefined command" unless defined $cmd;
 321         croak "run3(): command ('')" unless length  $cmd;
 322     }
 323
 324     foreach (qw/binmode_stdin binmode_stdout binmode_stderr/) {
 325         if (my $mode = $options->{$_}) {
 326             croak qq[option $_ must be a number or a proper layer string: "$mode"]
 327                 unless $mode =~ /^(:|\d+$)/;
 328         }
 329     }
 330
 331     my $in_type  = _type $stdin;
 332     my $out_type = _type $stdout;
 333     my $err_type = _type $stderr;
 334
 335     if ($fh_cache_pid != $$) {
 336         # fork detected, close all cached filehandles and clear the cache
 337         close $_ foreach values %fh_cache;
 338         %fh_cache = ();
 339         $fh_cache_pid = $$;
 340     }
 341
 342     # This routine procedes in stages so that a failure in an early
 343     # stage prevents later stages from running, and thus from needing
 344     # cleanup.
 345
 346     my $in_fh  = _spool_data_to_child $in_type, $stdin,
 347         $options->{binmode_stdin} if defined $stdin;
 348
 349     my $out_fh = _fh_for_child_output "stdout", $out_type, $stdout,
 350         $options if defined $stdout;
 351
 352     my $tie_err_to_out =
 353         defined $stderr && defined $stdout && $stderr eq $stdout;
 354
 355     my $err_fh = $tie_err_to_out
 356         ? $out_fh
 357         : _fh_for_child_output "stderr", $err_type, $stderr,
 358             $options if defined $stderr;
 359
 360     # this should make perl close these on exceptions
 361 #    local *STDIN_SAVE;
 362     local *STDOUT_SAVE;
 363     local *STDERR_SAVE;
 364
 365     my $saved_fd0 = dup( 0 ) if defined $in_fh;
 366
 367 #    open STDIN_SAVE,  "<&STDIN"#  or croak "run3(): $! saving STDIN"
 368 #        if defined $in_fh;
 369     open STDOUT_SAVE, ">&STDOUT" or croak "run3(): $! saving STDOUT"
 370         if defined $out_fh;
 371     open STDERR_SAVE, ">&STDERR" or croak "run3(): $! saving STDERR"
 372         if defined $err_fh;
 373
 374     my $errno;
 375     my $ok = eval {
 376         # The open() call here seems to not force fd 0 in some cases;
 377         # I ran in to trouble when using this in VCP, not sure why.
 378         # the dup2() seems to work.
 379         dup2( fileno $in_fh, 0 )
 380 #        open STDIN,  "<&=" . fileno $in_fh
 381             or croak "run3(): $! redirecting STDIN"
 382             if defined $in_fh;
 383
 384 #        close $in_fh or croak "$! closing STDIN temp file"
 385 #            if ref $stdin;
 386
 387         open STDOUT, ">&" . fileno $out_fh
 388             or croak "run3(): $! redirecting STDOUT"
 389             if defined $out_fh;
 390
 391         open STDERR, ">&" . fileno $err_fh
 392             or croak "run3(): $! redirecting STDERR"
 393             if defined $err_fh;
 394
 395         $sys_call_time = gettimeofday() if profiling;
 396
 397         my $r = ref $cmd
 398               ? system { $cmd->[0] }
 399                        is_win32
 400                            ? map {
 401                                  # Probably need to offer a win32 escaping
 402                                  # option, every command may be different.
 403                                  ( my $s = $_ ) =~ s/"/"""/g;
 404                                  $s = qq{"$s"};
 405                                  $s;
 406                              } @$cmd
 407                            : @$cmd
 408               : system $cmd;
 409
 410         $errno = $!;            # save $!, because later failures will overwrite it
 411         $sys_exit_time = gettimeofday() if profiling;
 412         if ( debugging ) {
 413             my $err_fh = defined $err_fh ? \*STDERR_SAVE : \*STDERR;
 414             if ( defined $r && $r != -1 ) {
 415                 print $err_fh "run3(): \$? is $?\n";
 416             } else {
 417                 print $err_fh "run3(): \$? is $?, \$! is $errno\n";
 418             }
 419         }
 420
 421         die $! if defined $r && $r == -1 && !$options->{return_if_system_error};
 422
 423         1;
 424     };
 425     my $x = $@;
 426
 427     my @errs;
 428
 429     if ( defined $saved_fd0 ) {
 430         dup2( $saved_fd0, 0 );
 431         POSIX::close( $saved_fd0 );
 432     }
 433
 434 #    open STDIN,  "<&STDIN_SAVE"#  or push @errs, "run3(): $! restoring STDIN"
 435 #        if defined $in_fh;
 436     open STDOUT, ">&STDOUT_SAVE" or push @errs, "run3(): $! restoring STDOUT"
 437         if defined $out_fh;
 438     open STDERR, ">&STDERR_SAVE" or push @errs, "run3(): $! restoring STDERR"
 439         if defined $err_fh;
 440
 441     croak join ", ", @errs if @errs;
 442
 443     die $x unless $ok;
 444
 445     _read_child_output_fh "stdout", $out_type, $stdout, $out_fh, $options
 446         if defined $out_fh && $out_type && $out_type ne "FH";
 447     _read_child_output_fh "stderr", $err_type, $stderr, $err_fh, $options
 448         if defined $err_fh && $err_type && $err_type ne "FH" && !$tie_err_to_out;
 449     $profiler->run_exit(
 450        $cmd,
 451        $run_call_time,
 452        $sys_call_time,
 453        $sys_exit_time,
 454        scalar gettimeofday()
 455     ) if profiling;
 456
 457     $! = $errno;                # restore $! from system()
 458
 459     return 1;
 460 }
 461
 462 1;
 463
 464 __END__
 465
 466 =head2 C<< run3($cmd, $stdin, $stdout, $stderr, \%options) >>
 467
 468 All parameters after C<$cmd> are optional.
 469
 470 The parameters C<$stdin>, C<$stdout> and C<$stderr> indicate
 471 how the child's corresponding filehandle
 472 (C<STDIN>, C<STDOUT> and C<STDERR>, resp.) will be redirected.
 473 Because the redirects come last, this allows C<STDOUT> and C<STDERR> to default
 474 to the parent's by just not specifying them -- a common use case.
 475
 476 C<run3> throws an exception if the wrapped C<system> call returned -1
 477 or anything went wrong with C<run3>'s processing of filehandles.
 478 Otherwise it returns true.
 479 It leaves C<$?> intact for inspection of exit and wait status.
 480
 481 Note that a true return value from C<run3> doesn't mean that the command
 482 had a successful exit code. Hence you should always check C<$?>.
 483
 484 See L</%options> for an option to handle the case of C<system>
 485 returning -1 yourself.
 486
 487 =head3 C<$cmd>
 488
 489 Usually C<$cmd> will be an ARRAY reference and the child is invoked via
 490
 491   system @$cmd;
 492
 493 But C<$cmd> may also be a string in which case the child is invoked via
 494
 495   system $cmd;
 496
 497 (cf. L<perlfunc/system> for the difference and the pitfalls of using
 498 the latter form).
 499
 500 =head3 C<$stdin>, C<$stdout>, C<$stderr>
 501
 502 The parameters C<$stdin>, C<$stdout> and C<$stderr>
 503 can take one of the following forms:
 504
 505 =over 4
 506
 507 =item C<undef> (or not specified at all)
 508
 509 The child inherits the corresponding filehandle from the parent.
 510
 511   run3 \@cmd, $stdin;                   # child writes to same STDOUT and STDERR as parent
 512   run3 \@cmd, undef, $stdout, $stderr;  # child reads from same STDIN as parent
 513
 514 =item C<\undef>
 515
 516 The child's filehandle is redirected from or to the
 517 local equivalent of C</dev/null> (as returned by
 518 C<< File::Spec->devnull() >>).
 519
 520   run3 \@cmd, \undef, $stdout, $stderr; # child reads from /dev/null
 521
 522 =item a simple scalar
 523
 524 The parameter is taken to be the name of a file to read from
 525 or write to. In the latter case, the file will be opened via
 526
 527   open FH, ">", ...
 528
 529 i.e. it is created if it doesn't exist and truncated otherwise.
 530 Note that the file is opened by the parent which will L<croak|Carp/croak>
 531 in case of failure.
 532
 533   run3 \@cmd, \undef, "out.txt";        # child writes to file "out.txt"
 534
 535 =item a filehandle (either a reference to a GLOB or an C<IO::Handle>)
 536
 537 The filehandle is inherited by the child.
 538
 539   open my $fh, ">", "out.txt";
 540   print $fh "prologue\n";
 541   ...
 542   run3 \@cmd, \undef, $fh;              # child writes to $fh
 543   ...
 544   print $fh "epilogue\n";
 545   close $fh;
 546
 547 =item a SCALAR reference
 548
 549 The referenced scalar is treated as a string to be read from or
 550 written to. In the latter case, the previous content of the string
 551 is overwritten.
 552
 553   my $out;
 554   run3 \@cmd, \undef, \$out;           # child writes into string
 555   run3 \@cmd, \<<EOF;                  # child reads from string (can use "here" notation)
 556   Input
 557   to
 558   child
 559   EOF
 560
 561 =item an ARRAY reference
 562
 563 For C<$stdin>, the elements of C<@$stdin> are simply spooled to the child.
 564
 565 For C<$stdout> or C<$stderr>, the child's corresponding file descriptor
 566 is read line by line (as determined by the current setting of C<$/>)
 567 into C<@$stdout> or C<@$stderr>, resp. The previous content of the array
 568 is overwritten.
 569
 570   my @lines;
 571   run3 \@cmd, \undef, \@lines;         # child writes into array
 572
 573 =item a CODE reference
 574
 575 For C<$stdin>, C<&$stdin> will be called repeatedly (with no arguments) and
 576 the return values are spooled to the child. C<&$stdin> must signal the end of
 577 input by returning C<undef>.
 578
 579 For C<$stdout> or C<$stderr>, the child's corresponding file descriptor
 580 is read line by line (as determined by the current setting of C<$/>)
 581 and C<&$stdout> or C<&$stderr>, resp., is called with the contents of the line.
 582 Note that there's no end-of-file indication.
 583
 584   my $i = 0;
 585   sub producer {
 586     return $i < 10 ? "line".$i++."\n" : undef;
 587   }
 588
 589   run3 \@cmd, \&producer;              # child reads 10 lines
 590
 591 Note that this form of redirecting the child's I/O doesn't imply
 592 any form of concurrency between parent and child - run3()'s method of
 593 operation is the same no matter which form of redirection you specify.
 594
 595 =back
 596
 597 If the same value is passed for C<$stdout> and C<$stderr>, then the child
 598 will write both C<STDOUT> and C<STDERR> to the same filehandle.
 599 In general, this means that
 600
 601     run3 \@cmd, \undef, "foo.txt", "foo.txt";
 602     run3 \@cmd, \undef, \$both, \$both;
 603
 604 will DWIM and pass a single file handle to the child for both C<STDOUT> and
 605 C<STDERR>, collecting all into file "foo.txt" or C<$both>.
 606
 607 =head3 C<\%options>
 608
 609 The last parameter, C<\%options>, must be a hash reference if present.
 610
 611 Currently the following
 612 keys are supported:
 613
 614 =over 4
 615
 616 =item C<binmode_stdin>, C<binmode_stdout>, C<binmode_stderr>
 617
 618 The value must a "layer" as described in L<perlfunc/binmode>.
 619 If specified the corresponding
 620 parameter C<$stdin>, C<$stdout> or C<$stderr>, resp., operates
 621 with the given layer.
 622
 623 For backward compatibility, a true value that doesn't start with ":"
 624 (e.g. a number) is interpreted as ":raw". If the value is false
 625 or not specified, the default is ":crlf" on Windows and ":raw" otherwise.
 626
 627 Don't expect that values other than the built-in layers ":raw", ":crlf",
 628 and (on newer Perls) ":bytes", ":utf8", ":encoding(...)" will work.
 629
 630 =item C<append_stdout>, C<append_stderr>
 631
 632 If their value is true then the corresponding
 633 parameter C<$stdout> or C<$stderr>, resp., will append the child's output
 634 to the existing "contents" of the redirector. This only makes
 635 sense if the redirector is a simple scalar (the corresponding file
 636 is opened in append mode), a SCALAR reference (the output is
 637 appended to the previous contents of the string)
 638 or an ARRAY reference (the output is C<push>ed onto the
 639 previous contents of the array).
 640
 641 =item C<return_if_system_error>
 642
 643 If this is true C<run3> does B<not> throw an exception if C<system>
 644 returns -1 (cf. L<perlfunc/system> for possible
 645 failure scenarios.), but returns true instead.
 646 In this case C<$?> has the value -1 and C<$!>
 647 contains the errno of the failing C<system> call.
 648
 649 =back
 650
 651 =head1 HOW IT WORKS
 652
 653 =over 4
 654
 655 =item (1)
 656
 657 For each redirector C<$stdin>, C<$stdout>, and C<$stderr>,
 658 C<run3()> furnishes a filehandle:
 659
 660 =over 4
 661
 662 =item *
 663
 664 if the redirector already specifies a filehandle it just uses that
 665
 666 =item *
 667
 668 if the redirector specifies a filename, C<run3()> opens the file
 669 in the appropriate mode
 670
 671 =item *
 672
 673 in all other cases, C<run3()> opens a temporary file
 674 (using L<tempfile|Temp/tempfile>)
 675
 676 =back
 677
 678 =item (2)
 679
 680 If C<run3()> opened a temporary file for C<$stdin> in step (1),
 681 it writes the data using the specified method (either
 682 from a string, an array or returnd by a function) to the temporary file and rewinds it.
 683
 684 =item (3)
 685
 686 C<run3()> saves the parent's C<STDIN>, C<STDOUT> and C<STDERR> by duplicating
 687 them to new filehandles. It duplicates the filehandles from step (1)
 688 to C<STDIN>, C<STDOUT> and C<STDERR>, resp.
 689
 690 =item (4)
 691
 692 C<run3()> runs the child by invoking L<system|perlfunc/system>
 693 with C<$cmd> as specified above.
 694
 695 =item (5)
 696
 697 C<run3()> restores the parent's C<STDIN>, C<STDOUT> and C<STDERR> saved in step (3).
 698
 699 =item (6)
 700
 701 If C<run3()> opened a temporary file for C<$stdout> or C<$stderr> in step (1),
 702 it rewinds it and reads back its contents using the specified method
 703 (either to a string, an array or by calling a function).
 704
 705 =item (7)
 706
 707 C<run3()> closes all filehandles that it opened explicitly in step (1).
 708
 709 =back
 710
 711 Note that when using temporary files, C<run3()> tries to amortize the overhead
 712 by reusing them (i.e. it keeps them open and rewinds and truncates them
 713 before the next operation).
 714
 715 =head1 LIMITATIONS
 716
 717 Often uses intermediate files (determined by File::Temp, and thus by the
 718 File::Spec defaults and the TMPDIR env. variable) for speed, portability and
 719 simplicity.
 720
 721 Use extrem caution when using C<run3> in a threaded environment if
 722 concurrent calls of C<run3> are possible. Most likely, I/O from different
 723 invocations will get mixed up. The reason is that in most thread
 724 implementations all threads in a process share the same STDIN/STDOUT/STDERR.
 725 Known failures are Perl ithreads on Linux and Win32. Note that C<fork>
 726 on Win32 is emulated via Win32 threads and hence I/O mix up is possible
 727 between forked children here (C<run3> is "fork safe" on Unix, though).
 728
 729 =head1 DEBUGGING
 730
 731 To enable debugging use the IPCRUN3DEBUG environment variable to
 732 a non-zero integer value:
 733
 734   $ IPCRUN3DEBUG=1 myapp
 735
 736 =head1 PROFILING
 737
 738 To enable profiling, set IPCRUN3PROFILE to a number to enable emitting profile
 739 information to STDERR (1 to get timestamps, 2 to get a summary report at the
 740 END of the program, 3 to get mini reports after each run) or to a filename to
 741 emit raw data to a file for later analysis.
 742
 743 =head1 COMPARISON
 744
 745 Here's how it stacks up to existing APIs:
 746
 747 =head2 compared to C<system()>, C<qx''>, C<open "...|">, C<open "|...">
 748
 749 =over
 750
 751 =item +
 752
 753 redirects more than one file descriptor
 754
 755 =item +
 756
 757 returns TRUE on success, FALSE on failure
 758
 759 =item +
 760
 761 throws an error if problems occur in the parent process (or the pre-exec child)
 762
 763 =item +
 764
 765 allows a very perlish interface to Perl data structures and subroutines
 766
 767 =item +
 768
 769 allows 1 word invocations to avoid the shell easily:
 770
 771  run3 ["foo"];  # does not invoke shell
 772
 773 =item -
 774
 775 does not return the exit code, leaves it in $?
 776
 777 =back
 778
 779 =head2 compared to C<open2()>, C<open3()>
 780
 781 =over
 782
 783 =item +
 784
 785 no lengthy, error prone polling/select loop needed
 786
 787 =item +
 788
 789 hides OS dependancies
 790
 791 =item +
 792
 793 allows SCALAR, ARRAY, and CODE references to source and sink I/O
 794
 795 =item +
 796
 797 I/O parameter order is like C<open3()>  (not like C<open2()>).
 798
 799 =item -
 800
 801 does not allow interaction with the subprocess
 802
 803 =back
 804
 805 =head2 compared to L<IPC::Run::run()|IPC::Run/run>
 806
 807 =over
 808
 809 =item +
 810
 811 smaller, lower overhead, simpler, more portable
 812
 813 =item +
 814
 815 no select() loop portability issues
 816
 817 =item +
 818
 819 does not fall prey to Perl closure leaks
 820
 821 =item -
 822
 823 does not allow interaction with the subprocess (which
 824 IPC::Run::run() allows by redirecting subroutines)
 825
 826 =item -
 827
 828 lacks many features of C<IPC::Run::run()> (filters, pipes,
 829 redirects, pty support)
 830
 831 =back
 832
 833 =head1 COPYRIGHT
 834
 835 Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved
 836
 837 =head1 LICENSE
 838
 839 You may use this module under the terms of the BSD, Artistic, or GPL licenses,
 840 any version.
 841
 842 =head1 AUTHOR
 843
 844 Barrie Slaymaker E<lt>C<barries@slaysys.com>E<gt>
 845
 846 Ricardo SIGNES E<lt>C<rjbs@cpan.org>E<gt> performed some routine maintenance in
 847 2005, thanks to help from the following ticket and/or patch submitters: Jody
 848 Belka, Roderich Schupp, David Morel, and anonymous others.
 849
 850 =cut