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