Debian Codegraph @

upstream/opensuse-tumbleweed/man3/IPC::Open2.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::Open2 3pm"
61 .TH IPC::Open2 3pm 2026-03-09 "perl v5.42.1" "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::Open2 \- open a process for both reading and writing using open2()
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use IPC::Open2;
72 \&
73 \& my $pid = open2(my $chld_out, my $chld_in,
74 \& \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq);
75 \& # or passing the command through the shell
76 \& my $pid = open2(my $chld_out, my $chld_in, \*(Aqsome cmd and args\*(Aq);
77 \&
78 \& # read from parent STDIN and write to already open handle
79 \& open my $outfile, \*(Aq>\*(Aq, \*(Aqoutfile.txt\*(Aq or die "open failed: $!";
80 \& my $pid = open2([\*(Aq&\*(Aq, $outfile], [\*(Aq&\*(Aq, *STDIN],
81 \& \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq);
82 \&
83 \& # read from already open handle and write to parent STDOUT
84 \& open my $infile, \*(Aq<\*(Aq, \*(Aqinfile.txt\*(Aq or die "open failed: $!";
85 \& my $pid = open2([\*(Aq&\*(Aq, *STDOUT], [\*(Aq&\*(Aq, $infile],
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 The \f(CWopen2()\fR function runs the given command and connects \f(CW$chld_out\fR for
95 reading and \f(CW$chld_in\fR for writing. It\*(Aqs what you think should work
96 when you try
97 .PP
98 .Vb 1
99 \& my $pid = open(my $fh, "|cmd args|"); # ERROR
100 .Ve
101 .PP
102 but you have to write it as:
103 .PP
104 .Vb 1
105 \& my $pid = open2($chld_out, $chld_in, @command_and_args);
106 .Ve
107 .PP
108 The \f(CW$chld_in\fR filehandle will have autoflush turned on.
109 .PP
110 By default, the filehandles you pass in are used as output parameters.
111 \&\f(CW\*(C`open2\*(C'\fR internally creates two pipes. The write end of the first pipe and the
112 read end of the second pipe are connected to the command\*(Aqs standard output and
113 input, respectively. The corresponding read and write ends are placed in the
114 first and second argument to \f(CW\*(C`open2\*(C'\fR.
115 .PP
116 The filehandle arguments can take the following forms:
117 .IP \(bu 4
118 An uninitialized variable (technically, either \f(CW\*(C`undef\*(C'\fR or the empty string
119 will work): \f(CW\*(C`open2\*(C'\fR generates a fresh filehandle and assigns it to the
120 argument, which must be a modifiable variable for this work (otherwise an
121 exception will be raised).
122 .IP \(bu 4
123 An existing handle in the form of a typeglob like \f(CW*STDIN\fR or \f(CW*FOO\fR or a
124 reference to such: \f(CW\*(C`open2\*(C'\fR places the filehandle in the \f(CW\*(C`IO\*(C'\fR slot of the
125 typeglob, which means the corresponding bareword filehandle (like \f(CW\*(C`STDIN\*(C'\fR or
126 \&\f(CW\*(C`FOO\*(C'\fR) can be used for I/O from/to the child process. (If the handle is
127 already open, it is automatically closed first.)
128 .IP \(bu 4
129 A string containing the name of a bareword handle (like \f(CW\*(AqSTDIN\*(Aq\fR or
130 \&\f(CW\*(AqFOO\*(Aq\fR): Such strings are resolved to typeglobs at runtime and then act like
131 the case described above.
132 .PP
133 However, it is possible to make \f(CW\*(C`open2\*(C'\fR use an existing handle directly (as an
134 input argument) and skip the creation of a pipe. To do this, the filehandle
135 argument must have one of the following two forms:
136 .IP \(bu 4
137 An array reference like \f(CW\*(C`[\*(Aq&\*(Aq, $fh]\*(C'\fR, i.e. the first element is the string
138 \&\f(CW\*(Aq&\*(Aq\fR and the second element is the existing handle to use in the child
139 process.
140 .IP \(bu 4
141 A string of the form \f(CW\*(Aq<&FOO\*(Aq\fR or \f(CW\*(Aq>&FOO\*(Aq\fR, i.e. a string starting
142 with the two characters \f(CW\*(C`<&\*(C'\fR (for input) or \f(CW\*(C`>&\*(C'\fR (for output),
143 followed by the name of a bareword filehandle. (The string form cannot be used
144 with handles stored in variables.)
145 .PP
146 If you use this form for \f(CW$chld_in\fR, the filehandle will be closed in the
147 parent process.
148 .PP
149 \&\f(CW\*(C`open2\*(C'\fR returns the process ID of the child process. It doesn\*(Aqt return on
150 failure: it just raises an exception matching \f(CW\*(C`/^open2:/\*(C'\fR. However,
151 \&\f(CW\*(C`exec\*(C'\fR failures in the child are not detected. You\*(Aqll have to
152 trap SIGPIPE yourself.
153 .PP
154 \&\f(CW\*(C`open2\*(C'\fR does not wait for and reap the child process after it exits.
155 Except for short programs where it\*(Aqs acceptable to let the operating system
156 take care of this, you need to do this yourself. This is normally as
157 simple as calling \f(CW\*(C`waitpid $pid, 0\*(C'\fR when you\*(Aqre done with the process.
158 Failing to do this can result in an accumulation of defunct or "zombie"
159 processes. See "waitpid" in perlfunc for more information.
160 .PP
161 This whole affair is quite dangerous, as you may block forever. It
162 assumes it\*(Aqs going to talk to something like \fBbc\fR\|(1), both writing
163 to it and reading from it. This is presumably safe because you
164 "know" that commands like \fBbc\fR\|(1) will read a line at a time and
165 output a line at a time. Programs like \fBsort\fR\|(1) that read their
166 entire input stream first, however, are quite apt to cause deadlock.
167 .PP
168 The big problem with this approach is that if you don\*(Aqt have control
169 over source code being run in the child process, you can\*(Aqt control
170 what it does with pipe buffering. Thus you can\*(Aqt just open a pipe to
171 \&\f(CW\*(C`cat \-v\*(C'\fR and continually read and write a line from it.
172 .PP
173 The IO::Pty and Expect modules from CPAN can help with this, as
174 they provide a real tty (well, a pseudo\-tty, actually), which gets you
175 back to line buffering in the invoked command again.
176 .SH WARNING
177 .IX Header "WARNING"
178 The order of arguments differs from that of \f(CW\*(C`open3\*(C'\fR from IPC::Open3.
179 .SH "SEE ALSO"
180 .IX Header "SEE ALSO"
181 See IPC::Open3 for an alternative that handles \f(CW\*(C`STDERR\*(C'\fR as well. This
182 function is really just a wrapper around \f(CW\*(C`open3\*(C'\fR.