package IPC::Open2;
+
+use strict;
+our ($VERSION, @ISA, @EXPORT);
+
require 5.000;
require Exporter;
-use Carp;
+
+$VERSION = 1.01;
+@ISA = qw(Exporter);
+@EXPORT = qw(open2);
=head1 NAME
=head1 SYNOPSIS
use IPC::Open2;
- $pid = open2(\*RDR, \*WTR, 'some cmd and args');
- # or
- $pid = open2(\*RDR, \*WTR, 'some', 'cmd', 'and', 'args');
+
+ $pid = open2(\*RDRFH, \*WTRFH, 'some cmd and args');
+ # or without using the shell
+ $pid = open2(\*RDRFH, \*WTRFH, 'some', 'cmd', 'and', 'args');
+
+ # or with handle autovivification
+ my($rdrfh, $wtrfh);
+ $pid = open2($rdrfh, $wtrfh, 'some cmd and args');
+ # or without using the shell
+ $pid = open2($rdrfh, $wtrfh, 'some', 'cmd', 'and', 'args');
=head1 DESCRIPTION
-The open2() function spawns the given $cmd and connects $rdr for
-reading and $wtr for writing. It's what you think should work
+The open2() function runs the given $cmd and connects $rdrfh for
+reading and $wtrfh for writing. It's what you think should work
when you try
- open(HANDLE, "|cmd args|");
+ $pid = open(HANDLE, "|cmd args|");
-open2() returns the process ID of the child process. It doesn't return on
-failure: it just raises an exception matching C</^open2:/>.
+The write filehandle will have autoflush turned on.
-=head1 WARNING
+If $rdrfh is a string (that is, a bareword filehandle rather than a glob
+or a reference) and it begins with C<< >& >>, then the child will send output
+directly to that file handle. If $wtrfh is a string that begins with
+C<< <& >>, then $wtrfh will be closed in the parent, and the child will read
+from it directly. In both cases, there will be a dup(2) instead of a
+pipe(2) made.
-It will not create these file handles for you. You have to do this yourself.
-So don't pass it empty variables expecting them to get filled in for you.
+If either reader or writer is the null string, this will be replaced
+by an autogenerated filehandle. If so, you must pass a valid lvalue
+in the parameter slot so it can be overwritten in the caller, or
+an exception will be raised.
-Additionally, this is very dangerous as you may block forever.
-It assumes it's going to talk to something like B<bc>, both writing to
-it and reading from it. This is presumably safe because you "know"
-that commands like B<bc> will read a line at a time and output a line at
-a time. Programs like B<sort> that read their entire input stream first,
-however, are quite apt to cause deadlock.
+open2() returns the process ID of the child process. It doesn't return on
+failure: it just raises an exception matching C</^open2:/>. However,
+C<exec> failures in the child are not detected. You'll have to
+trap SIGPIPE yourself.
+
+open2() does not wait for and reap the child process after it exits.
+Except for short programs where it's acceptable to let the operating system
+take care of this, you need to do this yourself. This is normally as
+simple as calling C<waitpid $pid, 0> when you're done with the process.
+Failing to do this can result in an accumulation of defunct or "zombie"
+processes. See L<perlfunc/waitpid> for more information.
+
+This whole affair is quite dangerous, as you may block forever. It
+assumes it's going to talk to something like B<bc>, both writing
+to it and reading from it. This is presumably safe because you
+"know" that commands like B<bc> will read a line at a time and
+output a line at a time. Programs like B<sort> that read their
+entire input stream first, however, are quite apt to cause deadlock.
The big problem with this approach is that if you don't have control
-over source code being run in the the child process, you can't control what it does
-with pipe buffering. Thus you can't just open a pipe to C<cat -v> and continually
-read and write a line from it.
+over source code being run in the child process, you can't control
+what it does with pipe buffering. Thus you can't just open a pipe to
+C<cat -v> and continually read and write a line from it.
+
+The IO::Pty and Expect modules from CPAN can help with this, as they
+provide a real tty (well, a pseudo-tty, actually), which gets you
+back to line buffering in the invoked command again.
+
+=head1 WARNING
+
+The order of arguments differs from that of open3().
=head1 SEE ALSO
-See L<open3> for an alternative that handles STDERR as well.
+See L<IPC::Open3> for an alternative that handles STDERR as well. This
+function is really just a wrapper around open3().
=cut
-@ISA = qw(Exporter);
-@EXPORT = qw(open2);
-
# &open2: tom christiansen, <tchrist@convex.com>
#
# usage: $pid = open2('rdr', 'wtr', 'some cmd and args');
#
# abort program if
# rdr or wtr are null
-# pipe or fork or exec fails
+# a system call fails
-$fh = 'FHOPEN000'; # package static in case called more than once
+require IPC::Open3;
sub open2 {
- local($kidpid);
- local($dad_rdr, $dad_wtr, @cmd) = @_;
-
- $dad_rdr ne '' || croak "open2: rdr should not be null";
- $dad_wtr ne '' || croak "open2: wtr should not be null";
-
- # force unqualified filehandles into callers' package
- local($package) = caller;
- $dad_rdr =~ s/^([^']+$)/$package'$1/ unless ref $dad_rdr;
- $dad_wtr =~ s/^([^']+$)/$package'$1/ unless ref $dad_wtr;
-
- local($kid_rdr) = ++$fh;
- local($kid_wtr) = ++$fh;
-
- pipe($dad_rdr, $kid_wtr) || croak "open2: pipe 1 failed: $!";
- pipe($kid_rdr, $dad_wtr) || croak "open2: pipe 2 failed: $!";
-
- if (($kidpid = fork) < 0) {
- croak "open2: fork failed: $!";
- } elsif ($kidpid == 0) {
- close $dad_rdr; close $dad_wtr;
- open(STDIN, "<&$kid_rdr");
- open(STDOUT, ">&$kid_wtr");
- warn "execing @cmd\n" if $debug;
- exec @cmd
- or croak "open2: exec of @cmd failed";
- }
- close $kid_rdr; close $kid_wtr;
- select((select($dad_wtr), $| = 1)[0]); # unbuffer pipe
- $kidpid;
+ local $Carp::CarpLevel = $Carp::CarpLevel + 1;
+ return IPC::Open3::_open3('open2', scalar caller,
+ $_[1], $_[0], '>&STDERR', @_[2 .. $#_]);
}
-1; # so require is happy
+1