IPC::Open3: fix dup example in synopsis

Unfortunately, this feature is based on parsing out filehandle names
from strings, so it requires bareword filehandles to work.

Try to make this clearer in the documentation  and mention that
arguments starting with `>&` or `<&` are input parameters (i.e. existing
open handles to use) as opposed to regular output parameters (which
open3 connects to newly created pipes).

Fixes #22608.

Author: mauke

ext/IPC-Open3/lib/IPC/Open2.pm

@@ -5,8 +5,8 @@ use strict;
 require 5.006;
 use Exporter 'import';
 
-our $VERSION	= 1.06;
-our @EXPORT		= qw(open2);
+our $VERSION = 1.07;
+our @EXPORT  = qw(open2);
 
 =head1 NAME
 
@@ -22,12 +22,12 @@ IPC::Open2 - open a process for both reading and writing using open2()
     my $pid = open2(my $chld_out, my $chld_in, 'some cmd and args');
 
     # read from parent STDIN and write to already open handle
-    open my $outfile, '>', 'outfile.txt' or die "open failed: $!";
-    my $pid = open2($outfile, '<&STDIN', 'some', 'cmd', 'and', 'args');
+    open OUTFILE, '>', 'outfile.txt' or die "open failed: $!";
+    my $pid = open2('>&OUTFILE', '<&STDIN', 'some', 'cmd', 'and', 'args');
 
     # read from already open handle and write to parent STDOUT
-    open my $infile, '<', 'infile.txt' or die "open failed: $!";
-    my $pid = open2('>&STDOUT', $infile, 'some', 'cmd', 'and', 'args');
+    open INFILE, '<', 'infile.txt' or die "open failed: $!";
+    my $pid = open2('>&STDOUT', '<&INFILE', 'some', 'cmd', 'and', 'args');
 
     # reap zombie and retrieve exit status
     waitpid( $pid, 0 );

ext/IPC-Open3/lib/IPC/Open3.pm

@@ -8,8 +8,8 @@ use Exporter 'import';
 use Carp;
 use Symbol qw(gensym qualify);
 
-our $VERSION	= '1.22';
-our @EXPORT		= qw(open3);
+our $VERSION = '1.23';
+our @EXPORT  = qw(open3);
 
 =head1 NAME
 
@@ -26,8 +26,8 @@ IPC::Open3 - open a process for reading, writing, and error handling using open3
 
     # read from parent STDIN
     # send STDOUT and STDERR to already open handle
-    open my $outfile, '>>', 'output.txt' or die "open failed: $!";
-    my $pid = open3('<&STDIN', $outfile, undef,
+    open OUTFILE, '>>', 'output.txt' or die "open failed: $!";
+    my $pid = open3('<&STDIN', '>&OUTFILE', undef,
 		    'some', 'cmd', 'and', 'args');
 
     # write to parent STDOUT and STDERR
@@ -49,11 +49,16 @@ cannot be used for the STDERR filehandle, but gensym from L<Symbol> can
 be used to vivify a new glob reference, see L</SYNOPSIS>.  The $chld_in
 will have autoflush turned on.
 
-If $chld_in begins with C<< <& >>, then $chld_in will be closed in the
-parent, and the child will read from it directly.  If $chld_out or
-$chld_err begins with C<< >& >>, then the child will send output
-directly to that filehandle.  In both cases, there will be a L<dup(2)>
-instead of a L<pipe(2)> made.
+If $chld_in begins with C<< <& >> followed by the name of a bareword
+filehandle, then $chld_in will be closed in the parent, and the child
+will read from it directly.  If $chld_out or $chld_err begins with C<<
+>& >>, then the child will send output directly to that filehandle.  In
+both cases, there will be a L<dup(2)> instead of a L<pipe(2)> made.  In
+other words, a string that starts with C<< <& >> or C<< >& >> acts like
+an input parameter (i.e. open3() will simply pass the given handle on to
+the child process) whereas normally handles act like output parameters
+(i.e. open3() will create a pipe and place the respective read or write
+end in the given parameter).
 
 If either reader or writer is the empty string or undefined, this will
 be replaced by an autogenerated filehandle.  If so, you must pass a