Commit | Line | Data |
a0d0e21e |
1 | package IPC::Open2; |
7e1af8bc |
2 | |
3 | use strict; |
2675ae2b |
4 | our ($VERSION, @ISA, @EXPORT); |
7e1af8bc |
5 | |
a0d0e21e |
6 | require 5.000; |
7 | require Exporter; |
7e1af8bc |
8 | |
9 | $VERSION = 1.01; |
10 | @ISA = qw(Exporter); |
11 | @EXPORT = qw(open2); |
a0d0e21e |
12 | |
f06db76b |
13 | =head1 NAME |
14 | |
15 | IPC::Open2, open2 - open a process for both reading and writing |
16 | |
17 | =head1 SYNOPSIS |
18 | |
19 | use IPC::Open2; |
2675ae2b |
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 |
30 | |
31 | =head1 DESCRIPTION |
32 | |
2675ae2b |
33 | The open2() function runs the given $cmd and connects $rdrfh for |
34 | reading and $wtrfh for writing. It's what you think should work |
f06db76b |
35 | when you try |
36 | |
2675ae2b |
37 | $pid = open(HANDLE, "|cmd args|"); |
f06db76b |
38 | |
eeba3357 |
39 | The write filehandle will have autoflush turned on. |
40 | |
2675ae2b |
41 | If $rdrfh is a string (that is, a bareword filehandle rather than a glob |
42 | or a reference) and it begins with C<< >& >>, then the child will send output |
43 | directly to that file handle. If $wtrfh is a string that begins with |
5b67648c |
44 | C<< <& >>, then $wtrfh will be closed in the parent, and the child will read |
7e1af8bc |
45 | from it directly. In both cases, there will be a dup(2) instead of a |
46 | pipe(2) made. |
47 | |
2675ae2b |
48 | If either reader or writer is the null string, this will be replaced |
49 | by an autogenerated filehandle. If so, you must pass a valid lvalue |
50 | in the parameter slot so it can be overwritten in the caller, or |
51 | an exception will be raised. |
f06db76b |
52 | |
2675ae2b |
53 | open2() returns the process ID of the child process. It doesn't return on |
54 | failure: it just raises an exception matching C</^open2:/>. However, |
55 | C<exec> failures in the child are not detected. You'll have to |
56 | trap SIGPIPE yourself. |
f06db76b |
57 | |
2675ae2b |
58 | This whole affair is quite dangerous, as you may block forever. It |
59 | assumes it's going to talk to something like B<bc>, both writing |
60 | to 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 |
62 | output a line at a time. Programs like B<sort> that read their |
63 | entire input stream first, however, are quite apt to cause deadlock. |
f06db76b |
64 | |
65 | The big problem with this approach is that if you don't have control |
7a2e2cd6 |
66 | over source code being run in the child process, you can't control |
67 | what it does with pipe buffering. Thus you can't just open a pipe to |
68 | C<cat -v> and continually read and write a line from it. |
f06db76b |
69 | |
2675ae2b |
70 | The IO::Pty and Expect modules from CPAN can help with this, as they |
71 | provide a real tty (well, a pseudo-tty, actually), which gets you |
72 | back to line buffering in the invoked command again. |
73 | |
74 | =head1 WARNING |
75 | |
76 | The order of arguments differs from that of open3(). |
77 | |
f06db76b |
78 | =head1 SEE ALSO |
79 | |
7e1af8bc |
80 | See L<IPC::Open3> for an alternative that handles STDERR as well. This |
81 | function is really just a wrapper around open3(). |
f06db76b |
82 | |
83 | =cut |
84 | |
a0d0e21e |
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 |
103 | require IPC::Open3; |
a0d0e21e |
104 | |
105 | sub open2 { |
7e1af8bc |
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 |
111 | 1 |