This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate with Sarathy.
[perl5.git] / lib / IPC / Open2.pm
CommitLineData
a0d0e21e 1package IPC::Open2;
7e1af8bc
PP
2
3use strict;
2675ae2b 4our ($VERSION, @ISA, @EXPORT);
7e1af8bc 5
a0d0e21e
LW
6require 5.000;
7require Exporter;
7e1af8bc
PP
8
9$VERSION = 1.01;
10@ISA = qw(Exporter);
11@EXPORT = qw(open2);
a0d0e21e 12
f06db76b
AD
13=head1 NAME
14
15IPC::Open2, open2 - open a process for both reading and writing
16
17=head1 SYNOPSIS
18
19 use IPC::Open2;
2675ae2b
GS
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');
f06db76b
AD
30
31=head1 DESCRIPTION
32
2675ae2b
GS
33The open2() function runs the given $cmd and connects $rdrfh for
34reading and $wtrfh for writing. It's what you think should work
f06db76b
AD
35when you try
36
2675ae2b 37 $pid = open(HANDLE, "|cmd args|");
f06db76b 38
eeba3357
RS
39The write filehandle will have autoflush turned on.
40
2675ae2b
GS
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
5b67648c 44C<< <& >>, then $wtrfh will be closed in the parent, and the child will read
7e1af8bc
PP
45from it directly. In both cases, there will be a dup(2) instead of a
46pipe(2) made.
47
2675ae2b
GS
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.
f06db76b 52
2675ae2b
GS
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.
f06db76b 57
2675ae2b
GS
58This whole affair is quite dangerous, as you may block forever. It
59assumes it's going to talk to something like B<bc>, both writing
60to it and reading from it. This is presumably safe because you
61"know" that commands like B<bc> will read a line at a time and
62output a line at a time. Programs like B<sort> that read their
63entire input stream first, however, are quite apt to cause deadlock.
f06db76b
AD
64
65The big problem with this approach is that if you don't have control
7a2e2cd6
PP
66over source code being run in the child process, you can't control
67what it does with pipe buffering. Thus you can't just open a pipe to
68C<cat -v> and continually read and write a line from it.
f06db76b 69
2675ae2b
GS
70The IO::Pty and Expect modules from CPAN can help with this, as they
71provide a real tty (well, a pseudo-tty, actually), which gets you
72back to line buffering in the invoked command again.
73
74=head1 WARNING
75
76The order of arguments differs from that of open3().
77
f06db76b
AD
78=head1 SEE ALSO
79
7e1af8bc
PP
80See L<IPC::Open3> for an alternative that handles STDERR as well. This
81function is really just a wrapper around open3().
f06db76b
AD
82
83=cut
84
a0d0e21e
LW
85# &open2: tom christiansen, <tchrist@convex.com>
86#
87# usage: $pid = open2('rdr', 'wtr', 'some cmd and args');
88# or $pid = open2('rdr', 'wtr', 'some', 'cmd', 'and', 'args');
89#
90# spawn the given $cmd and connect $rdr for
91# reading and $wtr for writing. return pid
92# of child, or 0 on failure.
93#
94# WARNING: this is dangerous, as you may block forever
95# unless you are very careful.
96#
97# $wtr is left unbuffered.
98#
99# abort program if
100# rdr or wtr are null
7e1af8bc 101# a system call fails
a0d0e21e 102
7e1af8bc 103require IPC::Open3;
a0d0e21e
LW
104
105sub open2 {
7e1af8bc
PP
106 local $Carp::CarpLevel = $Carp::CarpLevel + 1;
107 return IPC::Open3::_open3('open2', scalar caller,
2675ae2b 108 $_[1], $_[0], '>&STDERR', @_[2 .. $#_]);
a0d0e21e 109}
a0d0e21e 110
7e1af8bc 1111