Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 163 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/IPC::Open3.3perl b/upstream/archlinux/man3/IPC::Open3.3perl
new file mode 100644
index 00000000..24016e81
--- /dev/null
+++ b/upstream/archlinux/man3/IPC::Open3.3perl
@@ -0,0 +1,163 @@
+.\" -*- 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::Open3 3perl"
+.TH IPC::Open3 3perl 2024-02-11 "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::Open3 \- open a process for reading, writing, and error handling using open3()
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 6
+\&    use Symbol \*(Aqgensym\*(Aq; # vivify a separate handle for STDERR
+\&    my $pid = open3(my $chld_in, my $chld_out, my $chld_err = gensym,
+\&                    \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq);
+\&    # or pass the command through the shell
+\&    my $pid = open3(my $chld_in, my $chld_out, my $chld_err = gensym,
+\&                    \*(Aqsome cmd and args\*(Aq);
+\&
+\&    # read from parent STDIN
+\&    # send STDOUT and STDERR to already open handle
+\&    open my $outfile, \*(Aq>>\*(Aq, \*(Aqoutput.txt\*(Aq or die "open failed: $!";
+\&    my $pid = open3(\*(Aq<&STDIN\*(Aq, $outfile, undef,
+\&                    \*(Aqsome\*(Aq, \*(Aqcmd\*(Aq, \*(Aqand\*(Aq, \*(Aqargs\*(Aq);
+\&
+\&    # write to parent STDOUT and STDERR
+\&    my $pid = open3(my $chld_in, \*(Aq>&STDOUT\*(Aq, \*(Aq>&STDERR\*(Aq,
+\&                    \*(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"
+Extremely similar to \fBopen2()\fR, \fBopen3()\fR spawns the given command and
+connects \f(CW$chld_out\fR for reading from the child, \f(CW$chld_in\fR for writing to
+the child, and \f(CW$chld_err\fR for errors.  If \f(CW$chld_err\fR is false, or the
+same file descriptor as \f(CW$chld_out\fR, then STDOUT and STDERR of the child
+are on the same filehandle.  This means that an autovivified lexical
+cannot be used for the STDERR filehandle, but gensym from Symbol can
+be used to vivify a new glob reference, see "SYNOPSIS".  The \f(CW$chld_in\fR
+will have autoflush turned on.
+.PP
+If \f(CW$chld_in\fR 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.  If \f(CW$chld_out\fR or
+\&\f(CW$chld_err\fR begins with \f(CW\*(C`>&\*(C'\fR, then the child will send output
+directly to that filehandle.  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
+The filehandles may also be integers, in which case they are understood
+as file descriptors.
+.PP
+\&\fBopen3()\fR returns the process ID of the child process.  It doesn't return on
+failure: it just raises an exception matching \f(CW\*(C`/^open3:/\*(C'\fR.  However,
+\&\f(CW\*(C`exec\*(C'\fR failures in the child (such as no such file or permission denied),
+are just reported to \f(CW$chld_err\fR under Windows and OS/2, as it is not possible
+to trap them.
+.PP
+If the child process dies for any reason, the next write to \f(CW$chld_in\fR is
+likely to generate a SIGPIPE in the parent, which is fatal by default.
+So you may wish to handle this signal.
+.PP
+Note if you specify \f(CW\*(C`\-\*(C'\fR as the command, in an analogous fashion to
+\&\f(CW\*(C`open(my $fh, "\-|")\*(C'\fR the child process will just be the forked Perl
+process rather than an external command.  This feature isn't yet
+supported on Win32 platforms.
+.PP
+\&\fBopen3()\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
+If you try to read from the child's stdout writer and their stderr
+writer, you'll have problems with blocking, which means you'll want
+to use \fBselect()\fR or IO::Select, which means you'd best use
+\&\fBsysread()\fR instead of \fBreadline()\fR for normal stuff.
+.PP
+This is very 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.
+.SH "See Also"
+.IX Header "See Also"
+.IP IPC::Open2 4
+.IX Item "IPC::Open2"
+Like Open3 but without STDERR capture.
+.IP IPC::Run 4
+.IX Item "IPC::Run"
+This is a CPAN module that has better error handling and more facilities
+than Open3.
+.SH WARNING
+.IX Header "WARNING"
+The order of arguments differs from that of \fBopen2()\fR.