Debian Codegraph @

upstream/debian-unstable/man3/IPC::Open2.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "IPC::Open2 3perl"
58 .TH IPC::Open2 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 IPC::Open2 \- open a process for both reading and writing using open2()
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use IPC::Open2;
69 \&
70 \& my $pid = open2(my $chld_out, my $chld_in,
71 \& \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq);
72 \& # or passing the command through the shell
73 \& my $pid = open2(my $chld_out, my $chld_in, \*(Aqsome cmd and args\*(Aq);
74 \&
75 \& # read from parent STDIN and write to already open handle
76 \& open my $outfile, \*(Aq>\*(Aq, \*(Aqoutfile.txt\*(Aq or die "open failed: $!";
77 \& my $pid = open2($outfile, \*(Aq<&STDIN\*(Aq, \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq);
78 \&
79 \& # read from already open handle and write to parent STDOUT
80 \& open my $infile, \*(Aq<\*(Aq, \*(Aqinfile.txt\*(Aq or die "open failed: $!";
81 \& my $pid = open2(\*(Aq>&STDOUT\*(Aq, $infile, \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq);
82 \&
83 \& # reap zombie and retrieve exit status
84 \& waitpid( $pid, 0 );
85 \& my $child_exit_status = $? >> 8;
86 .Ve
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 The \fBopen2()\fR function runs the given command and connects \f(CW$chld_out\fR for
90 reading and \f(CW$chld_in\fR for writing. It's what you think should work
91 when you try
92 .PP
93 .Vb 1
94 \& my $pid = open(my $fh, "|cmd args|");
95 .Ve
96 .PP
97 The \f(CW$chld_in\fR filehandle will have autoflush turned on.
98 .PP
99 If \f(CW$chld_out\fR is a string (that is, a bareword filehandle rather than a glob
100 or a reference) and it begins with \f(CW\*(C`>&\*(C'\fR, then the child will send output
101 directly to that file handle. If \f(CW$chld_in\fR is a string that begins with
102 \&\f(CW\*(C`<&\*(C'\fR, then \f(CW$chld_in\fR will be closed in the parent, and the child will
103 read from it directly. In both cases, there will be a \fBdup\fR\|(2) instead of a
104 \&\fBpipe\fR\|(2) made.
105 .PP
106 If either reader or writer is the empty string or undefined, this will be
107 replaced by an autogenerated filehandle. If so, you must pass a valid lvalue
108 in the parameter slot so it can be overwritten in the caller, or
109 an exception will be raised.
110 .PP
111 \&\fBopen2()\fR returns the process ID of the child process. It doesn't return on
112 failure: it just raises an exception matching \f(CW\*(C`/^open2:/\*(C'\fR. However,
113 \&\f(CW\*(C`exec\*(C'\fR failures in the child are not detected. You'll have to
114 trap SIGPIPE yourself.
115 .PP
116 \&\fBopen2()\fR does not wait for and reap the child process after it exits.
117 Except for short programs where it's acceptable to let the operating system
118 take care of this, you need to do this yourself. This is normally as
119 simple as calling \f(CW\*(C`waitpid $pid, 0\*(C'\fR when you're done with the process.
120 Failing to do this can result in an accumulation of defunct or "zombie"
121 processes. See "waitpid" in perlfunc for more information.
122 .PP
123 This whole affair is quite dangerous, as you may block forever. It
124 assumes it's going to talk to something like \fBbc\fR\|(1), both writing
125 to it and reading from it. This is presumably safe because you
126 "know" that commands like \fBbc\fR\|(1) will read a line at a time and
127 output a line at a time. Programs like \fBsort\fR\|(1) that read their
128 entire input stream first, however, are quite apt to cause deadlock.
129 .PP
130 The big problem with this approach is that if you don't have control
131 over source code being run in the child process, you can't control
132 what it does with pipe buffering. Thus you can't just open a pipe to
133 \&\f(CW\*(C`cat \-v\*(C'\fR and continually read and write a line from it.
134 .PP
135 The IO::Pty and Expect modules from CPAN can help with this, as
136 they provide a real tty (well, a pseudo-tty, actually), which gets you
137 back to line buffering in the invoked command again.
138 .SH WARNING
139 .IX Header "WARNING"
140 The order of arguments differs from that of \fBopen3()\fR.
141 .SH "SEE ALSO"
142 .IX Header "SEE ALSO"
143 See IPC::Open3 for an alternative that handles STDERR as well. This
144 function is really just a wrapper around \fBopen3()\fR.