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