Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 227 insertions, 0 deletions

diff --git a/upstream/archlinux/man3p/pclose.3p b/upstream/archlinux/man3p/pclose.3p
new file mode 100644
index 00000000..b9c81747
--- /dev/null
+++ b/upstream/archlinux/man3p/pclose.3p
@@ -0,0 +1,227 @@
+'\" et
+.TH PCLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+pclose
+\(em close a pipe stream to or from a process
+.SH SYNOPSIS
+.LP
+.nf
+#include <stdio.h>
+.P
+int pclose(FILE *\fIstream\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIpclose\fR()
+function shall close a stream that was opened by
+\fIpopen\fR(),
+wait for the command to terminate, and return the termination status
+of the process that was running the command language interpreter.
+However, if a call caused the termination status to be unavailable to
+\fIpclose\fR(),
+then
+\fIpclose\fR()
+shall return \-1 with
+.IR errno
+set to
+.BR [ECHILD] 
+to report this situation. This can happen if the application calls one
+of the following functions:
+.IP " *" 4
+\fIwait\fR()
+.IP " *" 4
+\fIwaitpid\fR()
+with a
+.IR pid
+argument less than or equal to 0 or equal to the process ID of the
+command line interpreter
+.IP " *" 4
+Any other function not defined in this volume of POSIX.1\(hy2017 that could do one of the above
+.P
+In any case,
+\fIpclose\fR()
+shall not return before the child process created by
+\fIpopen\fR()
+has terminated.
+.P
+If the command language interpreter cannot be executed, the child
+termination status returned by
+\fIpclose\fR()
+shall be as if the command language interpreter terminated using
+.IR exit (127)
+or
+.IR _exit (127).
+.P
+The
+\fIpclose\fR()
+function shall not affect the termination status of any child of the
+calling process other than the one created by
+\fIpopen\fR()
+for the associated stream.
+.P
+If the argument
+.IR stream
+to
+\fIpclose\fR()
+is not a pointer to a stream created by
+\fIpopen\fR(),
+the result of
+\fIpclose\fR()
+is undefined.
+.P
+If a thread is canceled during execution of
+\fIpclose\fR(),
+the behavior is undefined.
+.SH "RETURN VALUE"
+Upon successful return,
+\fIpclose\fR()
+shall return the termination status of the command language
+interpreter. Otherwise,
+\fIpclose\fR()
+shall return \-1 and set
+.IR errno
+to indicate the error.
+.SH ERRORS
+The
+\fIpclose\fR()
+function shall fail if:
+.TP
+.BR ECHILD
+The status of the child process could not be obtained, as described
+above.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+None.
+.SH "APPLICATION USAGE"
+None.
+.SH RATIONALE
+There is a requirement that
+\fIpclose\fR()
+not return before the child process terminates. This is intended to
+disallow implementations that return
+.BR [EINTR] 
+if a signal is received while waiting. If
+\fIpclose\fR()
+returned before the child terminated, there would be no way for the
+application to discover which child used to be associated with the
+stream, and it could not do the cleanup itself.
+.P
+If the stream pointed to by
+.IR stream
+was not created by
+\fIpopen\fR(),
+historical implementations of
+\fIpclose\fR()
+return \-1 without setting
+.IR errno .
+To avoid requiring
+\fIpclose\fR()
+to set
+.IR errno
+in this case, POSIX.1\(hy2008 makes the behavior unspecified. An application
+should not use
+\fIpclose\fR()
+to close any stream that was not created by
+\fIpopen\fR().
+.P
+Some historical implementations of
+\fIpclose\fR()
+either block or ignore the signals SIGINT, SIGQUIT, and SIGHUP while
+waiting for the child process to terminate. Since this behavior is not
+described for the
+\fIpclose\fR()
+function in POSIX.1\(hy2008, such implementations are not conforming. Also, some
+historical implementations return
+.BR [EINTR] 
+if a signal is received, even though the child process has not
+terminated. Such implementations are also considered non-conforming.
+.P
+Consider, for example, an application that uses:
+.sp
+.RS 4
+.nf
+
+popen("command", "r")
+.fi
+.P
+.RE
+.P
+to start
+.IR command ,
+which is part of the same application. The parent writes a prompt to
+its standard output (presumably the terminal) and then reads from the
+\fIpopen\fR()ed
+stream. The child reads the response from the user, does some
+transformation on the response (pathname expansion, perhaps) and
+writes the result to its standard output. The parent process reads the
+result from the pipe, does something with it, and prints another
+prompt. The cycle repeats. Assuming that both processes do appropriate
+buffer flushing, this would be expected to work.
+.P
+To conform to POSIX.1\(hy2008,
+\fIpclose\fR()
+must use
+\fIwaitpid\fR(),
+or some similar function, instead of
+\fIwait\fR().
+.P
+The code sample below illustrates how the
+\fIpclose\fR()
+function might be implemented on a system conforming to POSIX.1\(hy2008.
+.sp
+.RS 4
+.nf
+
+int pclose(FILE *stream)
+{
+    int stat;
+    pid_t pid;
+.P
+    pid = <pid for process created for stream by popen()>
+    (void) fclose(stream);
+    while (waitpid(pid, &stat, 0) == -1) {
+        if (errno != EINTR){
+            stat = -1;
+            break;
+        }
+    }
+    return(stat);
+}
+.fi
+.P
+.RE
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIfork\fR\^(\|)",
+.IR "\fIpopen\fR\^(\|)",
+.IR "\fIwait\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<stdio.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .