1package IPC::Open2; 2 3use strict; 4our ($VERSION, @ISA, @EXPORT); 5 6require 5.000; 7require Exporter; 8 9$VERSION = 1.05; 10@ISA = qw(Exporter); 11@EXPORT = qw(open2); 12 13=head1 NAME 14 15IPC::Open2 - open a process for both reading and writing using open2() 16 17=head1 SYNOPSIS 18 19 use IPC::Open2; 20 21 my $pid = open2(my $chld_out, my $chld_in, 22 'some', 'cmd', 'and', 'args'); 23 # or passing the command through the shell 24 my $pid = open2(my $chld_out, my $chld_in, 'some cmd and args'); 25 26 # read from parent STDIN and write to already open handle 27 open my $outfile, '>', 'outfile.txt' or die "open failed: $!"; 28 my $pid = open2($outfile, '<&STDIN', 'some', 'cmd', 'and', 'args'); 29 30 # read from already open handle and write to parent STDOUT 31 open my $infile, '<', 'infile.txt' or die "open failed: $!"; 32 my $pid = open2('>&STDOUT', $infile, 'some', 'cmd', 'and', 'args'); 33 34 # reap zombie and retrieve exit status 35 waitpid( $pid, 0 ); 36 my $child_exit_status = $? >> 8; 37 38=head1 DESCRIPTION 39 40The open2() function runs the given command and connects $chld_out for 41reading and $chld_in for writing. It's what you think should work 42when you try 43 44 my $pid = open(my $fh, "|cmd args|"); 45 46The $chld_in filehandle will have autoflush turned on. 47 48If $chld_out is a string (that is, a bareword filehandle rather than a glob 49or a reference) and it begins with C<< >& >>, then the child will send output 50directly to that file handle. If $chld_in is a string that begins with 51C<< <& >>, then $chld_in will be closed in the parent, and the child will 52read from it directly. In both cases, there will be a L<dup(2)> instead of a 53L<pipe(2)> made. 54 55If either reader or writer is the empty string or undefined, this will be 56replaced by an autogenerated filehandle. If so, you must pass a valid lvalue 57in the parameter slot so it can be overwritten in the caller, or 58an exception will be raised. 59 60open2() returns the process ID of the child process. It doesn't return on 61failure: it just raises an exception matching C</^open2:/>. However, 62C<exec> failures in the child are not detected. You'll have to 63trap SIGPIPE yourself. 64 65open2() does not wait for and reap the child process after it exits. 66Except for short programs where it's acceptable to let the operating system 67take care of this, you need to do this yourself. This is normally as 68simple as calling C<waitpid $pid, 0> when you're done with the process. 69Failing to do this can result in an accumulation of defunct or "zombie" 70processes. See L<perlfunc/waitpid> for more information. 71 72This whole affair is quite dangerous, as you may block forever. It 73assumes it's going to talk to something like L<bc(1)>, both writing 74to it and reading from it. This is presumably safe because you 75"know" that commands like L<bc(1)> will read a line at a time and 76output a line at a time. Programs like L<sort(1)> that read their 77entire input stream first, however, are quite apt to cause deadlock. 78 79The big problem with this approach is that if you don't have control 80over source code being run in the child process, you can't control 81what it does with pipe buffering. Thus you can't just open a pipe to 82C<cat -v> and continually read and write a line from it. 83 84The L<IO::Pty> and L<Expect> modules from CPAN can help with this, as 85they provide a real tty (well, a pseudo-tty, actually), which gets you 86back to line buffering in the invoked command again. 87 88=head1 WARNING 89 90The order of arguments differs from that of open3(). 91 92=head1 SEE ALSO 93 94See L<IPC::Open3> for an alternative that handles STDERR as well. This 95function is really just a wrapper around open3(). 96 97=cut 98 99# &open2: tom christiansen, <tchrist@convex.com> 100# 101# usage: $pid = open2('rdr', 'wtr', 'some cmd and args'); 102# or $pid = open2('rdr', 'wtr', 'some', 'cmd', 'and', 'args'); 103# 104# spawn the given $cmd and connect $rdr for 105# reading and $wtr for writing. return pid 106# of child, or 0 on failure. 107# 108# WARNING: this is dangerous, as you may block forever 109# unless you are very careful. 110# 111# $wtr is left unbuffered. 112# 113# abort program if 114# rdr or wtr are null 115# a system call fails 116 117require IPC::Open3; 118 119sub open2 { 120 local $Carp::CarpLevel = $Carp::CarpLevel + 1; 121 return IPC::Open3::_open3('open2', $_[1], $_[0], '>&STDERR', @_[2 .. $#_]); 122} 123 1241 125