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 | |
227e8dd4 |
58 | open2() does not wait for and reap the child process after it exits. |
59 | Except for short programs where it's acceptable to let the operating system |
60 | take care of this, you need to do this yourself. This is normally as |
61 | simple as calling C<waitpid $pid, 0> when you're done with the process. |
62 | Failing to do this can result in an accumulation of defunct or "zombie" |
63 | processes. See L<perlfunc/waitpid> for more information. |
64 | |
2675ae2b |
65 | This whole affair is quite dangerous, as you may block forever. It |
66 | assumes it's going to talk to something like B<bc>, both writing |
67 | to 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 |
69 | output a line at a time. Programs like B<sort> that read their |
70 | entire input stream first, however, are quite apt to cause deadlock. |
f06db76b |
71 | |
72 | The big problem with this approach is that if you don't have control |
7a2e2cd6 |
73 | over source code being run in the child process, you can't control |
74 | what it does with pipe buffering. Thus you can't just open a pipe to |
75 | C<cat -v> and continually read and write a line from it. |
f06db76b |
76 | |
2675ae2b |
77 | The IO::Pty and Expect modules from CPAN can help with this, as they |
78 | provide a real tty (well, a pseudo-tty, actually), which gets you |
79 | back to line buffering in the invoked command again. |
80 | |
81 | =head1 WARNING |
82 | |
83 | The order of arguments differs from that of open3(). |
84 | |
f06db76b |
85 | =head1 SEE ALSO |
86 | |
7e1af8bc |
87 | See L<IPC::Open3> for an alternative that handles STDERR as well. This |
88 | function is really just a wrapper around open3(). |
f06db76b |
89 | |
90 | =cut |
91 | |
a0d0e21e |
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 |
7e1af8bc |
108 | # a system call fails |
a0d0e21e |
109 | |
7e1af8bc |
110 | require IPC::Open3; |
a0d0e21e |
111 | |
112 | sub open2 { |
7e1af8bc |
113 | local $Carp::CarpLevel = $Carp::CarpLevel + 1; |
114 | return IPC::Open3::_open3('open2', scalar caller, |
2675ae2b |
115 | $_[1], $_[0], '>&STDERR', @_[2 .. $#_]); |
a0d0e21e |
116 | } |
a0d0e21e |
117 | |
7e1af8bc |
118 | 1 |