Commit | Line | Data |
---|---|---|
a0d0e21e | 1 | package IPC::Open2; |
7e1af8bc | 2 | |
3 | use strict; | |
2675ae2b | 4 | our ($VERSION, @ISA, @EXPORT); |
7e1af8bc | 5 | |
a0d0e21e LW |
6 | require 5.000; |
7 | require Exporter; | |
7e1af8bc | 8 | |
9 | $VERSION = 1.01; | |
10 | @ISA = qw(Exporter); | |
11 | @EXPORT = qw(open2); | |
a0d0e21e | 12 | |
f06db76b AD |
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 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 |
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 AD |
35 | when you try |
36 | ||
2675ae2b | 37 | $pid = open(HANDLE, "|cmd args|"); |
f06db76b | 38 | |
eeba3357 RS |
39 | The write filehandle will have autoflush turned on. |
40 | ||
2675ae2b GS |
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 GS |
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 GS |
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 GS |
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 GS |
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 AD |
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 GS |
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 AD |
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 AD |
89 | |
90 | =cut | |
91 | ||
a0d0e21e LW |
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 LW |
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 |