integrate cfgperl contents into mainline

[p5sagit/p5-mst-13.2.git] / lib / IPC / Open2.pm

diff --git a/lib/IPC/Open2.pm b/lib/IPC/Open2.pm
index cfd15a8..161620b 100644 (file)
--- a/lib/IPC/Open2.pm
+++ b/lib/IPC/Open2.pm
@@ -1,7 +1,7 @@
 package IPC::Open2;
 
 use strict;
-use vars qw($VERSION @ISA @EXPORT);
+our ($VERSION, @ISA, @EXPORT);
 
 require 5.000;
 require Exporter;
@@ -17,44 +17,63 @@ IPC::Open2, open2 - open a process for both reading and writing
 =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|");
+
+The write filehandle will have autoflush turned on.
 
-If $rdr is a string (that is, a bareword filehandle rather than a glob
-or a reference) and it begins with ">&", then the child will send output
-directly to that file handle.  If $wtr is a string that begins with
-"<&", then WTR will be closed in the parent, and the child will read
+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.
 
+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.
+
 open2() returns the process ID of the child process.  It doesn't return on
-failure: it just raises an exception matching C</^open2:/>.
+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.
 
-=head1 WARNING 
+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.
 
-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.
+The big problem with this approach is that if you don't have control 
+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.
 
-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.  
+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.
 
-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.
+=head1 WARNING 
+
+The order of arguments differs from that of open3().
 
 =head1 SEE ALSO
 
@@ -84,10 +103,9 @@ function is really just a wrapper around open3().
 require IPC::Open3;
 
 sub open2 {
-    my ($read, $write, @cmd) = @_;
     local $Carp::CarpLevel = $Carp::CarpLevel + 1;
     return IPC::Open3::_open3('open2', scalar caller,
-                               $write, $read, '>&STDERR', @cmd);
+                               $_[1], $_[0], '>&STDERR', @_[2 .. $#_]);
 }
 
 1