Merging upstream version 6.8.

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

1 files changed, 208 insertions, 0 deletions

diff --git a/man/man3/popen.3 b/man/man3/popen.3
new file mode 100644
index 0000000..9467e06
--- /dev/null
+++ b/man/man3/popen.3
@@ -0,0 +1,208 @@
+'\" t
+.\" Copyright 1991 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\"     @(#)popen.3	6.4 (Berkeley) 4/30/91
+.\"
+.\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu
+.\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de)
+.\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
+.\"
+.TH popen 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+popen, pclose \- pipe stream to or from a process
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdio.h>
+.P
+.BI "FILE *popen(const char *" command ", const char *" type );
+.BI "int pclose(FILE *" stream );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR popen (),
+.BR pclose ():
+.nf
+    _POSIX_C_SOURCE >= 2
+        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
+.fi
+.SH DESCRIPTION
+The
+.BR popen ()
+function opens a process by creating a pipe, forking, and invoking the
+shell.
+Since a pipe is by definition unidirectional, the
+.I type
+argument may specify only reading or writing, not both; the resulting
+stream is correspondingly read-only or write-only.
+.P
+The
+.I command
+argument is a pointer to a null-terminated string containing a shell
+command line.
+This command is passed to
+.I /bin/sh
+using the
+.B \-c
+flag; interpretation, if any, is performed by the shell.
+.P
+The
+.I type
+argument is a pointer to a null-terminated string which must contain
+either the letter \[aq]r\[aq] for reading or the letter \[aq]w\[aq] for writing.
+Since glibc 2.9,
+this argument can additionally include the letter \[aq]e\[aq],
+which causes the close-on-exec flag
+.RB ( FD_CLOEXEC )
+to be set on the underlying file descriptor;
+see the description of the
+.B O_CLOEXEC
+flag in
+.BR open (2)
+for reasons why this may be useful.
+.P
+The return value from
+.BR popen ()
+is a normal standard I/O stream in all respects save that it must be closed
+with
+.BR pclose ()
+rather than
+.BR fclose (3).
+Writing to such a stream writes to the standard input of the command; the
+command's standard output is the same as that of the process that called
+.BR popen (),
+unless this is altered by the command itself.
+Conversely, reading from
+the stream reads the command's standard output, and the command's
+standard input is the same as that of the process that called
+.BR popen ().
+.P
+Note that output
+.BR popen ()
+streams are block buffered by default.
+.P
+The
+.BR pclose ()
+function waits for the associated process to terminate and returns the exit
+status of the command as returned by
+.BR wait4 (2).
+.SH RETURN VALUE
+.BR popen ():
+on success, returns a pointer to an open stream that
+can be used to read or write to the pipe;
+if the
+.BR fork (2)
+or
+.BR pipe (2)
+calls fail, or if the function cannot allocate memory,
+NULL is returned.
+.P
+.BR pclose ():
+on success, returns the exit status of the command; if
+.\" These conditions actually give undefined results, so I commented
+.\" them out.
+.\" .I stream
+.\" is not associated with a "popen()ed" command, if
+.\".I stream
+.\" already "pclose()d", or if
+.BR wait4 (2)
+returns an error, or some other error is detected,
+\-1 is returned.
+.P
+On failure, both functions set
+.I errno
+to indicate the error.
+.SH ERRORS
+The
+.BR popen ()
+function does not set
+.I errno
+if memory allocation fails.
+If the underlying
+.BR fork (2)
+or
+.BR pipe (2)
+fails,
+.I errno
+is set to indicate the error.
+If the
+.I type
+argument is invalid, and this condition is detected,
+.I errno
+is set to
+.BR EINVAL .
+.P
+If
+.BR pclose ()
+cannot obtain the child status,
+.I errno
+is set to
+.BR ECHILD .
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR popen (),
+.BR pclose ()
+T}	Thread safety	MT-Safe
+.TE
+.SH VERSIONS
+The \[aq]e\[aq] value for
+.I type
+is a Linux extension.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH CAVEATS
+Carefully read Caveats in
+.BR system (3).
+.SH BUGS
+Since the standard input of a command opened for reading shares its seek
+offset with the process that called
+.BR popen (),
+if the original process has done a buffered read, the command's input
+position may not be as expected.
+Similarly, the output from a command
+opened for writing may become intermingled with that of the original
+process.
+The latter can be avoided by calling
+.BR fflush (3)
+before
+.BR popen ().
+.P
+Failure to execute the shell is indistinguishable from the shell's failure
+to execute the command, or an immediate exit of the command.
+The only hint is an exit status of 127.
+.\" .SH HISTORY
+.\" A
+.\" .BR popen ()
+.\" and a
+.\" .BR pclose ()
+.\" function appeared in Version 7 AT&T UNIX.
+.SH SEE ALSO
+.BR sh (1),
+.BR fork (2),
+.BR pipe (2),
+.BR wait4 (2),
+.BR fclose (3),
+.BR fflush (3),
+.BR fopen (3),
+.BR stdio (3),
+.BR system (3)