Debian Codegraph @

upstream/mageia-cauldron/man3pm/IPC::Open3.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "IPC::Open3 3pm"
61 .TH IPC::Open3 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 IPC::Open3 \- open a process for reading, writing, and error handling using open3()
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 6
71 \& use Symbol \*(Aqgensym\*(Aq; # vivify a separate handle for STDERR
72 \& my $pid = open3(my $chld_in, my $chld_out, my $chld_err = gensym,
73 \& \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq);
74 \& # or pass the command through the shell
75 \& my $pid = open3(my $chld_in, my $chld_out, my $chld_err = gensym,
76 \& \*(Aqsome cmd and args\*(Aq);
77 \&
78 \& # read from parent STDIN
79 \& # send STDOUT and STDERR to already open handle
80 \& open my $outfile, \*(Aq>>\*(Aq, \*(Aqoutput.txt\*(Aq or die "open failed: $!";
81 \& my $pid = open3([\*(Aq&\*(Aq, *STDIN], [\*(Aq&\*(Aq, $outfile], undef,
82 \& \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq);
83 \&
84 \& # write to parent STDOUT and STDERR
85 \& my $pid = open3(my $chld_in, [\*(Aq&\*(Aq, *STDOUT], [\*(Aq&\*(Aq, *STDERR],
86 \& \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq);
87 \&
88 \& # reap zombie and retrieve exit status
89 \& waitpid( $pid, 0 );
90 \& my $child_exit_status = $? >> 8;
91 .Ve
92 .SH DESCRIPTION
93 .IX Header "DESCRIPTION"
94 Extremely similar to \f(CW\*(C`open2\*(C'\fR from IPC::Open2, \f(CW\*(C`open3\*(C'\fR spawns the given
95 command and provides filehandles for interacting with the command\*(Aqs standard
96 I/O streams.
97 .PP
98 .Vb 1
99 \& my $pid = open3($chld_in, $chld_out, $chld_err, @command_and_args);
100 .Ve
101 .PP
102 It connects \f(CW$chld_in\fR for writing to the child\*(Aqs standard input, \f(CW$chld_out\fR
103 for reading from the child\*(Aqs standard output, and \f(CW$chld_err\fR for reading from
104 the child\*(Aqs standard error stream. If \f(CW$chld_err\fR is false, or the same file
105 descriptor as \f(CW$chld_out\fR, then \f(CW\*(C`STDOUT\*(C'\fR and \f(CW\*(C`STDERR\*(C'\fR of the child are on
106 the same filehandle. This means that you cannot pass an uninitialized variable
107 for \f(CW$chld_err\fR and have \f(CW\*(C`open3\*(C'\fR auto\-generate a filehandle for you, but
108 gensym from Symbol can be used to vivify a new glob reference; see
109 "SYNOPSIS". The \f(CW$chld_in\fR handle will have autoflush turned on.
110 .PP
111 By default, the filehandles you pass in are used as output parameters.
112 \&\f(CW\*(C`open3\*(C'\fR internally creates three pipes. The write end of the first pipe and
113 the read ends of the other pipes are connected to the command\*(Aqs standard
114 input/output/error, respectively. The corresponding read and write ends are
115 placed in the first three argument to \f(CW\*(C`open3\*(C'\fR.
116 .PP
117 The filehandle arguments can take the following forms:
118 .IP \(bu 4
119 An uninitialized variable (technically, either \f(CW\*(C`undef\*(C'\fR or the empty string
120 will work): \f(CW\*(C`open3\*(C'\fR generates a fresh filehandle and assigns it to the
121 argument, which must be a modifiable variable for this work (otherwise an
122 exception will be raised).
123 .Sp
124 This does not work for \f(CW$chld_err\fR, however: If the \f(CW$chld_err\fR argument is
125 a false value, the child\*(Aqs error stream is automatically redirected to its
126 standard output.
127 .IP \(bu 4
128 An existing handle in the form of a typeglob like \f(CW*STDIN\fR or \f(CW*FOO\fR or a
129 reference to such: \f(CW\*(C`open3\*(C'\fR places the filehandle in the \f(CW\*(C`IO\*(C'\fR slot of the
130 typeglob, which means the corresponding bareword filehandle (like \f(CW\*(C`STDIN\*(C'\fR or
131 \&\f(CW\*(C`FOO\*(C'\fR) can be used for I/O from/to the child process. (If the handle is
132 already open, it is automatically closed first.)
133 .IP \(bu 4
134 A string containing the name of a bareword handle (like \f(CW\*(AqSTDIN\*(Aq\fR or
135 \&\f(CW\*(AqFOO\*(Aq\fR): Such strings are resolved to typeglobs at runtime and then act like
136 the case described above.
137 .PP
138 However, it is possible to make \f(CW\*(C`open3\*(C'\fR use an existing handle directly (as an
139 input argument) and skip the creation of a pipe. To do this, the filehandle
140 argument must have one of the following two forms:
141 .IP \(bu 4
142 An array reference like \f(CW\*(C`[\*(Aq&\*(Aq, $fh]\*(C'\fR, i.e. the first element is the string
143 \&\f(CW\*(Aq&\*(Aq\fR and the second element is the existing handle to use in the child
144 process.
145 .IP \(bu 4
146 A string of the form \f(CW\*(Aq<&FOO\*(Aq\fR or \f(CW\*(Aq>&FOO\*(Aq\fR, i.e. a string starting
147 with the two characters \f(CW\*(C`<&\*(C'\fR (for input) or \f(CW\*(C`>&\*(C'\fR (for output),
148 followed by the name of a bareword filehandle. (The string form cannot be used
149 with handles stored in variables.)
150 .PP
151 If you use this form for \f(CW$chld_in\fR, the filehandle will be closed in the
152 parent process.
153 .PP
154 The filehandles may also be integers, in which case they are understood
155 as file descriptors.
156 .PP
157 \&\f(CW\*(C`open3\*(C'\fR returns the process ID of the child process. It doesn\*(Aqt return on
158 failure: it just raises an exception matching \f(CW\*(C`/^open3:/\*(C'\fR. However,
159 \&\f(CW\*(C`exec\*(C'\fR failures in the child (such as no such file or permission denied),
160 are just reported to \f(CW$chld_err\fR under Windows and OS/2, as it is not possible
161 to trap them.
162 .PP
163 If the child process dies for any reason, the next write to \f(CW$chld_in\fR is
164 likely to generate a SIGPIPE in the parent, which is fatal by default,
165 So you may wish to handle this signal.
166 .PP
167 Note: if you specify \f(CW\*(C`\-\*(C'\fR as the command, in an analogous fashion to
168 \&\f(CW\*(C`open(my $fh, "\-|")\*(C'\fR the child process will just be the forked Perl
169 process rather than an external command. This feature isn\*(Aqt yet
170 supported on Win32 platforms.
171 .PP
172 \&\f(CW\*(C`open3\*(C'\fR does not wait for and reap the child process after it exits.
173 Except for short programs where it\*(Aqs acceptable to let the operating system
174 take care of this, you need to do this yourself. This is normally as
175 simple as calling \f(CW\*(C`waitpid $pid, 0\*(C'\fR when you\*(Aqre done with the process.
176 Failing to do this can result in an accumulation of defunct or "zombie"
177 processes. See "waitpid" in perlfunc for more information.
178 .PP
179 If you try to read from the child\*(Aqs stdout writer and their stderr
180 writer, you\*(Aqll have problems with blocking, which means you\*(Aqll want
181 to use \f(CW\*(C`select\*(C'\fR or IO::Select, which means you\*(Aqd best use
182 \&\f(CW\*(C`sysread\*(C'\fR instead of \f(CW\*(C`readline\*(C'\fR for normal stuff.
183 .PP
184 This is very dangerous, as you may block forever. \f(CW\*(C`open3\*(C'\fR assumes it\*(Aqs
185 going to talk to something like \fBbc\fR\|(1), both writing to it and reading
186 from it. This is presumably safe because you "know" that commands
187 like \fBbc\fR\|(1) will read a line at a time and output a line at a time.
188 Programs like \fBsort\fR\|(1) that read their entire input stream first,
189 however, are quite apt to cause deadlock.
190 .PP
191 The big problem with this approach is that if you don\*(Aqt have control
192 over source code being run in the child process, you can\*(Aqt control
193 what it does with pipe buffering. Thus you can\*(Aqt just open a pipe to
194 \&\f(CW\*(C`cat \-v\*(C'\fR and continually read and write a line from it.
195 .SH "See Also"
196 .IX Header "See Also"
197 .IP IPC::Open2 4
198 .IX Item "IPC::Open2"
199 Like IPC::Open3 but without \f(CW\*(C`STDERR\*(C'\fR capture.
200 .IP IPC::Run 4
201 .IX Item "IPC::Run"
202 This is a CPAN module that has better error handling and more facilities
203 than IPC::Open3.
204 .SH WARNING
205 .IX Header "WARNING"
206 The order of arguments differs from that of \f(CW\*(C`open2\*(C'\fR.