diff options
Diffstat (limited to 'upstream/debian-unstable/man3/IPC::Open2.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/IPC::Open2.3perl | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/IPC::Open2.3perl b/upstream/debian-unstable/man3/IPC::Open2.3perl new file mode 100644 index 00000000..65ebb653 --- /dev/null +++ b/upstream/debian-unstable/man3/IPC::Open2.3perl @@ -0,0 +1,144 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "IPC::Open2 3perl" +.TH IPC::Open2 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +IPC::Open2 \- open a process for both reading and writing using open2() +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use IPC::Open2; +\& +\& my $pid = open2(my $chld_out, my $chld_in, +\& \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq); +\& # or passing the command through the shell +\& my $pid = open2(my $chld_out, my $chld_in, \*(Aqsome cmd and args\*(Aq); +\& +\& # read from parent STDIN and write to already open handle +\& open my $outfile, \*(Aq>\*(Aq, \*(Aqoutfile.txt\*(Aq or die "open failed: $!"; +\& my $pid = open2($outfile, \*(Aq<&STDIN\*(Aq, \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq); +\& +\& # read from already open handle and write to parent STDOUT +\& open my $infile, \*(Aq<\*(Aq, \*(Aqinfile.txt\*(Aq or die "open failed: $!"; +\& my $pid = open2(\*(Aq>&STDOUT\*(Aq, $infile, \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq); +\& +\& # reap zombie and retrieve exit status +\& waitpid( $pid, 0 ); +\& my $child_exit_status = $? >> 8; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBopen2()\fR function runs the given command and connects \f(CW$chld_out\fR for +reading and \f(CW$chld_in\fR for writing. It's what you think should work +when you try +.PP +.Vb 1 +\& my $pid = open(my $fh, "|cmd args|"); +.Ve +.PP +The \f(CW$chld_in\fR filehandle will have autoflush turned on. +.PP +If \f(CW$chld_out\fR is a string (that is, a bareword filehandle rather than a glob +or a reference) and it begins with \f(CW\*(C`>&\*(C'\fR, then the child will send output +directly to that file handle. If \f(CW$chld_in\fR is a string that begins with +\&\f(CW\*(C`<&\*(C'\fR, then \f(CW$chld_in\fR will be closed in the parent, and the child will +read from it directly. In both cases, there will be a \fBdup\fR\|(2) instead of a +\&\fBpipe\fR\|(2) made. +.PP +If either reader or writer is the empty string or undefined, this will be +replaced by an autogenerated filehandle. If so, you must pass a valid lvalue +in the parameter slot so it can be overwritten in the caller, or +an exception will be raised. +.PP +\&\fBopen2()\fR returns the process ID of the child process. It doesn't return on +failure: it just raises an exception matching \f(CW\*(C`/^open2:/\*(C'\fR. However, +\&\f(CW\*(C`exec\*(C'\fR failures in the child are not detected. You'll have to +trap SIGPIPE yourself. +.PP +\&\fBopen2()\fR does not wait for and reap the child process after it exits. +Except for short programs where it's acceptable to let the operating system +take care of this, you need to do this yourself. This is normally as +simple as calling \f(CW\*(C`waitpid $pid, 0\*(C'\fR when you're done with the process. +Failing to do this can result in an accumulation of defunct or "zombie" +processes. See "waitpid" in perlfunc for more information. +.PP +This whole affair is quite dangerous, as you may block forever. It +assumes it's going to talk to something like \fBbc\fR\|(1), both writing +to it and reading from it. This is presumably safe because you +"know" that commands like \fBbc\fR\|(1) will read a line at a time and +output a line at a time. Programs like \fBsort\fR\|(1) that read their +entire input stream first, however, are quite apt to cause deadlock. +.PP +The big problem with this approach is that if you don't have control +over source code being run in the child process, you can't control +what it does with pipe buffering. Thus you can't just open a pipe to +\&\f(CW\*(C`cat \-v\*(C'\fR and continually read and write a line from it. +.PP +The IO::Pty and Expect modules from CPAN can help with this, as +they provide a real tty (well, a pseudo-tty, actually), which gets you +back to line buffering in the invoked command again. +.SH WARNING +.IX Header "WARNING" +The order of arguments differs from that of \fBopen3()\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +See IPC::Open3 for an alternative that handles STDERR as well. This +function is really just a wrapper around \fBopen3()\fR. |